1X3270-SCRIPT(1) General Commands Manual X3270-SCRIPT(1)
2
6 Scripting Facilities for x3270, s3270, ws3270 and c3270
7
9 x3270 -script [ x3270-options ]
10 s3270 [ s3270-options ]
11 ws3270 [ ws3270-options ]
12 Script ( command [ ,arg... ] )
13
15 The x3270 scripting facilities allow the interactive 3270 emulators
16 x3270 and c3270 to be operated under the control of another program,
17 and form the basis for the script-only emulators s3270 and ws3270.
18 There are two basic scripting methods. The first is the peer script
20 facility, invoked by the x3270 -script switch, and the default mode for
21 s3270 and ws3270. This runs x3270, s3270 or ws3270 as a child of
22 another process. Typically this would be a script using expect(1),
23 perl(1), or the co-process facility of the Korn Shell ksh(1). Inthis
24 mode, the emulator process looks for commands on its standard input,
25 and places the responses on standard output.
26 The second method is the child script facility, invoked by the Script
28 action in x3270, c3270, or s3270. This runs a script as a child
29 process of the emulator. The child has access to pipes connected to
30 the emulator; the emulator look for commands on one pipe, and places
31 the responses on the other. (The file descriptor of the pipe for com‐
32 mands to the emulator is passed in the environment variable X3270INPUT;
33 the file descriptor of the pipe for responses from the emulator is
34 passed in the environment variable X3270OUTPUT.)
35 It is possible to mix the two methods. A script can invoke another
37 script with the Script action, and may also be implicitly nested when a
38 script invokes the Connect action, and the ibm_hosts file specifies a
39 login script for that host name.
40 Commands are emulator actions; the syntax is the same as for the right-
42 hand side of an Xt translation table entry (an x3270 or c3270 keymap).
43 Unlike translation tables, action names are case-insensitive, can be
44 uniquely abbreviated, and the parentheses may be omitted if there are
45 no parameters. Any input line that begins with # or ! is treaded as a
46 comment and will be ignored.
47 Any emulator action may be specified. Several specific actions have
49 been defined for use by scripts, and the behavior of certain other
50 actions (and of the emulators in general) is different when an action
51 is initiated by a script.
52 Some actions generate output; some may delay completion until the cer‐
54 tain external events occur, such as the host unlocking the keyboard.
55 The completion of every command is marked by a two-line message. The
56 first line is the current status of the emulator, documented below. If
57 the command is successful, the second line is the string "ok"; other‐
58 wise it is the string "error".
59
61 The status message consists of 12 blank-separated fields:
62 1 Keyboard State
64 If the keyboard is unlocked, the letter U. If the keyboard is
65 locked waiting for a response from the host, or if not connected
66 to a host, the letter L. If the keyboard is locked because of
67 an operator error (field overflow, protected field, etc.), the
68 letter E.
69 2 Screen Formatting
71 If the screen is formatted, the letter F. If unformatted or in
72 NVT mode, the letter U.
73 3 Field Protection
75 If the field containing the cursor is protected, the letter P.
76 If unprotected or unformatted, the letter U.
77 4 Connection State
79 If connected to a host, the string C(hostname). Otherwise, the
80 letter N.
81 5 Emulator Mode
83 If connected in 3270 mode, the letter I. If connected in NVT
84 line mode, the letter L. If connected in NVT character mode,
85 the letter C. If connected in unnegotiated mode (no BIND active
86 from the host), the letter P. If not connected, the letter N.
87 6 Model Number (2-5)
89 7 Number of Rows
91 The current number of rows defined on the screen. The host can
92 request that the emulator use a 24x80 screen, so this number may
93 be smaller than the maximum number of rows possible with the
94 current model.
95 8 Number of Columns
97 The current number of columns defined on the screen, subject to
98 the same difference for rows, above.
99 9 Cursor Row
101 The current cursor row (zero-origin).
102 10 Cursor Column
104 The current cursor column (zero-origin).
105 11 Window ID
107 The X window identifier for the main x3270 window, in hexadeci‐
108 mal preceded by 0x. For s3270, ws3270 and c3270, this is zero.
109 12 Command Execution Time
111 The time that it took for the host to respond to the previous
112 commnd, in seconds with milliseconds after the decimal. If the
113 previous command did not require a host response, this is a
114 dash.
115
117 When an action is initiated by a script, the emulators behave in sev‐
118 eral different ways:
119 If an error occurs in processing an action, the usual pop-up window
121 does not appear. Instead, the text is written to standard output.
122 If end-of-file is detected on standard input, the emulator exits. (A
124 script can exit without killing the emulator by using the CloseScript
125 action, below.) Note that this applies to peer scripts only; end-of-
126 file on the pipe connected to a child script simply causes the pipes to
127 be closed and the Script action to complete.
128 The Quit action always causes the emulator to exit. (When called from
130 the keyboard, it will exit only if not connected to a host.)
131 Normally, the AID actions (Clear, Enter, PF, and PA) will not complete
133 until the host unlocks the keyboard. If the parameter to a String
134 action includes a code for one these actions, it will also wait for the
135 keyboard to unlock before proceeding.
136 The AidWait toggle controls with behavior. When this toggle is set
138 (the default), actions block as described above. When the toggle is
139 clear, AID actions complete immediately. The Wait(Output) action can
140 then be used to delay a script until the host changes something on the
141 screen, and the Wait(Unlock) action can be used to delay a script until
142 the host unlocks the keyboard, regardless of the state of the AidWait
143 toggle.
144 Note that the Script action does not complete until end-of-file is
146 detected on the pipe or the CloseScript action is called by the child
147 process. This behavior is not affected by the state of the AidWait
148 toggle.
149
151 The following actions have been defined or modified for use with
152 scripts. (Note that unlike the display on the status line, row and col
153 coordinates used in these actions use [0,0] as their origin, not
154 [1,1]).
155 AnsiText
157 Outputs whatever data that has been output by the host in NVT
158 mode since the last time that AnsiText was called. The data is
159 preceded by the string "data: ", and has had all control charac‐
160 ters expanded into C backslash sequences.
161 This is a convenient way to capture NVT mode output in a syn‐
163 chronous manner without trying to decode the screen contents.
164 Ascii(row,col,rows,cols)
166 Ascii(row,col,length)
168 Ascii(length)
170 Ascii Outputs an ASCII text representation of the screen contents.
172 Each line is preceded by the string "data: ", and there are no
173 control characters.
174 If four parameters are given, a rectangular region of the screen
176 is output.
177 If three parameters are given, length characters are output,
179 starting at the specified row and column.
180 If only the length parameter is given, that many characters are
182 output, starting at the cursor position.
183 If no parameters are given, the entire screen is output.
185 The EBCDIC-to-ASCII translation and output character set depend
187 on the both the emulator character set (the -charset option) and
188 the locale. UTF-8 and certain DBCS locales may result in multi-
189 byte expansions of EBCDIC characters that translate to ASCII
190 codes greater than 0x7f.
191 AsciiField
193 Outputs an ASCII text representation of the field containing the
194 cursor. The text is preceded by the string "data: ".
195 Connect(hostname)
197 Connects to a host. The command does not return until the emu‐
198 lator is successfully connected in the proper mode, or the con‐
199 nection fails.
200 CloseScript(status)
202 Causes the emulator to stop reading commands from the script.
203 This is useful to allow a peer script to exit, with the emulator
204 proceeding interactively. (Without this command, the emulator
205 would exit when it detected end-of-file on standard input.) If
206 the script was invoked by the Script action, the optional status
207 is used as the return status of Script; if nonzero, Script will
208 complete with an error, and if this script was invoked as part
209 of login through the ibm_hosts file, the connection will be bro‐
210 ken.
211 ContinueScript(param)
213 Allows a script that is waiting in a PauseScript action, below,
214 to continue. The param given is output by the PauseScript
215 action.
216 Disconnect
218 Disconnects from the host.
219 Ebcdic(row,col,rows,cols)
221 Ebcdic(row,col,length)
223 Ebcdic(length)
225 Ebcdic The same function as Ascii above, except that rather than gener‐
227 ating ASCII text, each character is output as a hexadecimal
228 EBCDIC code, preceded by 0x.
229 EbcdicField
231 The same function as AsciiField above, except that it generates
232 hexadecimal EBCDIC codes.
233 Info(message)
235 In x3270, pops up an informational message. In c3270 and
236 wc3270, writes an informational message to the OIA (the line
237 below the display). Not defined for s3270 or tcl3270.
238 Expect(text[,timeout])
240 Pauses the script until the specified text appears in the data
241 stream from the host, or the specified timeout (in seconds)
242 expires. If no timeout is specified, the default is 30 seconds.
243 Text can contain standard C-language escape (backslash)
244 sequences. No wild-card characters or pattern anchor characters
245 are understood. Expect is valid only in NVT mode.
246 MoveCursor(row,col)
248 Moves the cursor to the specified coordinates.
249 PauseScript
251 Stops a script until the ContinueScript action, above, is exe‐
252 cuted. This allows a script to wait for user input and con‐
253 tinue. Outputs the single parameter to ContinueScript.
254 PrintText([command,]filter))
256 Pipes an ASCII representation of the current screen image
257 through the named filter, e.g., lpr.
258 PrintText([html,],file,filename))
260 Saves the current screen contents in a file. With the html
261 option, saves it as HTML, otherwise saves it as plain ASCII.
262 PrintText(html,string)
264 Returns the current screen contents as HTML.
265 ReadBuffer(Ascii)
267 Dumps the contents of the screen buffer, one line at a time.
268 Positions inside data fields are generally output as 2-digit
269 hexadecimal codes in the current display character set. If the
270 current locale specifies UTF-8 (or certain DBCS character sets),
271 some positions may be output as multi-byte strings (4-, 6- or
272 8-digit codes). DBCS characters take two positions in the
273 screen buffer; the first location is output as a multi-byte
274 string in the current locale codeset, and the second location is
275 output as a dash. Start-of-field characters (each of which
276 takes up a display position) are output as SF(aa=nn[,...]),
277 where aa is a field attribute type and nn is its value.
278 Attribute Values
280 ─────────────────────────────────────
281 c0 basic 3270 20 protected
282 10 numeric
283 04 detectable
284 08 intensified
285 0c non-display
286 01 modified
287 41 highlighting f1 blink
288 f2 reverse
289 f4 underscore
290 f8 intensify
291 42 foreground f0 neutral black
292 f1 blue
293 f2 red
294 f3 pink
295 f4 green
296 f5 turquoise
297 f6 yellow
298 f7 neutral white
299 f8 black
300 f9 deep blue
301 fa orange
302 fb purple
303 fc pale green
304 fd pale turquoise
305 fe grey
306 ff white
307 43 character set f0 default
308 f1 APL
309 f8 DBCS
310 Extended attributes (which do not take up display positions) are
312 output as SA(aa=nn), with aa and nn having the same definitions
313 as above (though the basic 3270 attribute will never appear as
314 an extended attribute).
315 In addition, NULL characters in the screen buffer are reported
317 as ASCII character 00 instead of 20, even though they should be
318 displayed as blanks.
319 ReadBuffer(Ebcdic)
321 Equivalent to Snap(Ascii), but with the data fields output as
322 hexadecimal EBCDIC codes instead. Additionally, if a buffer
323 position has the Graphic Escape attribute, it is displayed as
324 GE(xx).
325 Snap Equivalent to Snap(Save) (see below).
327 Snap(Ascii,...)
329 Performs the Ascii action on the saved screen image.
330 Snap(Cols)
332 Returns the number of columns in the saved screen image.
333 Snap(Ebcdic,...)
335 Performs the Ebcdic action on the saved screen image.
336 Snap(ReadBuffer)
338 Performs the ReadBuffer action on the saved screen image.
339 Snap(Rows)
341 Returns the number of rows in the saved screen image.
342 Snap(Save)
344 Saves a copy of the screen image and status in a temporary
345 buffer. This copy can be queried with other Snap actions to
346 allow a script to examine a consistent screen image, even when
347 the host may be changing the image (or even the screen
348 dimensions) dynamically.
349 Snap(Status)
351 Returns the status line from when the screen was last saved.
352 Snap(Wait[,timeout],Output)
354 Pauses the script until the host sends further output, then
355 updates the snap buffer with the new screen contents. Used when
356 the host unlocks the keyboard (allowing the script to proceed
357 after an Enter, PF or PA action), but has not finished updating
358 the screen. This action is usually invoked in a loop that uses
359 the Snap(Ascii) or Snap(Ebcdic) action to scan the screen for
360 some pattern that indicates that the host has fully processed
361 the last command.
362 The optional timeout parameter specifies a number of seconds to
364 wait before failing the Snap action. The default is to wait
365 indefinitely.
366 Source(file)
368 Read and execute commands from file. Any output from those
369 commands will become the output from Source. If any of the
370 commands fails, the Source command will not abort; it will
371 continue reading commands until EOF.
372 Title(text)
374 Changes the x3270 window title to text.
375 Transfer(keyword=value,...)
377 Invokes IND$FILE file transfer. See FILE TRANSFER below.
378 Wait([timeout,] 3270Mode)
380 Used when communicating with a host that switches between NVT
381 mode and 3270 mode. Pauses the script or macro until the host
382 negotiates 3270 mode, then waits for a formatted screen as
383 above.
384 The optional timeout parameter specifies a number of seconds to
386 wait before failing the Wait action. The default is to wait
387 indefinitely.
388 For backwards compatibility, Wait(3270) is equivalent to
390 Wait(3270Mode)
391 Wait([timeout,] Disconnect)
393 Pauses the script until the host disconnects. Often used to
394 after sending a logoff command to a VM/CMS host, to ensure that
395 the session is not unintentionally set to disconnected state.
396 The optional timeout parameter specifies a number of seconds to
398 wait before failing the Wait action. The default is to wait
399 indefinitely.
400 Wait([timeout,] InputField)
402 A useful utility for use at the beginning of scripts and after
403 the Connect action. In 3270 mode, waits until the screen is
404 formatted, and the host has positioned the cursor on a
405 modifiable field. In NVT mode, waits until the host sends at
406 least one byte of data.
407 The optional timeout parameter specifies a number of seconds to
409 wait before failing the Wait action. The default is to wait
410 indefinitely.
411 For backwards compatibility, Wait is equivalent to
413 Wait(InputField).
414 Wait([timeout,] NVTMode)
416 Used when communicating with a host that switches between 3270
417 mode and NVT mode. Pauses the script or macro until the host
418 negotiates NVT mode, then waits for a byte from the host as
419 above.
420 The optional timeout parameter specifies a number of seconds to
422 wait before failing the Wait action. The default is to wait
423 indefinitely.
424 For backwards compatibility, Wait(ansi) is equivalent to
426 Wait(NVTMode).
427 Wait([timeout,] Output)
429 Pauses the script until the host sends further output. Often
430 needed when the host unlocks the keyboard (allowing the script
431 to proceed after a Clear, Enter, PF or PA action), but has not
432 finished updating the screen. Also used in non-blocking AID
433 mode (see DIFFERENCES for details). This action is usually
434 invoked in a loop that uses the Ascii or Ebcdic action to scan
435 the screen for some pattern that indicates that the host has
436 fully processed the last command.
437 The optional timeout parameter specifies a number of seconds to
439 wait before failing the Wait action. The default is to wait
440 indefinitely.
441 Wait([timeout,] Unlock)
443 Pauses the script until the host unlocks the keyboard. This is
444 useful when operating in non-blocking AID mode (toggle AidWait
445 clear), to wait for a host command to complete. See DIFFERENCES
446 for details).
447 The optional timeout parameter specifies a number of seconds to
449 wait before failing the Wait action. The default is to wait
450 indefinitely.
451 Wait(timeout, Seconds)
453 Delays the script timeout seconds. Unlike the other forms of
454 Wait, the timeout is not optional.
455 WindowState(mode)
457 If mode is Iconic, changes the x3270 window into an icon. If
458 mode is Normal, changes the x3270 window from an icon to a
459 normal window.
460
462 The Transfer action implements IND$FILE file transfer. This action
463 requires that the IND$FILE program be installed on the IBM host, and
464 that the 3270 cursor be located in a field that will accept a TSO or
465 VM/CMS command.
466 The Transfer action can be entered at the command prompt with no
468 parameters, which will cause it to prompt interactively for the file
469 names and options. It can also be invoked with parameters to define
470 the entire transfer.
471 Because of the complexity and number of options for file transfer, the
473 parameters to the Transfer action take the unique form of option=value,
474 and can appear in any order. Note that if the value contains spaces
475 (such as a VM/CMS file name), then the entire parameter must be quoted,
476 e.g., "HostFile=xxx foo a". The options are:
477 Option Required? Default Other Values
479 ────────────────────────────────────────────────────────
480 Direction No receive send
481 HostFile Yes
482 LocalFile Yes
483 Host No tso vm
484 Mode No ascii binary
485 Cr No remove add, keep
486 Remap No yes no
487 Exist No keep replace, append
488 Recfm No fixed, variable,
489 undefined
490 Lrecl No
491 Blksize No
492 Allocation No tracks,
493 cylinders,
494 avblock
495 PrimarySpace No
496 SecondarySpace No
497 BufferSize No 4096
498 The option details are as follows.
500 Direction
502 send to send a file to the host, receive to receive a file from
503 the host.
504 HostFile
506 The name of the file on the host.
507 LocalFile
509 The name of the file on the local workstation.
510 Host The type of host (which dictates the form of the IND$FILE
512 command): tso (the default) or vm.
513 Mode Use ascii (the default) for a text file, which will be
515 translated between EBCDIC and ASCII as necessary. Use binary
516 for non-text files.
517 Cr Controls how Newline characters are handled when transferring
519 Mode=ascii files. remove (the default) strips Newline
520 characters in local files before transferring them to the host.
521 add adds Newline characters to each host file record before
522 transferring it to the local workstation. keep preserves
523 Newline characters when transferring a local file to the host.
524 Remap Controls text translation for Mode=ascii files. The value yes
526 (the default) causes x3270-script to remap the text to ensure
527 maximum compatibility between the workstation's character set
528 and encoding and the host's EBCDIC code page. The value no
529 causes x3270-script to pass the text to or from the host as-is,
530 leaving all translation to the IND$FILE program on the host.
531 Exist Controls what happens when the destination file already exists.
533 keep (the default) preserves the file, causing the Transfer
534 action to fail. replace overwrites the destination file with
535 the source file. append appends the source file to the
536 destination file.
537 Recfm Controls the record format of files created on the host. fixed
539 creates a file with fixed-length records. variable creates a
540 file with variable-length records. undefined creates a file
541 with undefined-length records (TSO hosts only). The Lrecl
542 option controls the record length or maximum record length for
543 Recfm=fixed and Recfm=variable files, respectively.
544 Lrecl Specifies the record length (or maximum record length) for files
546 created on the host.
547 Blksize
549 Specifies the block size for files created on the host. (TSO
550 hosts only.)
551 Allocation
553 Specifies the units for the TSO host PrimarySpace and
554 SecondarySpace options: tracks, cylinders or avblock.
555 PrimarySpace
557 Primary allocation for a file created on a TSO host. The units
558 are given by the Allocation option.
559 SecondarySpace
561 Secondary allocation for a file created on a TSO host. The
562 units are given by the Allocation option.
563 BufferSize
565 Buffer size for DFT-mode transfers. Can range from 256 to
566 32768. Larger values give better performance, but some hosts
567 may not be able to support them.
568
570 expect(1)
571 ksh(1)
572 x3270(1)
573 c3270(1)
574 s3270(1)
575 ws3270(1)
576
578 Version 3.3.12ga12
579 25 August 2012 X3270-SCRIPT(1)