topen, tclose, tread, twrite, trewin, tskipf, tstate - FORTRAN tape I/O (OBSOLETE)
This man page is provided for historical reasons only. This functionality is not implemented in Fortran 95 (f95).
You can use these functions to manipulate magnetic tapes from FORTRAN.
On any one unit, do not mix these functions with standard FORTRAN I/O.
You must first use topen() to open a tape logical unit, tlu, for the specified device. Then you do all other operations on the specified tlu. tlu has no relationship at all to any normal FORTRAN logical unit.
Before you use one of these functions, its name must be in an INTEGER statement.
topen -- Associate a device name with a tape logical unit, that is, does not move tape.
Syntax: n = topen( tlu, devnam, islabeled )
tlu is the tape logical unit. It is an integer input argument and must be in the range 0 to 7. islabeled indicates whether the tape is labeled. It is a logical input argument.
If you know the tape contains a tape label, then you set islabeled to true. A label is the first file on the tape.
n is the return value: n=0 indicates OK. n<0 indicates an error. See perror(3F) for details.
Example: Open a 1/4" tape file:
CHARACTER devnam*9 / '/dev/rst0' /
INTEGER n / 0 /, tlu / 1 /, topen
LOGICAL islabeled / .false. /
n = topen ( tlu, devnam, islabeled )
IF ( n .LT. 0 ) STOP "topen: cannot open"
WRITE(*,'("topen ok:", 2I3, 1X, A10)') n, tlu, devnam
END
The output is:
topen ok: 0 1 /dev/rst0
tclose -- Write EOF and close tape device channel and remove its association with tlu.
Syntax: n = tclose ( tlu )
tlu is the tape logical unit. It is an integer input argument in range 0 to 7. n is the integer return value. n=0 indicates OK. n<0 indicates an error. tclose() places an EOF marker immediately after the current location of the unit pointer, and then closes the unit. So if you trewin() a unit before you use tclose() it, its contents are thrown away.
Example: Close an opened 1/4" tape file:
CHARACTER devnam*9 / '/dev/rst0' /
INTEGER n / 0 /, tlu / 1 /, tclose, topen
LOGICAL islabeled / .false. /
n = topen ( tlu, devnam, islabeled )
n = tclose ( tlu )
IF ( n .LT. 0 ) STOP "tclose: cannot close"
WRITE(*, '("tclose ok:", 2I3, 1X, A10)') n, tlu, devnam
END
The output is:
tclose ok: 0 1 /dev/rst0
twrite -- Write the next physical record from buffer to tape.
Syntax: n = twrite ( tlu, buffer )
tlu is the tape logical unit. It is an integer input argument and must be in the range 0 to 7. buffer must be of type character and must be sized at a multiple of 512. n is the return value. n >0 indicates OK, and n = number of bytes written. n =0 indicates end of tape n <0 indicates an error. The physical record length is the size of buffer.
Example: Write a two-record file:
CHARACTER devnam*9 / '/dev/rst0' /, rec1*512 / "abcd" /
CHARACTER rec2*512 / "wxyz" /
INTEGER n / 0 /, tlu / 1 /, tclose, topen, twrite
LOGICAL islabeled / .false. /
n = topen ( tlu, devnam, islabeled )
IF ( n .LT. 0 ) STOP "topen: cannot open"
n = twrite ( tlu, rec1 )
IF ( n .LT. 0 ) STOP "twrite: cannot write 1"
n = twrite ( tlu, rec2 )
IF ( n .LT. 0 ) STOP "twrite: cannot write 2"
WRITE(*, '("twrite ok:", 2I4, 1X, A10)') n, tlu, devnam
END
The output is:
twrite ok: 512 1 /dev/rst0
tread -- Read next physical record from tape into buffer. If at EOF or EOT, return; do not read tape.
Syntax: n = tread ( tlu, buffer )
tlu is the tape logical unit. It is an integer input argument, and must be in the range 0 to 7. buffer must be of type character and must be sized at a multiple of 512.
The size of buffer should be large enough to hold the largest physical record to be read.
n is the return value. n <0 indicates an error. n =0 indicates the end-of-file. If n >0, then n is the actual number of bytes read.
Example: Read the first record of the file written above.
CHARACTER devnam*9 / '/dev/rst0' /, onerec*512 / " " /
INTEGER n / 0 /, tlu / 1 /, topen, tread
LOGICAL islabeled / .false. /
n = topen ( tlu, devnam, islabeled )
IF ( n .LT. 0 ) STOP "topen: cannot open"
n = tread ( tlu, onerec )
IF ( n .LT. 0 ) STOP "tread: cannot read"
WRITE(*,'("tread ok:", 2I4, 1X, A10)') n, tlu, devnam
WRITE(*,'( A4)') onerec
END
The output is:
tread ok: 512 1 /dev/rst0 abcd
trewin -- Rewind the tape to the beginning of the first data file.
Syntax: n = trewin ( tlu )
tlu is the tape logical unit. It is an integer input argument, and must be in the range 0 to 7. n is the return value. n =0 indicates OK. n <0 indicates an error. If the tape is labeled (see topen above), then the label is skipped over after rewinding.
Example 1: Typical fragment:
CHARACTER devnam*9 / '/dev/rst0' /
INTEGER n /0/, tlu /1/, tclose, topen, tread, trewin
...
n = trewin ( tlu )
IF ( n .LT. 0 ) STOP "trewin: cannot rewind"
WRITE(*, '("trewin ok:", 2I4, 1X, A10)') n, tlu, devnam
...
END
Example 2: In a two-record file, try to read 3 records, then rewind and read 1 record.
CHARACTER devnam*9 / '/dev/rst0' /, onerec*512 / " " /
INTEGER n / 0 /, r, tlu / 1 /, topen, tread, trewin
LOGICAL islabeled / .false. /
n = topen ( tlu, devnam, islabeled )
IF ( n .LT. 0 ) STOP "topen: cannot open"
DO r = 1, 3
n = tread ( tlu, onerec )
WRITE(*,'(1X, I2, 1X, A4)') r, onerec
END DO
n = trewin ( tlu )
IF ( n .LT. 0 ) STOP "trewin: cannot rewind"
WRITE(*, '("trewin ok:" 2I4, 1X, A10)') n, tlu, devnam
n = tread ( tlu, onerec )
IF ( n .LT. 0 ) STOP "tread: cannot read after rewind"
WRITE(*,'(A4)') onerec
END
The output is:
1 abcd 2 wxyz 3 wxyz trewin ok: 0 1 /dev/rst0 abcd
tskipf -- Skip forward over files or records, and reset EOF status. It does not skip backward.
Syntax: n = tskipf( tlu, nf, nr )
tlu is the tape logical unit. It is an integer input argument. It must be in the range 0 to 7. nf is the integer number of end-of-file marks to skip over first. nr is the integer number of physical records to skip over after skipping files. n is the integer return value. n=0 indicates OK. n<0 indicates an error. First, it skips nf end-of-file marks. Then it skips over nr physical records. If the current file is at EOF, this counts as one file to skip. This function also resets the EOF status. See tstate below.
Example: Typical fragment (\m skip four files and then skip one record. See also tstate, second example.
INTEGER nfiles / 4 /, nrecords / 1 /, tskipf, tlu / 1 /
...
n = tskipf( tlu, nfiles, nrecords )
IF ( n .LT. 0 ) STOP "tskipf: cannot skip"
tstate -- Determine the logical state of the tape I/O channel.
Syntax: n = tstate ( tlu, fileno, recno, errf, eoff, eotf, tcsr )
tlu is the tape logical unit. It is an integer input argument, and must be in the range 0 to 7. fileno is an integer output argument indicating the current file number. recno is an integer output argument indicating the current record number. errf is a logical output argument indicating an error occurred. eoff is a logical output argument indicating the current file is at EOF.
While eoff is true, you cannot read from that tlu. You can set this EOF status flag to false by using tskipf() to skip one file and zero records: n=tskipf( tlu, 1, 0 ). Then you can read any valid record that follows.
eotf is a logical output argument indicating the tape has reached logical end-of-tape.
EOT is indicated by an empty file, often referred to as a double EOF mark. You cannot read past EOT, but you can write past EOT.
tcsr is an integer output argument for hardware errors on the device. It contains the tape drive control status register. If the error is software, then tcsr is returned as zero. The values returned in this status register vary grossly with the brand and size of tape drive. For details, see st(4s).
Example: Write 3 files of 2 records each. The next example uses tstate() to trap eof and get at all files:
CHARACTER devnam*10 / '/dev/nrst0' /,
& f0rec1*512 / "eins" /, f0rec2*512 / "zwei" /,
& f1rec1*512 / "ichi" /, f1rec2*512 / "ni__" /,
& f2rec1*512 / "un__" /, f2rec2*512 / "deux" /
INTEGER n / 0 /, tlu / 1 /, tclose, topen, trewin, twrite
LOGICAL islabeled / .false. /
n = topen ( tlu, devnam, islabeled )
n = trewin ( tlu )
n = twrite ( tlu, f0rec1 )
n = twrite ( tlu, f0rec2 )
n = tclose ( tlu )
n = topen ( tlu, devnam, islabeled )
n = twrite ( tlu, f1rec1 )
n = twrite ( tlu, f1rec2 )
n = tclose ( tlu )
n = topen ( tlu, devnam, islabeled )
n = twrite ( tlu, f2rec1 )
n = twrite ( tlu, f2rec2 )
n = tclose ( tlu )
END
Example: Use tstate() in a loop that reads all records of the three files written in the previous example:
CHARACTER devnam*10 / '/dev/nrst0' /, onerec*512 / " " /
INTEGER f, n / 0 /, tlu / 1 /, tcsr, topen, tread, trewin
INTEGER tskipf, tstate
LOGICAL errf, eoff, eotf, islabeled / .false. /
n = topen ( tlu, devnam, islabeled )
n = tstate ( tlu, fn, rn, errf, eoff, eotf, tcsr )
WRITE(*,1) 'open:', fn, rn, errf, eoff, eotf, tcsr
1 FORMAT(1X, A10, 2I2, 1X, 1L, 1X, 1L,1X, 1L, 1X, I2 )
2 FORMAT(1X, A10, 1X, A4, 1X, 2I2, 1X, 1L, 1X, 1L,1X, 1L, 1X, I2)
n = trewin ( tlu )
n = tstate ( tlu, fn, rn, errf, eoff, eotf, tcsr )
WRITE(*,1) 'rewind:', fn, rn, errf, eoff, eotf, tcsr
DO f = 1, 3
eoff = .false.
DO WHILE ( .NOT. eoff )
n = tread ( tlu, onerec )
n = tstate ( tlu, fn, rn, errf, eoff, eotf, tcsr )
IF (.NOT. eoff) WRITE(*,2) 'read:', onerec, fn, rn, errf,
1 eoff, eotf, tcsr
END DO
n = tskipf ( tlu, 1, 0 )
n = tstate ( tlu, fn, rn, errf, eoff, eotf, tcsr )
WRITE(*,1) 'tskip: ', fn, rn, errf, eoff, eotf, tcsr
END DO
END
The output is:
open: 0 0 F F F 0
rewind: 0 0 F F F 0
read: eins 0 1 F F F 0
read: zwei 0 2 F F F 0
tskip: 1 0 F F F 0
read: ichi 1 1 F F F 0
read: ni__ 1 2 F F F 0
tskip: 2 0 F F F 0
read: un__ 2 1 F F F 0
read: deux 2 2 F F F 0
tskip: 3 0 F F F 0
EOF and EOT Summary:
If at either EOF or EOT, then:
Any tread() just returns; it does not read the tape.
A tskipf( tlu, 1, 0 ) resets the EOF status to false, and returns; it does not advance the tape pointer.
A successfull twrite() resets the EOF and EOT status flags to false.
A succesfull tclose() resets all those flags to false.
tclose() truncates. tclose() places an EOF marker immediately after the current location of the unit pointer and then closes the unit. So if you use trewin() to rewind a unit before you use tclose() to close it, its contents are discarded. This behavior of tclose() is inherited from the Berkeley code.
This man page is provided for historical reasons only. This functionality is not implemented in Fortran 95 (f95).