HBOOK -- H2Input-Output-Routines

Input/Output Routines

HBOOK files are in fact ZEBRA RZ files [bib-ZEBRARZ]. Input/output error return codes are available vin the ZEBRA communication vector IQUEST, and the user should consult the RZ manual for their meaning. Both disk and memory resident files are supported, the latter being particularly useful in online applications, where histogram data have to be shared between different processes.

HBOOK files are written in Zebra exchange format and thus need not be converted when transferred between different computer systems using binary ftp (see section [more info]), or accessed over the network using a distributed file system such as AFS or NFS.

Reading and writing histograms to a direct access file

                     +------------------------------+
                     | CALL  HRPUT (ID,CHFILE,CHOPT) |
                     +------------------------------+

Action: Write a histogram to a given direct access file. This routine cannot be used for Ntuples.

Input parameters:

ID

Histogram identifier. ID=0 writes all histograms in the current directory to the output file.

CHFILE

Character variable or constant defining the filename. If CHFILE=' ' the histogram is saved in the current working directory on disk.

CHOPT

Character option specifying the desired option.

'N': Write the histogram to a New file.
'T': Can be used together with ID=0. All histograms in the current directory and all subdirectories in memory are written to the output file.
'U': Write the histogram to an already existing HBOOK file. When an histogram with the same identifier already exists on the output file, then a new cycle is added.

                     +------------------------------+
                     | CALL  HRGET (ID,CHFILE,CHOPT) |
                     +------------------------------+

Action: Read a histogram from a given direct access file. This routine cannot be used for Ntuples.

Input parameters:

ID

Histogram identifier. ID=0 read all histograms into the current directory.

CHFILE

Character variable or constant defining the input filename. If CHFILE=' ' the histogram is read from the current working directory on disk.

CHOPT

Character option specifying the desired option.

'A': Add to the current histogram in memory.
'T': Get a complete tree (not yet implemented)

Remarks:

The following remarks apply to both HRPUT and HRGET.

HRGET and HRPUT issue automatically Fortran OPEN and CLOSE calls.
With HRPUT the file is created with LREC=1024 machine words.
On VM/CMS no FILEDEF statement should be given. The filename CHFILE can be given in either of the forms Filename Filetype Filemode or Filename.Filetype.Filemode
On Unix the filename CHFILE will be translated to lowercase.
Fortran logical unit 88 is used by these routines.
HRPUT calls HROPEN, HROUT and HREND.
HRGET calls HROPEN, HRIN and HREND.

Open an RZ direct access file or map a Global Section
```
          +----------------------------------------------------+
          | CALL  HROPEN (LUN,CHTOP,CHFILE,CHOPT,*LREC*,ISTAT*) |
          +----------------------------------------------------+
                                  
```
Action: Open a direct access HBOOK file. If several direct access files are opened, they are identified by the top directory only.

Input parameter(s)

LUN
Logical unit number associated to the file.
CHTOP
Character variable specifying the name of the top directory associated with unit LUN (maximum 8 characters). This is an arbitrary name used to identify the file on unit LUN in subsequent calls to HR.. routines.
CHFILE
Character variable specifying the name of the file to be opened.
CHOPT
Character variable specifying the options selected

Medium

' '
Disk (default)
'G'
Global Section (see chapter [more info])

mode

' '
Existing HBOOK file (default)
'N'
Create a new file
'P'
Preserve file case
'Q'
Override default number of records for new file with contents of IQUEST(10)
'X'
The file is/will be in exchange format
'U'
Update an existing file

LREC
Record length in machine words (recommended value is 1024). If LREC=0 the actual record length is returned on exit.

Output parameter(s)

ISTAT
Return code. ISTAT=0 indicates success.
LREC
(Only when (LREC=0) on input) The actual record length of the file on disk.

Remarks:
1. HROPEN performs a Fortran direct access open for the file CHFILE on logical unit LUN.
2. On VM/CMS no FILEDEF statement should be given. The filename CHFILE can be given in either of the forms Filename Filetype Filemode or Filename.Filetype.Filemode
3. On Unix the filename CHFILE will be translated to lowercase.
4. If LREC=0 on input, HROPEN will automatically determine the record length of existing files.
5. On MVS systems, the current userid prefix will be automatically added to the front of the file name unless the first character is a dot (.).
6. The maximum number of records is by default 32000. You can use option Q to change this.
7. A file declared with HROPEN must be released with HREND.
8. HROPEN calls HRFILE internally.
```
                     +------------------------------+
                     |CALL  HRFILE (LUN,CHTOP,CHOPT) |
                     +------------------------------+
                                  
```
  Action: Establishes a temporary unique correspondance between a logical unit and a top directory name. Users should call HROPEN instead of HRFILE.
  By default, HROPEN ( HRFILE) creates new files (option N) with the maximum number of records set to a large number (default 32000). If this is insufficient, the user can override this value by specifying the Q option and setting IQUEST(10) to the actual number of records required (up to a maximum of 65K), as shown below.
```
             Overriding the default record allocation
                                  
```
```
      COMMON/QUEST/IQUEST(100)                         ! Declare IQUEST communication vector
      IQUEST(10) = 65000                               ! I require 65000 records
      CALL HROPEN(1,'FILE','file.ext','NQ',1024,ISTAT) ! Call HROPEN
```
  Note that after a call to HROPEN ( HRFILE) (if CHTOP='MYDST' for example), the current directory is set to '//MYDST'. If LUN is an existing file, one can change the current directory to an existing subdirectory 'SUBDIR' using CALL HCDIR ('SUBDIR',' '), which sets the current directory CD to '//CHTOP/SUBDIR'.
  1. The contents of a directory is listed using routine HLDIR.
  2. A new subdirectory can be created with routine HMDIR.
  3. The current directory in memory (//PAWC/) and hence on the direct access files may be set by one of the routines HCDIR or HMDIR.
    Notice that when calling HCDIR or HRFILE on a direct access file, the current directory in memory will be the latest current directory set.
    Writing to a file
    
    [HWRITFIL]
```
                     +------------------------------+
                     |CALL  HROUT (ID,ICYCLE*,CHOPT) |
                     +------------------------------+
                                  
```
    Action: Write a histogram from the current directory in memory onto the current directory on the direct access file.
    
    Input parameters:
    
    ID
    Histogram identifier. ID=0 means write all histograms from the current directory in memory.
    CHOPT
    Character variable specifying the options selected.
    
    'T'
    Write the whole directory tree hanging from the current directory (if ID=0).
    
    Output parameter:
    
    ICYCLE
    Cycle number. The first time a given histogram with identifier ID is stored on a directory on a direct access file, ICYCLE is set to 1. If the histogram identifier ID already exists on the direct access file, then the call to HROUT will increment the cycle number ICYCLE by one.
    
    Experienced users may invoke routines from the ZEBRA RZ package to purge a directory, i.e. delete all versions of an identifier but the most recent one using routine RZPURG.
    
    [HREADDAF]
    Reading from a direct-access file or global section
```
                     +------------------------------+
                     | CALL  HRIN (ID,ICYCLE,IOFSET) |
                     +------------------------------+
                                  
```
    Action: Read a histogram from the current directory on the direct access file (or global section) into the current directory in memory.
    
    Input parameters:
    
    ID
    Histogram identifier. ID=0 means that all histograms from the current directory on the direct access file (global section) should be read into memory. If a histogram identifier ID already exists in memory a message is printed and it is deleted from memory before reading the new histogram from the file or global section.
    ICYCLE
    Cycle number. If ICYCLE=0 then the lowest cycle is read. To read the highest cycle, use a large number, e.g. 999999.
    IOFSET
    The histogram which is read in memory will have the identifier IDN=ID+IOFSET. Specifying IOFSET different of zero permits to have in memory copies of histograms with the same identifiers ID in different files. This parameter may be very useful when HRIN is called together with routines such as HOPERA or HDIFF.
    
    [HSCRATCH]
    Scratching histogram in a file
```
                      +----------------------------+
                      |CALL  HSCR (ID,ICYCLE,CHOPT) |
                      +----------------------------+

                                  
```
    Action: Scratch (delete) a histogram from the current directory in the direct access file.
    
    Input parameters:
    
    ID
    Histogram identifier. ID=0 means scratch all histograms in the current directory.
    ICYCLE
    Cycle number. If ICYCLE=0 then all cycles are deleted.
    CHOPT
    Character variable specifying options selected.
    
    ' '
    Only possible value (not used at present)
    
    Close a file
    
    [HCLOSFIL]
```
                          +--------------------+
                          | CALL  HREND (CHTOP) |
                          +--------------------+
                                  
```
    Action: Closes a direct access file if is not needed anymore or when the options 'N' or 'U' are specified in HRFILE.
    
    Input parameter:
    
    CHTOP
    Character variable specifying the name of the top directory associated with the file to be closed. This should correspond to the name declared with HRFILE. After this call, the system bank associated to this file is deleted. The call to HREND is obligatory when the file has been modified.
    Remark:
    A Fortran CLOSE statement should follow a call to HREND.

Input/Output Routines

Reading and writing histograms to a direct access file

Open an RZ direct access file or map a Global Section

Writing to a file

[HREADDAF] Reading from a direct-access file or global section

[HSCRATCH] Scratching histogram in a file

Close a file

[HREADDAF]
Reading from a direct-access file or global section

[HSCRATCH]
Scratching histogram in a file