03/31/83 ibm3270_ Function: The ibm3270_ I/O module performs stream I/O to and from an IBM 3270 Information Display System (or any compatible device) over a binary synchronous communications channel. NOTE: Do not use this module to communicate with a 3270 device over a multiplexed channel. Use the tty_ module in that case. This module description assumes a knowledge of the IBM 3270 communications protocol as described in the "IBM 3270 Information Display System Component Description", Order No. GA27-2749-4. Entry points in this module are not called directly by the user; rather, the module is accessed through the I/O system. Syntax and Attach Description: ibm3270_ device {-control_args} Arguments: device is the name of the communications channel to be used. Control arguments: -ascii uses the ASCII bisync protocol and character code. -async specifies that the I/O module is to return to its caller immediately after performing a read order (described below under "Control Operation") when input is not available, rather than blocking and waiting for a response from the device. -ebcdic uses the EBCDIC bisync protocol and character code. This is the default. Open Description: This I/O module supports only the stream_input_output opening mode. If the -async control argument is specified in the attach description, the open operation may return the status code error_table_$request_pending; in this case, the caller should perform an event_info order (see "Control Operation") and block on the returned event channel; when the process receives a wakeup on this channel, the open operation should be retried. Control Operation: This I/O module supports all the orders supported by the tty_ I/O module, as well as those described below. All orders are supported when the I/O switch is open, except for event_info, which is supported when the I/O switch is attached. event_info returns the name of the event channel over which wakeups are sent when input or status is received from the communications channel. The info_ptr must point to an aligned fixed binary (71) number, in which the value of the event channel is returned. This order should be used if the -async control argument appears in the attach description (see "Attach Description" above). general_poll causes a general poll operation to be initiated at the 3270 controller. Once the I/O switch is open, either a general_poll order or a poll order must be issued before any input can be received; however, the general_poll order does not have to be repeated, as polling is automatically resumed when appropriate by the I/O module. The info_ptr is not used. get_input_message_size is used to obtain the maximum input message size. The info_ptr must point to a fixed binary variable in which the maximum message size is returned as a result of the call. This size is the one most recently specified by a set_input_message_size order. If no set_input_message_size order has been done since the switch was attached, a size of 0 is returned. poll causes a specific poll operation to be performed on a single device connected to the controller. The info_ptr must point to a fixed binary number containing the identification number of the device to be polled. To ensure that the device is polled as soon as possible, this order usually should be preceded by a stop_general_poll order. read causes input or status information from a single device to be returned, if any is available. If no status or input is available for any device on the communications channel, then the process blocks if the -async control argument is not specified in the attach description; if it is specified, a status code of error_table_$request_pending is returned. The info_ptr must point to a user-supplied structure of the following form: dcl 1 read_ctl aligned, 2 version fixed bin, 2 areap ptr, 2 read_infop ptr, 2 max_len fixed bin, 2 max_fields fixed bin; where: version is the version number of the structure. (Input). It must be 1. areap is a pointer to an area in which the read_info structure is allocated. (Output) read_infop is a pointer to the read_info structure. (Output) max_len is the largest number of characters that can be returned in a single data field. (Output) max_fields is the largest number of data fields that can be returned in the read_info structure. (Output) A read_info structure is allocated by the I/O module at the address specified by read_ctl.read_infop. This structure must be freed by the calling program. The read_info structure has the following form: dcl 1 read_info aligned based (read_ctl.read_infop), 2 version fixed bin, 2 next_read_infop ptr, 2 controller fixed bin, 2 device fixed bin, 2 reason, 3 key fixed bin, 3 sub_key fixed bin, 3 code fixed bin(35), 2 status, 3 bits bit(12) unal, 3 fill bit(24) unal, 2 cursor_position fixed bin, 2 max_fields fixed bin, 2 max_len fixed bin, 2 mod_fields fixed bin, 2 data (read_ctl.max_fields refer (read_info.max_fields)), 3 field_position fixed bin, 3 contents char (read_ctl.max_len refer (read_info.max_len)) var; where: version is the version number of this structure. The structure described here is version 1. next_read_infop is a pointer to the next read_info structure used by the I/O module. (The calling program should not attempt to make use of this item.) controller is the identification number of the 3270 controller from which the data or status has been received. device is the identification number of the particular device (attached to the specified controller) that produced the data or status information. reason describes the event that caused the structure to be filled in. key identifies the nature of the event, which is either an error or status condition, or an action on the part of the 3270 operator. It can have any of the following values: 1 an error was detected at the device. A status code describing the error is returned in reason.code (see "code" below). 2 the device reported status. The particular status is described by status.bits (see "status" below). 3 the operator pressed the ENTER key. 4 the operator pressed one of the program function (PF) keys. The particular key is identified by reason.sub_key (see "sub_key" below). 5 the operator pressed one of the program attention (PA) keys. The particular key is identified by reason.sub_key (see "sub_key" below). 6 the operator pressed the CLEAR key. 7 the operator inserted a card in the identification card reader. 8 the operator used the selector pen on an "attention" field. 9 the operator pressed the TEST REQUEST key. sub_key is the number of the PF or PA key pressed if reason.key is 4 or 5, respectively. code is a status code describing an error at the device if reason.key is 1. status contains the device status if reason.key is 2. cursor_position is the current position of the cursor on the display screen. max_fields is the number of elements in the data array (below). max_len is the length of the longest contents string (below). mod_fields is the number of elements in the data array (below) that are actually filled in in this instance of the structure. data describes the data fields containing the input. No data fields are provided if reason.key is 1, 2, 5, or 6. field_position is the starting buffer address of the data field. contents is the contents of the data field. It is always a null string if reason.key is 8. set_input_message_size specifies the length, in characters, of the largest input message that is expected. The info_ptr must point to a fixed binary number containing the message size. A size of 0 indicates that there is no maximum message size. Use of this order when a maximum message size is defined greatly increases the efficiency of the channel. stop_general_poll causes automatic general polling to stop; polling is not resumed until a general_poll order is issued. The info_ptr is not used. write causes commands and data to be sent to the 3270. The info_ptr must point to a user-supplied structure of the following form: dcl 1 write_info aligned, 2 version fixed bin, 2 controller fixed bin, 2 device fixed bin, 2 from_device fixed bin, 2 command fixed bin, 2 write_ctl_char, 3 bits unal, 4 print_format bit(2) unal, 4 start_printer bit(1) unal, 4 sound_alarm bit(1) unal, 4 keyboard_restore bit(1) unal, 4 reset_mdt bit(1) unal, 3 copy_bits bit(2) unal, 3 pad bit(28) unal, 2 max_fields fixed bin, 2 max_len fixed bin, 2 mod_fields fixed bin, 2 data (max_write_fields refer (write_info.max_fields)), 3 orders unal, 4 set_buffer_addr bit(1), 4 start_field bit(1), 4 insert_cursor bit(1), 4 program_tab bit(1), 4 repeat_to_addr bit(1), 4 erase_to_addr bit(1), 3 attributes unal, 4 protected bit(1), 4 numeric bit(1), 4 display_form bit(2), 4 reserved bit(1), 4 mdt bit(1), 3 pad1 bit(12) unal, 3 field_position fixed bin, 3 contents char (max_write_len refer (write_info.max_len)) var; where: version is the version number of the structure. It must be 1. controller is the identification number of the 3270 controller to which the data is to be sent. device is the identification number of the device on that controller to which the data is to be sent. from_device is the identification number of the device to be used as the "from" device for a copy command. command is the command to be sent to the device. It can have any of the following values: 1 write 2 erase/write 3 copy 4 erase all unprotected 5 read modified 6 read buffer write_ctl_char contains the low-order 6 bits of the write control character (WCC) to be inserted in the data stream. If command (above) is 3 (copy), this field contains the low-order 6 bits of the copy control character (CCC), except that the keyboard_restore and reset_mdt bits are replaced by the copy_bits (below). copy_bits contains the two low-order bits of the copy control character if command is 3. These are the bits that specify what type of data is to be copied. max_fields is the number of elements in the data array (below). max_len is the maximum length of any contents string (below). mod_fields is the number of elements of the data array actually filled in in this instance of the structure. data describes the individual data fields to be sent to the device. orders identify orders to be inserted in the output stream. set_buffer_addr indicates a set buffer address (SBA) order. The field_position (below) contains the buffer address to be set. start_field indicates a start field (SF) order. The attribute character for the field is derived from attributes (below). If an SBA order is also indicated, the field starting address is contained in field_position (below); otherwise, the current device buffer address is used. The contents string, if nonnull, is written starting after the attribute character. insert_cursor indicates an insert cursor (IC) order. If an SBA order is also indicated, the cursor is positioned to the address specified in field_position (below); otherwise, it is set to the current device buffer address. If contents is nonnull, the data is written starting at the new cursor position. program_tab indicates a program tab (PT) order. If an SBA order is also indicated, the tab is inserted at the address specified in field_position (below); otherwise, it is inserted at the current device buffer address. If contents is nonnull, the data is written at the start of the field following the tab. repeat_to_addr indicates a repeat to address (RA) order. The starting address is the current device buffer address; the ending address is specified in field_position (below). Neither an SBA order nor an EUA order can be indicated in the same field. The contents string must consist of a single character, which is to be repeated up to the address immediately preceding field_position. erase_to_addr indicates an erase unprotected to address (EUA) order. The starting address is the current device buffer address; the ending address is specified in field_position (below). Neither an SBA order nor an RA order can be indicated in the same field. If contents is nonnull, the data is written starting at the address specified in field_position. attributes contains the low-order six bits of the attribute character to be assigned to a field if start_field (above) is "1"b. field_position is the device buffer address to be set if set_buffer_addr (above) is "1"b, or the ending address if repeat_to_addr or erase_to_addr (above) is "1"b. contents is the data to be written. It may be a null string. ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved