HTTP server

The x3270 family supports an HTTP server. Scripts can send REST requests to the emulator via HTTP to modify the emulator or query its state.

This is only a remote control facility -- it is not a way to access an interactive 3270 emulator over a web browser. See below for possible alternatives.

A global HTTP server is configured via the httpd resource or the -httpd command-line option. The Script action also creates a new instance of the HTTP server for each child script to use.

The HTTP server can be explored from a web browser. Just point a browser at the root (e.g., ) and appropriate directories will be displayed.

Note that on all platforms, lines of output from the HTTP server are separated by CR/LF sequences.

Namespace
These URLs assume that the server is set up to listen on the IPv4 loopback address, port 8080.
 * An interactive form for submitting actions to the emulator.
 * An interactive form for submitting actions to the emulator.


 * The current screen image.
 * The current screen image.


 * REST GET API with results returned as JSON.
 * REST GET API with results returned as JSON.


 * REST GET API with results returned as HTML.
 * REST GET API with results returned as HTML.


 * REST GET API with results returned as plain text.
 * REST GET API with results returned as plain text.


 * REST GET API with results returned as plain text, beginning with the status line.
 * REST GET API with results returned as plain text, beginning with the status line.


 * New in 4.2
 * REST POST API.

Note that when an action and parameters are passed as part of a URL, the  character must be escaped as , so it is not mistaken for the delimiter for query parameters.

POST API
New in 4.2

The POST API accepts multiple forms of input, based on the Content-type header field. Supported types are:
 * text/plain
 * Ordinary text, UTF-8 encoded. Uses formal action syntax. The reply is also plain text, with the status line first and any output following.


 * application/json
 * JSON formatted text. The request is a struct containing two elements,, a string naming the action, and  , an optional array giving a set of arguments. Multiple actions can be specified by using an array of these structs. The result is also returned as JSON, as a struct containing  , a string containing the status line, and  , an array of strings containing the output of the action or   if there was no output.

REST API GET Examples
These requests use the HTTP GET verb. Simply add the action and parameters to the desired URL. For example, to perform the Query action with the Proxies query, with the response in HTML, use this URL: http://127.0.0.1:8080/3270/rest/html/Query(Proxies)

JSON
HTTP GET: http://127.0.0.1:8080/3270/rest/json/Query(Proxies) Result: { "status": "L U U N N 4 24 80 0 0 0x0 0.000", "result": [ "passthru no-username 3514", "http username 3128", "telnet no-username", "socks4 username 1080", "socks4a username 1080", "socks5 username 1080", "socks5d username 1080" ] }

HTML
HTTP GET: http://127.0.0.1:8080/3270/rest/html/Query(Proxies) Result: &lt;!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> &lt;html> &lt;head> &lt;title>Success&lt;/title> &lt;/head> &lt;body> &lt;h1>Success&lt;/h1> &lt;h2>Status&lt;/h2> &lt;pre>L U U N N 4 24 80 0 0 0x0 0.000&lt;/pre> &lt;h2>Result&lt;/h2> &lt;pre>passthru no-username 3514 http username 3128 telnet no-username socks4 username 1080 socks4a username 1080 socks5 username 1080 socks5d username 1080 &lt;/pre> &lt;hr> &lt;i>wc3270 v4.0alpha2 Sat Dec 28 05:26:41 UTC 2019 pdm - &lt;a href="http://x3270.bgp.nu/">x3270.bgp.nu&lt;/a>&lt;/i> &lt;/body> &lt;/html>

Plain text with status line
HTTP GET: http://127.0.0.1:8080/3270/rest/stext/Query(Proxies) Result: L U U N N 4 24 80 0 0 0x0 0.000 passthru no-username 3514 http username 3128 telnet no-username socks4 username 1080 socks4a username 1080 socks5 username 1080 socks5d username 1080

Plain text
HTTP GET: http://127.0.0.1:8080/3270/rest/text/Query(Proxies) Result: passthru no-username 3514 http username 3128 telnet no-username socks4 username 1080 socks4a username 1080 socks5 username 1080 socks5d username 1080

REST API POST Examples
New in 4.2

Plain Text
Request: Set(monoCase) Response: L U U N N 4 24 80 0 0 0x0 0.000 false

JSON
Request: {  "action": "Set", "args": [ "monoCase" ] } Result: {  "result": [ "false" ],  "status": "L U U N N 4 24 80 0 0 0x0 0.000" } Request: [  {     "action": "Set", "args": [ "monoCase" ]  },   {      "action": "Set", "args": [ "model" ]  } ] Response: {  "result": [ "false", "3279-4-E" ],  "status": "L U U N N 4 24 80 0 0 0x0 0.000" }

3270 emulator inside a web browser
To view a live c3270 session inside a web browser, try web3270.

To view a live x3270 session inside a web browser, try noVNC.

Version history
JSON GET support was added to x3270 4.0 in 2020.

POST support was added to x3270 4.2 in 2021.