b3270 protocol

From The x3270 Wiki

The b3270 process accepts operation requests from the user interface and sends back indications. These messages are sent on b3270's standard input and output, or (via the callback resource) over a socket. Unlike the s3270 protocol, all b3270 operations are asynchronous; the next command is accepted immediately. The results of each operation are reported asynchronously. Emulator state changes are reported also asynchronously.

When b3270 receives input end-of-file, it exits.

Protocol Description

b3270 runs in one of two modes: XML and JSON. The mode is controlled by the json resource, and defaults to XML.

XML Mode

In XML mode, b3270 operations and indications are formatted as UTF-8-encoded XML. By default, b3270 input is a document called b3270-in and b3270 output is a document called b3270-out. So the input stream to b3270 must begin with the following:

<xml version="1.0" encoding="UTF-8"?>
<b3270-in>

The input stream should end with:

</b3270-in>

This will cause b3270 to exit.

Similarly, the entire b3270 output stream is bracketed by:

<xml version="1.0" encoding="UTF-8"?>
<b3270-out>

and:

</b3270-out>

Note: The <b3270-out> and <b3270-in> global wrapper elements are optional. The <b3270-out> element can be disabled by setting the wrapperDoc resource to false or passing the -nowrapperdoc command-line option. The <b3270-in> element is always optional, with one caveat: If the <b3270-in> wrapper is omitted, then each input line (delimited by a newline character) must contain parts of at most one XML element. That is to say, an XML element can span lines, but a line cannot include multiple elements or parts of more than one element.

B3270-initialization-xml.png

B3270-termination-xml.png

White space is allowed around and within XML elements, but plain text is never used in the protocol. All information is conveyed by elements and their attributes.

Except for the outer <b3270-out> element, XML elements and the elements nested inside them are normally output on a single line. For example, the initialize indication and screen indications each appear as one gigantic line of output. This behavior can be changed with the indent resource or -indent command-line option. If indent is set to true, output will be spread out on multiple lines and indented (pretty-printed).

XML elements sent from the UI to the emulator are referred to as operations. XML elements sent from the emulator to the user interface are referred to as indications.

Operations and indications are transmitted as complete XML elements. For example, the connection indication tells the user interface about changes to the state of the host session.

B3270-async-xml.png

Similarly, a run operation sent to the emulator tells it to run an action and the run-result indication tells the user interface that an action is complete.

B3270-run-xml.png

b3270 actions run asynchronously, and may complete in a different order than they were sent.

B3270-async-pair-xml.png

JSON Mode

New in 4.2

In JSON mode, every line of b3270 output is a single JSON value. Input can be free-form, with line boundaries having no special significance other than as white space.

JSON values sent from the UI to the emulator are referred to as operations. JSON values sent from the emulator to the user interface are referred to as indications.

JSON values are normally output on a single line. For some indications, such as initialization and screen updates, this line can be quite large. This behavior can be changed with the indent resource or -indent command-line option. If indent is set to true, output will be spread out on multiple lines and indented (pretty-printed).

At initialization, the emulator sends an initialize indication, and the user interface may register one or more pass-through actions that it implements:

B3270-initialization-json.png

The emulator can send other indications at any time. For example, the connection indication tells the user interface about changes to the state of the host session.

B3270-async-json.png

Similarly, a run operation sent to the emulator tells it to run an action and the run-result indication tells the user interface that an action is complete.

B3270-run-json.png

b3270 actions run asynchronously, and may complete in a different order than they were sent.

B3270-async-pair-json.png

Pass-Through Actions

b3270 supports pass-through actions, which are emulator actions implemented by the user interface. An example of a pass-through action would be wx3270's UCopy() action, used to copy selected text to the clipboard. b3270 has no knowledge of the clipboard, but it would be useful to allow this action to appear in keymaps, scripts, macros and sourced files processed by the the emulator. Yet b3270 cannot anticipate this and every other possible UI operation.

To support such an action, the UI can use the register operation at initialization time to inform b3270 of actions it would like to have passed through to it. When b3270 encounters one of these actions, it generates a passthru indication to the UI, giving the action name, parameters and a unique tag. When the UI has processed the action, it uses the succeed or fail operation operation to complete the action, giving back the unique tag and optional result text.

B3270-passthru-xml.png

B3270-passthru-json.png

The pass-through mechanism is also used to implement password prompting for TLS certificates. The action name TlsKeyPassword() is reserved for this purpose. If a password is needed to use an TLS client certificate, b3270 will invoke the TlsKeyPassword() action. If the user interface has not registered a pass-through for TlsKeyPassword(), then the TLS password operation will fail, and the host session will not be established. If a pass-through has been registered, a passthru indication will be generated for it. If the action succeeds, the TLS password will come from the result text. If the action fails, the TLS password operation and host session will fail.

Initialization

When b3270 starts up, it sends an initialize indication. Within that are nested elements (XML) or an array of objects (JSON) that are initialization indications. The first is a hello. These indications give the initial state of the emulator, with useful information like the code page, model number, and TLS options supported.

See also

b3270 operations

b3270 indications

Version history

JSON support, making the XML outer document optional, and the indentation option were added in x3270 4.2 in 2022.