TAPEIO USER'S GUIDE     1982-SEP-16     JWB     REVISION 0    PAGE 1

Purpose:   Perform tape block I/O and positioning functions.

Overview:  TAPEIO contains entry points for opening, closing,
           reading, writing, and positioning magnetic tapes.
           It is intended for "foreign" (i.e. not VAX/VMS
           labelled) tapes which cannot be processed using Fortran
           I/O.  (Note that fixed-blocked tapes CAN be processed
           with Fortran I/O.)  To be used with TAPEIO, tape(s)
           must be mounted /FOREIGN.  This can be done with the
           $MOUNT command, or with subroutine MOUNTF (described
           separately).  TAPEIO uses the RMS Block I/O facility.
           Positioning commands use QIOW calls.

Restrictions:  You can have at most one input and one output file
               open at any given time.  You must close a file
               before opening another for the same function.
               Records may not span blocks.

Linking:   Include in your $LINK command or linker options file:

           ...,BUILD:[BLDUTIL.LIB]TAPEIO.OBJ,...

Opening and Closing Files:

CALL TOPENR(DEVICE,MAXLBK,  STATUS,SYSTAT)

   Open a tape device for reading.

CALL TOPENW(DEVICE,MAXLBK,  STATUS,SYSTAT)

   Open a tape device for writing.

   INPUTS: DEVICE - CHAR*(*) - Logical or physical device name.
           MAXBLK - INTEGER  - Maximum number of bytes in a block.

   OUTPUT: STATUS - INTEGER - 1 = OK,
                            - 3 = error opening file,
                            - 4 = error connecting record stream.
           SYSTAT - INTEGER - System status code.

CALL TCLOSR(DEVICE,  STATUS,SYSTAT)

   Close a tape file that was opened by TOPENR.

CALL TCLOSW(DEVICE,  STATUS,SYSTAT)

   Close a tape file that was opened by TOPENW.

   INPUT:  DEVICE - CHAR*(*) - Logical or physical device name.

   OUTPUT: STATUS - INTEGER - 1 = OK.
           SYSTAT - INTEGER - System status code.


TAPEIO USER'S GUIDE     1982-SEP-16     JWB     REVISION 0    PAGE 2

Reading and Writing Blocks:

CALL TPREAD(BUFSIZ,  BUFFER,LENGTH,STATUS,SYSTAT)

   Read a tape block into BUFFER.  (You must call TOPENR first.)

   INPUT:  BUFSIZ - INTEGER - Size of BUFFER, bytes.

   OUTPUT: BUFFER - INTEGER(BUFSIZ/4) - Input buffer
                  - or BYTE(BUFSIZ)
           LENGTH - INTEGER - Block length read, in bytes.
           STATUS - INTEGER - 1 = OK,
                            - 2 = end of file,
                            - 3 = error - file not open for input,
                            - 4 = error - read failure - see SYSTAT.
           SYSTAT - INTEGER - System status code.

CALL TPWRIT(BUFSIZ,BUFFER,LENGTH,  STATUS,SYSTAT)

   Write a tape block from BUFFER.  (You must call TOPENW first.)

   INPUT:  BUFSIZ - INTEGER - Size of BUFFER, bytes (not used).
           BUFFER - INTEGER(BUFSIZ/4) - Output buffer
                  - or BYTE(BUFSIZ)
           LENGTH - INTEGER - Block length to write, in bytes.
                              (Should be .LE. BUFSIZ; must be
                               .LE. MAXBLK as specified in TOPENW.)

   OUTPUT: STATUS - INTEGER - 1 = OK,
                            - 2 = end of file / end of medium,
                            - 3 = error - file not open for output,
                            - 4 = error - write failure - see SYSTAT.
           SYSTAT - INTEGER - System status code.

Device Positioning Calls:

(You should NOT have a file open on DEVICE when making these calls.)

CALL TPSKPF(DEVICE,  STATUS,SYSTAT)

   Skip forward past next end of file, but not past a double EOF.

CALL TPREWD(DEVICE,  STATUS,SYSTAT)

   Rewind a tape device.  Return when rewind completes.

CALL TPREWO(DEVICE,  STATUS,SYSTAT)

   Rewind a tape device, and put it offline.  Return immediately.

   INPUT:  DEVICE - CHAR*(*) - Logical or physical device name.
   OUTPUT: STATUS - INTEGER  - 1 = OK,
                             - 3 = channel assignment error,
                             - 4 = I/O error.
           SYSTAT - INTEGER  - System status code.