Scripting

From The x3270 Wiki
Jump to navigation Jump to search

Description

The x3270 family supports scripting (automation of an interactive session and screen scraping) in a number of different ways.

Scripting types

Peer scripting

In peer scripting, the emulator is started by another program which intends to control it. The emulator is started with command-line options that indicate how it is to be accessed. (In the case of s3270, no option is necessary, but options can specify methods other than the default.)

Options include:

-script
Use the s3270 protocol over the emulator process's standard input and standard output.
-scriptport
Use the s3270 protocol over a particular TCP port.
-socket
Use the s3270 protocol over a Unix-domain socket (POSIX systems only).
-httpd
Use REST over HTTP connections.

Child scripting

In child scripting, the emulator creates a child process to perform some sort of automated action. This is done through the Script() action, which is given the name of an executable program to run and optional parameters. Typically Script() is invoked via a keymap or macro.

The child process then accesses the emulator using HTTP, or using the s3270 protocol over a TCP socket or (on POSIX only) pipes, with environment variables indicating the correct ports to use.

Passive scripting

In passive scripting, a group of actions are executed one after another without any intelligence applied to the results.

Keymap entries and macros, if they specify more than one action, are passive scripts.

Actions can also be read from a file with the Source() action, or (if the emulator supports it) they can be supplied to the emulator's standard input.

Emulator actions

Every emulator action either succeeds for fails. For example, an action could fail if it is supplied with incorrect arguments, if it was executed when the emulator was in the wrong mode, or if it depends on a host session being connected and the host disconnects. If an action fails, the macro the invoked it stops and fails. That is, if it is one of several actions on the same line, the remaining actions on the line will be ignored.

Some actions produce output, which is returned to the script. Error messages produced by failures are also returned to the script.

Many actions block until they complete. For example, the PF() action blocks until the host unlocks the keyboard. (The aidWait resource can be used to disable this behavior, with caution.) In addition, the Wait() action is specifically designed to delay a script until a specified condition is met.

See also

-script command-line option

-scriptport command-line option

-socket command-line option

-httpd command-line option

s3270 protocol

HTTP server

Category:Actions

Category:Scripting actions

Action syntax