The b3270 Protocol

b3270 is a 3270 emulation back-end, designed to allow flexible implementation of different user interfaces.

Basic Operation

The b3270 process accepts operation requests from the user interface on its standard input stream, and sends indications on its standard output stream. Unlike the s3270 scripting 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.

A user interface application creates an instance of the b3270 process with b3270's standard input and output connected to it by pipes or a similar mechanism, allowing its operation as a 'captive' process. When b3270 receives end-of-file on its standard input, it exits.

Protocol Description

b3270 operations and indications are formatted as UTF-8-encoded XML. b3270 input is a document called b3270-in. 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 first line is actually optional, but helpful.) 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>

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

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 bell indication, which tells the user interface to ring the terminal bell, looks like this:

 <bell/>

Similarly, a run operation sent to the emulator might look like this:

 <run r-tag="ui-1234" type="keymap" actions="Enter()"/>

Pass-Through Actions

b3270 supports pass-through actions, which are emulator actions implemented by the user interface. An example of a pass-through action could be UI-Copy(), used to copy selected text to the clipboard. The emulator back end 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 the emulator 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 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 that operation succeeds, the TLS password will come from the result text. If the operation fails, the TLS password operation and host session will fail.

Initialization

When b3270 starts up, it sends an initialize indication. Within that element are a series of initialization indications to the user interface. The first is a hello. These indications give the initial state of the emulator, with useful information like the character set, model number, and TLS options supported.

User Interface Operations

The following operations can be initiated by the user interface.

fail register run
succeed

Emulator Indications

The following indications can be generated by the emulator. Indications that are generated at initialization time are marked with an asterisk.

attr bell char
code-page* code-pages* connect-attempt
connection cursor erase*
flipped font formatted
ft hello* icon-name
model model models*
oia* passthru popup
prefixes* proxies* proxy*
row run-result screen
screen-mode* scroll setting*
stats terminal-name* thumb
tls tls-hello* trace-file
ui-error window-title

b3270: Protocol - Operations - Indications