FZIN - read one data-structure

To read the next data-structure one calls FZIN. The return code in IQUEST(1) will tell the caller whether the READ operation was free of error, and whether the object read was a d/s, a start-of-run, an end-of-run, or an end-of-file signal. FZIN may be asked to skip to and then read the next start-of-event d/s or the next start-of-run record.

In the simplest case (opt = '.' or blank) FZIN will read the next data-structure into the division indicated by the parameter IXDIV, at the same time delivering the user-header vector to IUHEAD.

The selective read has been provided to rapidly skip unwanted d/ss without expansion into memory and without relocation of the links: calling FZIN with opt='S' causes reading of the next pilot information only, returning to the user the header-vector (and the text-vector, if any) for taking a decision to read or to skip the 'pending d/s'. Skipping is done by asking for the next d/s; accepting is done by calling FZIN with opt='A'. Note that every call to FZIN has to be checked for the success of the operation by testing on IQUEST(1).

In the cases described so far the complete data-structure is read and is deposited into one particular division. It is however possible to steer individual data segments of the d/s into particular divisions, or to cause them to be ignored. This can be done by using the options T and D , as described separately in the next paragraph.

Specifications for 269

FZIN returns the read status, either normal or error, in IQUEST; be careful about the meaning of status codes 4 and 5: '4' means EoF seen on a file which can be a multi-file file; '5' means 'End-of-Data'. Reading a file which cannot be multi-file can never produce status 4, the end will always be indicated by status 5.

Error status

IQUEST(1) =  -8  . . .
             -7  for 3 consecutive errors
             -6  for 2 consecutive errors
             -5  read error
             -4  bad constructs, maybe not a file written by FZOUT
             -3  bad data
             -2  not enough space to read the d/s and its table
             -1  faulty call: T,D,A option given, but no pending d/s

IQUEST(2) =  number of logical records read so far

IQUEST(3) =  number of physical records read so far (exchange mode)

To read the next data-structure:

CALL FZIN (LUN,IXDIV,!LSUP,JBIAS,opt,*NUH*,IUHEAD*)

with    LUN:  logical unit number

      IXDIV:  index of the default division to receive the d/s
               zero: division 2 of the primary store
               (ignored if S option given)

               The d/s read is linked into a pre-existing d/s as directed by
               !LSUP and JBIAS, which have the same meaning as for MZLIFT:

      !LSUP:  if JBIAS < 1: !LSUP is the supporting bank,
      JBIAS:                 connection to link LQ(!LSUP-JBIAS)
                              IQUEST(13) returns the entry adr to the d/s

               if JBIAS = 1: *!LSUP is the supporting link,
                              connection to *!LSUP* (top-level d/s)
                              !LSUP* returns the entry adr to the d/s

               if JBIAS = 2: stand-alone d/s, no connection
                              !LSUP* returns the entry adr to the d/s
               (ignored if options S or T selected)

    options:  character string,
               individual characters select options:

          event:    default: go for the next d/s
                   E skip to and read the next start-of-event d/s
                   R skip to and read the next start-of-run record
                   2 skip to and read the next   end-of-run record
                   3 skip to and read the next   Zebra end-of-file
                   4 skip to and read the next machine end-of-file

                     any skip operation stops also on machine EoF;
                     option E or 2 skipping stop also on Zebra EoF,
                     option R skipping does not stop on Zebra EoF.

         select:    default: read the next header and its d/s
                     (may mean: skip pending d/s or current event)

                   S select, read next header and text-vector only
                     (may mean: skip pending d/s or current event)
                     (LSUP and JBIAS not used)

                   T table,  load the segment table for the current
                             d/s into /FZCSEG/
                     (LSUP, JBIAS, NUH, and IUHEAD not used)

                   A accept, read the pending d/s
                     (NUH and IUHEAD not used)

                   D divisional accept, read the pending d/s under
                                        control from /FZCSEG/
                     (NUH and IUHEAD not used)

                   F accept also DaT records, which are normally ignored;
                     see section~\re{sec:random-access} 

      *NUH*:  size of the user header vector
                 on  input:  maximum size of IUHEAD
                 on output:  useful size stored in IUHEAD
               (ignored if options T, A, or D  selected)

    IUHEAD*:  user header vector
               (ignored if options T, A, or D  selected)

Normal read status returned in 272

IQUEST(1) =  -ve  error, see separate list
               0  normal completion
               1  start-of-run record
               2  end-of-run record
               3  Zebra  end-of-file
               4  system end-of-file, continuation possible
               5  system end-of-data, continuation not possible
               6  first attempt to read beyond EoD

IQUEST(2) =  number of logical records read so far

IQUEST(3) =  number of physical records read so far (exchange mode)

IQUEST(5) =  word 1 of the direct access adr of the d/s read
IQUEST(6) =  word 2                     (exchange mode only)

IQUEST(11)   if IQUEST(1)=0:  = 1 or 0 for yes/no start new event
             if IQUEST(1)=1:  = run number for start/end of run

IQUEST(12) = processing bits of pilot, normally zero

IQUEST(13) = LENTRY, the entry address into the data structure
             zero means: empty d/s
             (not yet a valid address if S option return)

IQUEST(14) = NWBK, the number of words occupied by the d/s in memory
             zero means: empty d/s

IQUEST(20) = NWIOCH, size of the I/O characteristic

IQUEST(21) = NWIOCH words of I/O characteristic
      ...           for the user header vector