Script() action

From The x3270 Wiki

The Script() action runs a child process of the emulator, which can supply actions for the emulator to execute. (This is in contrast to the Source() action, which reads a file containing a list of actions, and executes them one after the other.)

Parameters

The syntax for Script() is as follows:

[option...] script-name [argument...]
option
All Script() options begin with a - character.
script-name
The name (full pathname if necessary) of an executable program to run.
argument
The balance of the parameters as passed as command-line arguments to the program.

Options

-async

Asynchronous script. The Script() action returns immediately, without waiting for the program to exit. Any output from the program will be reported with a pop-up, unless -nostdoutredirect is also given.

-interactive

(c3270 and wc3270 only) Run the script on the terminal or window where the emulator is running, allowing it to access standard input and standard output. New in 4.2

-nolock

Do not disable the keyboard while the script is running. (Normally the keyboard is disabled during script execution, so user actions do not interfere with the operation of the script.)

-nostdoutredirect

Do not redirect standard output and standard error from the script. Without this option, the result of the Script() action is the output from the program.

-single

If a socket is used with the s3270 protocol, the emulator will accept just a single connection and then close the listener.

-shareconsole

(Windows only) Share the console between the emulator and the child process. Without this option, the child process is started detached, with no console. New in 4.0

Blocking behavior

Script() blocks until the program exits. This can be overridden with the -async option.

Communication between the script and emulator

There are three different ways that a child script can communicate with the emulator.

On POSIX, pipes will be created for communicating with the emulator via the s3270 protocol. The file descriptor number for the pipe for passing commands to the emulator is passed to the program via the X3270INPUT environment variable. The file descriptor number for the pipe for returning results back to the emulator is passed to the program via the X3270OUTPUT environment variable.

On all platforms, the script can use a socket and the s3270 protocol to communicate with the emulator. The X3270PORT environment variable gives the TCP port to connect to.

On all platforms, the program can use HTTP requests to communicate with the emulator. The X3270URL environment variable gives the base of the URL to connect to.

New in 4.4 On all platforms, if a security cookie is defined, the X3270COOKIEFILE environment variable gives the pathname of the security cookie file.

Return value

Script() returns the output of the program. This can be overridden with the -nostdoutredirect option. Script() will fail if the program exits with non-zero status.

Examples

Run a typical script, giving it two command-line parameters.

Script(MyScript,first,foo)