3270 data stream protocol

This is a simplified overview of the protocol between the host and the terminal. For a complete reference, please see the full IBM 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.

Text and orders

Each location on the screen contains either text or an order. Orders, which are generally displayed as blanks, control how information is displayed or can be edited on the screen. Orders are also called control characters.

Some examples of orders are:

NUL (Null) X'00': No data -- nothing has been written into this field by either the host or the user
FF (Form Feed) X'0C': Start a new page (printing only)
SO (Shift Out) X'0E': Starts a DBCS sub-field
SI (Shift In) X'0F': Ends a DBCS sub-field
NL (Newline) X'15': Skips to the beginning of the next line (printing only)
EM (End of Medium) X'19': End of print job (printing only)
SF (Start Field) X'1D': Start of a new field (see below)
SFE (Start Field Extended) X'29': Start of a new field (see below)

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 order, 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 orders, and can span rows. The Start Field order that ends a field (and starts the next one) is found by scanning to the right of the starting Start Field order, 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 order has one gigantic field, consisting of the entire screen (except for the Start Field order itself).

In the example below, there are four fields on the screen. The Start Field for field 1 is the darker blue position labeled 1. That field extends until the Start Field for field 2, the darker green position labeled 2. Field 3 begins with the darker yellow position labeled 3 -- almost to the bottom of the screen. Field 4 starts with the darker gray position labeled 4; it wraps around to the top of the screen until the Start Field for field 1. Note that Start Field orders are generally displayed as blanks, and cannot be modified. If they begin a modifiable field, the modifiable part of the field begins to the right of the Start Field orders.

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 orders and other control characters visible, for debugging purposes.

For more details, see the ReadBuffer() action and the article on Field attributes.

Host commands

The host can send a number of different commands to the emulator. These include:

Write: Writes data to the screen buffer.
Erase/Write: Erases the screen and writes data to the buffer. The terminal is set to its default screen size.
Erase/Write Alternate: Erases the screen and writes data to the buffer. The terminal is set to its alternate screen size.
Read Buffer: Requests that the terminal send the entire contents of the screen buffer to the host.

Keyboard lock and reset

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 the Reset flag 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 (↑, ↓, ←, →, ↲, ⇥, ⇤ 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 Access keys (PA1 through PA4), the twenty-four PF Program Function keys (PF1 through PF24), and (depending on the mode) SYS REQ.

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 insert mode is set, new data is inserted into a field, with existing data in the field shifted to the right. When insert mode is unset, new data overwrite existing data. Insert mode is indicated in the Operator Information Area at the bottom of the screen.

Insert mode is controlled by the insertMode resource.

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

Graphic escape

Certain special characters, such as line-drawing characters and APL characters, are represented in the screen buffer with a Graphic Escape (GE) sequence. A GE indicates a switch to a secondary host code page, which in the x3270 family means code page 310. GE characters are called out in the results of the ReadBuffer() action.

Extended data stream

Later 3270 models also support an extended data stream, which supports structured fields. One of the more important features that depends on structured fields is oversize screen dimensions.