Directories

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

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 .

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 .

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',' ')     ! {\rm Go to directory with given absolute pathname}
                                   
CALL HCDIR('TPC',' ')            ! {\rm Go to directory with given relative pathname}
                                 ! {\rm we are now in} //PAW/CDET/TPC

CALL HCDIR('//PAW/CDET/TPC',' ') ! {\rm Equivalent to 1+2 above}

CALL HCDIR('\',' ')              ! {\rm Go to parent directory, i.e.} //PAW/CDET

CALL HCDIR('TPC',' ')            ! {\rm Go to TPC subdirectory again}

CALL HCDIR ('{}VERTEX',' ')       ! {\rm Go to directory} //PAW/CDET/VERTEX
                                 ! {\rm 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 .

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.

'S'

Sort the directory entries.

'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 [19] 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 HLNEXT (*IDH*,CHTYPE*,CHTITL*,CHOPT)

Action: Scan the contents of the current directory in memory or on an RZ file.

Input parameter description:

IDH

Must be zero for first call

CHTYPE

Character variable specifying items to be scanned.

'1'

include 1-D histograms

'2'

include 2-D histograms

'N'

include Ntuples

'D'

include subdirectories

' '

include everything, i.e., equivalent to '12ND'.

Output parameter description:

IDH

On return contains identifier of next histogram. When all histograms are processed, a value of zero is returned.

CHTYPE

Character variable specifying type of histogram.

'1'

1-dimensional

'2'

2-dimensional

'N'

Ntuple

'D'

subdirectory

'?'

unknown.

CHTYPE

Character variable containing title or subdirectory name.

Scan content of current directory

      IDH=0
  1   CONTINUE
      CALL HLNEXT(IDH,CHTYPE,CHTITL,CHOPT)
      IF(IDH.NE.0) THEN
         ... process
         GOTO 1
      ENDIF

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 .

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