Description of user callable RZ routines

Description of user callable RZ routines

CALL RZOPEN (*LUN*,CHDIR*,CHNAME,CHOPT,*LRECL*,ISTAT*)

LUN

Logical unit number associated with the RZ file. The RZOPEN routine issues a FORTRAN OPEN statement for the specified logical unit, unless option C is specified. Option C selects C I/O using the KERNLIB CFIO routines. If this option is selected, LUN returns the file pointer from the C library I/O routines.

CHDIR

Character variable in which the top directory name is returned (option W). The name has the form ``LUNn'', e.g. ``LUN1'' or ``LUN99'', if FORTRAN I/O is used, or ``LUN1003'' or ``LUN11021'' in the case of C I/O.

CHNAME

Character variable specifying the name of the file to be opened.

CHOPT

Character variable specifying the options required.

' '

default, open file in readonly mode

'L'

create file with relative organization (VAX only)

'N'

open a new file

'S'

open file in shared readonly mode

'U'

open file in update mode

'SU'

open file in shared update mode

'1'

open file read/write assume single user

'W'

return in CHDIR directory name include

'Y'

suppress LRECL consistency check

'C'

Use C I/O instead of FORTRAN I/O

'X'

Exchange mode file

'P'

Preserve case of file name (Unix systems)

LRECL

Integer variable specifying the record length of the file in machine words. If a value of zero (0) is specified, the RZOPEN routine will attempt to obtain the correct record length from the file itself. A value of zero must not be specified for new files.

ISTAT

Integer variable in which the status code is returned.

RZOPEN status information returned in IQUEST

IQUEST(10

Record length (machine words, 32-bit words for exchange mode).

IQUEST(11

C-file pointer (from CFOPEN).

IQUEST(12

Exchange mode flag (set if X is specified or is an existing file is in exchange mode).

Operating system dependent features

On Unix systems, filenames are translated to lowercase unless the P option is specified. Lowercase filenames are recommended to avoid problems with mixed or uppercase filenames which might occur, for example with NFS servers.

When accessing RZ files over DECnet, care should be taken to ensure that the RMS network block count is sufficient to process the remote file. The block count is specified in 512 byte blocks.

Accessing a file with record length 4096 words over DECnet

$ SET RMS/NETWORK_BLOCK_COUNT=32

On MVS systems, the prefix for the current userid will be automatically prepended to the filename unless the filename begins with a dot (``.''). For instance, assuming R01jds is the current userid prefix, RZOPEN opens file R01JDS.RZTEST.DATA for both of the following file specifications:

CHFILE = 'RZTEST.DATA'
      CHFILE = '.R01JDS.RZTEST.DATA'

AFS and NFS specific considerations

C input/output is particularly interesting when accessing Unix files from a VAX/VMS system via NFS. Such files cannot be read by FORTRAN, but can be processed successfully using C. If the file resides on a Unix system, such as an Apollo, Sun etc. the option 'X' should also be specified to indicate that the file is in exchange format by default. Files created on Cray Unicos systems are not, by default, in exchange format.

Create a new RZ file

CALL RZMAKE (LUN,CHDIR,NWKEY,CHFORM,CHTAG,NREC,CHOPT)

LUN

Logical unit number associated with the RZ file. A FORTRAN OPEN statement or call to the routine RZOPEN must precede the call to RZMAKE.
Starting address of the memory area which will contain the RZ information ('M' option)

CHDIR

Character variable specifying the name of the top directory to be associated with unit LUN (up to 16 characters).

NWKEY

Number of words associated to a key (maximum 100)

CHFORM

Character variable describing each element of the key vector

'B'

Bit string but not zero

'H'

Hollerith (4 characters)

'A'

Same as 'H' except for RZLDIR

'I'

Integer (nonzero)

CHTAG

Character array defined as CHARACTER*8 CHTAG(NWKEY).
Each element of the array allows the description of the corresponding element in the key vector with a tag of up to 8 characters.

NREC

Number of physical records for the primary allocation

CHOPT

Character variable specifying the selected options.

medium

' '

Disk (default)

'M'

Memory - The user must allocate at least NREC*LUN words of memory starting at address LUN if this option is used (see below).

mode

' '

Native mode (default)

'X'

Exchange mode (32 bit machines only)

other

'F'

Format NREC records, unless option 'M'.

'C'

Use C I/O

The following example opens and creates a new RZ file, whose top directory contains three words per key, the first one being an integer (the year) and the two others being Hollerith (the month and the day). A total of 5000 records of length 4096 bytes are requested.

Example of using the routine RZMAKE

CHARACTER*16 CHDIR
      CHARACTER    CHTAG(3)*8
      DATA CHTAG/'Year','Month','Day'/
      LRECL = 1024
      CALL RZOPEN(LUN,CHDIR,'RZTEST.DAT','N',LRECL,ISTAT)
      IF(ISTAT.NE.0) GOTO 999
      CALL RZMAKE(LUN,'Top_Dir',3,'IHH',CHTAG,5000,' ')
 
  999 PRINT *,'Return code from RZOPEN = ',ISTAT

Option 'F' is particularly important for RZ files on VM/CMS systems, when shared access is required. Further details are given in Appendix A.

N.B. when using option C, the call to RZMAKE must immediately follow a call to RZOPEN. This permits the record length of the file to be passed from RZOPEN to RZMAKE, where it is stored in an RZ control bank for future use.

Option 'M' creates an RZ file in memory. The variable LUN contains the record length. The address of this variable is used as the starting address for the memory file, as shown in the following example. Example of creating a memory file

COMMON/MEMRZ/IBUFF(163840)
*
*     Set record length of memory file to 1024 words
*     Starting address is LOCF(IBUF(1))
*     Number of 'records' is 160 (length of IBUFF/lrecl)
*
      IBUF(1) = 1024
      CALL RZMAKE(IBUF(1),'MEMRZ',3,'IHH',CHTAG,160,'M')

Create a new RZ file

CALL RZFILE (LUN,CHDIR,CHOPT)

LUN

Logical unit number associated with the RZ file. A call to the routine RZOPEN or a FORTRAN OPEN statement must precede the call to RZFILE.

CHDIR

Character variable specifying the name of the top directory to be associated with unit LUN.

CHOPT

Character variable specifying the selected options.

medium

' '

Disk (default)

mode

' '

Read mode (default)

'S'

Shared mode

'U'

Update mode

'1'

Update mode and only one user (no LOCKs necessary)

'L'

List current LOCK identifiers

'D'

Reset "locking" word of the file (after program crash !)

'C'

Use C I/O

'X'

Exchange format file

Subroutine RZFILE accesses an existing RZ file on the specified logical unit. Should the file not yet exist, the routine RZMAKE should be used.

On return from RZFILE, IQUEST(1) will be set to 0 if the routine was successful. A non-zero value for IQUEST(1) indicates an error.

N.B. when using option C, the call to RZFILE must immediately follow a call to RZOPEN. This permits the record length of the file to be passed from RZOPEN to RZFILE, where it is stored in an RZ control bank for future use.

CALL RZHOOK (LUN,CHDIR,TARGET,LRECL,CHOPT)

LUN

Logical unit number associated with the RZ file. The RZ file must already be open before calling RZHOOK

CHDIR

Character variable specifying the name of the top directory to be associated with unit LUN.

TARGET

Integer variable containing the address of the user routine that is to be called to perform the I/O. This routine must be declared EXTERNAL in the routine that calls RZHOOK.

LRECL

Integer variable containing the record length of the RZFILE in words.

CHOPT

Character variable specifying the selected options, as for RZFILE.

The specifications for the user I/O routine are the same as for FZHOOK.

An example of a user coded I/O routine

SUBROUTINE FMXZIO(IBUF,IOWAY)
      DIMENSION IBUF(8192)
+CDE,ZMACH.
+CDE,QUEST.
+CDE,FATBUG.
      CHARACTER*6  CHWAY

      IRC  = 0
      IF(IDEBFA.GE.3) PRINT *,'FMXZIO. IQUEST(1-6) = ',
     +   (IQUEST(J),J=1,6)
      LUN  = IQUEST(1)
      NREC = IQUEST(4)
      IF(IOWAY.EQ.0) THEN
         CALL XZREAD(LUN,IBUF,NREC,IQUEST(2)*IQCHAW,NGOT,' ',IRC)
      ELSEIF(IOWAY.EQ.1) THEN
         CALL XZRITE(LUN,IBUF,NREC,IQUEST(2)*IQCHAW,' ',IRC)
      ELSE
         WRITE(CHWAY,'(I6)') IOWAY
         CALL ZFATAM('Invalid value for IOWAY in FMXZIO - '//CHWAY)
      ENDIF

      IQUEST(1) = IRC

      END

Create a new RZ file

CALL RZLOGL (LUN,LOGLEV)

LUN

Logical unit number for which the logging level has to be set

LOGLEV

Logging level

-3

Suppress all messages

-2

Error messages only

-1

Terse logging

0

Normal logging: RZFILE, RZMAKE, RZEND, RZCLOS

1

Log to watch rare events

2

Log to monitor calls

3

Short dumps to debug user-written output routines

4

Full dumps to debug user-written output routines

Each declaration of an RZ file via RZMAKE or RZFILE associates a default logging level of 0 to the file. At any point in a program the logging level can be reset to a new value by calling RZLOGL with the appropriate parameters.

Create a new RZ file

CALL RZCLOS (CHDIR,CHOPT)

CHDIR

Character variable specifying the name of the top directory of the file to be closed.

CHOPT

Character variable specifying the options required.

' '

default, close file specified by the variable CHDIR

'A'

close all files - CHDIR not used

CALL RZEND (CHDIR)

CHDIR

Character variable specifying the name of the top directory of the file to be closed.

Create a new RZ file

CALL RZSAVE

All directories which have been modified in memory and the current output buffer are written to the output file by a call to RZSAVE. This routine is called automatically by the system when using RZCDIR, RZCLOS, RZEND or RZFREE. In an interactive environment it may save to call RZSAVE from time to time.

Create a new RZ file

Create a new RZ file

CALL RZNDIR (*CHPATH*,CHOPT)

Input parameter description:

*CHPATH*

Character variable specifying the complete pathname of the naming directory ('S' option)

CHOPT

Character variable specifying the option

' '

Set the naming directory to the path specified in CHPATH (default)

'P'

Print the naming directory

'R'

Read the naming directory pathname into CHPATH

Output parameter description:

*CHPATH*

Character variable containing the complete pathname of the naming directory ('R' option).

When one is working with many different directories, and has to refer frequently the same directory, then the latter can be defined as the naming directory, designated by the symbol '~' in pathnames. A typical example would be an application where subdirectories have to be created in user routines in which the complete pathname of the naming directory is unknown. To set the naming directory a call to RZNDIR must be made.

RZNDIR return codes

0

Normal completion

1

'S' (default) option and the pathname CHPATH is invalid

RZNDIR return codes

CALL RZCDIR (*CHPATH*,CHOPT)

Input parameter description:

*CHPATH*

Character variable specifying the pathname of the CWD (default).
CHPATH = ' ' means the CWD (useful with the 'U' option)
Unless several RZ files are open at the same time, the path name can be specified either as a path starting with the character '/', in which case an absolute pathname is intended for the given top directory. When several RZ files are open, an absolute pathname must start with a double slash '//' and the top directory. When the pathname does not start with a '/', the pathname is prefixed with the path of the CWD.

CHOPT

Character variable specifying the option

' '

Set the CWD (default)

'P'

Print the CWD

'R'

Read the CWD pathname into CHPATH

'U'

The same as the default but the time stamp in the directory in memory is checked against the one on the file and if needed the directory in memory is brought up to date. This option should be used when the user expects that directories can be changed concurrently by another user and he wants to use the latest version.

'K'

Keep the Current Directory in memory. By default, space occupied by the Current Directory may be released in case there is not enough space to accomodate the new directory.

Output parameter description:

*CHPATH*

Character variable containing the complete pathname of the CWD ('R' option)

The CWD is set to the top directory after a call to RZMAKE. The CWD can be changed, displayed or obtained by a call to RZCDIR.

All operations of RZ routines manipulating keys (i.e. RZIN, RZOUT, RZRDIR, RZKEYS, RZPURG, RZDELK, RZDELT, RZQUOT, RZPASS) refer to objects in the ``Current Working Directory'' or CWD for short.

RZCDIR return codes

IQUEST(1)

Error status

0

Normal completion

1

The pathname CHPATH is invalid (default option)

IQUEST(7)

NKEYS, number of keys in the directory

IQUEST(8)

NWKEY, number of words in a key

IQUEST(9)

Number of directories below CWD.

IQUEST(10)

NQUOTA, the record quota for the CWD tree.

Examples:

It is not necessary to specify //Top_dir in a pathname unless several RZ files are open simultaneously. If only one RZ file is declared, the following two calls are equivalent:

CALL RZCDIR('//top_dir/dira/dirb/dirc',' ')
and
      CALL RZCDIR('/dira/dirb/dirc',' ')

If the CWD was already set to /dira/dirb one can further abbreviate the calling sequence to

CALL RZCDIR('dirc',' ')

To go one level up in the directory tree one can use '

n


CALL RZCDIR('\',' ')
and
      CALL RZCDIR('/dira/dirb',' ')

To set the CWD to the Naming directory one uses:

CALL RZCDIR('~',' ')

Examples:

CALL RZMDIR (CHDIR,NWKEY,CHFORM,CHTAG)

CHDIR

Character variable with a maximum of 16 characters (for the given level), specifying the name of the directory to be created. All characters, but /, \ ,* ,~ or ? are allowed in a directory name.

NWKEY

Number of words associated to a key (maximum 100)

CHFORM

Character variable describing each element of the key vector (a blank is equivalent to 'I').

'B'

Bit string but not zero

'H'

Hollerith (4 characters)

'A'

same as 'H' (see RZLDIR)

'I'

Integer (nonzero)

CHTAG

Character array defined as CHARACTER*8 CHTAG(NWKEY).
Each element of the array allows the description of the corresponding element in the key vector with a tag of up to 8 characters.

Example 1: Creating the geometry file of a LEP experiment

To create a geometry file for the OPAL detector the data base for the experiment has as top directory called //OPAL. A directory called Geometry is created, which will contain the names of the 12 main detectors of OPAL.

CHARACTER TAGS(2)*8
      INTEGER   KEY(2)
 
      CALL RZMDIR('Geometry',1,'H','Detector')
      CALL RZCDIR('Geometry',' ')
      TAGS(1)='Volume'
      TAGS(2)='Number'
      CALL RZMDIR('CDET',2,'HI',TAGS)
      CALL RZMDIR('ECAL',2,'HI',TAGS)
      CALL RZMDIR('HCAL',2,'HI',TAGS)
      CALL RZMDIR('FDET',2,'HI',TAGS)
      CALL RZMDIR('MUON',2,'HI',TAGS)
              .......

As we now want to introduce information into the CDET directory, we put our working directory equal to the latter by a call to RZCDIR:

CALL RZCDIR('CDET',' ')

which is equivalent to

CALL RZCDIR('//OPAL/Geometry/CDET'),' ')

Example 2: Using the geometry file of a LEP experiment

Logical records can then be entered corresponding to the parameters of each of the 24 sectors of the Jet chamber of the Central detector, of the vertex detector and of the Z chambers (routine RZOUT is described below).

C--     Write the information for the 24 Jet chamber sectors
      CALL UCTOH('SECT',KEY,4,4)
      DO 10 ISECT=1,24
          KEY(2)=ISECT
          CALL RZOUT(IXSTOR,LQ(LCDET-ISECT),KEY,ICYCLE,' ')
   10 CONTINUE
C--     Write the information for the vertex chamber
      CALL UCTOH('VERT',KEY,4,4)
      KEY(2)=1
      CALL RZOUT(IXSTOR,LVERT,KEY,ICYCLE,' ')
C--     Write the information for the Z chambers
      CALL UCTOH('ZCHA',KEY,4,4)
      CALL RZOUT(IXSTOR,LZCHA,KEY,ICYCLE,' ')

Update records for the geometry of each detector can be foreseen, e.g. by creating a directory 'Updates' below 'CDET'

CALL RZMDIR('Updates',1,'I','RUN')

The Logical records in the 'Updates' directory will contain the detector's identification as well as update parameters. KEY(1) could be the RUN number from which the given corrections should be applied. The procedure to build the geometry data structure could be the following:

 -- Read the standard parameters in directory 'CDET'

 -- Set the CWD to 'Updates' and check if there are corrections to be
    applied for that run,etc.

Example 2: Using the geometry file of a LEP experiment

CALL RZKEYD (NWKEY*,CHFORM*,CHTAG*)

Output parameter description:

NWKEY*

Number of words associated to a key in the CWD

CHFORM*

Character variable describing each element of the key vector (see RZMDIR)

CHTAG*

Character array defined as CHARACTER*8 CHTAG(NWKEY).
Each element of the array describes the corresponding element in the key vector.

Example 2: Using the geometry file of a LEP experiment

CALL RZLOCK (CHLOCK)

CHLOCK

Character variable (up to 8 characters) identifying the owner of the lock (e.g. specifying the name of the user, his computer identifier,...). This parameter is used to avoid two users, who have both the write password for a directory, trying to change it at the same time. CHLOCK is also useful in the case of a system crash while a directory was locked.

Note that two or more branches of a directory can be modified concurrently by different users (each one making a call to RZLOCK), as long as for any given directory to be locked there is no higher level directory already in a locked state.

CALL RZFREE (CHLOCK)

CHLOCK

Character variable identifying the owner of the lock.

Example 2: Using the geometry file of a LEP experiment

CALL RZQUOT (NQUOTA)

Input parameter description:

NQUOTA

The maximum number of records which can be used by the CWD and its subdirectories
By default NQUOTA is equal to the minimum of the total number of records allowed for the complete file (parameter NREC in RZMAKE) and the quota of the parent directory.

Example 2: Using the geometry file of a LEP experiment

CALL RZSCAN (CHPATH,UROUT)

CHPATH

Character variable specifying the directory pathname from which the scan should start.

UROUT

Variable containing the address of the user routine to be called by RZSCAN for each directory. This variable must be declared EXTERNAL in the routine which calls RZSCAN.

EXTERNAL UROUT

      CALL RZSCAN('//CERN/DELPHI',UROUT)

      END

      SUBROUTINE UROUT(CHPATH)
      CHARACTER*(*)    CHPATH
      PRINT *,CHPATH(1:LENOCC(CHPATH))
      END

Example 2: Using the geometry file of a LEP experiment

CALL RZLDIR (CHPATH,CHOPT)

CHPATH

Character variable specifying the directory pathname.

' '

List information for the CWD (default).

'T'

List also subdirectory tree from specified directory.

'//'

List all the RZ files.

CHOPT

Character variable specifying the options

'A'

List all keys created with option 'A' by RZOUT or RZVOUT.

' '

By default such keys are not listed.

If the keys have been defined by RZMAKE or RZMDIR with format 'H', they are listed each with 4 characters. If keys have been defined with format 'A', they are listed without separators.

Example 2: Using the geometry file of a LEP experiment

CALL RZRDIR (MAXDIR,CHDIR*,NDIR*)

Input parameter description:

MAXDIR

Length of the character array CHDIR

Output parameter description:

CHDIR*

Character array which will contain the directory names attached to the CWD. If the length of the directory name is greater then the length of one element of CHDIR (as obtained by the LEN function), only as many characters as will fit in the array element are returned, and an error code will be set in IQUEST(1).

NDIR*

Actual number of subdirectories attached to the CWD
If this number is greater than MAXDIR, only the first MAXDIR directory names will be returned in CHDIR (see IQUEST(11))

RZRDIR return codes

IQUEST(1)

Error status

0

Normal completion

1

More entries present in the directory than returned in CHDIR (see NDIR and IQUEST(11)).

IQUEST(11)

Actual number of subdirectories

RZRDIR return codes

CALL RZPASS (CHPASS,CHOPT)

CHPASS

Character string specifying the password.

CHOPT

Character string specifying the options desired:

' '

Specify a password (default),

'S'

Set or change a password (to change a password a previous call to RZPASS specifying the old password must have been made).

By default, when a directory is created (RZMDIR), the write password is set equal to the one of the parent directory. If a password is set, a call to RZPASS is necessary to be able to write a new key, create a new directory or delete a key or directory. The password specified using RZPASS is checked against the one encrypted in the RZ directory referenced.

Examples:

  CALL RZPASS('password',' ')    specifies a write password

  CALL RZPASS('Newpassword,'S')  changes or sets a password

RZRDIR return codes

CALL RZOUT (IXDIV,LSUP,KEY,*ICYCLE*,CHOPT)

Input parameter description:

IXDIV

Index of the division(s)
May be zero if the D option is not selected
May be a compound index (see the description of the routine MZIXCO in the MZ reference manual). if the D option is selected

LSUP

Supporting address of the data structure (may be zero if the D option is selected)

KEY

Keyword vector of length NWKEY as specified by RZMDIR.

ICYCLE

Cycle number (A option only)

CHOPT

Character variable specifying the selected options.

data structure

' '

The data structure supported by the bank at LSUP is written out (the next link is not followed)

'D'

Complete division(s)
default: Dropped banks are squeezed out
(slower but maybe more economic than DI)

'DI'

Immediate dump of divisions with dropped banks included

'L'

Write the data structure supported by the linear structure at LSUP (the next link is followed)

'S'

Single bank at LSUP

mode

' '

Keep banks available after output (default)

'A'

Key will not be visible by RZLDIR

'N'

No links, i.e. linkless handling

'R'

Replace existing object of identical size and keys

'W'

Drop data structure or wipe division(s) after output

Output parameter description:

ICYCLE

Cycle number associated to the key entered
ICYCLE=1 if KEY was not already present in the directory, and one larger than the previous cycle associated to the key otherwise.

RZOUT return codes

IQUEST(1)

Error status

0

Normal completion

1

The directory quota is exhausted, no more space - nothing has been written

IQUEST(2)

Number of physical records written

IQUEST(3)

Record number of the first record written

IQUEST(4)

Offset of the information inside the first record

IQUEST(5)

Record number of the continuation record

IQUEST(6)

Cycle number of the data structure written

IQUEST(7)

Number of keys in the directory

IQUEST(8)

NWKEY, the number of words per key

IQUEST(9)

Number of records still available in the current subdirectory

IQUEST(11)

NWBK, number of words of bank material

RZOUT return codes

CALL RZVOUT (VECT,NOUT,KEY,*ICYCLE*,CHOPT)

Input parameter description:

VECT

Array to be output onto the RZ file
VECT should be dimensioned at least to NOUT

NOUT

number of words of array VECT to be output

KEY

Keyword vector of length NWKEY as specified by RZMDIR.

ICYCLE

Cycle number ('A' option only)

CHOPT

Character variable specifying the selected options.

format

' '

The array contains floating point data (default)

'A'

Key will not be visible by RZLDIR

'B'

The array contains bitted data

'H'

The array contains Hollerith data

'I'

The array contains integer data

'R'

Replace existing object of identical size and keys

Output parameter description:

ICYCLE

Cycle number associated to the key entered
ICYCLE=1 if KEY was not already present in the directory, and one larger than the previous cycle associated to the key otherwise.

The contents of a FORTRAN array can be written into an RZ file and associated with a key in the CWD by a call to RZVOUT. The convention for the cycle number is the same as for RZOUT.

RZOUT return codes

CALL RZIN (IXDIV,*LSUP*,JBIAS,KEY,ICYCLE,CHOPT)

Input parameter description:

IXDIV

Index of the division to receive the data structure
IXDIV = 0 means division 2 of the primary store

*LSUP*

JBIAS

JBIAS < 1: LSUP is the supporting bank and JBIAS is the link bias specifying where the data structure has to be introduced into this bank, i.e. the data structure will be connected to LQ(LSUP+JBIAS).
JBIAS = 1: LSUP is the supporting link, i.e. the data structure is connected to LSUP (top level data structure)
JBIAS = 2: Stand alone data structure, no connection.

KEY

Keyword vector of the information to be read (default)
sequential number of the key vector in the directory if 'S' option

ICYCLE

Cycle number of the key to be read
ICYCLE > 0 highest cycle number means read the highest cycle
ICYCLE = 0 means read the lowest cycle

CHOPT

Character variable specifying the options selected.

data structure

' '

Default - Same as 'D' below

'C'

Provide information about the cycle numbers associated with KEY.
The total number of cycles and the cycle number identifiers of the 19 highest cycles are returned in IQUEST(50) and IQUEST(51..89) respectively.
The data struture associated with KEY will not be read in unless the option D is also specified.

'D'

Read the data structure with the (KEY,ICYCLE) pair specified.

'N'

Read the neighbouring keys (i.e. those preceding and following KEY).
The first 9 elements of the key-vectors of the previous and next key are available respectively as IQUEST(31..39) and IQUEST(41..49), see below.

'R'

Read data into existing bank at LSUP, JBIAS. Note that the bank must have the same size as the one stored in the file.

'S'

KEY(1) contains the sequential number of the key vector in the current directory (No search required).

Output parameter description:

*LSUP*

For JBIAS = 1 or 2, LSUP contains the entry address to the data structure
In any case IQUEST(11) returns the entry address

CALL RZINPA (CHPATH,IXDIV,*LSUP*,JBIAS,KEY,ICYCLE*,CHOPT)

CHPATH

Character variable specifying the name of the directory containing the objects to be retrieved.

others

Remaining arguments as for RZIN.

RZIN and RZINPA return codes

RZIN and RZINPA return the status, either normal or error completion, in the QUEST vector as follows:

Normal read status returns are:

IQUEST(1)

Operation status code

1

key/cycle pair not present in the CWD

0

normal completion

IQUEST(2)

number of physical records read

IQUEST(3)

Record number of the first record read

IQUEST(4)

Offset of the start of the information in the first record.

IQUEST(5)

Record number of the continuation record (0 if not 'A' option).

IQUEST(6)

ICYCLE: cycle number of information returned.

IQUEST(7)

Number of keys in the directory

IQUEST(8)

NWKEY, the number of words per key

IQUEST(11)

LSUP, the entry address into the data structure
zero means: empty data structure

IQUEST(12)

NWBK, the number of words occupied by the data structure in memory
zero means: empty data structure

IQUEST(14)

Time stamp of the information(compressed). In order to get the unpacked date and time (integers), one can use the RZ internal routine RZDATE as follows

CALL RZDATE(IQUEST(14),IDATE,ITIME,1)

IQUEST(20)

Key serial number in the directory

IQUEST(21..20+NWKEY)

KEY(1)...KEY(NWKEY) if 'S' option given

IQUEST(30)

NWKEY or zero if no previous key is present ('N' option)

IQUEST(31..39)

The first 9 elements of the key vector for the element preceding KEY (if IQUEST(30) > 0)
Only IQUEST(31..30+MIN(NWKEY,9)) are significant

IQUEST(40)

NWKEY or zero if no following key is present ('N' option)

IQUEST(41..49)

The first 9 elements of the key vector for the element following KEY (if IQUEST(40) > 0)
Only IQUEST(41..40+MIN(NWKEY,9)) are significant

IQUEST(50)

Number of cycles present for KEY ('C' option)

IQUEST(51..69)

The cycle number identifiers associated with KEY
If IQUEST(50)

<=

19 then only IQUEST(51..50+IQUEST(50)) are meaningful
If IQUEST(50) >19 then IQUEST(51..69) contain the 19 highest cycles for KEY

IQUEST(71..89)

The time stamp information corresponding to each of the initialized cycle numbers in IQUEST(51..69)

If the pair (KEY,ICYCLE) is not present in the CWD (IQUEST(1)=1) and the 'N' option is given, then IQUEST(30...) and IQUEST(40...) will contain, respectively, the ``lowest'' and ``highest'' key vectors present.

RZIN and RZINPA return codes

CALL RZVIN (VECT*,NDIM,NFILE*,KEY,ICYCLE,CHOPT)

Input parameter description:

NDIM

Number of words available in array VECT (e.g. declared dimension)

KEY

Keyword vector of the information to be read

ICYCLE

Cycle number of the key to be read
ICYCLE > 0 highest cycle number means read the highest cycle
ICYCLE = 0 means read the lowest cycle

CHOPT

Character variable specifying the options selected(see RZIN).

Output parameter description:

VECT*

FORTRAN array to contain the information input
The array VECT should be at least dimensioned to NDIM words

NFILE*

Actual length of the array on the file

RZVIN return codes

RZVIN returns the read status, either normal or error completion, in QUEST in a way similar to RZIN.

RZVIN return codes

RZVIN return codes

CALL RZPURG (NKEEP)

NKEEP

Number of cycles which must be kept for the given key
If NKEEP < 1 then NKEEP is taken to be 1 and only the highest cycle is kept

RZPURG return codes

IQUEST(9)

Number of records still available in the current subdirectory

IQUEST(11)

Maximum number of cycles purged

IQUEST(12)

Number of words freed

IQUEST(13)

Number of records freed

RZPURG return codes

CALL RZDELT (CHDIR)

CHDIR

Character variable specifying the directory name of the subtree of the CWD.

RZDELT return codes

IQUEST(1)

Error status

0

Normal completion

1

Invalid directory subtree name

RZDELT return codes

CALL RZDELK (KEY,ICYCLE,CHOPT)

KEY

Key array of dimension NWKEY (see RZMDIR)

ICYCLE

Cycle number of the key to be deleted

>0

highest cycle number means delete the highest cycle

=0

means delete the lowest cycle

=-1,-2,...

means delete the highest cycle -1, -2,...

CHOPT

Character variable specifying the options selected.

' '

Delete the explicitly specified cycle ICYCLE only (default).
If cycle ICYCLE does not exist, no action is taken.

'C'

Delete all cycles corresponding to key (ICYCLE not used)

'K'

Delete all keys in the CWD (ICYCLE and KEY not used)

'S'

Delete all cycles smaller than cycle ICYCLE for the given key-vector

RZDELK return codes

IQUEST(1)

Operation status code

1

No entry for key/cycle pair specified

0

normal completion

IQUEST(11)

Maximum number of cycles deleted

IQUEST(12)

Number of words freed

IQUEST(13)

Number of records freed

  CALL RZDELK(KEY,2,' ')  deletes the in-
                          formation associated with key KEY and
                          cycle number 2 in the CWD.


  CALL RZDELK(KEY,4,'S')  deletes all information associated
                          with key KEY and a cycle number
                          smaller than 4 in the CWD.

  CALL RZDELK(0,0,'K')    deletes all cycles of all keys in the
                          CWD.

RZDELK return codes

CALL RZRENK (KEYOLD,KEYNEW)

KEYOLD

Key array of dimension NWKEY containing the old key vector

KEYNEW

Key array of dimension NWKEY containing the new key vector

Return codes

IQUEST(1)

Operation status code

1

No entry for KEYOLD in the CWD

0

normal completion

Return codes

CALL RZKEYS (MAXDIM,MAXKEY,KEYS*,NKEYS*)

Input parameter description:

MAXDIM

The actual first dimension of output array KEYS. It should in principle be at least equal to the number of key elements NWKEY as declared to RZMDIR.

MAXKEY

The actual second dimension of output array KEYS.

Output parameter description:

KEYS*

A 2-dimensional array dimensioned KEYS(MAXDIM,MAXKEY). It will contain the key vectors associated with the CWD. Its first index runs over the key elements for a given key, while its second index runs over the different keys.

NKEYS*

Number of keys returned in array KEYS.

Return codes

IQUEST(1)

Error status

0

Normal completion

1

The keys have a length NWKEY > MAXKEY or more entries present in the directory than returned in KEYS (see IQUEST(11)).

IQUEST(11)

Actual number of keys in the CWD.

IQUEST(12)

NWKEY, number of words characterizing a key vector element for the CWD (as defined on Page for RZMDIR).

Examples

For the lead glass blocks file in the example in section 1, we could write:

INTEGER KEYS(5000)
 
      CALL RZKEYS(1,5000,KEYS,NKEYS)

INTEGER KEYS(2,500)                      ! Up to 500 keys vectors
 
      CALL RZKEYS(2,500,KEYS,NKEYS)

Examples

CALL RZCOPY (CHPATH,KEYIN,ICYCIN,KEYOUT,CHOPT)

CHPATH

The pathname of the directory tree which has to be copied to the CWD

KEYIN

Key-vector of the object to be copied from CHPATH.

ICYCIN

Cycle number of the key to be copied

KEYOUT

Key array of the object in the CWD after the copy

CHOPT

Character variable specifying the options selected.

' '

Copy the object from (KEYIN,ICYCIN) from CHPATH to the CWD (default).
If KEYOUT already exists, a new cycle is created.

'C'

Copy all cycles for the specified key (ICYCIN not used)

'K'

Copy all keys in the CWD (ICYCIN and KEYIN not used) Given together with the 'C' option it copies all cycles of all keys.

'T'

Not yet implemented. Copy the complete tree CHPATH. By default only the highest cycles are copied. Given together with the 'C option all cycles are copied.

A directory tree identified by its pathname CHPATH can be copied to the CWD with the help of subroutine RZCOPY. Routine RZCOPY can also be used to merge two RZ files.

Return codes

IQUEST(1)

Error status

1

Invalid pathname

0

Normal completion

Return codes

CALL RZTOFZ (LUNFZ,CHOPT)

LUNFZ

Logical unit number of the FZ sequential access file

CHOPT

Character variable specifying the options selected.

' '

Write the highest cycle of the keys in the CWD to the FZ file (default).

'C'

Write all cycles of the keys in the CWD to the FZ file

CALL RZFRFZ (LUNFZ,CHOPT)

LUNFZ

Logical unit number of the FZ sequential access file

CHOPT

Character variable specifying the options selected.

' '

Read all cycles of the keys present on the FZ file into the CWD (default).

'H'

Read the highest cycle of the keys present on the FZ file into the CWD.

Return codes

CALL RZSTAT (CHPATH,NLEVELS,CHOPT)

CHPATH

The pathname of the directory about which information has to be provided.

NLEVELS

Number of levels below CHPATH about which space information has to be accumulated.

CHOPT

Character variable specifying the options desired

' '

Print the statistics (default)

'Q'

Return the statistics in the user communication vector IQUEST

If option 'Q' is specified, the IQUEST vector contains on return:

IQUEST(11)

number of records used

IQUEST(12)

number of words used

Overview of RZ calling Sequences

References

Global CERN library references

/user/goossens/cnasall/cnasbibl,/user/goossens/cnasall/textproc}