Usage for random access

Principles

For random access the location of a d/s within its file is specified by its 'data-structure address', the DsA, consisting of 2 words:

word 1

number of the physical record in which the d/s starts;

word 2

off-set within this record.

If the file contains less than 2 Gigawords you can pack this into one word with:

  JDSAP = (JDSA1-1) * LREC  + JDSA2

For every successful call to FZOUT or FZIN Zebra returns the DsA of the latest d/s in IQUEST(5) and IQUEST(6), provided the file-format is 'exchange' and even for a tape file. To prepare a file for reading it randomly the user would construct a table, the 'direct access table', or DaT, which contains the relevant properties of the d/ss on the file plus their DsA's. This can be done either by an extra read pass over the file to collect the data, or more economically at the time when the file is created. In the latter case the DaT can be written to the file as the last d/s before end-of-file, and is then ready for use for any future reading of the file.

When reading a file initialized with mode D given to FZFILE, repeated calls to FZIN will read the data sequentially. To obtain a particular data-structure one has to call FZINXT specifying the DsA of the wanted d/s; this will reset the 'current read point' for the file and the next call to FZIN will then deliver the wanted d/s.

File creation

Do this:

1. call FZFILE with CHOPT = 'DO' or 'LDO' for a disk file, or CHOPT = 'TO' or 'TLO' for a tape file.
2. lift a bank, generously large enough to hold the DaT.
3. CALL FZODAT (LUN,0,0) to create the 'DaT forward-reference record'. This is a small record to provide 2 words to hold the DsA of the DaT itself; they are initialized to zero and on the final call FZODAT will try to update them with the true address if the file is ready for random access. This should be provided on every file which later one may want to access randomly, like a tape file to be copied to disk. This is useful only if this record is the very first record on the file.
4. create the file by repeated calls to FZOUT, compiling at the same the Direct Acces Table, including into it IQUEST(5) and (6) returned from FZOUT.
5. call MZPUSH to reduce the bank holding the DaT to the size actually needed.
6. CALL FZODAT (LUN,IXDIV,LBANK) to store the bank with the DaT onto the file and to update the forward reference record if possible; Zebra will remember the DsA of this d/s in the control-bank for this file.
7. CALL FZENDO (LUN,'TX') to terminate and close the file. This will store the DsA of the DaT bank into the user header of the special Zebra EoF record, which is the very last item on the file.

Reading the file

Do this:

1) call FZFILE with CHOPT = 'D' or 'LD' to permit random access.

2) retrieve the direct-access table:

        CALL FZIDAT (LUN,IXDIV,LDAT,1)
        IF (IQUEST(1).NE.0)             GO TO trouble

1. first it will read the first record on the file to see whether it is a DaT forward reference record containing a non-zero DsA. If so it will use this adr to read the DaT and deliver it to the user.
2. if this is not successful it will try to get from the operating system the length of the file and then read its last physical record; this should contain the Zebra EoF record with the DsA of the DaT.
3. if this fails it will scan either the last 24 physical records or the whole file for the DaT record, depending on whether it did or did not get some indication of the file size.

3) to get a wanted d/s: find it in the DaT, get its DsA and call \Rind{FZINXT (LUN,MDS1,MDS2)}, with MDS the 2-word data-structure address. This resets the read point, calling \Rind{FZIN (LUN,...)} will then deliver the wanted d/s.

If acccess to the table was not immediate, FZIDAT will try to update the forward reference record, if it exists, to ease future use. It can do this only if the file hase been opened for read/write, and this has to be signalled by giving CHOPT='DIO' to FZFILE.

Keeping the DaT on the file to be read is obviously the simplest way to proceed, but other organisations are possible. For example, if one has a large disk with many files as the data-base for the events of an experiment, one may want to have a separate global DaT for all the events on the disk, with a structure reflecting the files and holding their names.

Remember: if one needs a data-base with key-word access or update capability one should use the RZ package of Zebra.