3270cn Special File

Purpose

Provides access to 3270 connection adapters by way of the 3270 connection adapter device handler.

Description

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:

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:

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:

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

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:

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:

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:

Error Conditions in DFT Mode

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

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:

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:

Error Conditions in CUT Mode

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

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.