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