source: trunk/third/x3270/x3270-script.man @ 11123

Revision 11123, 8.5 KB checked in by ghudson, 27 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r11122, which included commits to RCS files with non-trunk default branches.
Line 
1.TH X3270-SCRIPT 1 "14 October 1996"
2.SH NAME
3Scripting Facilities for x3270
4.SH SYNOPSIS
5.B x3270
6.B \-script
7[
8.I x3270-options
9]
10.br
11.B Script(
12.I command
13.B [
14.I , arg ...
15.B ] )
16.SH DESCRIPTION
17The
18.B x3270
19scripting facilities allow
20.B x3270
21to be operated under the control of another program.
22.PP
23There are two basic methods.
24The first is the
25.B "peer script"
26facility, invoked by the
27.B \-script
28switch.
29This runs
30.B x3270
31as a child of another process.
32Typically this would be a script using
33.IR expect (1)
34or the co-process facility of the Korn Shell
35.IR ksh (1).
36When the
37.B \-script
38switch is given,
39.B x3270
40looks for commands on its standard input, and places the responses on
41standard output and standard error output.
42.PP
43The second method is the
44.B "child script"
45facility, invoked by the
46.B Script()
47action.
48This runs a script as a child process of
49.B x3270.
50The child has access to pipes connected to
51.B x3270;
52.B x3270
53looks for commands on one pipe, and places the responses on the other.
54(The file descriptor of the pipe for commands to
55.B x3270
56is passed in the environment variable X3270INPUT; the file descriptor
57of the pipe for responses from
58.B x3270
59is passed in the environment variable X3270OUTPUT.)
60.PP
61(It is possible to mix the two methods: A script can invoke another script
62with the
63.B Script()
64action.
65Scripts may also be implicitly nested when a script invokes the
66.B Connect()
67action, and the
68.B ibm_hosts
69file specifies a login script for that host name.)
70.PP
71Commands are X actions; the syntax is the same as for the right-hand
72side of an X translation table (an
73.B x3270
74keymap), with two exceptions: only one action may appear per line, and
75if no parameters are needed by the action, the parentheses may be omitted.
76.PP
77Any
78.B x3270
79action may be specified.
80Several new actions have been defined for use by scripts, and the behavior
81of certain other actions (and of
82.B x3270
83in general) is different when an action is initiated by a script.
84.PP
85Some actions generate output; some may delay completion until the certain
86external events occur, such as the host unlocking the keyboard.
87The completion of every command is marked by a two-line message.
88The first line is the current status of
89.BR x3270 ,
90documented below.
91If the command is successful, the second line is the string "ok"; otherwise it
92is the string "error".
93.SH "STATUS FORMAT"
94The status message consists of 12 blank-separated fields:
95.TP
96Keyboard State
97If the keyboard is unlocked, the letter
98.BR U .
99If the keyboard is locked waiting for a response from the host, or if not
100connected to a host, the letter
101.BR L .
102If the keyboard is locked because of an operator error (field overflow,
103protected field, etc.), the letter
104.BR E .
105.TP
106Screen Formatting
107If the screen is formatted, the letter
108.BR F .
109If unformatted or in
110.SM ANSI
111mode,
112the letter
113.BR U .
114.TP
115Field Protection
116If the field containing the cursor is protected, the letter
117.BR P .
118If unprotected or unformatted, the letter
119.BR U .
120.TP
121Connection State
122If connected to a host, the string
123.BI C( hostname ).
124Otherwise, the letter
125.B N .
126.TP
127Emulator Mode
128If connected in 3270 mode, the letter
129.BR I .
130If connected in ANSI line mode, the letter
131.BR L .
132If connected in ANSI character mode, the letter
133.BR C .
134If not connected, the letter
135.BR N .
136.TP
137Model Number (2-5)
138.TP
139Number of Rows
140The current number of rows defined on the screen.
141The host can request that
142.B x3270
143use a 24x80 screen, so this number may be smaller than the maximum number of
144rows possible with the current model.
145.TP
146Number of Columns
147The current number of columns defined on the screen, subject to the same
148difference for rows, above.
149.TP
150Cursor Row
151The current cursor row (zero-origin).
152.TP
153Cursor Column
154The current cursor column (zero-origin).
155.TP
156Window ID
157The X window identifier for the main
158.B x3270
159window, in hexadecimal preceded by
160.BR 0x .
161.SH DIFFERENCES
162When an action is initiated by a script,
163.B x3270
164behaves in several different ways:
165.PP
166If an error occurs, the usual pop-up window does not appear.
167Instead, the text is written to standard error output.
168.PP
169If end-of-file is detected on standard input,
170.B x3270
171exits.
172(A script can exit without killing
173.B x3270
174by using the CloseScript action, below.)
175Note that this applies to peer scripts only; end-of-file on the pipe
176connected to a child script simply causes the pipes to be closed and
177the
178.B Script()
179action to complete.
180.PP
181The
182.B Quit()
183action always causes
184.B x3270
185to exit.
186(When called from the keyboard, it will exit only if not connected to a host.)
187.PP
188The
189.BR Clear() ,
190.BR Enter() ,
191.BR PF() ,
192and
193.B PA()
194actions will not complete until the host
195unlocks the keyboard.
196If the parameter to a
197.B String()
198action includes a code for one these actions,
199it will also wait for the keyboard to unlock before completing.
200Similarly, the
201.B Script()
202action does not complete until end-of-file is
203detected on the pipe or the
204.B CloseScript()
205action is called by the child
206process.
207.SH "NEW ACTIONS"
208The following actions have been defined or modified for use with scripts.
209(Note that unlike the display on the status line,
210.I row
211and
212.I col
213coordinates used in these actions use [0,0] as their origin, not [1,1]).
214.TP
215.B AnsiText()
216Outputs whatever data that has been output by the host in
217.SM ANSI
218mode
219since the last time that
220.B AnsiText()
221was called.
222The data is preceded by the string "data:\ ", and has had all control characters
223expanded into C backslash sequences.
224.IP
225This is a convenient way to capture
226.SM ANSI
227mode output in a synchronous manner without trying to decode the screen
228contents.
229.TP
230.BI Ascii( row,col,rows,cols )
231.TP
232.BI Ascii( row,col,len )
233.TP
234.BI Ascii( len )
235.TP
236.B Ascii()
237Outputs an
238.SM ASCII
239text representation of the screen contents.
240Each line is preceded by the string "data:\ ", and there are no control
241characters.
242.IP
243If four parameters are given, a rectangular region of the screen is output.
244.IP
245If three parameters are given,
246.I len
247characters are output, starting at the specified row and column.
248.IP
249If only the
250.I len
251parameter is given, that many characters are output, starting at the cursor
252position.
253.IP
254If no parameters are given, the entire screen is output.
255.TP
256.B AsciiField()
257Outputs an
258.SM ASCII
259text representation of the field containing the cursor.
260The text is preceded by the string "data:\ ".
261.TP
262.BI Connect( hostname )
263Connects to a host.
264The command does not return until
265.B x3270
266is successfully connected in the proper mode, or the connection fails.
267.TP
268.BI CloseScript( status )
269Causes
270.B x3270
271to stop reading commands from the script.
272This is useful to allow a peer script to exit, with
273.B x3270
274proceeding interactively.
275(Without this command,
276.B x3270
277would exit when it detected end-of-file on standard input.)
278If the script was invoked by the
279.B Script()
280action, the optional
281.I status
282is used as the return status of
283.B Script();
284if nonzero,
285.B Script()
286will complete with an error, and if this script was invoked as part of
287login through the
288.B ibm_hosts
289file, the connection will be broken.
290.TP
291.BI ContinueScript( param )
292Allows a script that is waiting in a
293.B PauseScript()
294action, below, to continue.
295The
296.I param
297given is output by the
298.B PauseScript()
299action.
300.TP
301.B Disconnect()
302Disconnects from the host.
303.TP
304.BI Ebcdic( row,col,rows,cols )
305.TP
306.BI Ebcdic( row,col,len )
307.TP
308.BI Ebcdic( len )
309.TP
310.B Ebcdic()
311The same function as
312.B Ascii()
313above, except that rather than generating
314.SM ASCII
315text, each character is output as a hexadecimal
316.SM EBCDIC
317code, preceded by
318.BR 0x .
319.TP
320.B EbcdicField()
321The same function as
322.B AsciiField()
323above, except that it generates hexadecimal
324.SM EBCDIC
325codes.
326.TP
327.BI Info( message )
328Pops up an informational message.
329.TP
330.BI Expect( text )
331.TP
332.BI Expect( text , timeout )
333Pauses the script until the specified
334.I text
335appears in the data stream from the host, or the specified
336.I timeout
337(in seconds) expires.
338If no
339.I timeout
340is specified, the default is 30 seconds.
341.I Text
342can contain standard C-language escape (backslash) sequences.
343No wild-card characters or pattern anchor characters are understood.
344.B Expect()
345is valid only in
346.SM ANSI
347mode.
348.TP
349.BI MoveCursor( row,col )
350Moves the cursor to the specified coordinates.
351.TP
352.B PauseScript()
353Stops a script until the
354.B ContinueScript()
355action, above, is executed.
356This allows a script to wait for user input and continue.
357Outputs the single parameter to
358.B ContinueScript().
359.TP
360.B Wait()
361A useful utility for use at the beginning of scripts and after the Connect()
362action.
363Waits until the screen is formatted, and the host has positioned the cursor
364on a modifiable field.
365.SH "SEE ALSO"
366expect(1)
367.br
368ksh(1)
369.br
370x3270(1)
Note: See TracBrowser for help on using the repository browser.