[unix-history] / usr / man / man3 / topen.3f

.TH TOPEN 3F "18 July 1983"
.UC 4
.SH NAME
topen, tclose, tread, twrite, trewin, tskipf, tstate \- f77 tape I/O
.SH SYNOPSIS
.B integer function topen 
(tlu, devnam, label)
.br
.B integer
tlu
.br
.B character*(*)
devnam
.br
.B logical
label
.sp 1
.B integer function tclose
(tlu)
.br
.B integer
tlu
.sp 1
.B integer function tread
(tlu, buffer)
.br
.B integer
tlu
.br
.B character*(*)
buffer
.sp 1
.B integer function twrite
(tlu, buffer)
.br
.B integer
tlu
.br
.B character*(*)
buffer
.sp 1
.B integer function trewin
(tlu)
.br
.B integer
tlu
.sp 1
.B integer function tskipf
(tlu, nfiles, nrecs)
.br
.B integer
tlu, nfiles, nrecs
.sp 1
.B integer function tstate
(tlu, fileno, recno, errf, eoff, eotf, tcsr)
.br
.B integer
tlu, fileno, recno, tcsr
.br
.B logical
errf, eoff, eotf
.SH DESCRIPTION
These functions provide a simple interface between f77 and magnetic
tape devices.
A ``tape logical unit'',
.IR 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
.IR tlu .
The
.I tlu
has no relationship at all to any normal f77 logical unit.
.PP
.I Topen
associates a device name with a
.IR tlu .
.I Tlu
must be in the range 0 to 3.
The logical argument
.I label
should indicate whether the tape includes a tape label.
This is used by
.I trewin
below.
.I 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
.IR perror (3F)
for details.
.PP
.I Tclose
closes the tape device channel and removes its association with
.IR tlu .
The normal returned value is 0.
A negative value indicates an error.
.PP
.I Tread
reads the next physical record from tape to
.IR buffer .
.I Buffer
.B must
be of type
.BR character .
The size of
.I 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.
.PP
.I Twrite
writes a physical record to tape from
.IR buffer .
The physical record length will be the size of
.IR buffer .
.I Buffer
.B must
be of type
.BR character .
The number of bytes written will be returned.
A value of 0 or negative indicates an error.
.PP
.I Trewin
rewinds the tape associated with
.I tlu
to the beginning of the first data file.
If the tape is a labelled tape
(see
.I topen
above)
then the label is skipped over after rewinding.
The normal returned value is 0.
A negative value indicates an error.
.PP
.I Tskipf
allows the user to skip over files and/or records.
First,
.I 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
.IR tlu .)
Next,
.I nrecs
physical records are skipped over.
The normal returned value is 0.
A negative value indicates an error.
.PP
Finally,
.I 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
.I fileno
and
.I recno
will be returned and indicate the current file and record number.
The logical values
.IR errf ,
.IR eoff ,
and
.I 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
.I tcsr
will reflect the tape drive control status register.
See
.IR ht (4)
for details.
.SH FILES
.ie \nM /usr/ucb/lib/libU77.a
.el /usr/lib/libU77.a
.SH "SEE ALSO"
ht(4), perror(3F), rewind(1)
Commit	Line	Data
e300f457 C	1	.TH TOPEN 3F "18 July 1983"
	2	.UC 4
	3	.SH NAME
	4	topen, tclose, tread, twrite, trewin, tskipf, tstate \- f77 tape I/O
	5	.SH SYNOPSIS
	6	.B integer function topen
	7	(tlu, devnam, label)
	8	.br
	9	.B integer
	10	tlu
	11	.br
	12	.B character()
	13	devnam
	14	.br
	15	.B logical
	16	label
	17	.sp 1
	18	.B integer function tclose
	19	(tlu)
	20	.br
	21	.B integer
	22	tlu
	23	.sp 1
	24	.B integer function tread
	25	(tlu, buffer)
	26	.br
	27	.B integer
	28	tlu
	29	.br
	30	.B character()
	31	buffer
	32	.sp 1
	33	.B integer function twrite
	34	(tlu, buffer)
	35	.br
	36	.B integer
	37	tlu
	38	.br
	39	.B character()
	40	buffer
	41	.sp 1
	42	.B integer function trewin
	43	(tlu)
	44	.br
	45	.B integer
	46	tlu
	47	.sp 1
	48	.B integer function tskipf
	49	(tlu, nfiles, nrecs)
	50	.br
	51	.B integer
	52	tlu, nfiles, nrecs
	53	.sp 1
	54	.B integer function tstate
	55	(tlu, fileno, recno, errf, eoff, eotf, tcsr)
	56	.br
	57	.B integer
	58	tlu, fileno, recno, tcsr
	59	.br
	60	.B logical
	61	errf, eoff, eotf
	62	.SH DESCRIPTION
	63	These functions provide a simple interface between f77 and magnetic
	64	tape devices.
65	A ``tape logical unit'',
66	.IR tlu ,
67	is ``topen''ed in much the same way as a normal f77 logical unit
68	is ``open''ed.
69	All other operations are performed via the
70	.IR tlu .
71	The
72	.I tlu
73	has no relationship at all to any normal f77 logical unit.
74	.PP
75	.I Topen
76	associates a device name with a
77	.IR tlu .
78	.I Tlu
79	must be in the range 0 to 3.
80	The logical argument
81	.I label
82	should indicate whether the tape includes a tape label.
83	This is used by
84	.I trewin
85	below.
86	.I Topen
87	does not move the tape.
88	The normal returned value is 0.
89	If the value of the function is negative, an error has occured.
90	See
91	.IR perror (3F)
92	for details.
93	.PP
94	.I Tclose
95	closes the tape device channel and removes its association with
96	.IR tlu .
97	The normal returned value is 0.
98	A negative value indicates an error.
99	.PP
100	.I Tread
101	reads the next physical record from tape to
102	.IR buffer .
103	.I Buffer
104	.B must
105	be of type
106	.BR character .
107	The size of
108	.I buffer
109	should be large enough to hold the largest physical record to be read.
110	The actual number of bytes read will be returned as the value of the
111	function.
112	If the value is 0, the end-of-file has been detected.
113	A negative value indicates an error.
114	.PP
115	.I Twrite
116	writes a physical record to tape from
117	.IR buffer .
118	The physical record length will be the size of
119	.IR buffer .
120	.I Buffer
121	.B must
122	be of type
123	.BR character .
124	The number of bytes written will be returned.
125	A value of 0 or negative indicates an error.
126	.PP
127	.I Trewin
128	rewinds the tape associated with
129	.I tlu
130	to the beginning of the first data file.
131	If the tape is a labelled tape
132	(see
133	.I topen
134	above)
135	then the label is skipped over after rewinding.
136	The normal returned value is 0.
137	A negative value indicates an error.
138	.PP
139	.I Tskipf
140	allows the user to skip over files and/or records.
141	First,
142	.I nfiles
143	end-of-file marks are skipped. If the current file is at
144	EOF, this counts as 1 file to skip.
145	(Note: This is the way to reset the EOF status for a
146	.IR tlu .)
147	Next,
148	.I nrecs
149	physical records are skipped over.
150	The normal returned value is 0.
151	A negative value indicates an error.
152	.PP
153	Finally,
154	.I tstate
155	allows the user to determine the logical state of the tape I/O channel
156	and to see the tape drive control status register.
157	The values of
158	.I fileno
159	and
160	.I recno
161	will be returned and indicate the current file and record number.
162	The logical values
163	.IR errf ,
164	.IR eoff ,
165	and
166	.I eotf
167	indicate an error has occurred, the current file is at EOF,
168	or the tape has reached logical end-of-tape.
169	End-of-tape (EOT) is indicated by an empty file, often
170	referred to as a double EOF mark.
171	It is not allowed to read past EOT although it is allowed to write.
172	The value of
173	.I tcsr
174	will reflect the tape drive control status register.
175	See
176	.IR ht (4)
177	for details.
178	.SH FILES
179	.ie \nM /usr/ucb/lib/libU77.a
180	.el /usr/lib/libU77.a
181	.SH "SEE ALSO"
182	ht(4), perror(3F), rewind(1)