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