B3270 protocol

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: &lt;xml version="1.0" encoding="UTF-8"?&gt; &lt;b3270-in&gt;

The input stream should end with: &lt;/b3270-in&gt;

This will cause b3270 to exit.

Similarly, the entire b3270 output stream is bracketed by: &lt;xml version="1.0" encoding="UTF-8"?&gt; &lt;b3270-out&gt; and: &lt;/b3270-out&gt;

Note: The  and   global wrapper elements are optional. The  element can be disabled by setting the wrapperDoc resource to false or passing the -nowrapperdoc command-line option. The  element is always optional, with one caveat: If the   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.





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  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.



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 actions run asynchronously, and may complete in a different order than they were sent.



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:



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.



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 actions run asynchronously, and may complete in a different order than they were sent.



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.





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.

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