1 03/31/83 ibm3270_
2
3
4 Function: The ibm3270_ I/O module performs stream I/O to and from an
5 IBM 3270 Information Display System or any compatible device over a
6 binary synchronous communications channel.
7
8 NOTE: Do not use this module to communicate with a 3270 device over a
9 multiplexed channel. Use the tty_ module in that case.
10
11 This module description assumes a knowledge of the IBM 3270
12 communications protocol as described in the "IBM 3270 Information
13 Display System Component Description", Order No. GA27-2749-4.
14
15 Entry points in this module are not called directly by the user;
16 rather, the module is accessed through the I/O system.
17
18
19 Syntax and Attach Description:
20 ibm3270_ device -control_args
21
22
23 Arguments:
24 device
25 is the name of the communications channel to be used.
26
27
28 Control arguments:
29 -ascii
30 uses the ASCII bisync protocol and character code.
31 -async
32 specifies that the I/O module is to return to its caller immediately
33 after performing a read order described below under "Control
34 Operation" when input is not available, rather than blocking and
35 waiting for a response from the device.
36 -ebcdic
37 uses the EBCDIC bisync protocol and character code. This is the
38 default.
39
40
41 Open Description:
42 This I/O module supports only the stream_input_output opening mode. If
43 the -async control argument is specified in the attach description, the
44 open operation may return the status code error_table_$request_pending;
45 in this case, the caller should perform an event_info order see
46 "Control Operation" and block on the returned event channel; when the
47 process receives a wakeup on this channel, the open operation should be
48 retried.
49
50
51 Control Operation:
52 This I/O module supports all the orders supported by the tty_ I/O
53 module, as well as those described below. All orders are supported
54 when the I/O switch is open, except for event_info, which is supported
55 when the I/O switch is attached.
56
57 event_info
58 returns the name of the event channel over which wakeups are sent
59 when input or status is received from the communications channel.
60 The info_ptr must point to an aligned fixed binary 71 number, in
61 which the value of the event channel is returned. This order should
62 be used if the -async control argument appears in the attach
63 description see "Attach Description" above.
64
65
66 general_poll
67 causes a general poll operation to be initiated at the 3270
68 controller. Once the I/O switch is open, either a general_poll
69 order or a poll order must be issued before any input can be
70 received; however, the general_poll order does not have to be
71 repeated, as polling is automatically resumed when appropriate by
72 the I/O module. The info_ptr is not used.
73 get_input_message_size
74 is used to obtain the maximum input message size. The info_ptr must
75 point to a fixed binary variable in which the maximum message size
76 is returned as a result of the call. This size is the one most
77 recently specified by a set_input_message_size order. If no
78 set_input_message_size order has been done since the switch was
79 attached, a size of 0 is returned.
80
81
82 poll
83 causes a specific poll operation to be performed on a single device
84 connected to the controller. The info_ptr must point to a fixed
85 binary number containing the identification number of the device to
86 be polled. To ensure that the device is polled as soon as possible,
87 this order usually should be preceded by a stop_general_poll order.
88 read
89 causes input or status information from a single device to be
90 returned, if any is available. If no status or input is available
91 for any device on the communications channel, then the process
92 blocks if the -async control argument is not specified in the attach
93 description; if it is specified, a status code of
94 error_table_$request_pending is returned.
95
96
97 The info_ptr must point to a user-supplied structure of the
98 following form:
99 dcl 1 read_ctl aligned,
100 2 version fixed bin,
101 2 areap ptr,
102 2 read_infop ptr,
103 2 max_len fixed bin,
104 2 max_fields fixed bin;
105
106
107 where:
108 version
109 is the version number of the structure. Input. It must be 1.
110 areap
111 is a pointer to an area in which the read_info structure is
112 allocated. Output
113 read_infop
114 is a pointer to the read_info structure. Output
115 max_len
116 is the largest number of characters that can be returned in a
117 single data field. Output
118 max_fields
119 is the largest number of data fields that can be returned in the
120 read_info structure. Output
121
122
123 A read_info structure is allocated by the I/O module at the
124 address specified by read_ctl.read_infop. This structure must be
125 freed by the calling program. The read_info structure has the
126 following form:
127 dcl 1 read_info aligned based read_ctl.read_infop,
128 2 version fixed bin,
129 2 next_read_infop ptr,
130 2 controller fixed bin,
131 2 device fixed bin,
132 2 reason,
133 3 key fixed bin,
134 3 sub_key fixed bin,
135 3 code fixed bin35,
136 2 status,
137 3 bits bit12 unal,
138 3 fill bit24 unal,
139 2 cursor_position fixed bin,
140 2 max_fields fixed bin,
141 2 max_len fixed bin,
142 2 mod_fields fixed bin,
143 2 data read_ctl.max_fields refer read_info.max_fields,
144 3 field_position fixed bin,
145 3 contents char read_ctl.max_len
146 refer read_info.max_len var;
147
148
149 where:
150 version
151 is the version number of this structure. The structure
152 described here is version 1.
153 next_read_infop
154 is a pointer to the next read_info structure used by the I/O
155 module. The calling program should not attempt to make use
156 of this item.
157 controller
158 is the identification number of the 3270 controller from which
159 the data or status has been received.
160 device
161 is the identification number of the particular device
162 attached to the specified controller that produced the data
163 or status information.
164
165
166 reason
167 describes the event that caused the structure to be filled in.
168 key
169 identifies the nature of the event, which is either an error
170 or status condition, or an action on the part of the 3270
171 operator. It can have any of the following values:
172
173 1 an error was detected at the device. A status code
174 describing the error is returned in reason.code see "code"
175 below.
176 2 the device reported status. The particular status is
177 described by status.bits see "status" below.
178 3 the operator pressed the ENTER key.
179
180
181 4 the operator pressed one of the program function PF keys.
182 The particular key is identified by reason.sub_key see
183 "sub_key" below.
184 5 the operator pressed one of the program attention PA
185 keys. The particular key is identified by reason.sub_key
186 see "sub_key" below.
187 6 the operator pressed the CLEAR key.
188 7 the operator inserted a card in the identification card
189 reader.
190 8 the operator used the selector pen on an "attention" field.
191 9 the operator pressed the TEST REQUEST key.
192
193
194 sub_key
195 is the number of the PF or PA key pressed if reason.key is 4
196 or 5, respectively.
197 code
198 is a status code describing an error at the device if
199 reason.key is 1.
200 status
201 contains the device status if reason.key is 2.
202 cursor_position
203 is the current position of the cursor on the display screen.
204 max_fields
205 is the number of elements in the data array below.
206 max_len
207 is the length of the longest contents string below.
208
209
210 mod_fields
211 is the number of elements in the data array below that are
212 actually filled in in this instance of the structure.
213 data
214 describes the data fields containing the input. No data
215 fields are provided if reason.key is 1, 2, 5, or 6.
216 field_position
217 is the starting buffer address of the data field.
218 contents
219 is the contents of the data field. It is always a null string
220 if reason.key is 8.
221
222
223 set_input_message_size
224 specifies the length, in characters, of the largest input message
225 that is expected. The info_ptr must point to a fixed binary number
226 containing the message size. A size of 0 indicates that there is no
227 maximum message size. Use of this order when a maximum message size
228 is defined greatly increases the efficiency of the channel.
229 stop_general_poll
230 causes automatic general polling to stop; polling is not resumed
231 until a general_poll order is issued. The info_ptr is not used.
232
233
234 write
235 causes commands and data to be sent to the 3270. The info_ptr must
236 point to a user-supplied structure of the following form:
237 dcl 1 write_info aligned,
238 2 version fixed bin,
239 2 controller fixed bin,
240 2 device fixed bin,
241 2 from_device fixed bin,
242 2 command fixed bin,
243 2 write_ctl_char,
244 3 bits unal,
245 4 print_format bit2 unal,
246 4 start_printer bit1 unal,
247 4 sound_alarm bit1 unal,
248 4 keyboard_restore bit1 unal,
249 4 reset_mdt bit1 unal,
250
251
252 3 copy_bits bit2 unal,
253 3 pad bit28 unal,
254 2 max_fields fixed bin,
255 2 max_len fixed bin,
256 2 mod_fields fixed bin,
257 2 data max_write_fields
258 refer write_info.max_fields,
259 3 orders unal,
260 4 set_buffer_addr bit1,
261 4 start_field bit1,
262 4 insert_cursor bit1,
263 4 program_tab bit1,
264 4 repeat_to_addr bit1,
265 4 erase_to_addr bit1,
266
267
268 3 attributes unal,
269 4 protected bit1,
270 4 numeric bit1,
271 4 display_form bit2,
272 4 reserved bit1,
273 4 mdt bit1,
274 3 pad1 bit12 unal,
275 3 field_position fixed bin,
276 3 contents char max_write_len
277 refer write_info.max_len var;
278
279
280 where:
281 version
282 is the version number of the structure. It must be 1.
283 controller
284 is the identification number of the 3270 controller to which the
285 data is to be sent.
286 device
287 is the identification number of the device on that controller to
288 which the data is to be sent.
289 from_device
290 is the identification number of the device to be used as the
291 "from" device for a copy command.
292
293
294 command
295 is the command to be sent to the device. It can have any of the
296 following values:
297 1 write
298 2 erase/write
299 3 copy
300 4 erase all unprotected
301 5 read modified
302 6 read buffer
303 write_ctl_char
304 contains the low-order 6 bits of the write control character
305 WCC to be inserted in the data stream. If command above is 3
306 copy, this field contains the low-order 6 bits of the copy
307 control character CCC, except that the keyboard_restore and
308 reset_mdt bits are replaced by the copy_bits below.
309
310
311 copy_bits
312 contains the two low-order bits of the copy control character if
313 command is 3. These are the bits that specify what type of data
314 is to be copied.
315 max_fields
316 is the number of elements in the data array below.
317 max_len
318 is the maximum length of any contents string below.
319 mod_fields
320 is the number of elements of the data array actually filled in in
321 this instance of the structure.
322 data
323 describes the individual data fields to be sent to the device.
324 orders
325 identify orders to be inserted in the output stream.
326
327
328 set_buffer_addr
329 indicates a set buffer address SBA order. The field_position
330 below contains the buffer address to be set.
331 start_field
332 indicates a start field SF order. The attribute character for
333 the field is derived from attributes below. If an SBA order is
334 also indicated, the field starting address is contained in
335 field_position below; otherwise, the current device buffer
336 address is used. The contents string, if nonnull, is written
337 starting after the attribute character.
338 insert_cursor
339 indicates an insert cursor IC order. If an SBA order is also
340 indicated, the cursor is positioned to the address specified in
341 field_position below; otherwise, it is set to the current
342 device buffer address. If contents is nonnull, the data is
343 written starting at the new cursor position.
344
345
346 program_tab
347 indicates a program tab PT order. If an SBA order is also
348 indicated, the tab is inserted at the address specified in
349 field_position below; otherwise, it is inserted at the current
350 device buffer address. If contents is nonnull, the data is
351 written at the start of the field following the tab.
352 repeat_to_addr
353 indicates a repeat to address RA order. The starting address
354 is the current device buffer address; the ending address is
355 specified in field_position below. Neither an SBA order nor an
356 EUA order can be indicated in the same field. The contents
357 string must consist of a single character, which is to be
358 repeated up to the address immediately preceding field_position.
359
360
361 erase_to_addr
362 indicates an erase unprotected to address EUA order. The
363 starting address is the current device buffer address; the ending
364 address is specified in field_position below. Neither an SBA
365 order nor an RA order can be indicated in the same field. If
366 contents is nonnull, the data is written starting at the address
367 specified in field_position.
368 attributes
369 contains the low-order six bits of the attribute character to be
370 assigned to a field if start_field above is "1"b.
371 field_position
372 is the device buffer address to be set if set_buffer_addr above
373 is "1"b, or the ending address if repeat_to_addr or erase_to_addr
374 above is "1"b.
375 contents
376 is the data to be written. It may be a null string.