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., http://127.0.0.1:8080/) 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.

http://127.0.0.1:8080/3270/interact.html: An interactive form for submitting actions to the emulator.
http://127.0.0.1:8080/3270/screen.html: The current screen image.
http://127.0.0.1:8080/3270/rest/json/action-and-parameters: REST GET API with results returned as JSON. New in 4.0
http://127.0.0.1:8080/3270/rest/html/action-and-parameters: REST GET API with results returned as HTML.
http://127.0.0.1:8080/3270/rest/text/action-and-parameters: REST GET API with results returned as plain text.
http://127.0.0.1:8080/3270/rest/stext/action-and-parameters: REST GET API with results returned as plain text, beginning with the status line.
http://127.0.0.1:8080/3270/rest/post: REST POST API. New in 4.2

Note that when an action and parameters are passed as part of a URL, the ? character must be escaped as %3F, 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, action, a string naming the action, and arg, 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 status, a string containing the status line, and result, an array of strings containing the output of the action or null if there was no output.

Security cookies

New in 4.4

If a security cookie is defined, requests will fail with status 403 unless they specify the cookie. The cookie value is specified using a cookie named x3270-security.

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

New in 4.0

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:

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
 <html>
 <head>
 <title>Success</title>
 </head>
 <body>
 <h1>Success</h1>
 <h2>Status</h2>
 <pre>L U U N N 4 24 80 0 0 0x0 0.000</pre>
 <h2>Result</h2>
 <pre>passthru no-username 3514
 http username 3128
 telnet no-username
 socks4 username 1080
 socks4a username 1080
 socks5 username 1080
 socks5d username 1080
 </pre>
 <hr>
 <i>wc3270 v4.0alpha2 Sat Dec 28 05:26:41 UTC 2019 pdm - <a href="http://x3270.bgp.nu/">x3270.bgp.nu</a></i>
 </body>
 </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.