Directories

[HDIRECTO]

HBOOK histogram data are kept in a ZEBRA tree structure similar to the directory structure of the Unix file system. Note that the ZEBRA RZ package uses the same conventions. (In fact, HBOOK uses the ZEBRA RZ package to manage files). With this convention, all references to histograms are still made using an integer identifier, but this identifier is relative to a directory. HBOOK initially sets the current directory to be //PAWC. This directory remains the current directory until changed either explicitly or implicitly by one of the calls described below. As with the Unix file system the current directory can be a subdirectory, e.g. //PAWC/L1, //PAWC/L1/L21 and //PAWC/L1/L22.

These HBOOK directories can reside in the local memory of the computer (i.e. the PAWC common, or they can be stored on a local (//LUN1) or remote disk file system (//VXCRNA). They can even be dynamically created by a ``producer'' in the memory of a remote computer and ''shared'' by that machine with the user's machine via global section (VMS) or shared memory (Unix).


                                                          HMDIR HCDIR HLDIR HPDIR

--------    //PAWC                     local memory         X     X     X     X
|      |    //LUN1                     local disk           X     X     X
| USER |    //VXCRNA ---- telnet (rsh) remote disk          X     X     X
|      |    //GLOSEC ---- tcp/ip ---   global section(VMS)  X     X     X
--------    //SHARE  ---- tcp/ip ---   shared memory(Unix)  X     X     X

Figure: Different kinds of HBOOK directories

[FDIRKIND]

                       +--------------------------+
                       |CALL  HMDIR (CHPATH,CHOPT) |
                       +--------------------------+
                                  

Action: Make a new subdirectory below the current directory. This command works with all five different kinds of directories described in figure [more info].

Input parameters:
CHPATH
Character variable or constant containing the name of the subdirectory.
CHOPT
Character variable specifying the option chosen. If CHOPT='S' then the current directory is changed to the new directory.

                      +----------------------------+
                      |CALL  HCDIR (*CHPATH*,CHOPT) |
                      +----------------------------+
                                  

Action: Change the current directory. This command works with all five different kinds of directories described in figure [more info].

Input parameters:
CHPATH
Character variable or constant containing the name of the directory which is to become the current directory (default action if CHOPT=' ').
CHOPT
Character variable specifying the option chosen. ' ' Set new directory. 'R' Read the name of the current directory.
Output Parameter
CHPATH
Character variable containing the name of the current directory (CHOPT='R').

                      Setting RZ directories
                                  

CALL HCDIR('//PAW/CDET',' ')     !  Go to directory with given absolute pathname
CALL HCDIR('TPC',' ')            !  Go to directory with given relative pathname
                                 !  we are now in //PAW/CDET/TPC
CALL HCDIR('//PAW/CDET/TPC',' ') !  Equivalent to 1+2 above
CALL HCDIR('\',' ')              !  Go to parent directory, i.e. //PAW/CDET
CALL HCDIR('TPC',' ')            !  Go to TPC subdirectory again
CALL HCDIR ('\VERTEX',' ')       !  Go to directory //PAW/CDET/VERTEX
                                 !  i.e. one level up then one down again

This concept of directories also applies to the direct access files when using HRFILE, HRIN and HROUT.

                       +--------------------------+
                       |CALL  HLDIR (CHPATH,CHOPT) |
                       +--------------------------+

                                  

Action: List the contents (identifiers, type of histograms and titles) of a HBOOK directory. This command works with all five different kinds of directories described in figure [more info].

Input parameters:
CHPATH
Character variable or constant containing the name of the directory to be listed. CHPATH=' ' stands for the current directory.
CHOPT
Character variable specifying the chosen option.
' '
List only the top directory.
'A'
List all Ntuple extentions.
'I'
HINDEX option selected instead of simple list.
'N'
List only the Ntuples.
'R'
List using RZ format.
'T'
List the complete subdirectory tree starting from the specified directory.

              List all existing directories in //PAWC
                                  

CALL HLDIR ('//PAWC','T')


                       +--------------------------+
                       |CALL  HPDIR (CHPATH,CHOPT) |
                       +--------------------------+
                                  

Action: Print the contents of a directory (This routine calls HPRINT). This routine works only for directories in local memory or remote RZ files accessed opened via XZRZOP (see the CSPACK manual [bib-CSPACK] for more information).

Input parameters:
CHPATH
Character variable or constant specifying the pathname of the directory to be printed. CHPATH=' ' stands for the current directory.
CHOPT
Character variable specifying the option chosen.
' '
Print the contents of the top directory.
'I'
Print an index.
'T'
Print the complete directory tree (i.e. the top directory and its subdirectories).

                    Printing list of histograms
                                  

CALL HPDIR ('//PAWC','T') ! Print list of all histograms in //PAWC
CALL HPDIR (' ',' ')      ! Print list of all histograms in current directory
CALL HPRINT(0)            ! Print histograms in current directory
                   +----------------------------------+
                   | CALL  HRDIR (MAXDIR,CHDIR*,NDIR*) |
                   +----------------------------------+
                                  

Action: Returns the list of subdirectories of the current working directory. This command works with all five different kinds of directories described in figure [more info].

Input parameter
MAXDIR
Length of the character array CHPATH.
Output parameters
CHDIR*
Character array which will contain the names of the subdirectories of the current working directory.
NDIR*
Actual number of subdirectories present in the current working directory. If this number is greater than MAXDIR, only the first MAXDIR subdirectory names will be returned in array CHDIR.

The use of directories is illustrated below:

                   Example of use of directories
                                  

      PROGRAM MAIN
*
      COMMON/PAWC/H(20000)
      CALL HLIMIT (20000)
      CALL HBOOK1 (10,'Energy distribution',100,0.,300.,0.)
           "   "
*
      CALL USECAL
           "   "
      CALL HFILL (10,EDER,0.,1.)

           "   "
      CALL HISTDO
           "   "
      END
      SUBROUTINE USECAL
*
*        Make a new directory ECAL and set the new current directory
*
          CALL HMDIR ('ECAL','S')
*
*        Create a new histogram with ID=10 in the new directory
*
          CALL HBOOK1 (10,'My histogram',50,-5.,5.,0.)
           "   "
          CALL HFILL (10,UX,0,1.)
           "   "
*         Go back to the parent directory
*
          CALL HCDIR ('\','  ')
           "   "
      END