For DBL3 Version 310       (inserted March 1992.  S. Abachi)

 
Pam history in inverse chronological order:
-------------------------------------------
 
Version 3.10  (December 1991)
------------
 
   Introduction of parameter statements for key names. New entry
point DBDONT added specifically for use of lumlist stored on DB.
 
Version 3.09  (November 1991)
------------
 
   Correction of character tables for new machines. Possibility of
enforced updating (no check on Key 1 value) on selective directories
supplied through routine DBILDF.
 
Version 3.08  (April 1991)
------------
 
   Extended functionality in DBUSE/DBFREE for character option M.
Bugs fixed in DBFREE. Patch name ACCESORY has been renamed to DBEXTRA.
Possibility of updating on selective directories supplied through
routine DBILDU. Improvement of handlings of data access in P3 mode.
 
Version 3.07  (July 1990)
------------
 
   Bug fixes and cleanup of code.
 
Version 3.06  (June 1990)
------------
 
   Implementation of the code in a parallel processing environment.
The  modifications needed to run DBL3 in a Host/Attached Processors
environment are of 2 types : (1) trivial: replacing WRITE with DBPRNT
(and internal write with UTWRIT for emulators); (2) substantial: storing
objects into the database RZ file is done by the host at request from
the child Requests from  the child tasks are centralized  through a
common routine DBCHLD, which is responsible for the dialogue with the
host. Its partner routine in the host library (server) is named DBHOST.
Data retrieval  (DBUSE,...) does  not need any  special code, since the
AP version of RZ already handles correctly RZIN calls. It also runs on
CRAY (new Patchy flag CRAY). New example DBEXAMB added, an example to
convert ASCII file to a database object (used in converting L3 field
map).
 
Version 3.05  (March 1990)
------------
 
   Facilities to retrieve data on the basis of serial number (DBGETS);
to extract certain part of the data base in the form of a journal file
(DBRTFZ); to delete all but the specified directory trees in the data
base (DBKEPT); to increment packed date/time by a given amount (DBINCT).
Provision for server mode option on Apollo. Bug correction in DBSEKY
(data retrieval through DBUSE) and added functionality in DBFZUP.
 
Version 3.04  (September 1989)
------------
 
   Facilities to store and retrieve help information for a given
directory (DBEHLP, DBRHLP); to give alias name for directory (DBEALI,
DBRALI); to store and use tags for data elements for a directory
(DBENAM, DBRNAM, DBGNAM). Facility to fetch a set of data base objects
within a time slice (DBGET). Calling sequence of the routine DBENFZ
(used internally by DBL3) has been changed. Facilities of transforming a
non-partitioned directory to a partitioned one is introduced (DBNTOP);
of deleting all but the last few partitions in a partitioned directory
(DBPRGD). Calling sequence of DBDELT is changed. New routine DBRKY1 to
return the serial numbers of all the objects stored. Now the S option
in DBINIT isv taken care inside the code by locking and freeing all
appropriate directories for the write operations. User should remove
all LOCK and FREE calls in their code (for such operations).
 
Version 3.03  (July 1989)
------------
 
   Introduction of Parameters in bit settings and introduction of
statement functions for bit/byte handlings. Backward incompatible
changes in the structure of the journal file and calling sequences of
DBFZOP, DBFZUP. Extension of the plotting and interactive facilities.
Introduction of the facility of deleting a directory (DBDELT). New
code for Servers on VAX and on IBM. Capability of introducing ASCII
files to data base and retrieving them (DBABRD, DBABWR). Routines
DBINIT and DBEFOR have backward incompatible codes. DBINIT for making
a new data base should have character option 'Z' along with NREC>0.
New routine DBRENK to rename keys (useful in the context of server).
 
Version 3.02  (February 1989)
------------
 
   Optional creation of journal files while creating or updating data
base (through routine DBFZOP). Updating of databases from the journal
file through a new routine DBFZUP. Creation and use of Dictionary
information (no change in the user code is required). Facilities to
plot validity time of data objects, variation of some data elements with
any key element, correlation of data elements (routine DBPLTI, DBPLOB,
DBPLOV). Modified interactive menu and use of plotting facilities
interactively. Global selection on insertion time (DBEFOR), utilities
to find the last inserted objects (DBLAST, DBLKEY), date of last change
in data base (DBLMOD), creation of DBTB bank with information of data
objects used (DBTBCR). All examples revisited in light of testing all
the modifications.
 
Version 3.01  (September 1988)
------------
 
   New routines DBENTB and DBPURK for storing and deleting objects. New
option 'S' in DBPURG. Some old bugs fixed. New example Patches DBEXAM9
and DBEXAMA. New routine DBCRSD to create standard L3 directory(ies).
 
Version 3.00  (April 1988)
------------
 
   The use of DBL3 is now independent of the ZEBRA store. Also a
facility is added (test on IQUEST(2)) in DBUSE for permitting the
user to be informed if data has been refreshed in the current pass.
 
Version 2.10  (February 1988)
------------
 
    Bugs have been fixed in routines DBUSE, DBKEYS, DBKXIN and DBKOUT.
 
    A new concept of partitioned database is introduced in view of the
directories accumulating a large number of data objects. A directory
could be defined to be of partitioned nature at the time of creation
only, by using the routine DBMDIP instead of DBMDIR or through the
character option 'P' in routines DBENTR or DBOUT or DBVOUT.
 
    An interactive version of the Data Base routines has been added in
the Patch DBXINT. These routines are based on the KUIP package (Version
1.00).
 
Version 2.00  (October 1987)
------------
 
    This version is based on a modified RZ-package (Version 3.54) which
allows the use of an increased number of keys (upto 100).
 
    A new option 'S' is added to the routine DBUSE enabling retrieval of
all objects in a directory satisfying prescribed conditions on a limited
number of key-elements. This new feature allows to use DBL3 as a
relational Data Base management system.
 
    This version provides two new routines DBENTR and DBREPL which can
enter data on to the disk and to the memory (like DBUSE in Node/Key
structure) at the same time. The routine DBREPL replaces a set of old
user keys by a new set where the keys are used to form a table (as in
relational data base).
 
    The routines DBKVIN and DBKXIN are no longer supported as user entry
points. They are now internal to DB package. The arguments of these
routines and also of DBKIN have been changed from previous versions.
 
Version 1.10  (April 1987)
------------
 
    This version provides two new routines DBUSE and DBFREE for
retrieving data and for freeing (not dropping) a data object not
used at this moment. This permits the user to optimise between the
frequency of data retrieval and the available space in memory.
 
Version 1.00  (February 1987)
------------
 
   This is the first version installed on APOLLO and on VM using
the ZEBRA Version 3.53 allowing for 9 keys in RZ.
 
Version 0.99  (9 December 1986)
------------
 
   This version is based on an early version of ZEBRA (Version 3.41)
allowing only 5 keys in an RZ directory. This version is installed
also on VM and used for BGO calibration. Y. Karyotakis has written
a version of it on VM allowing an interactive query on the database.
 

 - DOC 
 
      The basic concepts for the L3 database were defined by Francis Bruyant,
      Richard Mount and other members of the collaboration; in particular,
      Y.Karyotakis from the BGO Group, B.Adeva, E.Gonzales from the Muon
      Chamber Group, M.Fukushima, T.Hebecker, R.Dolin from the Trigger Group
      were involved in defining the specific requirements for various
      applications. The software presented here has mainly been written by
      S.Banerjee and E.Nagy. The work of L.Barone and N.Colino in the
      implementation of the server and the work of Z.L.Ren and A.Syed in
      developing the plotting facilities have been greatly appreciated.
      
 
        
        General documentation
        ---------------------
        
 
        A Software Utility Package for the L3 Data Bases :
        ------------------------------------------------
        
                     S.Banerjee, F.Bruyant, R.Mount, E.Nagy
                      
    1 . Introduction.
                      
      High Energy Physics experiments, nowadays, require the use of powerful
      data base systems. The data consist usually of a part which is largely
      time independent, for instance the parameters which describe the
      experimental setup, and of another part whose contents may vary with
      time, with different frequencies, and have therefore to be recorded
      repeatedly, with proper time validity ranges.
      
      The latter may represent quite a large amount of data. As an example,
      for the L3 Detector, one expects to have to store several gigabytes of
      data per year of operation.
      
      At program execution time, fast access to the data base contents is
      essential, and an efficient system which limits the rate of transactions
      between the directly addressable storage medium, where the data base
      resides, and the computer memory available to the user, has to be
      implemented.
      
      In a multi-user, multi-computer environment, keeping up to date a
      centralized data base and optimizing the data flow is not a trivial
      matter. This can only be achieved through dedicated 'service' machines
      under control of a data base 'server'.
      
      Last, but not least, the system has to be robust and safe, and
      equipped with facilities which minimize the inconveniences of a
      possible program crash or of a computer hang-up.
      
      The Software utility package DBL3, presented here, is an attempt to
      solve the above requirements. It has greatly benefitted from feasibility
      studies made by dedicated working groups within the L3 collaboration[1].
      
      The data base server, successfully put in operation for the LEP Pilot
      run, will be described elsewhere [2]. In short, the data bases are
      owned by a server program which is active all the time; any user who
      wants to update a data base, by addition or deletion of data, has to
      communicate a request to the server, which takes the appropriate action,
      avoiding clashes between different processes possibly trying to write on
      the same data base file. The communication between the server and the
      user program is taken care of by the DBL3 package.
      
      DBL3 is based on the ZEBRA system [3] and relies heavily on one of its
      constituents, the Random Access I/O package RZ, and also on the well
      known MZ (memory management), DZ (debug and dump) and FZ (sequential
      I/O files) packages, with which the user is assumed to have some
      familiarity.
      
      Section 2 gives an overview of RZ. Section 3 reviews the main concepts
      and the basic functionality of DBL3. Section 4 gives more information on
      the user interface, and Section 5 describes, for completness, other
      facilities available in the package.
      
      The present report refers to the version 3.04 of the package. The code
      is available from CERN, on request to the authors, as an exportable CETA
      Pam file. More details of the user callable routines can be found in the
      inline documentation at the beginning of each routine. Simple examples
      of application programs are also given inside the Pam file.
      
      
      2. An overview of the RZ package.
      
      The choice of RZ was natural, as all L3 Software components make use
      of Zebra. RZ seemed to have all basic features which one thought to be
      needed for the L3 data base system, including transportability from
      computer to computer. Furthermore, RZ was free of charge and frequent
      contacts with its authors, residing at CERN, could give us the
      opportunity to suggest adequate developments and to benefit from a fast
      feedback.
      
      Once a random access file has been opened, RZ permits the creation of
      a tree of directories, each one addressable through its pathname, and
      the storage and retrieval of data at any level of the tree. Pathnames
      are built-up by concatenating the names of the directory nodes along the
      given paths through the tree, following the conventions of the UNIX
      hierarchical file structure. Several files can be opened and handled by
      RZ at the same time; the top level directory names being not recorded in
      the files, they can be assigned by the user at initialization time, thus
      permitting concurrent access to directories with identical internal
      pathnames from different files.
      
      Several 'data objects' can be associated to any node; they are
      addressed by the pathname of the corresponding directory and by a vector
      of keys, which make possible their identification. The keys are stored
      by the system in a way which permits a fast retrieval of the data
      objects.
      
      The dimension of the key vector and the definition of the keys (names
      and types), are user defined, at the time of creating a directory.
      Therefore, before storing any data, the user has, if not yet done, to
      create a directory and, at the same time, to give the specifications of
      the key vector, which become an intrinsic property of the directory.
      Once this is done, the user is no longer free to change either the
      sequence of node names along the path to the directory or the number
      of keys and their definition. Note that the keys can only be of type
      integer, hollerith or bit string.
      
      The data objects are Zebra data structures, or single banks in the
      simplest case. Successive versions of the same data objects can coexist
      with different cycle numbers, but, as explained in the following
      section, this facility is not used by DBL3. Empty data objects are
      accepted, the key values playing the role of the data to be stored;
      then, the key vectors can be used as relational tables, and for the
      purpose, their maximum dimension permitted by RZ has been enlarged to
      100. It should be noted, however, that the usage of directories with
      both a large number of keys and a large number of data objects is not
      recommended in RZ, as it degrades the timing performance of the system
      (steps have been taken in DBL3 to cure this weakness).
      
      
      3. DBL3 concepts and basic functionality.
      
      Built upon RZ, the DBL3 package provides facilities and utilities
      which have been developed in the context of L3, but can nevertheless be
      considered of general interest. It increases the functionality of RZ
      where it was thought to be useful, in particular for a better control of
      the time validity of the data objects (L3 standard keys), for a more
      economical storage on the random access devices (data compression) and
      for an improvement of the overall performance (optimization of disk-
      memory transfers, partitioned directories).
      
      3.1 Data base representation in memory.
      
      The DBL3 package uses as Zebra dynamic store a labelled common block.
      This can be any of the stores used by the application program. DBL3
      operates inside two divisions in that store ; a DBL3 system division, of
      no concern for the user, and the division where, at user's request, the
      data objects are dumped from the random access medium and kept in memory
      as long as required by the user.
      
      In the latter division, data objects from a given data base file are
      stored as Zebra banks, or Zebra data structures, within a main data
      structure which reproduces, partially and only for the directories in
      use, the Node/Key structure of the data base files. As many main
      structures can be simultaneously handled in memory as there are data
      base files declared by the user; however, they are expected to all share
      the same division. The skeleton of NODE and KEY banks grows up,
      following the successive user requests, and stays permanently available
      in memory. The data banks, appended to the corresponding KEY
      banks, can be either refreshed when the time dependence of their
      contents requires it, or dropped when they are no longer needed by the
      user. They can also be marked as temporarily unwanted, so that the
      system can drop them in case of shortage of memory, at the cost of
      reaccessing them from the random access device if and when required
      again.
      
      3.2 L3 standard keys and user keys.
      
      In order to minimize the disk-memory transfers and to permit a tight
      control of the whole system, a few general standard keys have been
      defined. The DBL3 package assumes that all key vectors consist of at
      least 7 keys. The keys 1, 2 and 6 are totally internal to the system.
      The keys 3 and 4 carry the user assigned range of validity for the data
      objects (upto seconds). Key 5, set by the user, is the 'source
      identifier' reserved to identify, one way or another, the program which
      creates the corresponding data object. Key 7 is filled in by the system
      and carries the insertion time of the data object in the data base (upto
      minutes). Access to keys 3, 4 and 7 permits control of time dependence
      in a more flexible way than the RZ cycle numbers, which is why the
      latter are never used by the DBL3 package.
      
      Additional keys, the so-called user keys, can be declared by the user
      (within the overall limit of 100 keys). Their role will become more
      transparent when reviewing the functionality of the storage and
      retrieval of data objects, in Sections 4.3 and 4.4.
      
      3.3 Data compression.
      
      By default, whenever possible, that is when all elements of a data
      object are of the same type (integer or real), DBL3 proceeds
      automatically to packing, with the default storage precision or the one
      specified by the user. The default algorithm for packing searches for
      the optimum bit-length the majority of the data can be packed with, the
      rest being represented by two data words, the value and the location in
      the data array, so as to minimize the total number of words. Another
      packing algorithm, activated at user's request, stores only the data
      elements whose absolute values are greater than a predefined number.
      Packing and unpacking are automatic and not seen by the user, who always
      deals with unpacked data in memory. Furthermore, the user is in any case
      given the possibility to inhibit the packing.
      
      In order to store data as compactly as possible, a default updating
      procedure is built in the program. Provided the user has not explicitly
      turned off this process, the DBL3 software looks for a neighbouring
      object such that the difference with the object to be inserted can be
      described and packed in the least number of words. Like packing,
      updating is completely automatic and not seen by the user.
      
      3.4 Real time optimization.
      
      The RZ package is not optimized for handling directories with too many
      data objects; the memory resident part of the data describing the keys
      becomes very large and storage and retrieval become more expensive, both
      in CPU time and real time, when the number of data objects exceeds a few
      thousands. The concept of partitioned directory has been introduced to
      attenuate these effects. Subdirectories are automatically created when
      needed, with keys which permit to keep track of their contents and to
      quickly access the right partition. Partitioning is invisible to the
      user, who just has to give its characteristics when creating the
      directory. Subsequent storage and retrieval of data objects in a
      partitioned directory follow the same rules as for a normal directory,
      as far as the calling sequences of the user interface subroutines are
      concerned. It should be noted however that direct calls to RZ routines
      for handling such directories would be extremely hazardous and should
      be avoided.
      
      To further optimize real time usage in storing data, DBL3 also
      provides a facility to store several objects, belonging to the same
      directory, in one pass. In real time, the gain is about proportional to
      the number of objects one stores at once.
      
      3.5 Dictionary.
      
      The DBL3 package supports a dictionary in a special directory called
      DICTIONARY. In the dictionary the user can enter, for any of the
      directories, simple alias names for the pathnames as well as mnemonics
      for the data object elements (both limited to 8 characters). The
      DICTIONARY directory, which does not make use of the standard L3 keys,
      is automatically generated, at the top level, when the data base is
      created. To start with, it has only one data object, with key 1 set to
      -1. The data object contains the number of directories in the data base,
      followed by 25 words for each directory, 3 integers and 22 hollerith.
      The integers contain the unique numeric identifier assigned to the
      directory, the number of characters in the pathname and the date of the
      last modification. The 2 first hollerith are reserved to store an alias
      name for the pathname (up to 8 characters) and the rest to store the
      pathname itself (top directory name excluded).
      
      3.6 ASCII data objects and HELP directory.
      
      A facility has been introduced which permits to store in a data base
      the contents of ASCII files with a record length less or equal to 80
      characters. Several applications in the L3 software make use of
      it. One of them is, in the context of the Production Control, for
      storing in the Job Log data base a summary of the job performance.
      Another is related to the storage of help information in a special HELP
      directory generated at the top level when a data base file is created.
      HELP directories do not make use of the standard keys. One key is used
      to specify the node to which the help information is relevant.
      
      3.7 Journaling.
      
      For restoring the integrity of a data base after a crash, as well as
      for establishing communication with the data base server, a journaling
      facility has been implemented. It consists of recording on an FZ
      sequential file all kinds of updates which affect the data base, namely
      the addition or deletion of directory trees, the addition or deletion of
      data objects, the alteration of key values, the deletion of some
      partitions in a partitioned directory, the definition of aliases and
      mnemonics in the DICTIONARY directory or the insertion of items in the
      HELP directory. The information is recorded in different types of FZ
      records, consisting of at least an FZ header, with or without a data
      part, depending on the kind of action, recorded as first word in the FZ
      header. In case of several data base files, each corresponding top
      directory is associated with an RZ file number. The same FZ file can
      however serve several top directories, if the user has decided so. It is
      possible to update a database on a selective number of directories from
      a journal file.
      
      
      
      4. DBL3 User interface.
      
      In most of the DBL3 calling sequences, various character options can
      be preset by the user and transmitted as a character string, the
      argument 'CHOPT'. These will be referred to as 'options' in the
      following paragraphs.
      
      4.1 Initialization phase and use of non standard directories.
      
      The user is supposed to have initialized the ZEBRA memory management
      system through the standard MZ package routines. The data base files, on
      random access devices, have also to be opened through FORTRAN OPEN (+ a
      call to VMCMS, on IBM/VM). Then, for each data base file, a call to
      DBINIT initializes the DBL3/RZ control for the corresponding file. When
      using several data base files, the user should be careful always to give
      the complete pathnames for all subsequent references to the directories.
      
      For an optimum usage of the RZ system, the user is advised to have a
      reasonably large allocation for the system division. For the time being,
      a safe way to proceed is to lift a large bank in the system division and
      to drop it prior to the first call to DBINIT.
      
      A unique numeric identifier is associated to every given top directory
      (every file). The DBL3 package defines by default an identifier
      increasing monotonically as the user makes the successive calls to
      DBINIT. The choice of the identifier can however be imposed by the user,
      by presetting IQUEST(1), a Zebra short term communication variable, to
      the desired value, before calling DBINIT. The numeric identifier
      assigned to each directory packed with that of the top directory, is
      stored in the corresponding NODE bank. This permits to record in a
      simple way which data objects have been used in a given program
      execution.
      
      To activate the journaling mode, the user should first open the FZ
      file through a FORTRAN OPEN statement followed by a call to FZFILE, then
      define the appropriate unique FZ file number associated to the given top
      directory, through a call to DBFZOP (the file number being set by
      default to 0 at initialization time through DBINIT).
      
      When running in a server mode, the only differences with the stand
      alone mode concern the OPEN statement for the RZ file (read only and
      shared instead of read/write) and the call to DBINIT, where the option
      'P' (public) has to be specified.
      
      The DICTIONARY directory, initially generated under control of DBINIT,
      is dumped into memory at every call to DBINIT. It can be expanded at
      user's request to store mnemonics (upto 8 characters) for the elements
      of the data objects. These are mainly used in DBL3 interactive
      applications. For each directory, the mnemonics are stored in a data
      object of the DICTIONARY directory, with key 1 set equal to the numeric
      identifier of the corresponding directory. The routines which can be
      used for entering or retrieving the information are DBENAM and DBRNAM
      respectively. The alias names, in the DICTIONARY directory, can be
      stored and retrieved through the routines DBEALI and DBRALI.
      
      The HELP directory, also generated automatically under control of
      DBINIT, at the time of creating the data base, is initially empty. The
      user should enter the help information as an ASCII file through the
      routine DBEHLP. The content of the file is encoded as a computer
      independent single data object with the key 1 set equal to the numeric
      identifier of the relevant directory. The help information can be
      subsequently retrieved, decoded and displayed through the routine
      DBRHLP.
      
      
      4.2 Creation of standard directories.
      
      Before storing any data, the user has to create a directory with all
      specifications of the key vector. The routine DBCRSD permits to create
      L3 standard directories, with any number of additional user keys. The
      option 'P' (partitioned) can be used to create a partitioned directory.
      Any creation of a directory is accompanied by an automatic update of the
      dictionary. In case the directories at the intermediate nodes do not
      exist yet, DBCRSD will create them and, by default, assigns to them 9
      keys, all of type integer. To rescue from a situation where a directory,
      originally expected to receive a limited number of data objects and
      hence created as a normal directory, happens to have too many objects
      to be handled efficiently, the user can call DBNTOP to transform the
      directory into a partitioned directory.
      
      4.3 Storage of data.
      
      The user can store data from memory to disk with either of the two
      routines DBENTR or DBREPL, the data in memory being simple Zebra banks
      or Zebra data structures. In the latter case, the option 'R' (full RZ
      option) has to be used. The pathname of the directory as well as the key
      vector have to be supplied when storing the data (the system keys 1, 2,
      6 and 7 do not however need to be filled in). If the directory does not
      exist yet for the data object, the above routines will create it only
      when the option 'N' (new) has been required. Note that, with the option
      N, it is only possible to create a new directory with a maximum of 9
      keys, all of integer type. If the user wants to store the data object in
      a partitioned directory the option 'P' (partitioned) has also to be
      specified, unless the directory already exists.
      
      As mentioned earlier, the relatively large maximum number of keys
      allows the user to construct data tables which can be scanned by the
      program much faster than any equivalent data residing in the data
      objects. In this context, the use of DBREPL plays an important role, to
      the extent where, unlike DBENTR, it permits to replace an old set of key
      values by a new one. Both routines DBENTR and DBREPL can also be used,
      with the option 'C' (copy), to keep at the same time a copy of the data
      base object in memory in the NODE/KEY data structure.
      
      To store several objects belonging to the same directory in one pass,
      the user can call DBENTB. The addresses of the several data structures,
      or single banks, have to be prepared in a vector of addresses passed on
      as an argument.
      
      In relation to the automatic compression of data mentioned earlier, a
      number of options is available : 'U' (unpacked) to inhibit the packing,
      'Z' (zero suppression) to store only the non-zero elements, a zero
      element being defined according to the precision word given as argument
      in IPREC, 'R' (RZ) to store with full RZ options and therefore with no
      data compression, 'S' (stand alone) to inhibit the automatic updating
      procedure and 'F' (forced update) to force the updating with respect to
      a data object previously stored with identical user key values.
      
      The contents of an ASCII file can be encoded into machine independent
      format and stored in a data base through the routine DBABWR. The
      functionality and the calling sequence of the routine are quite similar
      to those of DBENTR. However, the logical unit number from which the
      routine is expected to read the file, has to be passed as an argument.
      The user is assumed to have opened the file with a FORTRAN
      OPEN, before calling DBABWR.
      
      The update of a data base from a journal file can be done by first
      initializing the relevant file (with a FORTRAN OPEN and a call to
      FZFILE), then by simply calling the routine DBFZUP. The user can make
      a journal file from the data enetered in the data base using the routine
      DBRTFZ. This file is useful to transmit updates to the data base. One
      can select only a few directories of the data base for the update
      purpose. The user has to create a file with a list of directory names
      to be updated; open this file through a FORTRAN open and call the
      routine DBILDU to load the names.
      
      4.4 Retrieval of data
      
      The user can retrieve Zebra data structures from any directory on a
      disk file into memory through the routine DBUSE. The data objects are
      selected according to the given directory pathname and to the contents
      of the key vector, namely the validity interval (keys 3 and 4) and, when
      relevant, the prescribed values for a number of user keys (from 8 to 29,
      through the options '8' to '29'). If not yet done, the routine creates
      in memory a tree structure of NODE banks, according to the pathname
      elements. At the lowest node, DBUSE inserts the information relevant to
      the keys in KEY banks (one or several, created as a linear chain at the
      next-of-same-type link of the corresponding NODE banks) and the
      information relevant to the data itself, in DATA banks supported by the
      first link of the corresponding KEY banks. As a general rule, when DBUSE
      finds that more than one data object satisfy the validity criteria, the
      default action is to return the latest inserted one. Special actions can
      however be taken, with the options '5' and '7', through the values of
      the system keys 5 and 7, to force the retrieval of a data object with
      given source identifier or with given insertion time. Independently, the
      user can set a global selection on insertion time, through the routine
      DBEFOR, for instance to ignore modifications to the data base past a
      certain date and be able to reproduce the conditions of a previous
      program execution.
      
      DBUSE can retrieve several data objects at once, with the option 'M'
      (multiple), which permits to prescribe several values per key, for upto
      5 user keys. The key numbers (from 8 to 29) have to be specified as
      options and the required values, for each key, have to be given in an
      extension to the input key vector.
      
      DBUSE also supports, with the option 'S' (selection), the retrieval of
      all valid objects, at the given directory, satisfying user conditions on
      any of the user keys (8 to 29). As for the 'M' option, the selected
      KEY banks are linked as a linear chain of banks and the address of the
      first one is returned to the user. The options 'M' and 'S' are mutually
      exclusive.
      
      With the option 'K' (key), DBUSE also permits retrieval of the keys
      only, without loading the data objects.
      
      In case DBUSE finds that the required data objects already exist in
      memory, it does not bother to transfer them again from disk. Also, by
      default, unless the option 'V' (variable size) is specified, DBUSE
      assumes that the refreshing of the data objects in memory can be done in
      situ and overwrites the contents of the same data banks, hence avoiding
      unnecessary memory management operations.
      
      For an optimum use of the memory, and in order to minimize the disk
      accesses, the user should call the routine DBFREE, in conjunction with
      DBUSE. DBFREE sets a flag in the specified KEY bank to signal that the
      corresponding data object is no longer needed, until a subsequent call
      to DBUSE requires it again. The data object bank is not dropped
      immediately, but only if and when any other call to DBUSE need more
      space than currently available in memory. If the 'frozen' data object
      has not been dropped when it is required again, the flag is cleared and
      no further disk transfer will take place.
      
      To read data objects where ASCII information has been encoded, the
      user can call DBABRD, similar to DBUSE, except that the logical unit
      number of the file reserved to write the ASCII information has to be
      passed as an argument.
      
      4.5 Alternative for data storage and retrieval.
      
      DBL3 has a few other user entry points. Some of them have been
      conserved only for backward compatibility with previously released
      versions of the package, and should preferably not be used. Others have
      been designed with some specific use in mind and it is recommended not
      to use them without understanding fully the implications of their
      specificity and their limitations.
      
      The creation of standard directories can be achieved by calling
      directly  either DBMDIR, for normal directories, or DBMDIP, for
      partitioned directories. Both routines are internally called by the
      recommended routine DBCRSD.
      
      The routine DBOUT can be used in a stand-alone program to store data
      from a single Zebra bank. The routine DBVOUT can be used to store data
      from a FORTRAN array. For historical reasons, the definition of the key
      vector transmitted as argument is slightly different from that in the
      standard routine DBENTR; the validity period and the source identifier
      have to be supplied explicitly by the user, so only the keys 6 and
      following have to appear in the key vector. The user should not use the
      routines DBOUT or DBVOUT when the number of keys exceeds 9.
      
      The routines DBIN and DBVIN can be used to retrieve data with given
      time of validity or with given source identifier. No other selection on
      user keys is supported and the data must belong to a single Zebra bank.
      DBIN returns the bank address, whereas DBVIN fills up a user vector with
      the contents of the bank. Another routine, DBKIN, permits to fetch an
      object from disk to memory on the basis of its serial number, specified
      in key 1.
      
      The routine DBSRTM allows retrieval of a data object inserted within
      a certain time interval.
      
      The routine DBGET can be used to retrieve data for a range of start of
      validity time. This range should be passed over through the values of
      the keys 3 and 4.
      
      The routine DBGETS can be used to retrieve data with selection on a
      range of serial number (stored as Key 1). This range should be passed
      over through the values of the keys 1 and 2.
      
      4.6 Error handling.
      
      The DBL3 package uses the Zebra common block /QUEST/ IQUEST(100) for
      communication with the user in transmiting error messages. On return
      from any DBL3 routine, the user is supposed to check the value of
      IQUEST(1). If this is zero, there is NO error. Otherwise, the setting of
      a non-zero value has some specific meaning; the value can be set from
      the user callable routine or from somewhere deeper in the DBL3 package.
      An explicit message is printed out when the debug log level has been
      set to 1 or a higher value, through a call to DBLOGL (the debug level
      is set by default to 0 in DBINIT).
      
      4.7 Termination.
      
      The user should always close the data base files at the end of the
      job, through a call to DBEND. This routine closes all the RZ files
      opened during the session. A single file can be closed through the
      routine DBENDF. The user should not make reference to any DBL3 routines
      (other than DBINIT !) after the call to DBEND.
      
      
      
      5. Other DBL3 facilities.
      
      In this section a few other user callable subroutines of general
      interest are mentioned, as well as some additional facilities which
      extend the functionality of the DBL3 package and make it more user
      friendly.
      
      5.1 Print and trace-back.
      
      The user can print the contents of a directory with the routine
      DBPRIN, only the keys with the option 'K' (keys), or both the data and
      the keys with the option 'D' (data).
      
      The user can print the summary of data base usage through the routine
      DBTBPR. The summary consists of the numbers of calls to DBUSE and actual
      disk accesses, for each set of user key values.
      
      Information on the data objects used in a given program execution can
      be obtained through the routine DBTBCR.
      
      5.2 Time related routines.
      
      Two sets of routines are available to pack/unpack the date and time
      to/from one single word :
      DBPKTM/DBUPTM, upto minutes, and
      DBPKTS/DBUPTS, upto seconds.
      The maximum of the start validity and the minimum of the end validity
      of all data base objects used in a given program execution can be
      obtained through the routine DBVLDT.
      
      The insertion time of the last inserted object in a given directory
      can be enquired through the routine DBLKEY, and the time when a
      directory has been last modified, through the routine DBLMOD.
      
      5.3 Purging operations.
      
      With the automatic updating mode, deleting data objects from a given
      directory is rather critical, because of the possibility of deleting a
      master object and leaving alive its updated version(s). Therefore, any
      direct call to RZ deletion routines should be avoided. The operation can
      be taken care of by the routines DBPURK and DBPURG. The latter provides
      a wide range of actions through a number of character options, while
      DBPURK can be used to purge data objects with selection on user keys
      like DBUSE.
      
      The user can delete a complete tree of directory starting from a given
      node, using the routine DBDELT. In the situation where a normal
      directory has been 'a posteriori' partitioned, through the use of
      DBNTOP, the user should call DBDELT to delete the original directory.
      
      With the routine DBPRGD, it is possible to delete all but the last few
      partitions, as specified by the user, from a partitioned directory.
      
      The user can delete all but a few directory trees from the data base
      using the routine DBKEPT.
      
      
      5.4 Plotting facilities.
      
      A few routines are available for plotting various quantities, such as
      the validity of data objects in a given directory (DBPLTI), the
      evolution of some data elements as a function of the value of a given
      key (DBPLOB) and the correlation between two data elements inside a
      given directory (DBPLOV).
      
      Another routine, DBPLNT, permits to prepare an N-tuple by reading data
      from one or several directories.
      
      5.5 Interactive facilities.
      
      Most of the DBL3 operations mentioned in this report, and some other
      specific ones, can be controlled interactively. The interactive version
      of DBL3 is based on the KUIP package [4] and therefore can be used on
      any usual computer.
      
      Note that there are two modes for displaying data :
      - Vertical (V-mode), available on all terminals without
      restriction,
      - Horizontal (H-mode), which can be used only if the screen is
      large enough to display the keys.
      
      The following commands (listed in alphabetic order) are provided :
      
      DBASCI  - loads objects from a pre-edited ASCII file
      DBCRDR  - creates a new directory
      DBDELT  - deletes a directory or a complete tree
      DBDISP  - displays the keys of objects in a given directory
      DBEALI  - enters an alias name for a directory
      DBEDIT  - inserts or replaces data objects, creating the directory if
                needed
      DBEFOR  - defines a maximum insertion time for all subsequent data
                retrievals
      DBEHLP  - enters help information for a given directory
      DBENAM  - enters mnemonics for the data elements of a given directory
      DBENFL  - closes one data base file
      DBEND   - closes all data base files
      DBFZOP  - opens a journal file for a given RZ file
      DBFZUP  - updates a data base from a journal file
      DBHELP  - displays the directory tree for the user to pick a given
                directory, and displays the corresponding Help information
      DBILDU  - initializes the list of directories to be updated from the
                journal file for a given top directory
      DBINIT  - initializes a data base file
      DBLOGL  - sets the log level of a data base file
      DBNTOP  - transforms a normal directory into a partitioned directory
      DBOPEN  - opens a FORTRAN direct access file
      DBPEEK  - displays user keys and data in a given directory
      DBPLNT  - prepares an N-tuple from data and keys from one or more
                directories
      DBPLOB  - displays data element(s) as a function of a given key
      DBPLOT  - displays the time evolution of a given data element (specified
                by its name) in a given directory(specified by its alias name)
      DBPLOV  - displays the correlation of two data elements in a given
                directory
      DBPLTI  - plots the validity period of data objects in a given directory
      DBPRGD  - deletes the first few partitions inside a partitioned
                directory
      DBPTIM  - packs the date and time in a single word, up to seconds
      DBPURG  - purges data objects in a directory
      DBRALI  - displays the full pathname of a directory with given alias
                name
      DBREAD  - displays the directory tree for the user to pick a given
                directory, and displays the user keys and data in that
                directory
      DBRENK  - renames one key element of an object in the given directory
      DBRHLP  - displays the help information for a given directory
      DBRNAM  - displays the mnemonics of the data elements for a given
                directory
      DBSETD  - sets the horizontal display width
      DBSHOW  - displays the data objects in a given directory
      DBTREE  - displays the directory tree
      DBUTIM  - unpacks the date and time (inverse of DBPTIM)
      DBVIEW  - displays objects preselected according to validity time and
                conditions on user keys, possibly across different directories
                (similar to joining tables in ORACLE)
      DBWRITE - inserts ASCII data objects, also creating the directory if
                needed
      
      In addition to these commands the user can also execute all standard
      MZ-, FZ-, DZ- and RZ-commands.
      
      The KUIP commands can be kept in the form of macros, and aliases can
      also be defined and used to execute them.
      A special macro called DBLOGN.KUMAC can be executed to initialize a data
      base file (DBINIT), to set the appropriate display range and, on VAX, to
      choose the host editor.
      
      A command can be executed in any one of the following ways :
      - Command mode, by typing the command together with the parameters
      - Menu mode, by typing /STYLE AN (or AL), then the menu numbers (or
      letters)    up to the desired command is reached
      - Help usage, by typing HELP in the command line and following the
      instructions
      - Macro execution, by typing EXEC followed by the macro name (a macro
      can be edited without exiting from the interactive session by typing
      /MACRO/EDIT )
      
      At the end of an interactive session, the command QUIT will
      automatically close all data base files, by invoking DBEND.
      
      
      
      
      
      
        [1]  L3 Offline Software Group   L3 Report No 315
      A.Gurtu                     L3 Report No 370 
      B.Adeva, E.Gonzales         L3 Report N  o 496
      L.Barone        A data base interfa  ce for BGO calibration, L3 Note,
                                                                  June 86
   [2]  (in preparation)                                             
                                                                  
   [3]  R.Brun, J.Zoll       ZEBRA user guide, CERN Program Lib      rary, Q 100
                                                                  
   [4]  R.Brun, P.Zanarini   KUIP user guide, CERN Program Libr      ary, I 202
                                                                  
                                                                  
                                                                  
    Technical appendices                                            
    --------------------                                            
                                                                  
    A. Pam structure :                                                
     -------------                                                  
                                                                  
   The organization of the Patches inside the Pam file is ba      sed on the
   classification of routines according to whether they can be   called by
   the user or not.                                                  
                                                                  
   The Patch DBL3 contains routines which can be called by t      he user.
   There are routines                                                
             to initialize a data base file (DBINIT); 
             to terminate all the data base oper  ations (DBEND);
             to create standard DBL3 directo  ry (DBCRSD);
             to store data in the mass s  torage (DBENTR, DBREPL, DBABWR);
             to retrieve data from t  he data base (DBUSE, DBABRD);
             to print keys and d  ata (DBPRIN);
             to purge data o  n the disk (DBPURG);
             to delete a   complete directory tree (DBDELT);
             to libe  rate space in the memory (DBFREE);
             to   pack/unpack date and time upto minute/second
             (DBPKTM,DBUPTM/DBPKTS,DPUPTS);
             to print the statistics of data base usage (DBTBPR);
             to set the debug level of the DBL3 package (DBLOGL).
             
      The Patch DATABASE contains a series of additional routines which
      are only for internal use to the DBL3 package. The user is advised not
      to use these routines, as the calling sequence, functionality, etc. of
      these routines may change in future editions.
      
      The Patch DBPLOT contains routines for presenting quantities stored
      in the data base to the user through the HPLOT package [3].
      
      The Patch DBXINT contains all the routines needed for the interactive
      version of the DBL3 package. The interactive commands defined in the
      INL3 Pam file for the menu DBL3 are interpreted by the KUIP package [4]
      and the execution of the various actions is steered through the routines
      DBACPL, DBACTI and DBAUXI.
      
      The Pam file also contains several examples of how to use the Package
      (in Patches DBEXAM1 through DBEXAMB).
      
      
      
      B.  Error codes :
      -----------
      
      The following table summarizes the meanings of the error codes
      returned in IQUEST(1).
      
      
      +-----+------------------------------------------------+--------------+
      |Error|             Meaning                            | Routine Name |
      |Code |                                                |              |
      +-----+------------------------------------------------+--------------+
      |  -1 |Invalid top directory name                      |   DBINIT     |
      |     |                                                |              |
      |  -2 |The file is already open with correct LUNRZ and |   DBINIT     |
      |     |TOPNM                                           |              |
      |     |                                                |              |
      |  -3 |The file is already open with wrong LUNRZ or    |   DBINIT     |
      |     |TOPNM                                           |              |
      |     |                                                |              |
      |  -4 |Already a file is opened with the same unique   |   DBINIT     |
      |     |identifier as requested through IQUEST(1) for   |              |
      |     |this top name                                   |              |
      |     |                                                |              |
      |  -5 |Invalid process name in Online context          |   DBINIT     |
      |     |                                                |              |
      |  -6 |Error in IC_BOOK for booking the CACHE          |   DBINIT     |
      |     |                                                |              |
      |  -7 |Error in CC_SETUP for reserving the CLUSCOM     |   DBINIT     |
      |     |                                                |              |
      |  -8 |Error in opening journal file on Apollo in the  |   DBINIT     |
      |     |server mode                                     |              |
      +-----+------------------------------------------------+--------------+
      |   1 |Illegal character option                        |DBABRD/DBUSE  |
      |     |                                                |              |
      |   2 |Illegal path name                               |DBABRD/DBGET/ |
      |     |                                                |DBGETS/DBUSE  |
      |     |                                                |              |
      |   3 |Data base structure in memory clobbered         |   DBUSE      |
      |     |                                                |              |
      |   4 |Illegal key option                              |DBABRD/DBUSE  |
      |     |                                                |              |
      |   5 |Error in DBCHLD in P3 communication             |DBGET/DBUSE   |
      +-----+------------------------------------------------+--------------+
      |  11 |Pathname not found in the RZ directory          |   DBNODE     |
      |     |                                                |              |
      |  12 |Illegal pathname                                |   DBNODE     |
      |     |                                                |              |
      |  13 |Not enough structural link to support a new Node|   DBNODE     |
      |     |                                                |              |
      |  14 |No space available to create bank NODB          |   DBNODE     |
      |     |                                                |              |
      |  15 |Cannot define IO descriptor for Key bank        |   DBNODE     |
      |     |                                                |              |
      |  16 |Cannot find appropriate top directory           |   DBNODE     |
      +-----+------------------------------------------------+--------------+
      |  21 |Too many keys with option M                     |   DBKEYS     |
      |     |                                                |              |
      |  22 |Illegal key option                              |   DBKEYS     |
      |     |                                                |              |
      |  23 |Key bank cannot be created; no space in memory  | DBKEYS/DBKYSE|
      |     |                                                |              |
      |  24 |No Key bank created satisfying key options for  |   DBKEYS     |
      |     |option S                                        |              |
      |     |                                                |              |
      |  25 |Illegal Path Name                               |   DBKEYS     |
      +-----+------------------------------------------------+--------------+
      |  31 |Illegal path name or path name in node bank     |DBIN/DBKIN/   |
      |     |is wrong                                        |DBKVIN/DBSRTM/|
      |     |                                                |DBVIN/DBCHCK/ |
      |     |                                                |DBKXIN        |
      |     |                                                |              |
      |  32 |No keys/data in this directory                  |DBGET/DBGETS/ |
      |     |                                                |DBIN/DBKIN/   |
      |     |                                                |DBKVIN/DBSRTM/|
      |     |                                                |DBVIN/DBCHCK  |
      |     |                                                |              |
      |  33 |No valid data for the given range of insertion  |DBSRTM/DBKXIN |
      |     |time or for the given set of keys and program   |              |
      |     |version number                                  |              |
      |     |                                                |              |
      |  34 |RZIN fails to read the data                     |   DBRZIN     |
      |     |                                                |              |
      |  35 |Wrong reference to data objects in update mode  |   DBKXIN     |
      |     |                                                |              |
      |  36 |Data bank address zero on return from DBKXIN    |DBKVIN/DBUSE/ |
      |     |                                                |DBVIN/DBCHCK  |
      |     |                                                |              |
      |  37 |Insufficient space in USER store array          |DBKVIN/DBUSE/ |
      |     |                                                |DBVIN/DBCHCK  |
      +-----+------------------------------------------------+--------------+
      |  41 |CHFOR for DB system keys declared wrongly by    |DBMDIP/DBMDIR |
      |     |user                                            |              |
      |     |                                                |              |
      |  42 |CHTAG for DB system keys declared wrongly by    |DBMDIP/DBMDIR |
      |     |user                                            |              |
      |     |                                                |              |
      |  43 |Too many key elements                           |DBCRSD/DBMDIP/|
      |     |                                                |DBMDIR        |
      |     |                                                |              |
      |  44 |Cannot find the top directory name              |DBMDIP/DBMDIR |
      |     |(wrong initialization)                          |              |
      |     |                                                |              |
      |  45 |Illegal Path name                               |DBMDIP/DBMDIR |
      |     |                                                |              |
      |  46 |Top directory name in the Path name does not    |DBMDIP/DBMDIR |
      |     |match with the Top directory name               |              |
      |     |                                                |              |
      |  47 |The Directory already exists                    |   DBMDIR     |
      |     |                                                |              |
      |  48 |Error in directory search sequence              |DBMDIP/DBMDIR |
      |     |                                                |              |
      |  49 |FZOUT fails to write on the sequential file     |   DBSDIR     |
      +-----+------------------------------------------------+--------------+
      |  51 |Illegal character option                        |   DBFREE     |
      |     |                                                |              |
      |  52 |No access to the Key banks                      |   DBFREE     |
      |     |                                                |              |
      |  53 |Pathname not found in the RZ directory          |   DBFREE     |
      |     |                                                |              |
      |  54 |Pathname not matched to that found in bank NODB |   DBFREE     |
      |     |                                                |              |
      |  55 |Too many keys with option M                     |   DBFREE     |
      |     |                                                |              |
      |  56 |Illegal Key option                              |   DBFREE     |
      |     |                                                |              |
      |  57 |Illegal pathname                                |   DBFREE     |
      |     |                                                |              |
      |  58 |Database structure in memory clobbered          |   DBFREE     |
      |     |                                                |              |
      |  59 |Some of the expected key banks not found        |   DBFREE     |
      +-----+------------------------------------------------+--------------+
      |  61 |Too many keys                                   |DBABWR/DBENTB/|
      |     |                                                |DBENTR/DBREPL |
      |     |                                                |              |
      |  62 |Too many keys with option N                     |DBENTR/DBOUT/ |
      |     |                                                |DBREPL/DBVOUT |
      |     |                                                |              |
      |  63 |Data base structure in memory clobbered         |DBENTR/DBREPL |
      |     |                                                |              |
      |  64 |Error in MZCOPY while copying Data bank         |DBENTR/DBREPL |
      |     |                                                |              |
      |  65 |Illegal number of data objects                  |   DBENTB     |
      |     |                                                |              |
      |  66 |Illegal logical unit number                     |DBABWR/DBEHLP/|
      |     |                                                |DBRHLP        |
      |     |                                                |              |
      |  67 |File too long; no space in buffer               |DBABWR/DBEHLP |
      |     |                                                |              |
      |  68 |Input directory is partitioned                  |   DBNTOP     |
      |     |                                                |              |
      |  69 |Input directory is not partitioned              |   DBPRGD     |
      |     |                                                |              |
      |  70 |Error in deleting a partition through RZDELT    |   DBPRGD     |
      +-----+------------------------------------------------+--------------+
      |  71 |Illegal path name                               |DBENTB/DBNTOP/|
      |     |                                                |DBPRGD/DBRTFZ/|
      |     |                                                |DBKOUT        |
      |     |                                                |              |
      |  72 |Number of keys does not match with that         |DBENTB/DBKOUT |
      |     |specified in the directory                      |              |
      |     |                                                |              |
      |  73 |RZOUT fails to write on disk                    |DBENTB/DBNTOP/|
      |     |                                                |DBPRGD/DBKOUT |
      |     |                                                |              |
      |  74 |Error in RZRENK in updating key values for      |DBENTB/DBNTOP/|
      |     |partitioned data set                            |DBPRGD/DBKOUT |
      |     |                                                |              |
      |  75 |Cannot find the top directory name in pathname  |DBENTB/DBNTOP/|
      |     |                                                |DBPRGD/DBKOUT |
      |     |                                                |              |
      |  76 |Cannot form the IO descriptor for the FZ header |DBENTB/DBFZUP/|
      |     |                                                |DBNTOP/DBFZWR/|
      |     |                                                |DBKOUT        |
      |     |                                                |              |
      |  77 |FZOUT fails to write on the sequential journal  |DBENTB/DBNTOP/|
      |     |file                                            |DBPRGD/DBENFZ/|
      |     |                                                |DBKOUT        |
      |     |                                                |              |
      |  78 |Illegal number of keys on data base/journal file|DBENTB/DBFZUP/|
      |     |                                                |DBKOUT        |
      +-----+------------------------------------------------+--------------+
      |  81 |Precision is not correctly given                |   DBUCMP     |
      |     |                                                |              |
      |  82 |Illegal Data Type                               |   DBUCMZ     |
      |     |                                                |              |
      |  83 |Data update but uncompreseed                    |   DBUNCP     |
      |     |                                                |              |
      |  84 |The update structure has different number of    |   DBUNCP     |
      |     |data words                                      |              |
      |     |                                                |              |
      |  85 |No data in the structure                        |   DBUNCP     |
      |     |                                                |              |
      |  86 |The update structure has different data type    |   DBUNCP     |
      +-----+------------------------------------------------+--------------+
      |  91 |Illegal Character Option                        |   DBOPTS     |
      |     |                                                |              |
      |  92 |Nonstandard IO descriptor                       |   DBFRUS     |
      |     |                                                |              |
      |  98 |Invalid path name in Node bank                  |   DBTBPR     |
      |     |                                                |              |
      |  99 |No space in memory for creating the bank        |DBBOOK/DBRZIN |
      +-----+------------------------------------------------+--------------+
      | 100 |Error in decoding                               |DBCTOB/DBCTOI/|
      |     |                                                |DBCTOR        |
      |     |                                                |              |
      | 101 |Illegal path name                               |DBKTYP/DBPRIN/|
      |     |                                                |DBRKY1/DBAIRD/|
      |     |                                                |DBDISD/DBDISP/|
      |     |                                                |DBEDAS/DBJOIN/|
      |     |                                                |DBVWPR        |
      |     |                                                |              |
      | 102 |No key or data for the path name                |DBPRIN/DBJOIN/|
      |     |                                                |DBVWPR        |
      |     |                                                |              |
      | 103 |Illegal data type                               |DBPRKY/DBDKYH/|
      |     |                                                |DBDKYV        |
      |     |                                                |              |
      | 104 |Read error in getting the RZ date and time      |   DBPRDT     |
      +-----+------------------------------------------------+--------------+
      | 111 |Illegal path name                               |DBPURG/DBPURK |
      |     |                                                |              |
      | 112 |No key or data for the path name                |DBPURG/DBPURK |
      |     |                                                |              |
      | 113 |Illegal character option                        |   DBPURK     |
      |     |                                                |              |
      | 114 |Valid data object(s) in the Node/Key structure  |   DBPURK     |
      |     |                                                |              |
      | 115 |Cannot form the IO descriptor for the FZ header |   DBSPUR     |
      |     |                                                |              |
      | 116 |FZOUT fails to write on the sequential file     |   DBSPUR     |
      +-----+------------------------------------------------+--------------+
      | 121 |Store area in DBGETA is insufficient            |   DBGETA     |
      |     |                                                |              |
      | 122 |NADMX is too small for the data structure       |   DBGETA     |
      |     |                                                |              |
      | 123 |Illegal data type                               |   DBTSAD     |
      +-----+------------------------------------------------+--------------+
      | 131 |Illegal pathname (in key bank for DBLAST)       |DBLAST/DBLKEY/|
      |     |                                                |DBLMOD        |
      |     |                                                |              |
      | 132 |Illegal number of keys in the directory         |DBLAST/DBLKEY |
      +-----+------------------------------------------------+--------------+
      | 140 |Illegal top directory name                      |   DBFZOP     |
      |     |                                                |              |
      | 141 |Read error on the FZ file (journal file)        |DBFZUP/DBENFZ |
      |     |                                                |              |
      | 142 |Top directory name illegal in the FZ file       |   DBFZUP     |
      |     |                                                |              |
      | 143 |Illegal path name in the FZ file                |DBFZUP/DBENFZ |
      |     |                                                |              |
      | 144 |Error in RZ for saving the data object          |   DBENFZ     |
      |     |                                                |              |
      | 145 |Error in RZ for renaming the keys               |   DBENFZ     |
      +-----+------------------------------------------------+--------------+
      | 150 |Error in loading the top directory              |   DBUDIC     |
      |     |                                                |              |
      | 151 |Cannot find the top directory                   |   DBCDIC     |
      |     |                                                |              |
      | 152 |Illegal path name                               |   DBCDIC     |
      |     |                                                |              |
      | 153 |Illegal top directory name                      |   DBCDIC     |
      |     |                                                |              |
      | 154 |Dictionary directory cannot be loaded           |   DBCDIC     |
      |     |                                                |              |
      | 155 |Error in RZ while reading the dictionary        |DBCDIC/DBUDIC |
      |     |                                                |              |
      | 156 |Pathname already exists in the dictionary       |   DBCDIC     |
      |     |                                                |              |
      | 157 |Error in RZ in writing the dictionary object    |DBCDIC/DBUDIC |
      |     |                                                |              |
      | 158 |Error in RZ in purging the dictionary directory |DBCDIC/DBUDIC |
      |     |                                                |              |
      | 159 |Error in creating the DICTIONARY/HELP directory |   DBUDIC     |
      +-----+------------------------------------------------+--------------+
      | 161 |Illegal path name                               |DBFPAT/DBPLNT/|
      |     |                                                |DBPLOB/DBPLOV/|
      |     |                                                |DBPLTI        |
      |     |                                                |              |
      | 162 |No keys or data in the directory                |DBPLNT/DBPLOB/|
      |     |                                                |DBPLOV/DBPLTI |
      |     |                                                |              |
      | 163 |Illegal number of objects in the request        |DBPLNT/DBPLOB/|
      |     |                                                |DBPLOV        |
      |     |                                                |              |
      | 164 |Illegal number of path names                    |   DBPLNT     |
      |     |                                                |              |
      | 165 |Illegal object element indices                  |   DBPLNT     |
      |     |                                                |              |
      | 166 |Illegal key element indices                     |   DBPLNT     |
      +-----+------------------------------------------------+--------------+
      | 171 |Illegal Path name                               |   DBDELT     |
      |     |                                                |              |
      | 172 |Cannot find the top directory for the path name |   DBDELT     |
      |     |                                                |              |
      | 173 |Error in RZ for reading the dictionary object   |   DBDELT     |
      |     |                                                |              |
      | 174 |Error in FZOUT for saving the journal file      |   DBDELT     |
      |     |                                                |              |
      | 175 |Error in RZ in writing the dictionary object    |   DBDELT     |
      |     |                                                |              |
      | 176 |Error in RZ in purging the dictionary directory |   DBDELT     |
      |     |                                                |              |
      | 177 |Error in RZ in deleting the tree                |   DBDELT     |
      +-----+------------------------------------------------+--------------+
      | 181 |Error in sending spool file to the server       |DBEND/DBENDF/ |
      |     |                                                |DBSAVE        |
      |     |                                                |              |
      | 182 |Illegal path name                               |DBEALI/DBEHLP/|
      |     |                                                |DBENAM/DBRHLP/|
      |     |                                                |DBRNAM/DBGNAM |
      |     |                                                |              |
      | 183 |Illegal number of data words                    |   DBENAM     |
      |     |                                                |              |
      | 184 |Illegal flag (IFLAG)                            |   DBSNAM     |
      |     |                                                |              |
      | 185 |Illegal top directory name                      |DBEALI/DBSNAM |
      |     |                                                |              |
      | 186 |FZIN error for reading the data structure       |   DBSNAM     |
      |     |                                                |              |
      | 187 |FZOUT fails to write on the sequential file     |DBEALI/DBSNAM |
      |     |                                                |              |
      | 188 |Error in RZ for writing to the R.A. file        |DBEALI/DBSNAM |
      +-----+------------------------------------------------+--------------+
      | 191 |Illegal path name                               |   DBRENK     |
      |     |                                                |              |
      | 192 |Specified key elements do not match with any of |   DBRENK     |
      |     |the existing set of keys                        |              |
      |     |                                                |              |
      | 193 |Cannot find the top directory name in pathname  |   DBRENK     |
      |     |                                                |              |
      | 194 |Cannot form the IO descriptor for the FZ header |   DBRENK     |
      |     |                                                |              |
      | 195 |FZOUT fails to write on the sequential journal  |   DBRENK     |
      |     |file                                            |              |
      |     |                                                |              |
      | 196 |Error in RZRENK in updating key values          |   DBRENK     |
      |     |partitioned data set                            |              |
      +-----+------------------------------------------------+--------------+
      | 201 |DICTIONARY directory not found                  |DBEALI/DBRNAM/|
      |     |                                                |DBGNAM        |
      |     |                                                |              |
      | 202 |No description of data elements for the given   |DBRNAM/DBGNAM |
      |     |path name exists in the data base               |              |
      |     |                                                |              |
      | 203 |No HELP directory inside the data base          |   DBRHLP     |
      |     |                                                |              |
      | 204 |No help information for this path stored yet    |   DBRHLP     |
      |     |                                                |              |
      | 205 |Illegal alias name for a directory              |   DBRALI     |
      +-----+------------------------------------------------+--------------+
      | 211 |Illegal number of paths                         |   DBKEPT     |
      |     |                                                |              |
      | 212 |Illegal path name                               |   DBKEPT     |
      |     |                                                |              |
      | 213 |Conflicting top directory names                 |   DBKEPT     |
      +-----+------------------------------------------------+--------------+
      | 221 |Error in CC_WRITELOCK for locking CLUSCOM (VAX);|   DBWLOK     |
      |     |                                                |              |
      | 222 |Error in CC_RELEASE for releasing CLUSCOM (VAX) |   DBCWSV     |
      |     |                                                |              |
      | 223 |Error in IC_SIGNAL for signalling the VAX Server|   DBCWSV     |
      |     |                                                |              |
      | 225 |Error in sending spool file to the server (IBM  |   DBSTSV     |
      |     |or APOLLO)                                      |              |
      +-----+------------------------------------------------+--------------+
      | 231 |Illgeal Top directory name                      |   DBILDU     |
      |     |                                                |              |
      | 232 |Illegal logical unit number                     |DBILDF/DBILDU |
      +-----+------------------------------------------------+--------------+
      
      Note :
      
      If IQUEST(1) = 0 on return in subroutine DBUSE, IQUEST(2) carries
      information whether data part has been actually read from the disk.
      
      IQUEST(2) =  0 : No disk i/o has been performed
      =  1 : Data have been refreshed from the disk
      
      
      C.  Format for FZ output :
      --------------------
      
      DBL3 can create a journal file and can also update a data base from
      the corresponding journal file. The journal file format is defined as an
      FZ record consisting of a header and the data part. The format is
      general enough and can also be used for the communication betwen the
      server and a process which wants to update the data base.
      
      The data part of the FZ record is relevant only for data to be
      entered. It is exactly the same data structure as input to DBENTR. For
      efficiency reason, DBL3 for its own journal file stores the data
      structure as input to the RZOUT call. This difference can be easily
      recognised from the value of KEY(1), which is zero for outside source
      and nonzero for DBL3's own journal file.
      
      The header part has very similar structure for the eight actions
      foreseen so far, e.g., entering data, creating new directories, deleting
      data objects, deleting a directory tree, renaming the keys, entering
      names of data elements or help information for a directory, entering
      alias name to a directory, deleting a few partitions in a partitioned
      directory. However, they differ in details and the eight different types
      of FZ headers are listed below.
      
      Header for entering data :
      
      +----------+----------+------+----------------------------------------+
      |Word Count| Mnemonic | Type |         Content                        |
      +----------+----------+------+----------------------------------------+
      |        1 |   IACT   |   I  | Action code (=1)                       |
      |        2 |  NWKEY   |   I  | Number of key elements                 |
      |        3 |  NWDOP   |   I  | Number of words used to store CHOPT    |
      |        4 |   NDOP   |   I  | Number of words used to to store the   |
      |          |          |      | path name                              |
      |        5 |  IPREC   |   I  | Precision chosen for packing           |
      |          |          |      | (see DBENTR)                           |
      |        6 |  KEY(1)  |   I  | Key element 1                          |
      |       .. |   ...    |  ..  |   ........                             |
      |  NWKEY+5 |KEY(NWKEY)|  ..  | Key element NWKEY                      |
      |  NWKEY+6 |  CHOPT   |   H  | Character option                       |
      |       .. |     ..   |   H  |                                        |
      |  NWKEY+6 |  PATHN   |   H  | Path name                              |
      |   +NWDOP |          |      |                                        |
      |       .. |     ..   |   H  |                                        |
      +----------+----------+------+----------------------------------------+
      
      Header for creating directories :
      
      +----------+----------+------+----------------------------------------+
      |Word Count| Mnemonic | Type |         Content                        |
      +----------+----------+------+----------------------------------------+
      |        1 |   IACT   |   I  | Action code (=2)                       |
      |        2 |  NWKEY   |   I  | Number of key elements                 |
      |        3 |  NWDOP   |   I  | Number of words used to store CHOPT    |
      |        4 |   NDOP   |   I  | Number of words used to to store the   |
      |          |          |      | path name                              |
      |        5 |   MXKP   |   I  | Maximum number of objects inside one   |
      |          |          |      | partition (see DBMDIP)                 |
      |        6 |  INSTM   |   I  | Insertion time packed up to minutes    |
      |          |          |      | (see DBPKTM)                           |
      |        7 |  NRECD   |   I  | Unused at this moment                  |
      |        8 |  CHOPT   |   H  | Character option ('P' for partitioned  |
      |       .. |   ...    |  ..  | directory)                             |
      |   NDOP+8 |  CHFOR   |   H  | Description of key element type. This  |
      |       .. |     ..   |  ..  | information is stored in NCFO = (NWKEY |
      |       .. |     ..   |  ..  | +3)/4 words                            |
      |   NDOP+8 |  CHTAG   |   H  | Tags for each key element. This info.  |
      |    +NCFO |     ..   |  ..  | is stored in NTAG = 2*NWKEY words.     |
      |NDOP+NCFO |  PATHN   |   H  | Path name                              |
      |  +NTAG+8 |          |      |                                        |
      |       .. |     ..   |   H  |                                        |
      +----------+----------+------+----------------------------------------+
      
      Header for deleting objects :
      
      +----------+----------+------+----------------------------------------+
      |Word Count| Mnemonic | Type |         Content                        |
      +----------+----------+------+----------------------------------------+
      |        1 |   IACT   |   I  | Action code (=3)                       |
      |        2 |  NWKEY   |   I  | Number of key elements                 |
      |        3 |  NWDOP   |   I  | Number of words used to store CHOPT    |
      |        4 |   NDOP   |   I  | Number of words used to to store the   |
      |          |          |      | path name                              |
      |        5 |  ITIME   |   I  | Argument ITIME in DBPURK or -1 for     |
      |          |          |      | DBPURG                                 |
      |        6 |  INSTM   |   I  | Deletion time packed up to minutes     |
      |          |          |      | (see DBPKTM)                           |
      |        7 |  KEY(1)  |   I  | Key element 1 for DBPURK or KYDAT for  |
      |          |          |      | DBPURG                                 |
      |        8 |  KEY(2)  |   I  | Key element 2 for DBPURK or KYTIM for  |
      |          |          |      | DBPURG                                 |
      |       .. |   ...    |  ..  |                                        |
      |  NWKEY+7 |  CHOPT   |   H  | Character option                       |
      |       .. |   ...    |  ..  |                                        |
      |  NWKEY+7 |  PATHN   |   H  | Path name                              |
      |   +NWDOP |          |      |                                        |
      |       .. |     ..   |   H  |                                        |
      +----------+----------+------+----------------------------------------+
      
      Header for deleting directories :
      
      +----------+----------+------+----------------------------------------+
      |Word Count| Mnemonic | Type |         Content                        |
      +----------+----------+------+----------------------------------------+
      |        1 |   IACT   |   I  | Action code (=4)                       |
      |        2 |    ---   |   I  | Unused (set to 0)                      |
      |        3 |  NWDOP   |   I  | Number of words used to store CHOPT    |
      |        4 |   NDOP   |   I  | Number of words used to to store the   |
      |          |          |      | path name                              |
      |        5 |    ---   |   I  | Unused (set to 0)                      |
      |        6 |  INSTM   |   I  | Deletion time packed up to minutes     |
      |          |          |      | (see DBPKTM)                           |
      |        7 |  CHOPT   |   H  | Character option                       |
      |  NWDOP+7 |  PATHN   |   H  | Path name                              |
      |       .. |     ..   |   H  |                                        |
      +----------+----------+------+----------------------------------------+
      
      Header for renaming keys :
      
      +----------+----------+------+----------------------------------------+
      |Word Count| Mnemonic | Type |         Content                        |
      +----------+----------+------+----------------------------------------+
      |        1 |   IACT   |   I  | Action code (=5)                       |
      |        2 |  NWKEY   |   I  | Number of key elements                 |
      |        3 |  NWDOP   |   I  | Number of words for CHOPT (= 0)        |
      |        4 |   NDOP   |   I  | Number of words used to to store the   |
      |          |          |      | path name                              |
      |        5 |  Unused  |   I  | Set to zero                            |
      |        6 |  KYO(1)  |   I  | Old key element 1                      |
      |       .. |   ...    |  ..  |   ........                             |
      |  NWKEY+5 |KYO(NWKEY)|  ..  | Old key element NWKEY                  |
      |  NWKEY+6 |  KYN(1)  |   I  | New key element 1                      |
      |       .. |     ..   |  ..  |   ........                             |
      |2*NWKEY+5 |KYO(NWKEY)|  ..  | New key element NWKEY                  |
      |2*NWKEY+6 |  PATHN   |   H  | Path name                              |
      |       .. |     ..   |   H  |                                        |
      +----------+----------+------+----------------------------------------+
      
      Header for entering names or help information :
      
      +----------+----------+------+----------------------------------------+
      |Word Count| Mnemonic | Type |         Content                        |
      +----------+----------+------+----------------------------------------+
      |        1 |   IACT   |   I  | Action code (=6)                       |
      |        2 |  NWKEY   |   I  | Number of key elements                 |
      |        3 |  NWDOP   |   I  | Number of words used to store CHOPT(=0)|
      |        4 |   NDOP   |   I  | Number of words used to to store the   |
      |          |          |      | path name (DICTIONARY or HELP)         |
      |        5 |  IFLAG   |   I  | Flag (1 for help information; 2 for    |
      |          |          |      | names of the data elements)            |
      |        6 |  PATHN   |   H  | Path name (DICTIONARY or HELP)         |
      |       .. |     ..   |   H  |                                        |
      +----------+----------+------+----------------------------------------+
      
      Header for entering the alias name :
      
      +----------+----------+------+----------------------------------------+
      |Word Count| Mnemonic | Type |         Content                        |
      +----------+----------+------+----------------------------------------+
      |        1 |   IACT   |   I  | Action code (=7)                       |
      |        2 |    ---   |   I  | Unused (set to 0)                      |
      |        3 |  NWDOP   |   I  | Number of words used to store CHOPT(=0)|
      |        4 |   NDOP   |   I  | Number of words used to to store the   |
      |          |          |      | path name of the dictitionary          |
      |        5 |  IFLAG   |   I  | Flag (0 means temporary; 1 permanent)  |
      |        6 |   NWDP   |   I  | Number of words used to store the      |
      |          |          |      | path name                              |
      |        7 |  PATHD   |   H  | Path name of the dictionary            |
      |       .. |     ..   |   H  |                                        |
      |   NDOP+7 |  ALIAS   |   H  | Alias name                             |
      |       .. |     ..   |   H  |                                        |
      |   NDOP+9 |  PATHN   |   H  | Path name of the directory             |
      |       .. |     ..   |   H  |                                        |
      +----------+----------+------+----------------------------------------+
      
      Header for deleting a few partitions in a partitioned directory :
      
      +----------+----------+------+----------------------------------------+
      |Word Count| Mnemonic | Type |         Content                        |
      +----------+----------+------+----------------------------------------+
      |        1 |   IACT   |   I  | Action code (=8)                       |
      |        2 |    ---   |   I  | Unused (set to 0)                      |
      |        3 |  NWDOP   |   I  | Number of words used to store CHOPT    |
      |        4 |   NDOP   |   I  | Number of words used to to store the   |
      |          |          |      | path name                              |
      |        5 |  INSTM   |   I  | Deletion time packed up to minutes     |
      |          |          |      | (see DBPKTM)                           |
      |        6 |  NKEEP   |   I  | Number of partitions to be kept        |
      |        7 |  CHOPT   |   H  | Character option                       |
      |  NWDOP+7 |  PATHN   |   H  | Path name of the directory             |
      |       .. |     ..   |   H  |                                        |
      +----------+----------+------+----------------------------------------+
      
      
      D.  Bank Description :
      ----------------
      
          (3)   +-------\
      +---------|  FZDB  >   List of directories to be updated
      |         +-------/
      |
      +--------\      +--------\
      |  UPDB   >-----|  UPDB   >  Support for all top directories opened
      +--------/      +--------/
      |   |
      |   |   (2)   +--------\
      |   +---------|  DICT   >  Dictionary information
      |             +--------/
      |
      |       (1)   +--------\
      +-------------|  NODB   >  Node bank for the top directory
                    +--------/
                    |..|..||
                    |
                    |
                    +--------\
                    |  NODB   >
                    +--------/
                    |....|||
                    |      Node bank of subdirectory for which data
                    +--------\   +--------\   +--------\   is retrieved
                    |  NODB   >--|  KYDB   >--|  KYDB   >
                    +--------/   +--------/   +--------/   Key banks
                    | (1)        | (1)
                    +--------+   +--------+
                    |  DATA  |   |  DATA  |
                    +--------+   +--------+
      
      
      
      ========================================================================
      |Bank:  UPDB                                            Top level bank |
      |NL_/NS_ =  2/2                                          IO_ = '8I -H' |
      |NW_     =  12                                                         |
      +----------------------------------------------------------------------+
      |LINKS:                                                                |
      |link   type   bank                                        offset      |
      |----   ----   ----                                        ------      |
      | -3     Ref   FZDB                                        KLFZDB ( 3) |
      | -2     Str   DICT                                        KLDICT ( 2) |
      | -1     Str   NODB                                                    |
      |  0     nxt   UPDB of the next data base file                         |
      +----------------------------------------------------------------------+
      |DATA WORDS:                                                           |
      |word  type  contents                                      offset      |
      |----  ----  --------                                      ------      |
      |   1    I   Logical unit number of RZ file                MUPLUN ( 1) |
      |   2    I   Flag if database to be updated (0 if not)     MUPFLG ( 2) |
      |   3    I   Logical unit number of standard journal file  MUPJFL ( 3) |
      |   4    I   Logical unit number of special backup file    MUPBAK ( 4) |
      |   5    I   Identifier of the top directrory              MUPDIC ( 5) |
      |   6    I   Number of characters in the top directory     MUPNCH ( 6) |
      |            name                                                      |
      |   7    I   Shared/server flag (IOPS*10 + IOPP)           MUPSRV ( 7) |
      |            (IOPS = 1 if S option in DBINIT;                          |
      |             IOPP = 1 if P option in DBINIT)                          |
      |   8    I   Maximum insertion time for subsequent         MUPKY7 ( 8) |
      |            object retrieval                                          |
      |9-12    H   Name of the top directory                     MUPNAM ( 9) |
      +----------------------------------------------------------------------+
      
      
      ========================================================================
      |Bank:  DICT                                           Dictionary bank |
      |NL_/NS_ =  0/0                                     IO_ = '1I /3I 22H' |
      |NW_     =  1 + 25*n                                                   |
      +----------------------------------------------------------------------+
      |DATA WORDS:                                                           |
      |word  type  contents                                      offset      |
      |----  ----  --------                                      ------      |
      |   1    I   Number of nodes in the dictionary             MDCNTM ( 1) |
      |      For each node (Node number n)                                   |
      |IOFF+      (= (n-1)*NWITDB + 1)  (NWITDB = 25)                        |
      |   1    I   Unique identifier of the node                 MDCITM ( 1) |
      |   2    I   Number of characters for describing the path  MDCNCH ( 2) |
      |            to the node                                               |
      |   3    I   Last update to the node (not avaialable yet)  MDCLUP ( 3) |
      | 4-5    H   Alias name                                    MDCALI ( 4) |
      |6-25    H   Name of the path to the node (excluding the   MDCNAM ( 6) |
      |            top directory part)                                       |
      +----------------------------------------------------------------------+
      
      
      ========================================================================
      |Bank:  NODB                                                 Node bank |
      |NL_/NS_ =  NS_/(number of down nodes)               IO_ = '4I 16B -H' |
      |NW_     =  20 + words needed for path name                            |
      +----------------------------------------------------------------------+
      |LINKS:                                                                |
      |link   type   bank                                        offset      |
      |----   ----   ----                                        ------      |
      | -n     Str   NODB (next level node)                                  |
      |  0     nxt   KYDB of the first key bank to the node      KLDYDB ( 0) |
      +----------------------------------------------------------------------+
      |DATA WORDS:                                                           |
      |word  type  contents                                      offset      |
      |----  ----  --------                                      ------      |
      |   1    I   Number of key elements for this node          MNDNWK ( 1) |
      |   2    I   Total number of data words in the Key bank    MNDNWD ( 2) |
      |   3    I   Number of characters describing the path to   MNDNCH ( 3) |
      |            the node                                                  |
      |   4    I   Unique identifier of this node                MNDDIC ( 4) |
      |5-20    B   IO descriptor of the Key bank                 MNDIOF ( 5) |
      |21-..   H   Name of the path to the node                  MNDNAM (21) |
      +----------------------------------------------------------------------+
      
      
      ========================================================================
      |Bank:  KYDB                                                  Key bank |
      |NL_/NS_ =  3/1                                          IO_ = Dynamic |
      |NW_     =  NWKEY + NWFXM(=6)                                          |
      +----------------------------------------------------------------------+
      |LINKS:                                                                |
      |link   type   bank                                        offset      |
      |----   ----   ----                                        ------      |
      | -2     Ref   UPDB (Top level bank)                       KLUPDB ( 3) |
      | -2     Ref   NODB (parent node bank)                     KLNODB ( 2) |
      | -1     Str   Data bank                                   KLDADB ( 1) |
      |  0     nxt   KYDB of the next key bank                               |
      +----------------------------------------------------------------------+
      |DATA WORDS:                                                           |
      |word  type  contents                                      offset      |
      |----  ----  --------                                      ------      |
      |   1    I   Serial number of the object                               |
      |   2    I   Refernce to the master object (for update)                |
      |   3    I   Start validity time (upto seconds)                        |
      |   4    I   End   validity time (upto seconds)                        |
      |   5    I   Source identifier                                         |
      |   6    I   Flag for storing the object (internal to DBL3)            |
      |             Bit JRZUDB (=1) : Full RZ option                         |
      |                 JIGNDB (=2) : Ignore the object                      |
      |                 JPRTDB (=3) : Directory is partitioned               |
      |                 JASFDB (=4) : Specially encoded ASCII                |
      |   7    I   Insertion time (upto minutes)                             |
      |8-NWKEY     User keys                                                 |
      |NWKEY+1 I   Logical end validity time (upto seconds)                  |
      |NWKYDB+                                                               |
      |  -4    I   Number of physical reads to disk for this key MKYRID (-4) |
      |  -3    I   Number of calls to DBUSE in the same event    MKYCEV (-3) |
      |  -2    I   Number of calls to DBUSE in the entire run    MKYCRU (-2) |
      |  -1    I   Precision used for storing the object         MKYPRE (-1) |
      |   0    I   Free flag (set by DBFREE call)                MKYFRI ( 0) |
      +----------------------------------------------------------------------+
      
      
      ========================================================================
      |Bank:  FZDB                         List of directories to be updated |
      |NL_/NS_ =  0/0                                    IO_ = '4H / 1I 20H' |
      |NW_     =  4 + 21*n                                                   |
      +----------------------------------------------------------------------+
      |LINKS:                                                                |
      |link   type   bank                                        offset      |
      |----   ----   ----                                        ------      |
      |  0     nxt   FZDB of the next data base file                         |
      +----------------------------------------------------------------------+
      |DATA WORDS:                                                           |
      |word  type  contents                                      offset      |
      |----  ----  --------                                      ------      |
      | 1-4    H   Top directory name                            MFZTOP ( 1) |
      |      For each directory (number n)                                   |
      |IOFF+      (= (n-1)*(MXLWDB+1) + MFZDIR)  (MXLWDB = 20; MFZDIR = 5)   |
      |  1     I   Number of characters in the path                          |
      |2-21    H   Complete pathname of the directory or the root            |
      +----------------------------------------------------------------------+
      
      
      ========================================================================
      |Bank:  FDDB             List of directories to be forced for updating |
      |NL_/NS_ =  0/0                                       IO_ = '/ 1I 20H' |
      |NW_     =  21*n                                                       |
      +----------------------------------------------------------------------+
      |DATA WORDS:                                                           |
      |word  type  contents                                      offset      |
      |----  ----  --------                                      ------      |
      |      For each directory (number n)                                   |
      |IOFF+      (= (n-1)*(MXLWDB+1) + 1)  (MXLWDB = 20)                    |
      |  1     I   Number of characters in the path                          |
      |2-21    H   Complete pathname of the directory                        |
      +----------------------------------------------------------------------+