Files Reference

3270cn Special File

Purpose

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:

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:

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
close
read
readx (non-SNA DFT mode only)
write
writex (non-SNA DFT mode only)
ioctl

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:

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: P/00, P/01, P/02,...P/1F The printer session specified by the P variable is equal to the control unit session address, and the value of a is less than or equal to 0x1F. 01 through 05 Terminal session number.
/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 Translation Table
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

The communication adapter receives data from the control unit in individual SNA data segments. The device driver notifies the application that data is available. During the read subroutine call, the data is transferred to the application's user space from the device driver's kernel space (without the TCA header from the control unit), and control is passed back to the application. The device driver acknowledges each SNA data segment received, making it unnecessary for the application to inquire about the link status after the read call.

Note: The STAT_ACK ioctl operation is not valid 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:

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.

Data received from the host is in the form of an outbound 3270 data stream. The device driver translates the command codes in the outbound 3270 data stream.

Note: The 3270 write commands require the application to send a status to the host. Status is sent using the WDC_SSTAT ioctl operation.

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:

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:

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: WDI_DAVAIL Data is available for reading. The data is buffered either in the driver or in the communication adapter. The data should be read immediately to avoid its having an impact on performance. In non-SNA DFT mode, a write or writex subroutine call cannot complete until the data has been read. In SNA DFT mode, the WDI_DAVAIL flag is used only to indicate that data is available when the device driver wakes up the application (if waiting on a poll or select call) after receiving data from the control unit. WDI_COMM, WDI_PROG, or WDI_MACH Indicates a communication check, program check, or machine check, respectively. In each of these cases, the `io_status` field contains a message code that specifies the type of check. WDI_FATAL Indicates that an error has occurred that prevents further communication between the application and the device driver, typically a coax disconnect or adapter failure. This flag may be set in conjunction with the WDI_COMM, WDI_PROG, or WDI_MACH flag. If the communications failure was caused by a coax disconnect, the `io_status` field contains a value of WEB_610. WDI_WCUS_30 A communications check reminder that occurs when there is a network failure and the control unit is still communicating with the communication adapter. The specific type of error is contained in the `io_status` field as a `5XX` error code. The communications check reminder is cleared automatically after the network condition is corrected. WDI_WCUS_31 Indicates that the communications check reminder has been cleared. WDI_CU Valid only for SNA DFT mode. Indicates that an ACTLU or DACTLU request was received by the device driver. The accompanying data is contained in the `io_extra` field of the io3270 structure.
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: STAT_ACK The previously received 3270 data stream is valid, and the proper response is made to the host. STAT_RESET Sends a RESET Key to the DFT device handler. STAT_PRTCMP The printer session has completed printing the data. STAT_BERR Received a bad buffer order or an invalid buffer address. STAT_UNSUP Received an unsupported 3270 command. The /usr/include/sys/io3270.h file contains the definitions of the structures used by the device handler.

Error Conditions in DFT Mode

The following error conditions may be returned when accessing the device handler through the 3270cn special file:

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

The read subroutine places data received by the communication adapter in a buffer.

Note: To set the offset into the communication adapter's buffer from which to read, use the EMSEEK ioctl operation.

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:

`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:

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:

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.

Implementation Specifics

This special file requires the IBM 3270 Connection Adapter.

The 3270cn special file is part of Base Operating System (BOS) Runtime.

Related Information

Special Files Overview.

The close subroutine, open subroutine, poll subroutine, read subroutine, write subroutine, ioctl subroutine.