1X3270-SCRIPT(1) General Commands Manual X3270-SCRIPT(1)
2
6 Scripting Facilities for x3270, s3270 and c3270
7
9 x3270 -script [ x3270-options ]
10 s3270 [ x3270-options ]
11 Script ( command [ ,arg... ] )
12
14 The x3270 scripting facilities allow the interactive 3270 emulators
15 x3270 and c3270 to be operated under the control of another program,
16 and form the basis for the script-only emulator s3270.
17 There are two basic scripting methods. The first is the peer script
19 facility, invoked by the x3270 -script switch, and the default mode for
20 s3270. This runs x3270 or s3270 as a child of another process. Typi‐
21 cally this would be a script using expect(1), perl(1), or the co-
22 process facility of the Korn Shell ksh(1). Inthis mode, the emulator
23 process looks for commands on its standard input, and places the
24 responses on standard output and standard error output.
25 The second method is the child script facility, invoked by the Script
27 action in x3270, c3270, or s3270. This runs a script as a child
28 process of the emulator. The child has access to pipes connected to
29 the emulator; the emulator look for commands on one pipe, and places
30 the responses on the other. (The file descriptor of the pipe for com‐
31 mands to the emulator is passed in the environment variable X3270INPUT;
32 the file descriptor of the pipe for responses from the emulator is
33 passed in the environment variable X3270OUTPUT.)
34 It is possible to mix the two methods. A script can invoke another
36 script with the Script action, and may also be implicitly nested when a
37 script invokes the Connect action, and the ibm_hosts file specifies a
38 login script for that host name.
39 Commands are emulator actions; the syntax is the same as for the right-
41 hand side of an Xt translation table entry (an x3270 or c3270 keymap).
42 Unlike translation tables, action names are case-insensitive, can be
43 uniquely abbreviated, and the parentheses may be omitted if there are
44 no parameters.
45 Any emulator action may be specified. Several specific actions have
47 been defined for use by scripts, and the behavior of certain other
48 actions (and of the emulators in general) is different when an action
49 is initiated by a script.
50 Some actions generate output; some may delay completion until the cer‐
52 tain external events occur, such as the host unlocking the keyboard.
53 The completion of every command is marked by a two-line message. The
54 first line is the current status of the emulator, documented below. If
55 the command is successful, the second line is the string "ok"; other‐
56 wise it is the string "error".
57
59 The status message consists of 12 blank-separated fields:
60 1 Keyboard State
62 If the keyboard is unlocked, the letter U. If the keyboard is
63 locked waiting for a response from the host, or if not connected
64 to a host, the letter L. If the keyboard is locked because of
65 an operator error (field overflow, protected field, etc.), the
66 letter E.
67 2 Screen Formatting
69 If the screen is formatted, the letter F. If unformatted or in
70 NVT mode, the letter U.
71 3 Field Protection
73 If the field containing the cursor is protected, the letter P.
74 If unprotected or unformatted, the letter U.
75 4 Connection State
77 If connected to a host, the string C(hostname). Otherwise, the
78 letter N.
79 5 Emulator Mode
81 If connected in 3270 mode, the letter I. If connected in NVT
82 line mode, the letter L. If connected in NVT character mode,
83 the letter C. If connected in unnegotiated mode (no BIND active
84 from the host), the letter P. If not connected, the letter N.
85 6 Model Number (2-5)
87 7 Number of Rows
89 The current number of rows defined on the screen. The host can
90 request that the emulator use a 24x80 screen, so this number may
91 be smaller than the maximum number of rows possible with the
92 current model.
93 8 Number of Columns
95 The current number of columns defined on the screen, subject to
96 the same difference for rows, above.
97 9 Cursor Row
99 The current cursor row (zero-origin).
100 10 Cursor Column
102 The current cursor column (zero-origin).
103 11 Window ID
105 The X window identifier for the main x3270 window, in hexadeci‐
106 mal preceded by 0x. For s3270 and c3270, this is zero.
107 12 Command Execution Time
109 The time that it took for the host to respond to the previous
110 commnd, in seconds with milliseconds after the decimal. If the
111 previous command did not require a host response, this is a
112 dash.
113
115 When an action is initiated by a script, the emulators behave in sev‐
116 eral different ways:
117 If an error occurs in processing an ection, the usual pop-up window
119 does not appear. Instead, the text is written to standard error out‐
120 put.
121 If end-of-file is detected on standard input, the emulator exits. (A
123 script can exit without killing the emulator by using the CloseScript
124 action, below.) Note that this applies to peer scripts only; end-of-
125 file on the pipe connected to a child script simply causes the pipes to
126 be closed and the Script action to complete.
127 The Quit action always causes the emulator to exit. (When called from
129 the keyboard, it will exit only if not connected to a host.)
130 Normally, the AID actions (Clear, Enter, PF, and PA) will not complete
132 until the host unlocks the keyboard. If the parameter to a String
133 action includes a code for one these actions, it will also wait for the
134 keyboard to unlock before proceeding.
135 The AidWait toggle controls with behavior. When this toggle is set
137 (the default), actions block as described above. When the toggle is
138 clear, AID actions complete immediately. The Wait(Output) action can
139 then be used to delay a script until the host changes something on the
140 screen, and the Wait(Unlock) action can be used to delay a script until
141 the host unlocks the keyboard, regardless of the state of the AidWait
142 toggle.
143 Note that the Script action does not complete until end-of-file is
145 detected on the pipe or the CloseScript action is called by the child
146 process. This behavior is not affected by the state of the AidWait
147 toggle.
148
150 The following actions have been defined or modified for use with
151 scripts. (Note that unlike the display on the status line, row and col
152 coordinates used in these actions use [0,0] as their origin, not
153 [1,1]).
154 AnsiText
156 Outputs whatever data that has been output by the host in NVT
157 mode since the last time that AnsiText was called. The data is
158 preceded by the string "data: ", and has had all control charac‐
159 ters expanded into C backslash sequences.
160 This is a convenient way to capture NVT mode output in a syn‐
162 chronous manner without trying to decode the screen contents.
163 Ascii(row,col,rows,cols)
165 Ascii(row,col,length)
167 Ascii(length)
169 Ascii Outputs an ASCII text representation of the screen contents.
171 Each line is preceded by the string "data: ", and there are no
172 control characters.
173 If four parameters are given, a rectangular region of the screen
175 is output.
176 If three parameters are given, length characters are output,
178 starting at the specified row and column.
179 If only the length parameter is given, that many characters are
181 output, starting at the cursor position.
182 If no parameters are given, the entire screen is output.
184 AsciiField
186 Outputs an ASCII text representation of the field containing the
187 cursor. The text is preceded by the string "data: ".
188 Connect(hostname)
190 Connects to a host. The command does not return until the emu‐
191 lator is successfully connected in the proper mode, or the con‐
192 nection fails.
193 CloseScript(status)
195 Causes the emulator to stop reading commands from the script.
196 This is useful to allow a peer script to exit, with the emulator
197 proceeding interactively. (Without this command, the emulator
198 would exit when it detected end-of-file on standard input.) If
199 the script was invoked by the Script action, the optional status
200 is used as the return status of Script; if nonzero, Script will
201 complete with an error, and if this script was invoked as part
202 of login through the ibm_hosts file, the connection will be bro‐
203 ken.
204 ContinueScript(param)
206 Allows a script that is waiting in a PauseScript action, below,
207 to continue. The param given is output by the PauseScript
208 action.
209 Disconnect
211 Disconnects from the host.
212 Ebcdic(row,col,rows,cols)
214 Ebcdic(row,col,length)
216 Ebcdic(length)
218 Ebcdic The same function as Ascii above, except that rather than gener‐
220 ating ASCII text, each character is output as a hexadecimal
221 EBCDIC code, preceded by 0x.
222 EbcdicField
224 The same function as AsciiField above, except that it generates
225 hexadecimal EBCDIC codes.
226 Info(message)
228 Pops up an informational message.
229 Expect(text[,timeout])
231 Pauses the script until the specified text appears in the data
232 stream from the host, or the specified timeout (in seconds)
233 expires. If no timeout is specified, the default is 30 seconds.
234 Text can contain standard C-language escape (backslash)
235 sequences. No wild-card characters or pattern anchor characters
236 are understood. Expect is valid only in NVT mode.
237 MoveCursor(row,col)
239 Moves the cursor to the specified coordinates.
240 PauseScript
242 Stops a script until the ContinueScript action, above, is exe‐
243 cuted. This allows a script to wait for user input and con‐
244 tinue. Outputs the single parameter to ContinueScript.
245 PrintText([command,]filter))
247 Pipes an ASCII representation of the current screen image
248 through the named filter, e.g., lpr.
249 PrintText([html,],file,filename))
251 Saves the current screen contents in a file. With the html
252 option, saves it as HTML, otherwise saves it as plain ASCII.
253 PrintText(html,string)
255 Returns the current screen contents as HTML.
256 ReadBuffer(Ascii)
258 Dumps the contents of the screen buffer, one line at a time.
259 Positions inside data fields are output as 2-digit hexadecimal
260 codes in the current display character set (typically ISO
261 8859-1, but it varies with the host character set). Start-of-
262 field characters (each of which takes up a display position) are
263 output as SF(aa=nn[,...]), where aa is a field attribute type
264 and nn is its value.
265 Attribute Values
267 ─────────────────────────────────────
268 c0 basic 3270 20 protected
269 10 numeric
270 04 detectable
271 08 intensified
272 0c non-display
273 01 modified
274 41 highlighting f1 blink
275 f2 reverse
276 f4 underscore
277 f8 intensify
278 42 foreground f0 neutral black
279 f1 blue
280 f2 red
281 f3 pink
282 f4 green
283 f5 turquoise
284 f6 yellow
285 f7 neutral white
286 f8 black
287 f9 deep blue
288 fa orange
289 fb purple
290 fc pale green
291 fd pale turquoise
292 fe grey
293 ff white
294 43 character set f0 default
295 f1 APL
296 f8 DBCS
297 Extended attributes (which do not take up display positions) are
299 output as SA(aa=nn), with aa and nn having the same definitions
300 as above (though the basic 3270 attribute will never appear as
301 an extended attribute).
302 In addition, NULL characters in the screen buffer are reported
304 as ASCII character 00 instead of 20, even though they should be
305 displayed as blanks.
306 ReadBuffer(Ebcdic)
308 Equivalent to Snap(Ascii), but with the data fields output as
309 hexadecimal EBCDIC codes instead. Additionally, if a buffer
310 position has the Graphic Escape attribute, it is displayed as
311 GE(xx).
312 Snap Equivalent to Snap(Save) (see below).
314 Snap(Ascii,...)
316 Performs the Ascii action on the saved screen image.
317 Snap(Cols)
319 Returns the number of columns in the saved screen image.
320 Snap(Ebcdic,...)
322 Performs the Ebcdic action on the saved screen image.
323 Snap(ReadBuffer)
325 Performs the ReadBuffer action on the saved screen image.
326 Snap(Rows)
328 Returns the number of rows in the saved screen image.
329 Snap(Save)
331 Saves a copy of the screen image and status in a temporary
332 buffer. This copy can be queried with other Snap actions to
333 allow a script to examine a consistent screen image, even when
334 the host may be changing the image (or even the screen
335 dimensions) dynamically.
336 Snap(Status)
338 Returns the status line from when the screen was last saved.
339 Snap(Wait[,timeout],Output)
341 Pauses the script until the host sends further output, then
342 updates the snap buffer with the new screen contents. Used when
343 the host unlocks the keyboard (allowing the script to proceed
344 after an Enter, PF or PA action), but has not finished updating
345 the screen. This action is usually invoked in a loop that uses
346 the Snap(Ascii) or Snap(Ebcdic) action to scan the screen for
347 some pattern that indicates that the host has fully processed
348 the last command.
349 The optional timeout parameter specifies a number of seconds to
351 wait before failing the Snap action. The default is to wait
352 indefinitely.
353 Transfer(keyword=value,...)
355 Invokes IND$FILE file transfer. See FILE TRANSFER below.
356 Wait([timeout,] 3270Mode)
358 Used when communicating with a host that switches between NVT
359 mode and 3270 mode. Pauses the script or macro until the host
360 negotiates 3270 mode, then waits for a formatted screen as
361 above.
362 The optional timeout parameter specifies a number of seconds to
364 wait before failing the Wait action. The default is to wait
365 indefinitely.
366 For backwards compatibility, Wait(3270) is equivalent to
368 Wait(3270Mode)
369 Wait([timeout,] Disconnect)
371 Pauses the script until the host disconnects. Often used to
372 after sending a logoff command to a VM/CMS host, to ensure that
373 the session is not unintentionally set to disconnected state.
374 The optional timeout parameter specifies a number of seconds to
376 wait before failing the Wait action. The default is to wait
377 indefinitely.
378 Wait([timeout,] InputField)
380 A useful utility for use at the beginning of scripts and after
381 the Connect action. In 3270 mode, waits until the screen is
382 formatted, and the host has positioned the cursor on a
383 modifiable field. In NVT mode, waits until the host sends at
384 least one byte of data.
385 The optional timeout parameter specifies a number of seconds to
387 wait before failing the Wait action. The default is to wait
388 indefinitely.
389 For backwards compatibility, Wait is equivalent to
391 Wait(InputField).
392 Wait([timeout,] NVTMode)
394 Used when communicating with a host that switches between 3270
395 mode and NVT mode. Pauses the script or macro until the host
396 negotiates NVT mode, then waits for a byte from the host as
397 above.
398 The optional timeout parameter specifies a number of seconds to
400 wait before failing the Wait action. The default is to wait
401 indefinitely.
402 For backwards compatibility, Wait(ansi) is equivalent to
404 Wait(NVTMode).
405 Wait([timeout,] Output)
407 Pauses the script until the host sends further output. Often
408 needed when the host unlocks the keyboard (allowing the script
409 to proceed after a Clear, Enter, PF or PA action), but has not
410 finished updating the screen. Also used in non-blocking AID
411 mode (see DIFFERENCES for details). This action is usually
412 invoked in a loop that uses the Ascii or Ebcdic action to scan
413 the screen for some pattern that indicates that the host has
414 fully processed the last command.
415 The optional timeout parameter specifies a number of seconds to
417 wait before failing the Wait action. The default is to wait
418 indefinitely.
419 Wait([timeout,] Unlock)
421 Pauses the script until the host unlocks the keyboard. This is
422 useful when operating in non-blocking AID mode (toggle AidWait
423 clear), to wait for a host command to complete. See DIFFERENCES
424 for details).
425 The optional timeout parameter specifies a number of seconds to
427 wait before failing the Wait action. The default is to wait
428 indefinitely.
429
431 The Transfer action implements IND$FILE file transfer. This action
432 requires that the IND$FILE program be installed on the IBM host, and
433 that the 3270 cursor be located in a field that will accept a TSO or
434 VM/CMS command.
435 Because of the complexity and number of options for file transfer, the
437 parameters to the Transfer action take the unique form of option=value,
438 and can appear in any order. The options are:
439 Option Required? Default Other Values
441 ────────────────────────────────────────────────────────
442 Direction No send receive
443 HostFile Yes
444 LocalFile Yes
445 Host No tso vm
446 Mode No ascii binary
447 Cr No remove add, keep
448 Exist No keep replace, append
449 Recfm No fixed, variable,
450 undefined
451 Lrecl No
452 Blksize No
453 Allocation No tracks,
454 cylinders,
455 avblock
456 PrimarySpace No
457 SecondarySpace No
458 BufferSize No 4096
459 The option details are as follows.
461 Direction
463 send (the default) to send a file to the host, receive to
464 receive a file from the host.
465 HostFile
467 The name of the file on the host.
468 LocalFile
470 The name of the file on the local workstation.
471 Host The type of host (which dictates the form of the IND$FILE
473 command): tso (the default) or vm.
474 Mode Use ascii (the default) for a text file, which will be
476 translated between EBCDIC and ASCII as necessary. Use binary
477 for non-text files.
478 Cr Controls how Newline characters are handled when transferring
480 Mode=ascii files. remove (the default) strips Newline
481 characters in local files before transferring them to the host.
482 add adds Newline characters to each host file record before
483 transferring it to the local workstation. keep preserves
484 Newline characters when transferring a local file to the host.
485 Exist Controls what happens when the destination file already exists.
487 keep (the default) preserves the file, causing the Transfer
488 action to fail. replace overwrites the destination file with
489 the source file. append appends the source file to the
490 destination file.
491 Recfm Controls the record of files created on the host. fixed
493 creates a file with fixed-length records. variable creates a
494 file with variable-length records. undefined creates a file
495 with undefined-length records (TSO hosts only). The Lrecl
496 option controls the record length or maximum record length for
497 Recfm=fixed and Recfm=variable files, respectively.
498 Lrecl Specifies the record length (or maximum record length) for files
500 created on the host.
501 Blksize
503 Specifies the block size for files created on the host. (TSO
504 hosts only.)
505 Allocation
507 Specifies the units for the TSO host PrimarySpace and
508 SecondarySpace options: tracks, cylinders or avblock.
509 PrimarySpace
511 Primary allocation for a file created on a TSO host. The units
512 are given by the Allocation option.
513 SecondarySpace
515 Secondary allocation for a file created on a TSO host. The
516 units are given by the Allocation option.
517 BufferSize
519 Buffer size for DFT-mode transfers. Can range from 256 to
520 32768. Larger values give better performance, but some hosts
521 may not be able to support them.
522
524 expect(1)
525 ksh(1)
526 x3270(1)
527 c3270(1)
528 s3270(1)
529
531 Version 3.3.4
532 09 April 2005 X3270-SCRIPT(1)