1 08/22/83 bisync_
2
3
4 Syntax for Attach Description:
5 bisync_ device -control_args
6
7
8 Function: The bisync_ I/O module performs stream I/O over a binary
9 synchronous communications channel.
10
11 Entry points in this module are not called directly by users; rather,
12 the module is accessed through the I/O system.
13
14
15 Arguments:
16 device
17 is the name of the communications channel to be used for
18 communications.
19
20
21 Control arguments:
22 -ascii
23 uses the ASCII bisync protocol. This is the default.
24 -bid_limit N
25 sets to N the number of times a line bid is retried. The default is
26 30 times.
27 -breot
28 causes the get_chars operation to return any block of data ending
29 with an end-of-transmission EOT character see "Get Chars
30 Operation" below.
31 -bretb
32 causes the get_chars operation to return any block of data ending
33 with an end-of-text block ETB character. The default is to return
34 only blocks ending with an end-of-text control character ETX or an
35 intermediate text block ITB control character see the discussion
36 of the get_chars operation below.
37
38
39 -ebcdic
40 uses the EBCDIC bisync protocol.
41 -hangup
42 causes an automatic hangup when the switch is detached.
43 -multi_record N
44 specifies that blocking of logical records is done by the I/O
45 module. If specified, N is the maximum number of records per block.
46 If N is not given, the number of records per block is as many as
47 fit.
48 -nontransparent
49 uses the nontransparent bisync protocol.
50 -size N
51 sets to N the number of characters to be transmitted in each bisync
52 block. The default is 256 characters.
53 -transparent
54 uses the transparent bisync protocol. This is the default.
55
56
57 -ttd_limit N
58 sets to N the maximum number of TTDs that are sent before sending an
59 EOT. The default is 30 TTDs.
60 -ttd_time N
61 sets to N the number of seconds of temporary text delay TTD
62 transmissions if output is delayed. The default is two seconds.
63
64
65 Open Operation:
66 The bisync_ I/O module supports the stream_input, stream_output, and
67 stream_input_output opening modes.
68
69
70 Put Chars Operation: The put_chars entry splits the data to be written
71 into blocks according to the -size control argument in the attach
72 description. The appropriate bisync control characters are added to
73 the beginning and end of each block. Each block except the last is
74 transmitted with an ETB control character at the end. The last block
75 is transmitted with an ETX control character at the end.
76
77
78 Get Chars Operation:
79 The get_chars entry reads and decodes bisync blocks, removes the
80 control characters, and returns the message text to the caller's
81 buffer.
82
83 Characters are returned up to the next logical bisync break character.
84 Normally this is ETX. If -bretb is specified in the attach
85 description, ETB is also considered to be a break character. If
86 -multi_record is given, the interrecord ITB characters are also
87 considered to be break characters. In addition, if -breot is
88 specified, error_table_$end_of_info is returned when an EOT is read.
89
90
91 Get Line Operation:
92 The get_line entry reads and decodes bisync blocks, removes the control
93 characters, and returns the message text to the caller's buffer.
94 Characters are returned until either a newline character is placed in
95 the buffer or the buffer is filled. The get_line entry does not
96 distinguish between blocks ending in ETB or ITB and blocks ending in
97 ETX.
98
99
100 List of Control Operations:
101 Several of the control operations supported by the bisync_ I/O
102 module are identical to those supported by the tty_ I/O module
103 and are documented there. They include:
104
105 abort
106 event_info
107 hangup
108 read_status
109 resetread
110 resetwrite
111 write_status
112
113
114 The following control operations are also supported by bisync.
115 end_write_mode
116 causes the I/0 module to block until all outstanding output has been
117 written.
118 get_bid_limit
119 where info_ptr points to a fixed binary bid limit that is set either
120 to the value specified at attach or in the last set_bid_limit order.
121 get_bsc_modes
122 returns the structure described under set_bsc_modes.
123
124
125 get_chars
126 performs a get_chars operation and returns additional information
127 about the input. The info_ptr points to a structure of the
128 following form:
129 dcl 1 get_chars_info,
130 2 buf_ptr ptr,
131 2 buf_len fixed bin21,
132 2 data_len fixed bin21,
133 2 hbuf_ptr ptr,
134 2 hbuf_len fixed bin21,
135 2 header_len fixed bin21,
136 2 flags,
137 3 etx bit1 unal,
138 3 etb bit1 unal,
139 3 soh bit1 unal,
140 3 eot bit1 unal,
141 3 pad bit32 unal;
142
143
144 where--
145 buf_ptr, buf_len
146 define an input buffer for the text of the message. Input
147 data_len
148 is set to the number of characters of text read. Output
149 hbuf_ptr, hbuf_len
150 define an input buffer for the header of the message. Input
151 header_len
152 is set to the header's length in characters. Output
153 etx
154 indicates that text is terminated with an ETX character.
155 Output
156 etb
157 indicates that text is terminated with an ETB character.
158 Output
159
160
161 soh
162 indicates that the data includes a header. Output
163 eot
164 indicates that an EOT is received. Output
165 pad
166 is unused space in this structure. Output
167 get_multi_record_mode
168 where info_ptr points to a fixed binary record count. This order
169 returns the multirecord record count. A 1 indicates single-record
170 mode.
171 get_size
172 where info_ptr points to a fixed binary buffer size and returns the
173 current size.
174
175
176 hangup_proc
177 sets up a procedure to be called if the communications channel hangs
178 up. The hangup_proc input structure has the following form:
179 dcl 1 hangup_proc aligned,
180 2 entry entry variable,
181 2 datap ptr,
182 2 prior fixed bin;
183 where--
184 entry
185 is the entry to call when a hangup is detected.
186 datap
187 is a pointer to data for the hangup procedure.
188 prior
189 is the ipc_ event call priority to be associated with hangup
190 notification.
191
192
193 runout
194 has meaning only in multirecord mode and writes the current
195 partially filled block.
196 send_nontransparent_msg
197 writes the data specified in nontransparent bisync mode, regardless
198 of the current transparency mode. This order is used to send short
199 nontransparent control sequences while in transparent mode. The
200 info_ptr points to a structure of the following form:
201 dcl 1 order_msg,
202 2 data_len fixed bin,
203 2 data char order_msg.data_len;
204 set_bid_limit
205 where info_ptr points to a fixed binary bid limit to replace the
206 bid_limit specified in the attach description.
207
208
209 set_bsc_modes
210 where info_ptr points to a structure of the following form:
211 dcl 1 bsc_modes,
212 2 transparent bit1 unal,
213 2 ebcdic bit1 unal,
214 2 mbz bit 34 unal;
215 The setting of the transparent and ebcdic bits then replaces the
216 values specified in the attach description.
217 set_multi_record_mode
218 where info_ptr points to a fixed binary record count. If the count
219 is 1, the I/O module enters single-record mode; otherwise,
220 multirecord mode is entered, and the count specifies the maximum
221 number of records per block. Zero or a null info_ptr specifies no
222 fixed limit; i.e., as many records as fit are blocked.
223 set_size
224 where info_ptr points to a fixed binary buffer size. This new size
225 replaces the size specified in the attach description. It cannot be
226 larger than the size originally specified in the attach description.