1 02/06/84 record_stream_
2
3
4 Syntax for attach description:
5 record_stream_ switch_name -control_args
6
7
8 Function: The record_stream_ I/O module attaches an I/O switch to a
9 target I/O switch so that record I/O operations on the attached switch
10 are translated into stream I/O operations on the target switch, or so
11 that stream I/O operations on the attached switch are translated into
12 record I/O operations on the target switch. In this way a program
13 that uses only record I/O may process unstructured files and do I/O
14 from/to the terminal. Similarly, a program that uses only stream I/O
15 can process some structured files.
16
17 Entry points in this module are not called directly by users; rather
18 the module is accessed through the I/O system.
19
20
21 Arguments:
22 switch_name
23 is the name of the target I/O switch. It need not be attached when
24 this attachment is made. If this argument is omitted, the -target
25 control argument must be present.
26
27
28 Control arguments:
29 The following control the transformation of records into a stream of
30 bytes and vice versa, or control the target attachment.
31 -nnl
32 transforms a record into a stream without appending a newline
33 character.
34 -length N
35 converts the stream of bytes to a sequence of records each of which
36 has length N.
37 -target attach_descrip
38 specifies the attachment of a uniquely named target switch. This
39 control argument must occur if and only if the switch_name argument
40 is omitted, and it must be the last control argument in the attach
41 description, if present.
42
43
44 Notes: If neither the -nnl nor -length control arguments are given,
45 lines are transformed into records after deleting trailing newlines
46 and records are transformed into lines by appending newlines.
47
48
49 List of opening modes:
50 stream_input
51 The target I/O switch must be either open for sequential_input, open
52 for sequential_input_output, or attached and closed. In the last
53 case, it is opened for sequential_input. The sequence of records
54 read from the target switch is transformed into a stream of bytes
55 that are transmitted to the calling program by the get_line and
56 get_chars operations. The read_record operation is used to read the
57 records from the target switch.
58
59
60 stream_output
61 The target I/O switch must be either open for sequential_output,
62 open for sequential_input_output, or attached and closed. In the
63 last case, it is opened for sequential_output. The stream of bytes
64 written to the attached switch by the put_chars operation is
65 transformed into a sequence of records that are written to the
66 target switch by use of the write_record operation.
67
68
69 sequential_input
70 The target I/O switch must be either open for stream_input, open for
71 stream_input_output, or attached and closed. In the last case, it
72 is opened for stream_input. The stream of bytes read from the
73 target switch is transformed into a sequence of records that are
74 transmitted to the calling program by read_record operations. If
75 the attach description specifies the default line to record
76 transformation, the get_line operation is used to read bytes from
77 the target switch. If the attach description specifies the -length
78 control argument, the get_chars operation is used to read bytes from
79 the target switch.
80
81
82 sequential_output
83 The target I/O switch must be either open for stream_output, open
84 for stream_input_output, or attached and closed. In the last case,
85 it is opened for stream_output. The sequence of bytes written to
86 the attached switch by the write_record operation is transformed
87 into a stream of bytes that are written to the target switch by use
88 of the put_chars operation.
89
90
91 Notes on transformations: The transformation from record to stream
92 form can be described in terms of taking records from a record switch
93 and giving bytes to a stream switch, and similarly for stream to
94 record a record is a string of bytes. Which switch is the record
95 switch and which the stream switch depends on the opening mode. The
96 details are as follows:
97
98 Record to stream
99 default A record is taken from the record switch, a newline
100 character is appended, and the resulting string is
101 given to the stream switch.
102
103 -nnl A record is taken from the record switch and given to
104 the stream switch without modification.
105
106
107 Stream to record
108 default A line string of bytes ending with a newline
109 character is taken from the stream switch, the
110 newline character is deleted, and the resulting
111 string is given to the record switch.
112
113 -length N To form a record, N bytes are taken from the stream
114 switch and given to the record switch as one record.
115
116
117 Notes on buffering: The I/O module may hold data in buffers between
118 operations when the switch is opened for stream_output, stream_input,
119 or sequential_input.
120
121
122 Close operation: The I/O module closes the target switch if and only
123 if the I/O module opened it.
124
125
126 Detach operation: The I/O module detaches the target switch if and
127 only if the I/O module attached it via the -target control argument.
128
129
130 Position operation: Only positioning to the beginning of file or end
131 of file and skipping forward are supported, except in the default
132 sequential case, which also permits backward skipping. These
133 operations are only supported to the extent the attachment of the
134 target I/O switch supports them.
135
136
137 Control and modes operations: These are supported for open switches in
138 the sense that they are passed along to the I/O module for the target
139 switch.
140
141
142 Notes on I/O status: In addition to the I/O status codes specified in
143 the description of the iox_ subroutine for the various I/O operations,
144 this I/O module returns codes returned by the target switch I/O module.