Scripting
Overview
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.