Operations on RZ directories

Define the naming directory

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

Define the current working directory

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 '$$ ', e.g. if the CWD is /dira/dirb/dirc then the two following calls are equivalent:

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

To set the CWD to the Naming directory one uses:

      CALL RZCDIR('~',' ')

Creation of a directory

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.

A directory below the current ``working directory'' (see RZCDIR) can be created by a call to RZMDIR.

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.

Get the key definitions for the current working directory

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.

Information about the key definitions, as declared by RZMDIR, for the CWD can be obtained be a call to RZKEYD.

Lock and unlock a directory

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.

When an RZ random access file is declared mode 'SU' (shared/update) with RZFILE , then care must be taken to propagate the changes made to the file to other processes, which are accessing the file concurrently. Therefore, whenever the directory structure or the data part of the CWD has to be changed by calling one of the following routines: RZMDIR, RZCOPY, RZDELT, RZDELK, RZFRFZ, RZOUT, RZPURG, RZQUOT, RZRENK,

then, before using the first time any of these routines, the CWD must be locked by a calling routine RZLOCK. To use this routine the write password must have been specified if one has been defined. Once a directory is locked, all subdirectories become unavailable for locking. Hence when the top directory is locked, the complete file is 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.

Once all modifications to a directory are performed, it must be unlocked by a call to RZFREE. This routine outputs the updated directories and provides them with a time stamp, so that other users can determine whether they want to update the copy of the directories they are working with.

Set the space quota for the current working directory

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.

Routine RZQUOT allows the user to define a space quota for the CWD and all its subdirectories.

Scan RZ directory structure

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.

Subroutine RZSCAN scans a directory structure from the specified starting directory. For each subdirectory found, the user provided routine UROUT is called as shown below.

Example of using the routine RZSCAN

      EXTERNAL UROUT

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

      END

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

List the contents of a directory

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.

The keys and the subdirectory names belonging to a given pathname can be listed by a call to RZLDIR.

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.

Retrieve the contents of a directory

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))

The list of NDIR directories attached to the CWD is retrieved and stored into the character array CHDIR.

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

Set the password of the current working directory

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).

Each directory of an RZ file can have its own write password. When an RZ file is first initialized with RZMAKE there is no write password set. Routine RZPASS can be used to specify or change the password of the CWD.

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('New,'S')	changes or sets a password