--- name: "x3270-script" section: "1x" platform: "linux" package: "x3270" version: "3.1.1.5-1" release: "Debian 1.3 (Bo)" platforms: ["linux"] url: "https://new.carta.tech/x3270-script/1x" --- # x3270-script(1x) ## NAME Scripting Facilities for x3270 ## SYNOPSIS **x3270** **-script** \[ *x3270-options* \]\ **Script(** *command* **\[** *, arg ...* **\] )** ## DESCRIPTION The **x3270** scripting facilities allow **x3270** to be operated under the control of another program. There are two basic methods. The first is the **peer script** facility, invoked by the **-script** switch. This runs **x3270** as a child of another process. Typically this would be a script using [*expect*(1)](/expect/1.md) or the co-process facility of the Korn Shell [*ksh*(1)](/ksh/1.md). When the **-script** switch is given, **x3270** looks for commands on its standard input, and places the responses on standard output and standard error output. The second method is the **child script** facility, invoked by the **Script()** action. This runs a script as a child process of **x3270.** The child has access to pipes connected to **x3270;** **x3270** looks for commands on one pipe, and places the responses on the other. (The file descriptor of the pipe for commands to **x3270** is passed in the environment variable X3270INPUT; the file descriptor of the pipe for responses from **x3270** is passed in the environment variable X3270OUTPUT.) (It is possible to mix the two methods: A script can invoke another script with the **Script()** action. Scripts may also be implicitly nested when a script invokes the **Connect()** action, and the **ibm\_hosts** file specifies a login script for that host name.) Commands are X actions; the syntax is the same as for the right-hand side of an X translation table (an **x3270** keymap), with two exceptions: only one action may appear per line, and if no parameters are needed by the action, the parentheses may be omitted. Any **x3270** action may be specified. Several new actions have been defined for use by scripts, and the behavior of certain other actions (and of **x3270** in general) is different when an action is initiated by a script. Some actions generate output; some may delay completion until the certain external events occur, such as the host unlocking the keyboard. The completion of every command is marked by a two-line message. The first line is the current status of **x3270**, documented below. If the command is successful, the second line is the string "ok"; otherwise it is the string "error". ## STATUS FORMAT The status message consists of 12 blank-separated fields: - Keyboard State If the keyboard is unlocked, the letter **U**. If the keyboard is locked waiting for a response from the host, or if not connected to a host, the letter **L**. If the keyboard is locked because of an operator error (field overflow, protected field, etc.), the letter **E**. - Screen Formatting If the screen is formatted, the letter **F**. If unformatted or in ANSI mode, the letter **U**. - Field Protection If the field containing the cursor is protected, the letter **P**. If unprotected or unformatted, the letter **U**. - Connection State If connected to a host, the string **C(***hostname***).** Otherwise, the letter **N .** - Emulator Mode If connected in 3270 mode, the letter **I**. If connected in ANSI line mode, the letter **L**. If connected in ANSI character mode, the letter **C**. If not connected, the letter **N**. - Model Number (2-5) - Number of Rows The current number of rows defined on the screen. The host can request that **x3270** use a 24x80 screen, so this number may be smaller than the maximum number of rows possible with the current model. - Number of Columns The current number of columns defined on the screen, subject to the same difference for rows, above. - Cursor Row The current cursor row (zero-origin). - Cursor Column The current cursor column (zero-origin). - Window ID The X window identifier for the main **x3270** window, in hexadecimal preceded by **0x**. ## DIFFERENCES When an action is initiated by a script, **x3270** behaves in several different ways: If an error occurs, the usual pop-up window does not appear. Instead, the text is written to standard error output. If end-of-file is detected on standard input, **x3270** exits. (A script can exit without killing **x3270** by using the CloseScript action, below.) Note that this applies to peer scripts only; end-of-file on the pipe connected to a child script simply causes the pipes to be closed and the **Script()** action to complete. The **Quit()** action always causes **x3270** to exit. (When called from the keyboard, it will exit only if not connected to a host.) The **Clear()**, **Enter()**, **PF()**, and **PA()** actions will not complete until the host unlocks the keyboard. If the parameter to a **String()** action includes a code for one these actions, it will also wait for the keyboard to unlock before completing. Similarly, the **Script()** action does not complete until end-of-file is detected on the pipe or the **CloseScript()** action is called by the child process. ## NEW ACTIONS The following actions have been defined or modified for use with scripts. (Note that unlike the display on the status line, *row* and *col* coordinates used in these actions use \[0,0\] as their origin, not \[1,1\]). - **AnsiText()** Outputs whatever data that has been output by the host in ANSI mode since the last time that **AnsiText()** was called. The data is preceded by the string "data: ", and has had all control characters expanded into C backslash sequences. - This is a convenient way to capture ANSI mode output in a synchronous manner without trying to decode the screen contents. - **Ascii(***row,col,rows,cols***)** - **Ascii(***row,col,len***)** - **Ascii(***len***)** - **Ascii()** Outputs an ASCII text representation of the screen contents. Each line is preceded by the string "data: ", and there are no control characters. - If four parameters are given, a rectangular region of the screen is output. - If three parameters are given, *len* characters are output, starting at the specified row and column. - If only the *len* parameter is given, that many characters are output, starting at the cursor position. - If no parameters are given, the entire screen is output. - **AsciiField()** Outputs an ASCII text representation of the field containing the cursor. The text is preceded by the string "data: ". - **Connect(***hostname***)** Connects to a host. The command does not return until **x3270** is successfully connected in the proper mode, or the connection fails. - **CloseScript(***status***)** Causes **x3270** to stop reading commands from the script. This is useful to allow a peer script to exit, with **x3270** proceeding interactively. (Without this command, **x3270** would exit when it detected end-of-file on standard input.) If the script was invoked by the **Script()** action, the optional *status* is used as the return status of **Script();** if nonzero, **Script()** will complete with an error, and if this script was invoked as part of login through the **ibm\_hosts** file, the connection will be broken. - **ContinueScript(***param***)** Allows a script that is waiting in a **PauseScript()** action, below, to continue. The *param* given is output by the **PauseScript()** action. - **Disconnect()** Disconnects from the host. - **Ebcdic(***row,col,rows,cols***)** - **Ebcdic(***row,col,len***)** - **Ebcdic(***len***)** - **Ebcdic()** The same function as **Ascii()** above, except that rather than generating ASCII text, each character is output as a hexadecimal EBCDIC code, preceded by **0x**. - **EbcdicField()** The same function as **AsciiField()** above, except that it generates hexadecimal EBCDIC codes. - **Info(***message***)** Pops up an informational message. - **Expect(***text***)** - **Expect(***text***,***timeout***)** Pauses the script until the specified *text* appears in the data stream from the host, or the specified *timeout* (in seconds) expires. If no *timeout* is specified, the default is 30 seconds. *Text* can contain standard C-language escape (backslash) sequences. No wild-card characters or pattern anchor characters are understood. **Expect()** is valid only in ANSI mode. - **MoveCursor(***row,col***)** Moves the cursor to the specified coordinates. - **PauseScript()** Stops a script until the **ContinueScript()** action, above, is executed. This allows a script to wait for user input and continue. Outputs the single parameter to **ContinueScript().** - **Wait()** A useful utility for use at the beginning of scripts and after the Connect() action. Waits until the screen is formatted, and the host has positioned the cursor on a modifiable field. ## SEE ALSO [expect(1)](/expect/1.md)\ [ksh(1)](/ksh/1.md)\ [x3270(1)](/x3270/1.md)