x3270 HTTP Scripting Support

The x3270 family of emulators support an HTTP server, which implements REST APIs to allow the emulator state to be queried and modified by scripts. It can also be used interactively from a browser for debug and experimentation.

Configuration

The HTTP server is enabled by the -httpd command-line option or the httpd resource. The value is a string that specifies the TCP port, and optionally the address to accept connections on. The default address is the IPv4 local loopback address, 127.0.0.1. The syntax for the option is:
   port
   :port
   *:port
   address:port
   [address]:port

The address can be a symbolic hostname and the port can be a symbolic service name. The address can also be specified as *, which means to accept connections from any IPv4 address. The syntax with the square brackets is intended to use with numeric IPv6 addresses, to resolve the ambiguity between colons inside the address and the colon separating the address from the port.

Namespace

The namespace looks like this:

Object Type Contents
/3270/ Directory Root of all emulator objects
/3270/rest/ Directory Root of REST APIs
/3270/rest/text/ REST object REST HTML API
/3270/rest/stext/ REST object REST plain text API with status line
/3270/rest/html/ REST object REST HTML API
/3270/interact.html Form Interactive experimentation
/3270/screen.html Document Current screen snapshot

Common REST Information

URL Syntax

Each REST object is followed by an arbitrary string parameter. The parameter is an x3270 action name, followed by optional parameters. For example, the plain text version of the command to execute the Enter action is:
  /3270/rest/text/Enter%28%29
Note that %28 is the ( character and %29 is the ) character, so this request is decoded as Enter().

In the REST parameter, special URL characters such as (, ), ?, &, #, /, % and spaces must be percent-encoded. (A good rule of thumb is to percent-encode any character besides upper- and lower-case letters and the digits 0-9.)

Character codes above 0xfe need to be percent-encoded in UTF-8. For example, the character á (U+00E1) would be encoded as %C3%A1.

Responses

The response to a REST command depends on the format chosen. All responses are encoded in UTF-8.

Failed requests result in bad HTTP status, usually 400 for an invalid request and 500 for an internal error. The body of the response, in HTML, includes descriptive text for the error.

Type-Specific Information

Plain Text

The /3270/rest/text/ object returns its result as plain UTF-8 text, as returned by the x3270 scripting API. For example, the following URL:
  /3270/rest/text/Query%28CodePage%29
might return the following in a text/plain response:
  37+
followed by CR and LF characters.

Plain Text with Status

The /3270/rest/stext/ object returns its result as plain UTF-8 text, as returned by the x3270 scripting API. In addition, the first line of the response is the x3270 scripting status line. For example, the following URL:
  /3270/rest/stext/Query%28CodePage%29
might return the following in a text/plain response:
  L U U N N 4 24 80 0 0 0x3800040 -
  37+
CR and LF characters terminate each line.

HTML

The /3270/rest/html/ object returns its results in UTF-8 encoded HTML. It is likely more useful for debug and interactive experimentation than for scripting.

The title and H1 heading indicate the success of the request.

There are two H2 sections. The first is the status line, and the second is the response text. The contents of each section is a <PRE> block containing the literal text. If the response is empty, the corresponding section has the italic string (empty) instead.

At the bottom is a horizontal rule and the x3270 version string.

Other Objects

Interactive Form

The /3270/interact.html object is an interactive form. It includes a text box for entering actions, a snapshot of the screen in with all available text attributes, and the text of the status line and response for the most recent command. Entering an empty action will refresh the screen display.

Screen Snapshot

The /3270/screen.html object is an HTML-formatted snapshot of the current screen contents. It uses all available text attributes, and is similar to what would be displayed by c3270 or wc3270.