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 description:

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 )

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 description:

ISTAT

Return code. ISTAT=0 indicates success.

LREC

(Only when (LREC=0) on input) The actual record length of the file on disk.

Remarks:

• HROPEN performs a Fortran direct access open for the file CHFILE on logical unit LUN.
• 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.  
• If LREC=0 on input, HROPEN will automatically determine the record length of existing files.
• 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 (.).
• The maximum number of records is by default 32000. You can use option Q to change this.
• A file declared with HROPEN must be released with HREND.
• 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'.

• The contents of a directory is listed using routine HLDIR.
• A new subdirectory can be created with routine HMDIR.
• 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

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.

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. This facility also works for Ntuples.