HEPDB -- H2hdbuser-Utility-routines

Utility routines

Changing the HEPDB logging level

                  +------------------------------------+
                  |CALL  CDLOGL (PATH,LOGLEV,CHOPT,IRC) |
                  +------------------------------------+

PATH

Top directory name of HEPDB file.

LOGLEV

Log level

<0: no messages are printed
1: error messages from main HEPDB routines (default value)
2: error messages and warnings from main HEPDB routines
3: error messages, warnings and informative messages from main HEPDB routines
4: as above, but also error messages from HEPDB internal routines
5: as above, but also warnings from HEPDB internal routines
>5: all messages are printed, and also additional debug.

CHOPT

Character option

'A': Set RZ loglevel for all HEPDB files that are currently open

IRC

Integer return code

0: Normal completion
1: Invalid path name
2: Database corresponding to specified path name is not open

The level of diagnostic print out can be set at any time using the routine CDLOGL. By default, the log level for each database file is set to 0 when the routine CDOPEN is called. Note that this routine sets both the HEPDB and RZ log levels.

Create a linear chain of keys banks

               +------------------------------------------+
               |CALL  CDBOOK (PATH,LSUP,NBANKS,CHOPT,IRC*) |
               +------------------------------------------+

PATH

Character variable specifying the pathname for which the banks are to be created

LSUP

Address of the first bank in the linear chain

NBANKS

Number of banks to create

CHOPT

Character options (not used at present)

IRC

Integer return code

0: Normal completion
99: Insufficient dynamic storage to create all of the requested banks

This routine creates a linear structure of NBANKS key banks. Each bank has a single structural link, to which a databank may eventually be attached.

Create information bank containing usage information

               +------------------------------------------+
               | CALL  CDINFO (IUDIV,LAD*,LSUP,JBIAS,IRC*) |
               +------------------------------------------+

IUDIV

User division where the DBTB bank has to be created

LAD

Address of the DBTB bank (should be in the same store as all DB objects)

LSUP

Address of the supporting bank

JBIAS

Link bias as described in ZEBRA manual

IRC

Integer return code

0: Normal completion

This routine creates the DBTB bank with information of the database objects used for this event (since the last call to DBINFO). It stores two words per object used, a unique identifier corresponding to the path name and the serial number of the object (KEY(1) value)

Print statistics on database usage

                        +------------------------+
                        | CALL  CDSTAT (LUN,IRC*) |
                        +------------------------+

LUN

Logical unit on which the statistics should be printed

IRC

Integer return code

0: Normal completion
98: Invalid path name in node bank

This routine prints a summary of database usage for the current job on the specified logical unit.

List directory

               +------------------------------------------+
               | CALL  CDLDIR (PATH,LUN,NLEVEL,CHOPT,IRC*) |
               +------------------------------------------+

PATH

Character string describing the pathname

LUN

Integer variable specifying the Fortran logical unit on which the information should be printed

NLEVEL

The number of levels of subdirectories that should be scanned.

CHOPT

Character string with any of the following characters

H: Write a header showing the command and options
C: List the creation date and time of the directory/ies
M: List the modification date and time of the directory/ies
O: Display the number of objects
R: List subdirectories recursively
S: Display number of subdirectories
T: Display the tags for the directory/ies
V: Generate a "very wide" listing (132 columns)
W: Generate a "wide" listing (80 columns)

IRC

Integer return code

0: Normal completion
101: Illegal path name
102: No key or data for specified path

List objects in a directory

   +------------------------------------------------------------------+
   |CALL  CDLIST (CHPATH,KSN,CHBANK,ILNK1,ILNK2,IDAT1,IDAT2,CHOPT,IRC) |
   +------------------------------------------------------------------+

CHPATH

Character variable specifying the path name to list

KSN

Key serial number of a specific object, or 0. If 0 is specified, no check will be made on key serial number.

CHBANK

Character bank identifier (for option Z)

ILNK1

First link to be printed (as in DZSHOW)

ILNK2

Last link to be printed

IDAT1

First data word to be printed

IDAT2

Last data word to be printed

CHOPT

Character string with any of the following characters

C: display object count
D: display key definitions
E: display the experiment keys
G: display keys using generic routine (RZPRNK)
K: display all keys
L: list only lowest level (end node) directories
M: show maxima and minima of validity ranges
N: display number of data words
P: display pathname
S: display the system keys
T: display insertion date and time (RZ value)
U: display user keys
V: display validity range pairs
Z: dump ZEBRA bank with DZSHOW

IRC

Display objects in a directory

   +------------------------------------------------------------------+
   |CALL  CDSHOW (CHPATH,KSN,CHBANK,ILNK1,ILNK2,IDAT1,IDAT2,CHOPT,IRC) |
   +------------------------------------------------------------------+

CHPATH

Character variable specifying the path name to list

ISEL

Integer vector specifying the instant of validity

IMASK

Integer vector indicating which elements of KEYS are significant for selection. If MASK corresponding to one of the fields of 'Beginning' validity range is set, it will select objects with start validity smaller than those requested in KEYS. If MASK corresponding to one of the fields of 'End' validity range is set, it will select objects with end validity larger than those in KEYS. If MASK corresponding to time of insertion is set, objects inserted earlier than KEYS(IDHINS) are selected

KEYS

Vector of keys.

CHBANK

ZEBRA bank name

IDBANK

ZEBRA bank identifier

IDAT1

First data word to be printed

IDAT2

Last data word to be printed

CHOPT

Character string with any of the following characters

: Find all banks with position in walk > IDBANK
S: FInd bank with Zebra ID = IDBANK

IRC

Obtain last object inserted into directory

              +--------------------------------------------+
              | CALL  CDLKEY (PATH,KEY*,IDATE*,ITIME*,IRC*) |
              +--------------------------------------------+

PATH

Character string describing the pathname

KEY

Scalar in which the highest KEY(1) (key serial number) is returned. If option K is specified, then KEY must be a vector of sufficient length to retrieve the entire key vector for objects in the specified directory. The length of the key vector may be obtained using the routine RZKEYD.

IDATE

Date (YYMMDD) of the insertion of the last element

ITIME

Time (HHMM) of the insertion of the last element

CHOPT

Character string with any of the following characters

' ': Return just the key serial number (KEY(1))
'K': Return complete key vector in KEY

IRC

Integer return code

0: Normal completion
131: Illegal pathname
132: Illegal number of keys in the directory

This routine returns the key serial number (optionally the complete key vector) of the last object inserted into the specified directory. If the option KEY must be of sufficient size as to receive the complete vector.

Date of last directory modification

              +--------------------------------------------+
              |CALL  CDLMOD (PATH,IDATE*,ITIME*,CHOPT,IRC*) |
              +--------------------------------------------+

PATH

Character variable specifying the path name of interest

IDATE

Date of last modification in YYMMDD format

ITIME

Time of last modification in HHMM format

IRC

Integer return code

0: Normal completion
131: Invalid path name

This routine returns the date and time of the last modification of the specified directory.

Pack and unpack date and time

Two sets of routines are provided: CDPKTM and CDUPTM, for storing times with 1 minute precision, and CDPKTS and CDUPTS which provide 1 second precision. In the case of the latter two routines, only times relating to 1980 and after may be stored.

                 +--------------------------------------+
                 |CALL  CDPKTM (IDATE,ITIME,IPACK*,IRC*) |
                 +--------------------------------------+

                 +--------------------------------------+
                 |CALL  CDPKTS (IDATE,ITIME,IPACK*,IRC*) |
                 +--------------------------------------+

IDATE

Integer variable with date in YYMMDD format

ITIME

Integer variable with time in HHMM format for CDPKTM and in HHMMSS format for CDPKTS.

IPACK*

Integer variable to store the date and time in packed format.

IRC

Integer return code

0: Normal completion
93: Illegal date or time

                +----------------------------------------+
                | CALL  CDUPTM (IDATE*,ITIME*,IPACK,IRC*) |
                +----------------------------------------+

                +----------------------------------------+
                | CALL  CDUPTS (IDATE*,ITIME*,IPACK,IRC*) |
                +----------------------------------------+

IDATE*

Integer variable to store the date in YYMMDD format.

ITIME*

Integer variable with time in HHMM format for CDUPTM and in HHMMSS format for CDUPTS.

IPACK

Integer variable with date and time in packed format.

IRC

Integer return code

0: Normal completion
93: Illegal packed time

These routines allow a date and time to be stored in, and retrieved from a 4 byte integer word. IPACK must be the result of a previous call to DATIME, entry Z007, can be used to obtain IDATE and ITIME in the correct format. The time can be obtained in the HHMMSS format required by CDPKTS as shown in the following example.

          Example of obtaining the time in HHMMSS format

*
*     Subroutine DATIME returns the date and time in the format
*     datime(id,it) ID=YYMMDD, e.g. 930425, IT=hhmm, e.g. 1230
*     Additional information is also returned in the common SLATE,
*     e.g. IS(6) = seconds
*
      COMMON/SLATE/IS(40)
      CALL DATIME(ID,IT)
      IT = IT*100 + IS(6)