1 11/16/88 mowse_io_
2
3 Function:
4 The I/O module is responsible for controlling communications within
5 MOWSE through data packetization, and dispatching received data to
6 its appropriate handler. An "appropriate handler" is either a
7 user_input queue which collects foreground data to be retrieved
8 through calls to iox_$get_chars and iox_$get_line, or background
9 applications which process background data packets.
10
11
12 Syntax:
13 mowse_io_ switch_name
14
15
16 Arguments:
17 switch_name
18 Is the name of the io switch under which mowse_io_ will be
19 attached. If none is given, then mowse_io_ will attempt to
20 attach itself next to tty_.
21
22
23 Notes:
24 If tty_ does not exist, then attachment will fail.
25
26
27 Opening:
28 The opening modes supported are stream_input_output.
29
30
31 Editing:
32 Editing is not the responsibility of mowse_io_, it merely passes on
33 editing requests to WSTERM.
34
35
36 Buffering:
37 This I/O module is responsible for the manipulation of two logical
38 subchannels of data communications: foreground and background. Both
39 of these subchannels will block awaiting the capability of
40 transmitting characters. Input of characters is performed upon the
41 arrival of a complete packet - signalled through the immediate call
42 event channels and the wake_tbl/wakeup tty_ modes - where the input is
43 sorted out and placed into the appropriate channel buffer.
44
45 Retrieval and transmission of characters along the foreground
46 subchannel will block to the calling routine awaiting the
47 availability of characters or the capability of transmission of
48 characters.
49
50
51 List of entry points:
52 The following is a list of all entry points in
53 mowse_io_ available through calls to iox_ entrypoints.
54
55
56 attach
57 close
58 detach_iocb
59
60 get_chars
61 The get chars operation reads as many characters as are available,
62 up to but not exceeding the number requested by the caller.
63 No error code is returned if the number read is less than the
64 number requested, at least one character is always returned. The
65 characters read may comprise only a partial input line, or several
66 input lines; no assumptions can be made in this regard.
67
68
69 get_line
70 The get_line operation is supported. No error
71 code is returned if the read operation occurs with the input buffer
72 length at zero. For further explanation, see the iox_$get_line
73 entry.
74
75 modes
76 open
77
78 put_chars
79 The put_chars operation is supported see the iox_$put_chars entry.
80
81
82 control
83 Control orders accessible through calls to iox_$control provide the
84 necessary additional functionality to the I/O module. These control
85 orders allow the caller to access functionality specific to the I/O
86 module. With mowse_io_ it has been necessary to provide control
87 orders which are "visible" to the user as well as specialized
88 orders which are to remain undocumented to the user. Following is
89 a list of the control orders which are supported by mowse_io_ and
90 require specific handling by mowse_io_.
91
92
93 List of orders:
94 For complete description of those orders not described, please
95 refer to the appropriate Multics documentation.
96
97
98 abort
99
100 debug_on
101 debug_off
102 These orders allow all communications packets being
103 sent and received both locally and remotely PC by Multics to be
104 recorded into a specified Multics segment. The info_ptr points to
105 the structure below defined in mowse_io_control_info.incl.pl1 or
106 can be null in which case the segment name "debug.mowse_io_" is
107 default.
108
109 dcl 01 mowse_io_debug_info based mowse_io_debug_info_ptr,
110 02 version char 8,
111 02 segment_name char 32 var;
112
113
114 where
115 version
116 Is the version number of the structure. It must be
117 mowse_io_info_version_1.
118 segment_name
119 Is the name of the segment in the current working
120 directory to which the packets will be recorded.
121
122
123 get_editing_chars
124
125 get_event_channel
126 returns the identifier of the ipc_ event channel associated
127 with the foregrond data event channel. The info_pointer
128 should point to a fixed bin 71 aligned quantity into which
129 the channel identifier is stored.
130
131
132 get_input_conversion
133 set_input_conversion
134 Input translation by MOWSE is performed by WSTERM and will
135 accept only one escape character, all other changes will be
136 recorded and installed into tty_ when mowse_i/o is detached see
137 tty_.
138
139 line_length
140
141 printer_off
142 printer_on
143 These orders allow the printer facility to be turned on and off in
144 order to specify read unechoed terminal characters. When these
145 orders are specified, a control message is formulated to the PC
146 MOWSE of the type PON/POFF.
147
148
149 quit_disable
150 quit_enable
151 read_status
152
153 reconnection
154 Is the control order which is to be received by mowse_io_ when a
155 reconnection to a disconnected process has been requested. It is
156 mandatory that this control order be issued to mowse_io_ at
157 reconnection, otherwise MOWSE will not operate correctly.
158
159 Reconnection will be implemented in a later version of MOWSE.
160
161
162 reset_read
163 reset_write
164 set_default_modes
165 set_editing_chars
166 set_term_type
167
168
169 trace_on
170 trace_off
171 These orders allow all messages being sent and received by an
172 application to be recorded in a specified Multics segment. The
173 info_ptr points to the structure below defined in
174 mowse_io_control_info.incl.pl1, or can be null in which case the
175 default segment name will be "trace.mowse_io_".
176
177 dcl 01 mowse_io_debug_info based mowse_io_debug_info_ptr,
178 02 version char 8,
179 02 segment_name char 32 var;
180
181
182 where
183 version
184 Is the version number of the structure. It must be
185 mowse_io_info_version_1.
186 segment_name
187 Is the name of the segment in the current working
188 directory to which the messages will be recorded.
189
190 write_status
191
192
193 List of non-supported control orders:
194 Because of the special need for mowse_io_ to control the
195 communications aspect of the Multics process, the following control
196 orders must be rejected by mowse_io_ as they will affect the
197 functionality of mowse_io_ these non-supported orders are list
198 in mowse_io_bad_control.incl.pl1:
199
200 get_chars_timeout
201 get_line_timeout
202 interrupt
203 listen
204 position
205 put_chars_timeout
206
207
208 start_xmit_hd
209 stop_xmit_hd
210 input_flow_control_info
211 output_flow_control_chars
212 set_framing_chars
213 set_input_translation
214 set_line_type
215 set_output_translation
216 set_wakeup_table
217 send_initial_string
218 set_event_channel
219 wru
220
221
222 modes
223 The modes operation is supported when the I/O switch is open. The
224 recognized modes are below. The modes string is parsed via the
225 mode_string_ entries to parse the modes string. MOWSE requires full
226 control over the communication modes in order to communicate
227 effectively with the PC. Thus MOWSE will reset the modes to the
228 manner in which mowse_io_ requires them.
229
230 pl crecho more ignored
231 ll lfecho more_mode ignored
232
233 When a modes order is requested, in addition to "changing" the above
234 modes, mowse_io_ will also issue a message along the foreground
235 subchannel which is destined for the terminal emulator in order that
236 it may make the necessary changes.
237
238
239 Control operations from command level:
240
241 The following is a list of control operations which are accessible
242 from command level through io_call as follows:
243
244 io_call control switch_name order_arg
245
246
247 IO call arguments:
248
249 switch_name
250 The name of the I/O switch.
251
252
253 order_arg
254 Any control order described above and in tty_ which can
255 accept null info pointer as well as read_status, write_status,
256 terminal_info, and the following as shown:
257
258 store_id
259 where id is the answerback string.
260 set_term_type type -control_args
261 where type is the new terminal type and -control_args can
262 be of any -initial_string -istr, -modes, and
263 -ignore_line_type. These control_args are accepted by
264 io_call, but are ignored by mowse_io_.
265 line_length N
266 where N is the new line length.
267
268
269 Notes on acceptable control order active functions:
270 The following control orders can be used as active functions:
271
272 io_call control switch_name read_status
273 returns true if input available; false otherwise.
274 io_call control switch_name write_status
275 returns true if output is pending; false otherwise.
276 io_call control switch_name terminal_info terminal_type
277 returns the current terminal type.
278 io_call control switch_name terminal_info baud
279 returns the baud rate
280 io_call control switch_name terminal_info id
281 returns the terminal identifier answerback.
282 io_call control switch_name terminal_info line_type
283 returns the current line type