Provides access to 3270 connection adapters by way of the 3270 connection adapter device handler.
The 3270cn character special file provides access to the 3270 connection adapter device handler for the purpose of emulating 3270 display stations and printers. The device handler is a multiplexed device handler that supports an independent logical 3270 session on each of its channels.
The device handler supports two modes of operation:
Item | Description |
---|---|
Distributed Function Terminal (DFT) mode | In DFT mode, the adapter can appear as multiple SNA or non-SNA display sessions, non-SNA printer sessions, or both, and is an intelligent device to the control unit. In this mode, the device handler provides the capability of emulating several 3278/79 display stations. If the attached control unit does not support Extended Asynchronous Event Device Status, either the control unit port or the device handler must be configured for one session only. |
3278/79 emulation Control Unit Terminal (CUT) mode | In CUT mode, the adapter appears as a single-session, unintelligent device to the control unit. In this mode, the device handler provides the capability of emulating a single 3278/79 display station. |
The device handler supports up to four 3270 connection adapters, each of which may have up to five DFT sessions or one CUT session.
The /usr/include/sys/io3270.h file contains the definitions of the structures used by the device handler.
Usage Considerations
When accessing the 3270 connection device handler, the following should be taken into account:
Item | Description |
---|---|
Driver initialization and termination | The device handler may be loaded and unloaded. The device handler supports the configuration calls to initialize and terminate itself, but does not support the configuration call to query vital product data (VPD). |
Special file support | Subroutines other than open and close are discussed in regard to the mode in which the device handler is operating. |
Subroutine Support
The 3270 device handler provides 3270-specific support for the following subroutines:
open and close Subroutines
The device handler supports the 3270cn special file as a character-multiplex special file. The special file must be opened for both reading and writing (O_RDWR).
A special consideration exists for closing the 3270cn special file. If the file was opened in both CUT mode and CUT-File Transfer mode, the close operation for CUT-File Transfer mode must precede the close operation for CUT mode.
The special file name used in an open call takes on several different forms, depending on how the device is to be opened. Types of special file names are:
Item | Description |
---|---|
dev/3270cn/C | Starts the device handler in CUT mode for the selected port, where the value of n is 0 <= n <= 7. |
/dev/3270cn/F | Starts the device handler in CUT File-Transfer mode for the selected port, where the value of n is 0 <= n <= 7. The file must be currently open in CUT mode before it can be opened in CUT File-Transfer mode. |
/dev/3270cn/* | Starts the device handler in DFT mode for the selected port,
where the value of n is 0 <= n <= 7 and the *
(asterisk) is defined by P/a, as follows:
|
/dev/3270cn | Starts the device handler in DFT mode for the selected port, where the value of n is 0 <= n <= 7. |
read Subroutine in Non-SNA DFT Mode
Data received by the communication adapter from the host is placed in the buffer until the message is completed or the buffer is full. When either condition occurs, the driver returns program control back to the application. The application can determine the status of a read subroutine call by issuing a WDC_INQ ioctl operation.
If the WDC_INQ operation returns a status indicating that more data is available, the application should immediately issue another read call. Available data must be read as soon as possible to avoid degrading link or host performance.
If a read call is made and no data is available, the calling process is blocked until data becomes available. To avoid blocking, use the poll subroutine to determine if data is available.
The host sends data as an outbound 3270 data stream. The device handler translates the command codes in the outbound 3270 data stream. The command codes and translations are as follows:
Command Code | Into Driver | Out of Driver |
---|---|---|
Erase All Unprotected | 0x6F | 0x0F |
Erase/Write | 0xF5 | 0x03 |
Erase/Write Alternate | 0x7E | 0x0D |
Read Buffer | 0xF2 | 0x02 |
Read Modified | 0xF6 | 0x06 |
Write | 0xF1 | 0x01 |
Write Structured Field | 0xF3 | 0x11 |
read Subroutine in SNA DFT Mode
Unlike non-SNA DFT mode, neither chaining nor command interpretation is performed by the device driver in SNA DFT mode. The application must both accumulate SNA data segments to form an response unit (RU) and interpret any 3270 data contained within.
readx Subroutine in Non-SNA DFT Mode
Data received by the communication adapter from the host is placed in the buffer until either the message completes or the buffer is full. Upon completion of the read call, the io3270 structure pointed to by the read extension contains the status. One of the following status codes is set in the io_flags field of the io3270 structure:
Item | Description |
---|---|
WDI_DAVAIL | Additional data is available for this link address. |
WDI_COMM | A communication error occurred. The io_status field contains the corresponding message code. |
WDI_PROG | A program error occurred. The io_status field contains the corresponding message code. |
WDI_MACH | A hardware error occurred. The io_status field contains the corresponding message code. |
WDI_FATAL | An error occurred that prevents further communication with the host. This flag is optionally set in addition to the WDI_COMM, WDI_PROG, or WDI_MACH flag. It is also set when a coax failure occurs. In this case, the io_status field contains a value of WEB_610, but the WDI_COMM, WDI_PROG, or WDI_MACH flag is not set. |
When reset, the WDI_DAVAIL flag indicates that the data just read marks the completion of an outbound 3270 data stream.
If the WDI_DAVAIL flag indicates more data is available, another readx subroutine should be issued immediately. Available data must be read as soon as possible to avoid degrading link or host performance.
If a readx subroutine call is made and no data is available, the calling process is blocked until data becomes available. To avoid blocking, use the poll subroutine to determine if data is available.
write Subroutine in Non-SNA DFT Mode
In non-SNA DFT mode, the write subroutine sends an inbound 3270 data stream to the host. The buffer specified on a write subroutine call must contain a complete inbound 3270 data stream. The write call is complete when it has successfully transferred from the buffer specified on the subroutine call.
write Subroutine in SNA DFT Mode
In SNA DFT mode, the write subroutine transmits SNA data to the host system. This data can be either a 3270 data stream with SNA headers or an SNA response.
The application sends data to the device driver, one RU at a time. The device driver is then responsible for segmenting the inbound SNA data. If a second write call is made before the first call is processed, the second call does not proceed until the device driver is ready. After the data is transferred from the application's user space to the device driver's kernel space, the write subroutine completes and control is returned to the application.
If the device driver detects a coax disconnect between two write calls, the second write call will return to the application, with the errno global variable set to EFAULT.
writex Subroutine in Non-SNA DFT Mode
The writex subroutine sends an inbound 3270 data stream to the host. The buffer specified on a writex subroutine call must contain a complete inbound 3270 data stream.
The write subroutine is complete when it has successfully transferred the data from the specified buffer. Upon completion of the write subroutine call, the io3270 structure pointed to by the write extension contains the status. One of the following status codes is set in the io_flags field of the io3270 structure:
Item | Description |
---|---|
WDI_DAVAIL | Indicates that data is available for this link address; the data must be read before any write can occur. |
WDI_COMM | Indicates a communication error. The io_status field contains the corresponding message code. |
WDI_PROG | Indicates a program error. The io_status field contains the corresponding message code. |
WDI_MACH | Indicates a hardware error. The io_status field contains the corresponding message code. |
ioctl Subroutine in DFT Mode
The ioctl subroutine may be issued to the device handler when it is in DFT mode. The following are the available ioctl operations:
Item | Description |
---|---|
IOCINFO | Returns the logical terminal number. This number is the EBCDIC representation of the controller type and the controller attachment protocol in the iocinfo structure. |
WDC_AUTO | Valid only for non-SNA DFT mode. Provides the handler with the option to automatically acknowledge the receipt of a valid 3270 data stream. An acknowledgment is sent only if the beginning of the 3270 data stream consists of 0xF3 00 06 40 00 F1 C2 xx xx 10 14, where the xx fields are not examined. This command also allows the driver not to indicate acknowledgment upon receipt of data. |
WDC_INQ | Queries the status of the last non-SNA read or write call issued by the application. Also, the WDC_INQ operation
determines if data is available for reading. The status is placed
in the io_flags field of the io3270 structure. This
field accepts the following values:
|
WDC_POR | The link address is first disabled and then re-enabled to emulate a 3270 terminal power-on reset function. |
WDC_SSTAT | Valid only for non-SNA DFT mode. Sends status to the host.
The argument field contains one of the following values:
|
Error Conditions in DFT Mode
The following error conditions may be returned when accessing the device handler through the 3270cn special file:
Item | Description |
---|---|
EBUSY | An open was requested for a channel that is already open. |
EFAULT | A buffer specified by the caller was not valid. |
EINTR | A subroutine call was interrupted. |
EINVAL | An invalid argument was received. |
EIO | An unrecoverable I/O error occurred on the requested data transfer. |
ENODEV | An open was requested for an invalid channel. |
ENOMEM | The driver could not allocate memory for use in the data transfer. |
ENXIO | An operation was requested for an invalid minor device number. |
read Subroutine in CUT Mode
Two ioctl operations control the way the read subroutine operates: the EMNWAIT and EMWAIT operations. The EMNWAIT operation indicates that subsequent read calls should be satisfied immediately. The EMWAIT ioctl operation (the default) indicates that read calls should be satisfied only after an interrupt from the control unit indicates that something has changed on the display. The following are control unit interrupts:
Item | Description |
---|---|
Buffer Modification Complete | The read subroutine returns the number of bytes requested. |
Load I/O Address Command Decoded | The read subroutine returns 0 for the number of bytes read. |
write Subroutine in CUT Mode
The write subroutine sends an inbound 3270 data stream to the host. The buffer specified on a write subroutine must contain a complete inbound 3270 data stream. To set the offset into the communication adapter buffer to begin to write, use the EMSEEK ioctl operation.
ioctl Subroutine in CUT Mode
The ioctl subroutine may be issued to the device handler in CUT mode. The following are acceptable ioctl operations:
Item | Description |
---|---|
EMKEY | Sends a scancode to the emulation adapter. The scan code is logically ORed with the EMKEY operation, and the result is used as the command field on the ioctl subroutine call. |
EMCPOS | Returns the position of the cursor relative to the start of the communication adapter buffer. |
EMXPOR | Disables the link address and then re-enables it to emulate a 3270 terminal power-on reset function. |
EMNWAIT | Specifies that read subroutine calls should be satisfied immediately. |
EMWAIT | Specifies that read subroutine calls should be satisfied only after a change to the emulation buffer or the cursor position (this is the default setting). |
EMVISND | Returns the current contents of the emulation Visual/Sound register in the integer field. The address of this field is specified as the argument to the EMVISND operation. |
EMIMASK | Provides a mask to specify which interrupts appear. The argument
field specifies the address of the mask. The low-order bits of the
mask (0 through 7) correspond to bits 0 through 7 of the Interrupt
Status register. Bits 8 through 15 of the mask correspond to bits
0 through 7 of the Visual/Sound register. This operation allows the driver to ignore visual or sound interrupts except for those bits specifically masked ON. When a bit is on, the interrupt that corresponds to that bit position appears. Interrupts that correspond to off (0) bit positions in the mask are discarded by the device handler. The previous mask setting is returned to the caller in the mask field. The interrupt status bits and the visual or sound bits are documented in the IBM® 3270 Connection Technical Reference. |
IOCINFO | Returns a structure of device information, as defined in the /usr/include/sys/devinfo.h file, to the user-specified area. The devtype field has a value of DD_EM78, which is defined in the devinfo.h file, and the flag field value has a value of 0. |
EMSEEK | Sets the offset into the communication adapter buffer to begin a read or write subroutine call. |
Error Conditions in CUT Mode
The following error conditions may be returned when accessing the device handler through the dev/3270cn special file:
Item | Description |
---|---|
EBUSY | An open was requested for a channel that is already open. The keystroke buffer is full. |
EFAULT | A buffer specified by the caller is not valid. |
EINTR | A subroutine call was interrupted. |
EINVAL | An invalid argument was specified on an ioctl call. |
EL3RST | A reset command was received by the communications adapter. |
ENOCONNECT | The connection to the control unit stopped while a read operation, for which the EMWAIT ioctl operation had been specified, was waiting. |
EIO | An unrecoverable I/O error occurred on the requested data transfer. |
ENXIO | An operation was requested for a minor device number that is not valid. |
This special file requires the IBM 3270 Connection Adapter.