To initialize a Zebra file:
Fortran: OPEN (LUN, FILE=name, ...
C: CALL CFOPEN (LUNPTR, ..., name, ...)
IQUEST(1) = LUNPTR
CALL FZFILE (LUN,LREC,CHOPT)
with LUN: logical unit number (Fortran)
or Zebra stream identifier (otherwise),
this must be a unique small positive integer
LREC: record length, in words (ignored if A option)
native file format - maximum logical record length
zero: standard limit: 2440 words
+ve: user defined limit, but < 2500
exchange file format - physical record length
zero: standard length: 900 words
+ve: user defined length
must be a multiple of 30 words
CHOPT: character string,
individual characters select options:
medium: * sequential binary disk file, default
T magnetic tape
D direct access disk file
A alfa: 80 column card-image disk file
C channel mode
M memory mode
usage: F read/write with Fortran, default (except IBM)
Y read/write with special machine specific code
(IBM has IOPACK, NORD has MAGTAP)
L read/write with interface to the C Library
K read/write with user supplied code
file format: native file format is default
X exchange file format
modes M, C, A, D, L, K all imply 'X'
data format: native is default for native file format
exchange is default for exchange file format
N native data format
direction: default direction is 'input only'
I input enabled
O output enabled
IO input/output enabled
various: S separate d/ss
U unpacked d/ss, only with modes M or C
R initial rewind
Q quiet, set logging level to -2
P permissive, enable error return,
see 'Status returned' just below
NEOF: handling of system EoF
for output:
0 write no file-marks at all
1 write file-mark only for End-of-File
2 write file-mark only for End-of-Data
3 write file-marks both for EoF and EoD
for input:
1 or 3 one file-mark signals 'end-of-file',
otherwise: file-mark signals 'end-of-data'
IQUEST(1) = 0 all is well
1 file has already been initialized with FZFILE
2 LUN is invalid
3 requested format is not available on the particular
Zebra library (either because of the installation
options taken, or because the code is not ready
for the particular machine)
4 the file pointer is zero for modes L or K
The error returns are enabled only if the P option is selected, otherwise control goes to ZFATAL. If the P option is selected, the status must be checked, because the file will not be initialized if an error exit is taken.
M C A D T * K L Y
channel C - + combination useful
alfa A - - - combination not allowed
direct D - + - i option implied
tape T - - - d option default
neither * - - - - - ? depends on the user's
implementation
user K - - - ? ? +
lib C L - - - + + + -
special Y - - - - + + - -
Fortran F - - i d d d - - -
exchange X i i i i + + i i i
native N + + + + + d + + +
separate S i + + + + + + + +
unpacked U + + - - - - - - -
M C A D T * K L Y
FZFILE initializes only the Zebra controls for this file; the opening of the file has to be done by the user in his calling program, according to the needs of his machine and operating system.
if the file is to be handled with Fortran READ/WRITE one needs an
OPEN statement; one will find some hints in chapter 
.
for modes L or K the file should be opened by calling CFOPEN
(see the specifications at the end of this paragraph)
and the 'file pointer' returned by CFOPEN must be passed
on to FZFILE via IQUEST(1).
this is the Zebra stream identifier which will be used in all subsequent calls for this file; if the file is to be handled with Fortran this is at the same time the logical unit number.
for exchange file format it is important to choose a good value for
all one's files, and then stick to it.
One has to compromise between conflicting things:
on tapes one would like to make this large,
but this costs memory for the Zebra buffer,
multiplied by the number of files concurrently open,
and it wastes disk space for end-of-run records which occupy
a whole physical record.
Some numbers can be found in chapter .
The physical record size for the exchange file format needs to be specified both to Zebra with FZFILE and to the system with the OPEN statement and maybe even with some JCL, in which case the user may need to know this: the block size is specified to Zebra in words, the default is 900 words. These words correspond to words in the Zebra dynamic store, such that a bank of 900 words could just fill one block. Except for 32-bit machines, the number of bits written to the file for each word depends on the data format: for the exchange data format each word generates 32 bits, for the native data format a full machine word is transferred. To the system the block size has to be specified either in bytes or in native words. For example, on the CRAY (64-bit words) the record-size of a standard block will have to be given as 7200 bytes (900 machine words) for the native data format, but as 3600 bytes (450 machine words) for the exchange data format.
for the media 'memory' and 'channel' the Exchange File Format is implied, and this cannot be changed. The Native Data Format can be selected by giving the N option. Instructions on the use of these media is given in separate sections near the end of this chapter.
Alfa mode should only be used to transmit data over a network connection which cannot handle binary file transfers. The character representation (ASCII, EBCDIC, etc) used is that of the originating machine; the translation is expected to happen in the network station. Alfa mode must not be used for writing magnetic tapes, it is at least a factor of ten slower than binary.
this serves two different purposes: on some machines Fortran is not capable of handling fixed-length records without system control words in sequential mode, only in direct-access mode, but this only for disk files. A side-effect advantage is better error recovery from lost records on files which have been moved from tape to disk. No timing studies have yet been made to check whether direct access is slower than sequential acccess.
The other purpose is random access to the d/ss on the file,
this is described in section
``Usage for random access''.
Selecting D only gives the possibility, but no obligation for
random access: for input Zebra will read the file sequentially
except at moments when the user interfers with calls to FZINXT;
for output Zebra operates strictly sequentially.
at the moment no distinction is made internally in Zebra between disk and tape files (exception: NORD), but it may turn out that the C interface will have to have a separate branch for tape files on some machines.
read/write with Fortran, option F, is the default if none of Y, L, K are specified. Exception IBM: up to including Zebra version 3.66 the default for sequental files is Y, that is handling with IOPACK; from version 3.67 onwards the default will be F. Most people give now (version 3.65) option F, those who really want IOPACK should change their programs to request Y to be insensitive to the transition to 3.67. The only other machine sensitive to Y is presently the NORD: magnetic tapes must be written through the MAGTAP utility, on this machine TX implies Y.
read/write is with the routines CFGET/CFPUT which are part of the
interface to the C Library for handling files with fixed-length records.
This mode must be used for exchange file format tape files on those
Unix machines where Fortran does not provide the parameter
RECORDTYPE='FIXED' (or equivalent) in the OPEN statement,
like the Sun, or SGI, or DecStation.
On the same machines one might use this also for disk files as
an alternative to option D; no studies have yet been made to
see which is faster.
L can be combined with D for random access using the C interface.
this is a hook to enable a user to write his own handling of physical
records in case that none of the modes provided are satisfactory.
Chapter gives some hints of how to do this.
default is 'native' if none of A , C , D , K , L , M is given, which necessarily operate with exchange file format.
for native file format this is 'native'; for exchange file format data format 'exchange' is assumed by default, but native data format can be requested by giving the N option. In this case LREC native words are written for each physical record, and no data translation, packing, or byte inversion, is done.
the option IO is needed in two separate cases: - if the program first writes a new file which it then reads; - if the program positions an existing file by reading for further output. In this case the input or output mode of the file is defined by the first I/O action on the file; it can be changed at the end of the first phase only with FZENDI from input to output, or with FZENDO the other way round.
for the exchange file format, FZOUT normally places the start of a given d/s just after the end of the previous structure in the same physical record, to economize file space. This may be inconvenient if the file is later to be handled by means other than calling FZIN: giving the S option will force each d/s to start on a new physical record. For the medium 'memory' the S option is implied.
only for media 'memory' and 'channel': When handling the physical records for the Data Format 'exchange' it may be more convenient for the user to do himself the unpacking (FZIN) or packing (FZOUT) operation needed, because in this case he has immediate access to the control information in the records. (Note: on the VAX 'packing/unpacking' is in fact byte inversion.) The U option allows this: if given, FZOUT delivers the data non-packed, and FZIN expects data which have already been unpacked by the user.
if the initial REWIND is selected the file has to be OPENed before calling FZFILE.
giving this option suppresses message printing for this file.
this parameter controls for output
the explicit writing of system file-marks;
for input it controls the interpretation of a system file-mark,
which can mean either end-of-file or end-of-data
(two file-marks in succession always act as end-of-data).
On most machines the default value is NEOF=0,
meaning single-file files only.
This can be over-ridden by giving the 1, 2, or 3 option
if multi-file files must be handled.
See also section for more explanations.
Since this is a new KERNLIB routine not yet documented we print this here.
CALL CFOPEN (LUNPTR*,MEDIUM,NWREC,IOMODE,NBUF,NAME,ISTAT*)
LUNPTR* is the 'file pointer' returned by the C library
routine 'fopen', CFOPEN returns it to the caller who
must hand it on to FZFILE via IQUEST(1).
This will be zero if the open fails.
MEDIUM = 0 for disk file, normal
1 tape file, normal
2 disk file, user coded I/O
3 tape file, user coded I/O
NWREC the number of machine words per physical record, this
is used to calculate the buffer size if NBUF not zero.
MODE the 'type' parameter of 'fopen', of type CHARACTER:
r open for reading
w truncate or create for writing
a append: open for writing at end of file, or
create for writing
r+ open for update (reading and writing)
w+ truncate or create for update
a+ append; open or create for update at EOF
NBUF not currently used, always give zero
NAME the name of the file, of Fortran type CHARACTER.
ISTAT* status returned, zero if all is well,
otherwise a system error code.