s3270 protocol

The s3270 protocol is a script framing protocol originally defined for s3270. It is the protocol used by s3270 on its standard input and standard output, and optionally by x3270 in the same way. It is the protocol used on TCP sockets between peer scripts and any x3270 family emulator, defined by the scriptPort resource. It can also be used between the emulator and a script started by the Script() action.

The basic model is:

• The script sends a line containing actions and parameters, terminated by a newline character.
• The emulator responds with two or more lines of output, also terminated by newline characters. (On Windows s3270 standard output, the lines are terminated by a CR-LF sequence.)

Note that because the script has to initiate the sequence, the behavior of s3270 run from the command-line appears to be a little disappointing -- it does nothing. Pressing the Return key will send it an action to process (actually no action) and it will respond with a prompt.

s3270 mode

s3270-mode input

In s3270 mode, input consists of lines using action syntax. For example:

Query(CodePage)

Emulator output format (s3270 mode)

Data

Each line of output produced by the action is prefixed by the string data: . (Many actions produce no output, of course). If the command succeeds, this is the result of its operation. If it fails, it is an error message. The script must examine the success indication to determine which it is.

Prompt line

The prompt line has twelve fields, separated by spaces, containing the current state of the emulator. It has largely been superseded by the Query() action. The fields are:

Keyboard status

U unlocked

L locked

E locked due to operator error

Formatting status of the screen

F formatted

U unformatted

Protection status of the current field

U unprotected

P protected

Host connection status

N not connected

C(hostname) connected or connection pending

Emulator mode

N not connected

C connected in NVT character node

L connected NVT line mode

P negotiation pending

I connected in 3270 mode

Model number

2, 3 4 or 5

Number of rows on the display

Number of columns on the display

Cursor row (0 is the top row)

Cursor column (0 is the leftmost column)

Main window ID

The X11 window ID in hexadecimal, if applicable, 0x0 if not

Timing

The time required to execute the last command in seconds, a decimal value with millisecond resolution

Success indication

The last line of output is a single token: ok if the command succeeded, and error if the command failed.

Example responses

The result of running Query(LocalEncoding) on an idle s3270.

data: UTF-8
L U U N N 4 24 80 0 0 0x0 0.000
ok

The result of running Query(Garbage) on an idle s3270.

data: Query: Unknown parameter
L U U N N 4 24 80 0 0 0x0 0.000
error

JSON mode

New in 4.2

JSON input

s3270 protocol input can also be in JSON format. If an input line begins with the characters ", {, or [, it is assumed to be JSON.

JSON input can take one of three forms:

• A JSON string encapsulates the usual x3270 actions and parameters.

"Query(CodePage)"

• A struct gives the name of an action and its parameters as an optional list. Some examples:

{"action":"Set","args":["bsdTm","false"]}
{"action":"Clear"}

• An array can contain a set of structs defining a sequence of actions to perform. For example:

[{"action":"Set","args":["bsdTm","false"]},{"action":"Clear"}]

Emulator output format (JSON)

If the input is provided in JSON format, the response will be in JSON format.

The output is an object containing the following elements:

result

An optional array of output lines from the action.

success

A Boolean value indicating true for success and false for failure.

status

A string giving the current emulator status (prompt line) as described above.

Example responses

The result of running {"action":"Query","args":["LocalEncoding"]}

{"result":["UTF-8"],"success":true,"status":"L U U N N 4 24 80 0 0 0x0 0.000"}

The result of running {"action":"Query","args":["Garbage"]} on an idle s3270

{"result":["Query: Unknown parameter"],"success":false,"status":"L U U N N 4 24 80 0 0 0x0 0.000"}

Note: Asynchronous errors

When s3270 encounters an asynchronous error (in particular, when it encounters an error trying to negotiate a host session when the host is specified on the command line, or when automatically reconnecting to a host), the error message is written to the process' standard error output (stderr). This is outside the boundary of the s3270 protocol, and the output is not preceded by data:.

See also

x3270if