One set of status words per unit will be kept in a common block (which should reside in the root for overlayed programs). The status words contain all information the routines have to know in order to operate. The shorthand notations 'physical header' and 'record header' refer to the physical and logical headers respectively of the EP format description.
Words marked '*' can be defined and changed by the user through calls to special routines (the user should not write into the status word area directly).
r, w, and r/w under 'use' means reading or writing only, or both.
Table 5.1: Overview of the status words
1 * r/w Physical block length in 16-bit words. Used for writing;
should always be a multiple of the ``magic'' 180. For the UNIX
and ``standard Fortran'' versions it is the actual block
length.
For reading, it is the upper limit of the EPIO buffer IBUF.
The user has to provide sufficient space in IBUF.
Example: for a buffer length of 1800 16-bit words, IBUF(480)
is needed on a 60-bit machine.
Default=1800
2 * r Maximum logical record length (in machine words).
Default=999999
3 * r/w Reading : as read from physical header word 11
Writing : Logical record word length (16 or 32-bits); a word
of this length will be called a ``unit'' in the following.
Default=16
4 * r/w P.h. word 5 (run number), read or written
Default=10101
5 * w If >=0, logical record type identifier (will be used as
record header word 2).
If <=0, for user purposes.
Default=0
6 * w If >=0, logical record count will be placed in record header
word 4
If <0, record header word 4 will not be set (i.e. for user
purposes).
Default=0
7 * r/w Reading : as read from physical header word 2, or 0 if no
physical header
Writing : Actual physical header length. Is automatically set
at call to EPADDH.
Default=12 (see control word 6), 24 for 32 bit p.h.
8 * w Output padding flag, values i+j
i=0 : span logical records over blocks
i=10: do not span logical records
Remark: headers will never be spanned on writing
j=1 : pad physical block with zeros to full length (i.e. write
fixed length blocks)
j=2 : pad up to next magic multiple (see control word 5)
j=3 : do not pad at all
Default=1
9 * r/w Physical header word 6 (physical record type)
Default=0 (16 bit p.h.), 1 for 32 bit p.h.
10 r/w Logical unit number
11 r/w Number of blocks read or written
12 r/w Number of records read or written
13 r/w Number of read or write parities
14 r/w Actual occupation of I/O buffer (16-bit words)
15 r/w Displacement to start of first logical record (physical
header)
16 r/w Status indicator: 0 at start, 1 writing, 2 reading.
17 r Flag for old (=1) or new (=0) EP format. Recognized when
reading.
18 r Number of headerless blocks still following (from physical
header word 9)
19 r Normally 0, 1 if last read access resulted in E.O.F.
20 r Actual number of units read, including header, in current
logical record (logical record header word 1)
21 r Logical record header length (logical record header word 3)
22 r Position indicator - Internal in EPREAD
=0 : pointer at start of logical record (header)
=1 : pointer at start of logical record (data)
=2 : pointer at end of physical header
23 r Internal pointer IP1 in EPREAD
24 r/w Internal unit name UNIVAC and Apollo only
25 * r/w VAX: Channel address (magnetic tape)
UNIVAC: -1 if tape, otherwise sector address
IBM: if 0 (default) ULP option, else NULP (see IOPACK)
NULP allows concatenation of files, ULP does not
Apollo: must be set before first read Stream _$ID
UNIX C I/O: stream address (not user settable!)
26 * r Maximum logical record header length, for calls to EPREAD with
MODE=20 (default 999999)
27 * r User wants automatic byte-swapping if 1 (default) or
suppression of it (=0).
User forces new format if 2
28 r Internal usage
29 * r/w Select physical header record format
writing: 16 bit headers = 0 (default) or 32 bit headers = 1
reading: as deduced from header words 7 and 8
30 * w Vax tape append option,
= 0 (default) new tape file,= 1 append.
31 r =Pointer to logical reader header, for random access
32 r =Internal usage
33 * r/w Select type of I/O in the UNIX version; see section ?? ``Usage
on UNIX''.
The status words are kept in a common block
COMMON/EPCOMM/NMUNIT,NWUNIT,NCONT,ISTART,LASTUT,LREF,LIST($dim)
with
These defaults may change in a later version of the package. Users who want to use or modify these values (e.g.: to support more than 10 simultaneous units) are urged to check the current values by printing the start of above COMMON block after a call to EPINIT.
These control words are kept in the first 8 locations of the array LIST in common block /EPCOMM/.
The logical record header consists of 3 words minimum, but the standard form has four words, being:
Words 2 and 4 of the logical record will always be assigned the values described above when the user writes via calls to EPOUTS.
For use with EPOUTL, two status words, number 5 and 6, are used to assign values in the following way:
let the status words be S5, S6, S12 and the header words be H2, H4,then
Full padding, partial padding, and no padding have certain consequences on the different computers, and should therefore be considered beforehand.
Table 
explains the meaning of the integer IERR
returned as the last parameter of most EPIO subroutine calls,
zero meaning no error.
For each error two types of routines are quoted: those called by the user,
and in which the error condition was detected, and those in which the
error occurred.
Control is always returned to the user, but some of the errors (marked by * in first column) are so serious that it becomes meaningless to continue reading or writing on the unit concerned, at least after a limited number of them.
Table 5.2: Overview of the error codes
Error Routine User Meaning
routine
----------------------------------------------------------------------------
1 EPBLIN EPREAD End of file on reading or open failure on
IBM
EPBOUT EPOUTL reading or writing
EPOUTS
2 EPBLIN EPREAD r/w parity, or I/O error (IBM)
EPBOUT EPOUTL
EPOUTS
EPRWND
3 EPBLIN EPREAD end of information on reading, or in some
cases after an open error on IBM
4* EPBLIN EPREAD physical record length <=0
5* EPBLIN EPREAD physical record length of record just read >
actual length of block read or user buffer
too small
6 see ) EPREAD user record chopped (IREC too small, status
word 2) the actual length (including header)
can be retrieved from status word 20 using
EPGETW
7* see ) EPREAD physical header error; could be a record in
the old format
8 see ) EPOUTS invalid mode specified in call
EPOUTL
EPREAD
9 see ) EPREAD call to EPREAD with mode 11, 12, or 13,
without prior call with MODE=20
You can also get this error reading OLD for-
mat, with MODE=20 followed by 11, 12 or 13
10 EPBLIN EPREAD end-of-run (logical record length = 0)
11* EPBOUT EPOUTS unit not declared on JCL card,
EPOUTL or wrong BLKSIZE (only IBM)
EPBLIN EPREAD
12 EPBOUT EPOUTS end of volume, or unrecovered write
EPOUTL parity (only IBM [?])
EPCLOS
EPRWND
13 EPUNIT EPOUTS maximum number of units reached
EPOUTL
EPRWND
EPADDH
EPSETW
EPSETA
EPREAD
EPGETA
EPGETW
14 see ) EPDROP unit does not exist
EPADDH
EPEND
15 see ) EPOUTS logical record header (or complete record)
EPOUTL too long to fit in physical block
16 see ) EPGETW status word address out of range
EPGETA
EPSETW
EPSETA
17 see ) EPADDH user switches from reading to writing
EPREAD or vice versa, without rewinding unit
EPOUTL
EPOUTS
18 see ) EPREAD displacement to start of logical record
inconsistent with current logical record
length, not tested by EPFRD
Logical records may be of fixed or variable length. A logical record may be entirely contained in one physical record or may overflow into one or more physical records. Normally an event or trigger corresponds to one logical record but it may equally well consist of a sequence of related logical records.
Physical records may be of fixed or variable length.
A fixed record length is recommended (for ease of reading using standard system and particularly FORTRAN, input routines). A fixed record length is particularly important if the record has no header specifying the length.
A record length which is a multiple of 360 bytes is recommended (corresponding to an integral number of 16, 18, 24, 32, 36, 48, 60, 64-bits).
The following table indicates the increase in tape utilisation with record
length up to the maximum of 32K bytes for IBM 370 [4].
It is recommended that logical records relating to the same experimental conditions or 'run' are grouped in one file.
For unlabelled tapes the end-of-file (and end-of-run) is indicated by one EOF mark.
For labelled tapes the end-of-file (and end-of-run) is indicated by an EOF mark and the associated EOF records [5].
End-of-data on the tape (and end-of-file) is indicated by two consecutive EOF marks. It is NOT recommended that files (runs) span from one tape to another.
End-of-tape. It is NOT recommended to write past the EOT reflective marker, therefore, on detection of the EOT marker, the software should backspace over a sufficient number of data records to allow the required end-of-run and EOF records to be written.
Record formats. Logical records and physical records, (i.e. physical tape blocks) normally consist of a number of header words, followed by data. In some cases the number of header words in a physical record may be 0.
Word lengths. All lengths in the physical header are expressed in words where a word is defined as a 16-bit unsigned integer. The logical record wordlength is defined in the physical record header.
A logical record normally has a minimum of three header words followed by data. The logical record wordlength is defined in the physical record header. Logical record headers with 32 bit words should have their 16 bit components in ``IBM'' order.
Each physical record normally has a variable length physical record header, followed by data. However, certain records, following a record with a suitable header may have no header. The word length may be 16 or 32 bits but in both cases the values of lengths and pointers are in units of 16 bits.
The physical header identifier fields (7 and 8) are used by the off-line package to identify the header word length, to help in error detection and recovery, and to decide if byte swapping is required. For the 32 bit header words, the least significant 16 bits are in the leftmost 16 bits of the word, i.e. "IBM format". The off-line package achieves this by calling CTOIBM before the header is output.
Next: References
Up: EPIO
Previous: Auxiliary routines used