next up previous contents index
Next: FZENDO - output Up: User specifications for Previous: FZINXT - reset

FZCOPY - copy one data-structure from input to output

FZCOPY will copy a data-structure from the input to the output 'file' without expansion into memory and without translating the data representation, thereby saving the time which would otherwise be spent on these operations.

The file-format and the data-format of the input or the output file may be 'exchange' or 'native', but the following restrictions are imposed:

  1. the data-format of the output file must be the same as that of the input file, ie. FZCOPY will not translate between native and exchange data-format. (Note however that on some machines native and exchange data-format are identical.)
  2. the input and the output cannot both be in 'channel' mode.
  3. Alfa format is not handled.
  4. the locical record length for the input in native file-format must not be longer than 2500 words.

To copy a data-structure one has first to start reading it by calling FZIN with the S option; thereby one obtains the user header, which will normally be used to decide whether or not the copy is wanted. This 'pending' data-structure may then be copied by calling:

CALL FZCOPY (LUNIN,LUNOUT,IEVENT,options,IOCH,NUH,IUHEAD)

with  LUNIN:  logical unit number of the input file
     LUNOUT:  logical unit number of the output file

     IEVENT:  start-of-event flag
                 = 0  for event continued
                   1  for new event

    options:  character string,
               individual characters select options:

     I/O descr.:    by default the I/O descriptor from the input
                     file is used for IUHEAD

                   I use the new I/O descriptor given in IOCH for
                     the user header vector

               P special 'permit' option not normally given

       IOCH:  the I/O characteristic for the user header vector;
               this is ignored if the I option is not given;  as
               for a bank this may be either 'immediate' if the whole
               vector is of the same type, or it may be composite.

               - immediate: IOCH = 1  all bits
                                    2  all integers
                                    3  all floating
                                    4  all double precision
                                    5  all Hollerith
                                    7  self-describing

               - composite: set up with

                             CALL MZIOCH (IOCH,NW,'format')  where

                             IOCH is now a vector of NW words at most

        NUH:  number of words in the user header vector, < 401,
               may be zero, in which case IOCH is not used

     IUHEAD:  the user header vector

Status returned in 280

   IQUEST(1)  =   0 normal completion
                 +1 'pseudo end-of-tape' condition (cf. FZLIMI)
                < 0 input  error return, see below
                > 1 output error return, see below

   If normal completion:

   IQUEST(5)  =  word 1 of the direct access adr of the d/s just written
   IQUEST(6)  =  word 2
   IQUEST(9)  =  # of useful machine words ready in the user's memory
                 only for medium 'memory'
   IQUEST(11) =  NWBK, number of words of bank material
   IQUEST(12) =  NWTB, size of the relocation table
   IQUEST(13) =  number of pilot records written so far
   IQUEST(14) =  number of Mwords written so far
   IQUEST(15) =  number of words (up to 1 M) written so far
                 ie. the total is  IQUEST(15) + IQUEST(14)*10**6
                 careful: if this compound is bigger than 2G it
                          needs more than 32 bits to hold it
   IQUEST(16) =  number of logical records written so far
   IQUEST(17) =  number of physical records written (exchange mode only)

Input 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 FZCOPY
             -3  bad data
             -2  not enough space to read the d/s and its table
             -1  faulty call: no pending d/s, or: Alfa mode,
                 or: input/output have differen data format,
                 or: both input/output in channel mode,
                 or: native input record length too long;
                 (code -1 causes ZFATAL unless P option given)

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

IQUEST(3) =  number of physical records read so far (exchange mode)
Details about the error occurred are stored in IQUEST(11) ff. as described in the diagnostics chapter for FZIN.

Output error status returned in 281

Normally FZCOPY does not return to the caller for (program) errors, but exits to ZTELL or to ZFATAL. Exceptionally, some such error returns may be enabled by giving the P option in the call.

   IQUEST(1) = +2
   IQUEST(2) = 14: medium 'memory': user's memory too small


Janne Saarela
Mon May 15 08:34:47 METDST 1995