3270 data stream protocol

Description
This is a simplified overview of the protocol between the host and the terminal. For a complete reference, please see the full IBM reference document.

Basic protocol
3270 terminals are block-mode terminals, which means that the user can edit the contents of the display without any interaction with the host. The edited contents of the screen are sent to the host only when the user presses particular keys on the keyboard.

The host, by contrast, can send commands to the terminal at any time.

Screen buffer
The terminal display is a visual representation of the screen buffer, which is an array of characters with attributes. The characters are in EBCDIC.

There is one location in the screen buffer for each character position on the screen. For example, a model 2 has 24 rows with 80 columns each, so it has a 1920-element screen buffer. The first 80 buffer positions are the first row of the screen, the next 80 are the second row, etc.

Fields
The host can optionally program the display buffer with fields. Fields are sections of the screen buffer with particular attributes. A field is defined by a Start Field character, which takes up a position in the buffer and is displayed as a blank.

Field attributes include:
 * Protected (read-only)
 * Numeric-only
 * Intensified display
 * Light-pen selectable
 * Foreground color
 * Background color
 * Underlining
 * Character set (code page)

A field consists of each of the screen buffer positions between successive Start Field characters, and can span rows. The Start Field character that ends a field (and starts the next one) is found by scanning to the right of the starting Start Field character, wrapping from the end of one row to the beginning of the next row, and wrapping from the bottom-right corner of the screen back up to the top-left corner. Thus a screen buffer with just one Start Field character has one gigantic field, consisting of the entire screen (except for the Start Field character itself).

A screen buffer with at least one field is said to be formatted. A screen buffer with no fields is said to be unformatted.

x3270, c3270, wc3270 and wx3270 include options to make Start Field characters and other control characters visible, for debugging purposes.

Host commands
The host can send a number of different commands to the emulator. These include:
 * Write
 * Writes data to the screen buffer.


 * EraseWrite
 * Erases the screen and writes data to the buffer. The terminal is put in basic mode, where it emulates a 3270 model 2 with 24 rows of 80 columns.


 * EraseWriteAlternate
 * Erases the screen and writes data to the buffer. The terminal is put in alternate mode, where the full screen size (the additional rows and/or columns from other 3270 models, plus any oversize rows and columns) can be used.


 * ReadBuffer
 * Requests that the terminal send the entire contents of the screen buffer to the host.

Keyboard lock
3270 terminals have a keyboard lock, which disables all of the keys on the keyboard except for the Reset key. The keyboard is automatically locked when the user presses an AID key, or if the user makes some sort of error, such as attempting to overwrite a protected field or overflowing a field.

Normally only the Reset key or a host command with a Reset will clear a keyboard lock, but the x3270 family relaxes this rule somewhat. The oerrLock resource can be set to False to disable locking due to operator errors. Even if oerrLock is True, an operator error lock can be reset by pressing one of the cursor-movement keys (&#x2191;, &#x2193;, &#x2190;, &#x2192;, &#x21b2;, &#x21e5;, &#x21e4; or Home).

The x3270 family also implements an unlock delay feature to assist scripts and macros.

AID
When the terminal wants to send data to the host, it sends an Attention IDentifier (AID). There are distinct AIDs associated with the Clear key, the Enter key, the four Program Attention| keys (PA1 through PA4), and the twenty-four PF Program Function keys (PF1 through PF24).

The AID sent to the host also includes the contents of all of the modified fields on the screen, with EBCDIC NUL characters removed.

When the terminal sends an AID to the host, the keyboard is locked until the host explicitly unlocks it with a command that includes the Reset flag.

Insert Mode
3270 terminals have an insert mode. When set, new data is inserted into a field, with existing data in the field shifted to the right. When clear, new data overwrite existing data. Insert mode is indicated in the Operator Information Area at the bottom of the screen.

Normally, insert mode needs to be explicitly enabled, and it is automatically cleared when the host unlocks the keyboard. However, the alwaysInsert resource can be used to change the default to having insert mode set after a keyboard unlock.