User Routines

Initialisation

CALL EPINIT

Must be called once per job, in the root. Pulls common block /EPCOMM/ in and initializes the package.

More than 10 units can be handled simultaneously as follows:

1. Load a common block /EPCOMM/ that is big enough (see
   dim as dimension of LIST, table )
2. After the call to EPINIT set NMUNIT to the new maximum.

Reading

CALL EPREAD (LUNIT,MODE,NW*,*IREC*,IBUF*,IERR*)

Input parameters:

LUNIT

logical unit number

MODE

=j, j=1,2,3 : get next logical record data
j=1 : data transferred in packed form
j=2 : data unpacked as 16-bit bytes/word
j=3 : data unpacked as 32-bit bytes/word
=10+j, j=1,2,3 as above: get data of current logical record (only possible after a previous call with j=20).
=20 : get header of next logical record. The header will always be unpacked in units (16 or 32-bit words).
=30 : get next physical header.
The header will always be unpacked in units.

Input/Output buffer:

IBUF

user provided unit buffer. Must not be touched by user. Minimum size = (16*status word 1 - 1)/(bits/word) + 1

Output parameters:

NW

no. of words transferred into IREC.
For j=1 no. of units, for j=2 or j=3 no. of 16 or 32-bit words, i.e., number of machine words occupied in IREC

IREC

user provided area to store the header or data requested

IERR

error flag. See separate list.

Remarks:

1. For reading the old EP format status word 27 must be set to zero by a

   CALL EPSETW(LUN,27,0,IERR)

   and the previous call in the old ``EVENT'' package

   CALL EVENT(IARRAY,ISTAT)

   has to be replaced by a call to EPREAD with j=2. In this case, as for EVENT, the complete record (including the header) will be transferred. Please note that the data now start in IREC(1), instead of IARRAY(2) as before and the data are unpacked as 16-bit bytes/word only.

   Old format ``special records'' are not specifically decoded by EPREAD but return IERR=7. The user is left to do the unpacking himself, e.g.:

   CALL EPREAD(LUN,2,NW,irec,IBUF, ierr)
       :
       :
       IF (IERR.NE.7) GO TO 10
       NW=IWD16(IBUF,1)
       CALL BLO16W(IBUF,1,IREC,1,NW)
      10 CONTINUE

2. To read consecutive files of multifile tapes the user has only to make further calls to EPREAD after each end of file (signified by IERR=1). In the case of labelled tapes the labels will be treated as data and EPREAD will return a length error on reading (IERR=5). The user program should choose to continue reading in this case. A combination of these techniques with MODE=30 can provide the same facilities as EVENTIN in the old package. To prevent tapes running off the end of reel users should stop reading at end of information (IERR=3), signified by 2 consecutive EOF's, or by using the file or record count.

CALL EPFHDR (LUNIT,MLUSER,IHEAD*,*IBUF*,IERR*)

Fast logical record header reading routine.

Input parameters:

LUNIT

user unit number

MLUSER

no. of header words transferred to user

Input/Output buffer:

IBUF

user buffer

Output parameters:

IHEAD

MLUSER words of logical record header (regardless of actual length or of status word 26)

IERR

error number

Conditions for use:

1. 16-bit units only (i.e. logical record header consists of 16-bit words)
2. No spanned headers
3. Always MLUSER words transferred to user (word 3 is header length). This may exceptionally lead to a program range error if the input buffer IBUF coincides with the end of the user program. Remedy: increase size of IBUF by 16*MLUSER/(no. of bits per word)
4. No headerless blocks
5. No old EP format
6. No unknown length records

Calls to this routine are entirely compatible with EPREAD calls.

CALL EPFRD (LUNIT,MODE,NW,IREC,IBUF,IERR)

Fast logical record data reading routine.

Input parameters:

UNIT

user unit number

MODE

one of 11, 12, 13 (see EPREAD)

/Input/Output buffer:

IBUF

user buffer

Output parameters:

NW

no. of words in IREC

IREC

record transferred to user

IERR

error number

Conditions for use:

1. 16-bit units only (i.e. logical record header consists of 16-bit words)
2. no headerless blocks
3. no old EP format
4. no unknown length records
5. modes 11, 12, 13 only (otherwise error 8)

The routine is poorly protected against bad user data on input, and may lead to program aborts in cases where EPREAD would recover. In particular EPFRD does not test for the condition which leads to IERR=18 from EPREAD, and performs unpredictably in the case of this condition.

Therefore, in case the user wants to be better protected (e.g., after a fatal error in EPFRD), he should use EPREAD.

Calls to this routine are entirely compatible with EPREAD calls.

Writing

CALL EPOUTS (LUNIT,MODE,NW,IREC,*IBUF*,IERR*)

Writes one record with standard logical record header (4 words, see important remark on logical record headers in section .

Input parameters:

LUNIT

logical unit number

MODE

transfer more

1:

transfer data as they are (bit string)

2:

pack data before writing, given as 16-bit right adjusted

3:

pack data before writing, given as 32-bit right adjusted

NW

no. of words to be written.
For MODE=1 in units (as defined by physical header word 11), for MODE=2 or =3 in 16 or 32-bit words respectively, i.e. the number of machine words occupied

IREC

area containing the user data.

Input/Output buffer:

IBUF

user provided unit buffer. Must not be touched by user.
Minimum size = (16*status word 1 - 1)/(bits/word) + 1

Output parameters:

IERR

error flag. See separate list.

CALL EPOUTL (LUNIT,MODE,NH,IH,NW,IREC,*IBUF*,IERR*)

This routine writes a user specified logical record header in front of the data, instead of the header produced automatically from the status words. Words 1,3 (and possibly 2 and 4) will be set by the writing routine in any case (basic protection).

The logical record data are given in the same call.

Input parameters:

LUNIT

logical unit number

MODE

transfer more

1:

transfer data as they are (bit string)

2:

pack data before writing, given as 16-bit right adjusted

3:

pack data before writing, given as 32-bit right adjusted

NH

header length in words

IH

array containing header (in unpacked form)

NW

no. of words to be written.
For MODE=1 in units (as defined by physical header word 11), for MODE=2 or =3 in 16 or 32-bit words respectively, i.e. the number of machine words occupied

IREC

area containing the user data.

Input/Output buffer:

IBUF

user provided unit buffer. Must not be touched by user.
Minimum size = (16*status word 1 - 1)/(bits/word) + 1

Output parameters:

IERR

error flag. See separate list.

CALL EPCLOS (LUNIT,*IBUF*,IERR*)

Routine to close output units (write existing physical buffer out - writing may continue afterwards). The physical block count will continue from its current value at re-opening.

Closing an input unit has no effect.

Input parameters:

LUNIT

logical unit number

Input/Output buffer:

IBUF

user provided unit buffer. Must not be touched by user.

Output parameters:

IERR

error flag. See separate list.

Auxiliary Unit Operations-Rewind

CALL EPRWND (LUNIT,*IBUF*,IERR*)

Rewinds to the start of the current file in use on this unit.

Rewinding an output unit triggers writing the last buffer out and writes an end of file. After a rewind operation (and only in that case) the user may switch from reading to writing or vice versa.

The physical header is reset to the standard header after a rewind.

Input parameters:

LUNIT

logical unit number

Input/Output buffer:

IBUF

user provided unit buffer. Must not be touched by user.

Output parameters:

IERR

error flag. See separate list.

Note:

On the Apollo rewinding a magnetic tape file is done by explicitly closing the stream.

Drop

CALL EPDROP (LUNIT,IERR*)

Drops an existing unit. User should call EPCLOS beforehand when writing. This concerns only this package, i.e. the space in common block /EPCOMM/ becomes free for another unit. For the system, the unit still exists, and may therefore be ``opened'' again later. The physical block count will be reset at re-opening.

Input parameters:

LUNIT

logical unit number

Output parameters:

IERR

error flag. See separate list.

Write EOF mark

CALL EPEND (LUNIT,*IBUF*,IERR*)

Acts like EPCLOS, but in addition writes an end of file mark on LUNIT if output unit. On IBM and UNIVAC it must be called to properly terminate output units.

Note that on IBM this has the same effect as EPCLOS - the filemark written is backspaced over so a new write to the same logical unit will not result in a new physical file but will merely continue the existing file. Users who really want to write a multi-file tape on IBM within the same job step must call EPEND and then IODD [3].

Input parameters:

LUNIT

logical unit number

Input/Output buffer:

IBUF

user provided unit buffer. Must not be touched by user.

Output parameters:

IERR

error flag. See separate list.

Utility Routines

CALL EPUREF (LUNIT)

Returns internal reference number for logical unit in LREF in the common block /EPCOMM/. If LUNIT is invalid or there are no units open, then LREF=0.

Input parameters:

LUNIT

logical unit number

CALL EPDEFU (LUNIT,CHNAME,IERR*)

Allows to specify a file name other than the EPIO default name.

Input parameters:

LUNIT

logical unit number

CHNAME

Character variable, specifying the file name.

Output parameters:

IERR

error flag. See separate list.

Get Status Words

CALL EPGETW (LUNIT,NUMBER,IW*,IERR*)

Input parameters:

LUNIT

logical unit number

NUMBER

Number of the desired status word.

Output parameters:

IW

value of the status word.

IERR

error flag. See separate list.

CALL EPGETA (LUNIT,NW,IWS*,IERR*)

Input parameters:

LUNIT

logical unit number

NW

Number of desired status words (always start at word 1).

Output parameters:

IWS

value of status words 1..NW.

IERR

error flag. See separate list.

CALL EPGETC (NWCONT*,IWCONT*)

Output parameters:

NWCONT

no. of overall control words (word 3 of common /EPCOMM/).

IWCONT

control words (words 1..NWCONT of list of common /EPCOMM/)

Set Status Words

These routines enable the user to change defaults kept in the status words, such as the maximum length of the physical block he wants to read, the maximum length of the logical record, and so on.

Normally, control words should be changed before any writing on that unit takes place. Otherwise, it is strongly recommended to make a close call to the corresponding unit (EPCLOS) beforehand in order to avoid problems. The user should be fully aware of what he is doing, and foresee the possible effects of any change.

For the use of EPSETA, and EPSETC (setting more than one word), it is recommended to get hold of the existing status words by calls to EPGETA or EPGETC, modify where desired, and restore.

CALL EPSETW (LUNIT,NUMBER,IWORD,IERR*)

Input parameters:

LUNIT

logical unit number

NUMBER

Number of the status word to change.

IWORD

new value of the status word.

Output parameter:

IERR

error flag. See separate list.

CALL EPSETA (LUNIT,NW,IWORDS,IERR*)

Input parameters:

LUNIT

logical unit number

NW

Number of status words to set (always start at word 1).

IWORDS

new value for the status words 1..NW.

Output parameter:

IERR

error flag. See separate list.

CALL EPSETC (NW,IW)

Input parameters:

NW

no. of overall control words to set (from 1 up to NCONT)

IW

new overall control words.

CALL EPADDH (LUNIT,NH,IH,*IBUF*,IERR*)

Adds a user portion to the standard physical header. The current block is written out beforehand if not empty.

The physical header is reset to the standard header after a rewind.

Input parameters:

LUNIT

logical unit number

NH

number of 16-bit words to add (0 resets the standard physical header).

IH

user physical header words to add (16-bit, right adjusted, 0 filled)

Input/Output buffer:

User provided unit buffer. Must not be touched by the user.

Output parameter:

IERR

error flag. See separate list.

CALL EPUPDH (LUNIT,NH,IH,IBUF,IERR)

Updates the (optional) user portion of the physical block header. The necessary space for this optional portion must have been reserved by the user through a previous call to EPADDH (typically once at the start of the job). Whereas a call to EPADDH causes the existing (if any) block to be written out, EPUPDH does not have this effect.

Input parameters:

LUNIT

logical unit number

NH

no. of user words in header to be updated. It is cut at the actual no. of extra user words available in the physical block header.

IH

Array containing the new values. Words 1..NH of IH will replace the current words 1..NH of the user portion in the header.

Input/Output buffer:

User provided unit buffer. Must not be touched by the user.

Output parameter:

IERR

error flag. See separate list.

Print Overall Status

CALL EPSTAT

Prints the overall control words, and all unit status words in their

actual state. Useful for debugging.

CALL EPIOT (LUN)

Print PAM title on LUN.