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