TOPEN(3F)                            BSD                             TOPEN(3F)



NAME
     topen, tclose, tread, twrite, trewin, tskipf, tstate - f77 tape I/O

SYNOPSIS
     integer function topen (tlu, devnam, label)
     integer tlu
     character*(*) devnam
     logical label

     integer function tclose (tlu)
     integer tlu

     integer function tread (tlu, buffer)
     integer tlu
     character*(*) buffer

     integer function twrite (tlu, buffer)
     integer tlu
     character*(*) buffer

     integer function trewin (tlu)
     integer tlu

     integer function tskipf (tlu, nfiles, nrecs)
     integer tlu, nfiles, nrecs

     integer function tstate (tlu, fileno, recno, errf, eoff, eotf, tcsr)
     integer tlu, fileno, recno, tcsr
     logical errf, eoff, eotf

DESCRIPTION
     These functions provide a simple interface between f77 and magnetic tape
     devices.  A "tape logical unit", tlu, is "topen"ed in much the same way
     as a normal f77 logical unit is "open"ed.  All other operations are
     performed via the tlu.  The tlu has no relationship at all to any normal
     f77 logical unit.

     topen associates a device name with a tlu.  tlu must be in the range 0 to
     3.  The logical argument label should indicate whether the tape includes
     a tape label.  This is used by trewin below.  topen does not move the
     tape.  The normal returned value is 0.  If the value of the function is
     negative, an error has occured.  See perror(3F) for details.

     tclose closes the tape device channel and removes its association with
     tlu.  The normal returned value is 0.  A negative value indicates an
     error.

     tread reads the next physical record from tape to buffer.  buffer must be
     of type character.  The size of buffer should be large enough to hold the
     largest physical record to be read.  The actual number of bytes read will
     be returned as the value of the function.  If the value is 0, the end-
     of-file has been detected.  A negative value indicates an error.

     twrite writes a physical record to tape from buffer.  The physical record
     length will be the size of buffer.  buffer must be of type character.
     The number of bytes written will be returned.  A value of 0 or negative
     indicates an error.

     trewin rewinds the tape associated with tlu to the beginning of the first
     data file.  If the tape is a labelled tape (see topen above) then the
     label is skipped over after rewinding.  The normal returned value is 0.

     A negative value indicates an error.

     tskipf allows the user to skip over files and/or records.  First, nfiles
     end-of-file marks are skipped. If the current file is at EOF, this counts
     as 1 file to skip.  (Note: This is the way to reset the EOF status for a
     tlu.)  Next, nrecs physical records are skipped over.  The normal
     returned value is 0.  A negative value indicates an error.

     Finally, tstate allows the user to determine the logical state of the
     tape I/O channel and to see the tape drive control status register.  The
     values of fileno and recno will be returned and indicate the current file
     and record number.  The logical values errf, eoff, and eotf indicate an
     error has occurred, the current file is at EOF, or the tape has reached
     logical end-of-tape.  End-of-tape (EOT) is indicated by an empty file,
     often referred to as a double EOF mark.  It is not allowed to read past
     EOT although it is allowed to write.  The value of tcsr will reflect the
     tape drive control status register.

FILES
     /usr/lib/libU77.a

SEE ALSO
     perror(3F)