NAME

blmode − terminal block mode interface

DESCRIPTION

This terminal interface adds functionality to the current termio(7) functionality to allow for efficient emulation of MPE terminal driver functionality.  Most importantly, it adds the necessary functionality to support block mode transfers with HP terminals. The block mode interface only affects input processing and does not affect write requests.  Write requests are always processed as described in termio(7). In character mode the terminal sends each character to the system as it is typed.  However, in block mode data is buffered and possibly edited locally in the terminal memory as it is typed, then sent as a block of data when the <ENTER> key is pressed on the terminal.  During block mode data transmissions, the incoming data is not echoed and no special character processing is performed, other than recognizing a data block terminator character.  For subsequent character mode transmissions, the existing termio state will continue to determine echo and character processing. 

There are two parts of the block mode protocol.  The first part is the block mode handshake, which works as follows.  At the beginning of a read, a trigger character is sent to the terminal to notify it that the system wants a block of data. (The trigger character, if defined, is sent at the beginning of all reads, whether character or block.  The trigger character must be defined for block mode reads.)  After receiving the trigger character, and then the data the user has typed into the terminal’s memory, followed by a press of the <ENTER> key, the terminal will send an alert character to the system to notify it that the terminal has a block of data to send.  The system may then send user-definable cursor positioning or other data sequences to the terminal.  When that is done, the system will send another trigger character to the terminal. 

The second part of the block mode protocol is the block mode transmission.  During this transmission of data, the incoming data is not echoed and no special character processing is performed, other than recognizing the data block termination character.  It is possible to bypass the block mode handshake and have the block mode transmission occur after the first trigger character is sent. 

To prevent data loss, XON/XOFF flow control should be used between the system and the terminal.  The IXOFF bit should be set and the terminal strapped appropriately.  If flow control is not used, it is possible for incoming data to overflow and be lost.  (Note: some older terminals do not deal correctly with this flow control.) 

It is possible to intermix both character mode and block mode data transmissions.  If block mode transmissions are enabled, all transfers will be block mode transfers.  When block mode transmissions have not been enabled, character mode transmissions will be processed as described in termio(7). If block mode transmissions are not enabled, but an alert character is received anywhere in the input data, then the transmission mode will be switched to block mode automatically for a single transmission. 

Read requests that receive data from block mode transmissions will not be returned until the transmission is complete, i.e., the terminal has transmitted all characters.  If the read is satisfied by byte count or if a data transmission error occurs, any subsequent data will be discarded.  The read will wait until completion of the data transmission before returning. 

The data block terminator character will be included in the data returned to the user, and is included in the byte count.  If the number of bytes transferred by the terminal in a block mode transfer exceeds the number of bytes requested by the user, the read will return the requested number of bytes and the remaining bytes will be discarded.  The user can determine if data was discarded by checking the last character of the returned data.  If the last character is not the terminator character, then more data was received than was requested and data was discarded. 

If desired, the application program can provide its own handshake mechanism in response to the alert character by selecting the OWNTERM mode.  With this mode selected, the driver will complete a read request when the alert character is received.  The second trigger will be sent by the driver when the application issues the next read. 

There are several special characters (both input and output) which are used with block mode.  These characters and the normal values used for block mode are described below.  The initial value for these characters is 0377, which causes them to be disabled. 

CBTRIG1C (DC1) is the initial trigger character sent to the terminal at the beginning of a read request. 

CBTRIG2C (DC1) is the secondary trigger character sent to the terminal after the alert character has been received. 

CBALERTC (DC2) is the alert character sent by the terminal in response to the first trigger character.  It signifies that the terminal is ready to send the data block.  The alert character can be escaped by preceding it with a backslash ("\"). 

CBTERMC (RS) is sent by the terminal after the block mode transfer has completed.  It signifies the end of the data block to the computer. 

The two ioctl(2) system calls that apply to block mode use the following structure, defined in <blmodeio.h>:

};

The cb_flags field controls the basic block mode protocol:

The CB_BMTRANS bit is only effective when the ICANON flag in termio(7) is set.  If ICANON is clear, then all transfers will be done in raw mode, regardless of the CB_BMTRANS bit.  If CB_BMTRANS is not set, then input processing will be performed as described in termio(7). During this time, if the alert character is defined and is detected anywhere in the input stream, the input buffer will be flushed and the block mode handshake will be invoked.  The system will then send the cb_trig2c character to the terminal, and a block mode transfer will follow.  The alert character can be escaped by preceding it with a backslash ("\"). 

If CB_BMTRANS is set, then all transmissions are processed as block mode transmissions.  The block mode handshake is not required and data read is processed as block mode transfer data.  The block mode handshake may still be invoked by receipt of an alert character as the first character received.  Reads issued while the CB_BMTRANS bit is set cause any existing input buffer data to be flushed. 

If CB_OWNTERM is set, reads will be terminated upon receipt of a non-escaped alert character.  No input buffer flushing is performed, and the alert character is returned in the data read.  This allows application code to perform its own block mode handshaking.  If the bit is clear, an alert character will cause normal block mode handshaking to be used. 

The initial cb_flags value is all-bits-cleared. 

The cb_trig1c character is the initial trigger character that will be sent to the terminal at the beginning of a read request.  The initial value is undefined (0377), i.e. no trigger character is sent. 

The cb_trig2c character is the secondary trigger character sent to the terminal after the alert character has been received.  The initial value is undefined (0377). 

The cb_alertc character is the alert character sent by the terminal in response to the first trigger character sent by the computer.  It signifies that the terminal is ready to transmit data.  The initial value is undefined (0377). 

The cb_termc character is sent by the terminal after the block mode transfer has completed.  It signifies the end of the data block to the computer.  The initial value is undefined (0377). 

The cb_replen field specifies the length in bytes of the cb_reply field.  If set to zero, the cb_reply string will not be used.  It is initially set to zero. 

The cb_reply array contains a string to be sent out after receipt of the alert character, but before the second trigger character is sent by the computer.  Any character may be included in the reply string.  The number of characters sent is specified by cb_replen.  The initial value of all characters in the cb_reply array is null. 

On systems that support process group control, unless otherwise noted for a specific ioctl command, the ioctls are restricted from use by background processes. An attempt to issue an ioctl from a background process will cause the process to block and may cause a SIGTTOU signal to be sent to the process group. 

The primary ioctl(2) system calls have the form:

ioctl (fildes, command, arg)
struct blmodeio *arg;

The commands using this form are:

CBGETA Get the parameters associated with the block mode interface and store in the blmodeio structure referenced by arg. This command is allowed from a background process; however, the information may be subsequently changed by a foreground process.

CBSETA Set the parameters associated with the block mode interface from the blmodeio structure referenced by arg. The change is immediate.

RETURNS

During a read, it is possible for the user’s buffer to be altered even if an error value is returned.  The data in the user’s buffer should be ignored as it will not be complete.  The following errors may be returned by various system calls interfacing with this terminal protocol:

Read

[EIO] An error occurred during the transmission of the block mode data block. 

Ioctl

[EINVAL] An invalid parameter or command value was passed to the ioctl call. 

WARNINGS

The EIO error that is returned for read errors can be caused by many events. The read will return EIO for transmission, framing, parity, break, and overrun errors, or if the internal timer expires.  The internal timer starts when the second trigger character is sent by the computer, and ends when the terminating character is received by the computer.  The length of this timer is determined by the number of bytes requested in the read and the current baud rate, plus a fudge factor of ten seconds. 

AUTHOR

Blmode was developed by Hewlett-Packard. 

SEE ALSO

termio(7). 

Hewlett-Packard Company  —  HP-UX Release 7.0: Sept 1989