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.
In XML mode, b3270 operations and indications are formatted as -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:
This will cause b3270 to exit.
Similarly, the entire b3270 output stream is bracketed by:
<xml version="1.0" encoding="UTF-8"?> <b3270-out>
<b3270-in> global wrapper elements are optional.
<b3270-out> element can be disabled by setting the wrapperDoc resource to false or passing the -nowrapperdoc command-line option.
<b3270-in> element is always optional, with one caveat: If the
<b3270-in> wrapper is omitted, then each input line (delimited by a
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
<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).
New in 4.2
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).
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 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.
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.