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.

JSON input
New in 4.2

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. However, the response will be in JSON format. "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"}]

Data
Each line of output produced by the action is prefixed by the string. (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
 * unlocked
 * locked
 * locked due to operator error


 * Formatting status of the screen
 * formatted
 * unformatted


 * Protection status of the current field
 * unprotected
 * protected


 * Host connection status
 * not connected
 * connected or connection pending


 * Emulator mode
 * not connected
 * connected in NVT character node
 * connected NVT line mode
 * negotiation pending
 * connected in 3270 mode


 * Model number
 * ,    or


 * 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,  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:  if the command succeeded, and   if the command failed

Emulator output format (JSON)
New in 4.2

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

The output is a struct containing the following fields:
 * 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  on an idle s3270. data: UTF-8 L U U N N 4 24 80 0 0 0x0 0.000 ok The same command specified in JSON:  New in 4.2 {"result":["UTF-8"],"success":true,"status":"L U U N N 4 24 80 0 0 0x0 0.000"} The result of running  on an idle s3270. data: Query: Unknown parameter L U U N N 4 24 80 0 0 0x0 0.000 error The same command specified in JSON:  New in 4.2 {"result":["Query: Unknown parameter"],"success":false,"status":"L U U N N 4 24 80 0 0 0x0 0.000"}

Version history
JSON support was added to x3270 4.2 in 2022.