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