1X3270-SCRIPT(1)             General Commands Manual            X3270-SCRIPT(1)
2
3
4

NAME

6       Scripting Facilities for x3270, s3270, ws3270 and c3270
7

SYNOPSIS

9       x3270 -script [ x3270-options ]
10       s3270 [ s3270-options ]
11       ws3270 [ ws3270-options ]
12       Script ( command [ ,arg... ] )
13

DESCRIPTION

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
19       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 and standard error output.
26
27       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
36       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
41       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
48       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
53       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

STATUS FORMAT

61       The status message consists of 12 blank-separated fields:
62
63       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
70       2 Screen Formatting
71              If the screen is formatted, the letter F.  If unformatted or  in
72              NVT mode, the letter U.
73
74       3 Field Protection
75              If  the  field containing the cursor is protected, the letter P.
76              If unprotected or unformatted, the letter U.
77
78       4 Connection State
79              If connected to a host, the string C(hostname).  Otherwise,  the
80              letter N.
81
82       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
88       6 Model Number (2-5)
89
90       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
96       8 Number of Columns
97              The  current number of columns defined on the screen, subject to
98              the same difference for rows, above.
99
100       9 Cursor Row
101              The current cursor row (zero-origin).
102
103       10 Cursor Column
104              The current cursor column (zero-origin).
105
106       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
110       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

DIFFERENCES

117       When an action is initiated by a script, the emulators behave  in  sev‐
118       eral different ways:
119
120       If  an  error  occurs  in processing an action, the usual pop-up window
121       does not appear.  Instead, the text is written to standard  error  out‐
122       put.
123
124       If  end-of-file  is detected on standard input, the emulator exits.  (A
125       script can exit without killing the emulator by using  the  CloseScript
126       action,  below.)   Note that this applies to peer scripts only; end-of-
127       file on the pipe connected to a child script simply causes the pipes to
128       be closed and the Script action to complete.
129
130       The  Quit action always causes the emulator to exit.  (When called from
131       the keyboard, it will exit only if not connected to a host.)
132
133       Normally, the AID actions (Clear, Enter, PF, and PA) will not  complete
134       until  the  host  unlocks  the  keyboard.  If the parameter to a String
135       action includes a code for one these actions, it will also wait for the
136       keyboard to unlock before proceeding.
137
138       The  AidWait  toggle  controls  with behavior.  When this toggle is set
139       (the default), actions block as described above.  When  the  toggle  is
140       clear,  AID  actions complete immediately.  The Wait(Output) action can
141       then be used to delay a script until the host changes something on  the
142       screen, and the Wait(Unlock) action can be used to delay a script until
143       the host unlocks the keyboard, regardless of the state of  the  AidWait
144       toggle.
145
146       Note  that  the  Script  action  does not complete until end-of-file is
147       detected on the pipe or the CloseScript action is called by  the  child
148       process.   This  behavior  is  not affected by the state of the AidWait
149       toggle.
150

SCRIPT-SPECIFIC ACTIONS

152       The following actions have  been  defined  or  modified  for  use  with
153       scripts.  (Note that unlike the display on the status line, row and col
154       coordinates used in these  actions  use  [0,0]  as  their  origin,  not
155       [1,1]).
156
157       AnsiText
158              Outputs  whatever  data  that has been output by the host in NVT
159              mode since the last time that AnsiText was called.  The data  is
160              preceded by the string "data: ", and has had all control charac‐
161              ters expanded into C backslash sequences.
162
163              This is a convenient way to capture NVT mode output  in  a  syn‐
164              chronous manner without trying to decode the screen contents.
165
166       Ascii(row,col,rows,cols)
167
168       Ascii(row,col,length)
169
170       Ascii(length)
171
172       Ascii  Outputs  an  ASCII  text  representation of the screen contents.
173              Each line is preceded by the string "data: ", and there  are  no
174              control characters.
175
176              If four parameters are given, a rectangular region of the screen
177              is output.
178
179              If three parameters are given,  length  characters  are  output,
180              starting at the specified row and column.
181
182              If  only the length parameter is given, that many characters are
183              output, starting at the cursor position.
184
185              If no parameters are given, the entire screen is output.
186
187              The EBCDIC-to-ASCII translation and output character set  depend
188              on the both the emulator character set (the -charset option) and
189              the locale.  UTF-8 and certain DBCS locales may result in multi-
190              byte  expansions  of  EBCDIC  characters that translate to ASCII
191              codes greater than 0x7f.
192
193       AsciiField
194              Outputs an ASCII text representation of the field containing the
195              cursor.  The text is preceded by the string "data: ".
196
197       Connect(hostname)
198              Connects  to a host.  The command does not return until the emu‐
199              lator is successfully connected in the proper mode, or the  con‐
200              nection fails.
201
202       CloseScript(status)
203              Causes  the  emulator  to stop reading commands from the script.
204              This is useful to allow a peer script to exit, with the emulator
205              proceeding  interactively.   (Without this command, the emulator
206              would exit when it detected end-of-file on standard input.)   If
207              the script was invoked by the Script action, the optional status
208              is used as the return status of Script; if nonzero, Script  will
209              complete  with  an error, and if this script was invoked as part
210              of login through the ibm_hosts file, the connection will be bro‐
211              ken.
212
213       ContinueScript(param)
214              Allows  a script that is waiting in a PauseScript action, below,
215              to continue.  The param  given  is  output  by  the  PauseScript
216              action.
217
218       Disconnect
219              Disconnects from the host.
220
221       Ebcdic(row,col,rows,cols)
222
223       Ebcdic(row,col,length)
224
225       Ebcdic(length)
226
227       Ebcdic The same function as Ascii above, except that rather than gener‐
228              ating ASCII text, each character  is  output  as  a  hexadecimal
229              EBCDIC code, preceded by 0x.
230
231       EbcdicField
232              The  same function as AsciiField above, except that it generates
233              hexadecimal EBCDIC codes.
234
235       Info(message)
236              In x3270, pops  up  an  informational  message.   In  c3270  and
237              wc3270,  writes  an  informational  message to the OIA (the line
238              below the display).  Not defined for s3270 or tcl3270.
239
240       Expect(text[,timeout])
241              Pauses the script until the specified text appears in  the  data
242              stream  from  the  host,  or  the specified timeout (in seconds)
243              expires.  If no timeout is specified, the default is 30 seconds.
244              Text   can   contain   standard  C-language  escape  (backslash)
245              sequences.  No wild-card characters or pattern anchor characters
246              are understood.  Expect is valid only in NVT mode.
247
248       MoveCursor(row,col)
249              Moves the cursor to the specified coordinates.
250
251       PauseScript
252              Stops  a  script until the ContinueScript action, above, is exe‐
253              cuted.  This allows a script to wait for  user  input  and  con‐
254              tinue.  Outputs the single parameter to ContinueScript.
255
256       PrintText([command,]filter))
257              Pipes  an  ASCII  representation  of  the  current  screen image
258              through the named filter, e.g., lpr.
259
260       PrintText([html,],file,filename))
261              Saves the current screen contents in  a  file.   With  the  html
262              option, saves it as HTML, otherwise saves it as plain ASCII.
263
264       PrintText(html,string)
265              Returns the current screen contents as HTML.
266
267       ReadBuffer(Ascii)
268              Dumps  the  contents  of  the screen buffer, one line at a time.
269              Positions inside data fields are  generally  output  as  2-digit
270              hexadecimal  codes in the current display character set.  If the
271              current locale specifies UTF-8 (or certain DBCS character sets),
272              some  positions  may  be output as multi-byte strings (4-, 6- or
273              8-digit codes).  DBCS  characters  take  two  positions  in  the
274              screen  buffer;  the  first  location  is output as a multi-byte
275              string in the current locale codeset, and the second location is
276              output  as  a  dash.   Start-of-field  characters (each of which
277              takes up a display  position)  are  output  as  SF(aa=nn[,...]),
278              where aa is a field attribute type and nn is its value.
279
280                        Attribute          Values
281                        ─────────────────────────────────────
282                        c0 basic 3270      20 protected
283                                           10 numeric
284                                           04 detectable
285                                           08 intensified
286                                           0c non-display
287                                           01 modified
288                        41 highlighting    f1 blink
289                                           f2 reverse
290                                           f4 underscore
291                                           f8 intensify
292                        42 foreground      f0 neutral black
293                                           f1 blue
294                                           f2 red
295                                           f3 pink
296                                           f4 green
297                                           f5 turquoise
298                                           f6 yellow
299                                           f7 neutral white
300                                           f8 black
301                                           f9 deep blue
302                                           fa orange
303                                           fb purple
304                                           fc pale green
305                                           fd pale turquoise
306                                           fe grey
307                                           ff white
308                        43 character set   f0 default
309                                           f1 APL
310                                           f8 DBCS
311
312              Extended attributes (which do not take up display positions) are
313              output as SA(aa=nn), with aa and nn having the same  definitions
314              as  above  (though the basic 3270 attribute will never appear as
315              an extended attribute).
316
317              In addition, NULL characters in the screen buffer  are  reported
318              as  ASCII character 00 instead of 20, even though they should be
319              displayed as blanks.
320
321       ReadBuffer(Ebcdic)
322              Equivalent to Snap(Ascii), but with the data  fields  output  as
323              hexadecimal  EBCDIC  codes  instead.   Additionally, if a buffer
324              position has the Graphic Escape attribute, it  is  displayed  as
325              GE(xx).
326
327       Snap   Equivalent to Snap(Save) (see below).
328
329       Snap(Ascii,...)
330              Performs the Ascii action on the saved screen image.
331
332       Snap(Cols)
333              Returns the number of columns in the saved screen image.
334
335       Snap(Ebcdic,...)
336              Performs the Ebcdic action on the saved screen image.
337
338       Snap(ReadBuffer)
339              Performs the ReadBuffer action on the saved screen image.
340
341       Snap(Rows)
342              Returns the number of rows in the saved screen image.
343
344       Snap(Save)
345              Saves  a  copy  of  the  screen  image and status in a temporary
346              buffer.  This copy can be queried with  other  Snap  actions  to
347              allow  a  script to examine a consistent screen image, even when
348              the  host  may  be  changing  the  image  (or  even  the  screen
349              dimensions) dynamically.
350
351       Snap(Status)
352              Returns the status line from when the screen was last saved.
353
354       Snap(Wait[,timeout],Output)
355              Pauses  the  script  until  the  host sends further output, then
356              updates the snap buffer with the new screen contents.  Used when
357              the  host  unlocks  the keyboard (allowing the script to proceed
358              after an Enter, PF or PA action), but has not finished  updating
359              the  screen.  This action is usually invoked in a loop that uses
360              the Snap(Ascii) or Snap(Ebcdic) action to scan  the  screen  for
361              some  pattern  that  indicates that the host has fully processed
362              the last command.
363
364              The optional timeout parameter specifies a number of seconds  to
365              wait  before  failing  the  Snap action.  The default is to wait
366              indefinitely.
367
368       Source(file)
369              Read and execute commands from  file.   Any  output  from  those
370              commands  will  become  the  output  from Source.  If any of the
371              commands fails, the Source  command  will  not  abort;  it  will
372              continue reading commands until EOF.
373
374       Title(text)
375              Changes the x3270 window title to text.
376
377       Transfer(keyword=value,...)
378              Invokes IND$FILE file transfer.  See FILE TRANSFER below.
379
380       Wait([timeout,] 3270Mode)
381              Used  when  communicating  with a host that switches between NVT
382              mode and 3270 mode.  Pauses the script or macro until  the  host
383              negotiates  3270  mode,  then  waits  for  a formatted screen as
384              above.
385
386              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
390              For  backwards  compatibility,  Wait(3270)  is   equivalent   to
391              Wait(3270Mode)
392
393       Wait([timeout,] Disconnect)
394              Pauses  the  script  until  the host disconnects.  Often used to
395              after sending a logoff command to a VM/CMS host, to ensure  that
396              the session is not unintentionally set to disconnected state.
397
398              The  optional timeout parameter specifies a number of seconds to
399              wait before failing the Wait action.  The  default  is  to  wait
400              indefinitely.
401
402       Wait([timeout,] InputField)
403              A  useful  utility for use at the beginning of scripts and after
404              the Connect action.  In 3270 mode, waits  until  the  screen  is
405              formatted,   and  the  host  has  positioned  the  cursor  on  a
406              modifiable field.  In NVT mode, waits until the  host  sends  at
407              least one byte of data.
408
409              The  optional timeout parameter specifies a number of seconds to
410              wait before failing the Wait action.  The  default  is  to  wait
411              indefinitely.
412
413              For    backwards    compatibility,   Wait   is   equivalent   to
414              Wait(InputField).
415
416       Wait([timeout,] NVTMode)
417              Used when communicating with a host that switches  between  3270
418              mode  and  NVT  mode.  Pauses the script or macro until the host
419              negotiates NVT mode, then waits for a  byte  from  the  host  as
420              above.
421
422              The  optional timeout parameter specifies a number of seconds to
423              wait before failing the Wait action.  The  default  is  to  wait
424              indefinitely.
425
426              For   backwards   compatibility,  Wait(ansi)  is  equivalent  to
427              Wait(NVTMode).
428
429       Wait([timeout,] Output)
430              Pauses the script until the host sends  further  output.   Often
431              needed  when  the host unlocks the keyboard (allowing the script
432              to proceed after a Clear, Enter, PF or PA action), but  has  not
433              finished  updating  the  screen.   Also used in non-blocking AID
434              mode (see DIFFERENCES for  details).   This  action  is  usually
435              invoked  in  a loop that uses the Ascii or Ebcdic action to scan
436              the screen for some pattern that indicates  that  the  host  has
437              fully processed the last command.
438
439              The  optional timeout parameter specifies a number of seconds to
440              wait before failing the Wait action.  The  default  is  to  wait
441              indefinitely.
442
443       Wait([timeout,] Unlock)
444              Pauses  the script until the host unlocks the keyboard.  This is
445              useful when operating in non-blocking AID mode  (toggle  AidWait
446              clear), to wait for a host command to complete.  See DIFFERENCES
447              for details).
448
449              The optional timeout parameter specifies a number of seconds  to
450              wait  before  failing  the  Wait action.  The default is to wait
451              indefinitely.
452
453       Wait(timeout, Seconds)
454              Delays the script timeout seconds.  Unlike the  other  forms  of
455              Wait, the timeout is not optional.
456
457       WindowState(mode)
458              If  mode  is  Iconic, changes the x3270 window into an icon.  If
459              mode is Normal, changes the x3270  window  from  an  icon  to  a
460              normal window.
461

FILE TRANSFER

463       The  Transfer  action  implements  IND$FILE file transfer.  This action
464       requires that the IND$FILE program be installed on the  IBM  host,  and
465       that  the  3270  cursor be located in a field that will accept a TSO or
466       VM/CMS command.
467
468       The Transfer action can be  entered  at  the  command  prompt  with  no
469       parameters,  which  will  cause it to prompt interactively for the file
470       names and options.  It can also be invoked with  parameters  to  define
471       the entire transfer.
472
473       Because  of the complexity and number of options for file transfer, the
474       parameters to the Transfer action take the unique form of option=value,
475       and  can  appear  in any order.  Note that if the value contains spaces
476       (such as a VM/CMS file name), then the entire parameter must be quoted,
477       e.g., "HostFile=xxx foo a".  The options are:
478
479       Option           Required?   Default   Other Values
480       ────────────────────────────────────────────────────────
481       Direction           No       receive   send
482       HostFile            Yes
483       LocalFile           Yes
484       Host                No       tso       vm
485       Mode                No       ascii     binary
486       Cr                  No       remove    add, keep
487       Remap               No       yes       no
488       Exist               No       keep      replace, append
489       Recfm               No                 fixed, variable,
490                                              undefined
491       Lrecl               No
492       Blksize             No
493       Allocation          No                 tracks,
494                                              cylinders,
495                                              avblock
496       PrimarySpace        No
497       SecondarySpace      No
498       BufferSize          No       4096
499
500       The option details are as follows.
501
502       Direction
503              send to send a file to the host, receive to receive a file  from
504              the host.
505
506       HostFile
507              The name of the file on the host.
508
509       LocalFile
510              The name of the file on the local workstation.
511
512       Host   The  type  of  host  (which  dictates  the  form of the IND$FILE
513              command): tso (the default) or vm.
514
515       Mode   Use  ascii  (the  default)  for  a  text  file,  which  will  be
516              translated  between  EBCDIC  and ASCII as necessary.  Use binary
517              for non-text files.
518
519       Cr     Controls how Newline characters are  handled  when  transferring
520              Mode=ascii   files.    remove   (the   default)  strips  Newline
521              characters in local files before transferring them to the  host.
522              add  adds  Newline  characters  to  each host file record before
523              transferring  it  to  the  local  workstation.   keep  preserves
524              Newline characters when transferring a local file to the host.
525
526       Remap  Controls  text  translation for Mode=ascii files.  The value yes
527              (the default) causes x3270-script to remap the  text  to  ensure
528              maximum  compatibility  between  the workstation's character set
529              and encoding and the host's EBCDIC  code  page.   The  value  no
530              causes  x3270-script to pass the text to or from the host as-is,
531              leaving all translation to the IND$FILE program on the host.
532
533       Exist  Controls what happens when the destination file already  exists.
534              keep  (the  default)  preserves  the  file, causing the Transfer
535              action to fail.  replace overwrites the  destination  file  with
536              the  source  file.   append  appends  the  source  file  to  the
537              destination file.
538
539       Recfm  Controls the record format of files created on the host.   fixed
540              creates  a  file  with fixed-length records.  variable creates a
541              file with variable-length records.   undefined  creates  a  file
542              with  undefined-length  records  (TSO  hosts  only).   The Lrecl
543              option controls the record length or maximum record  length  for
544              Recfm=fixed and Recfm=variable files, respectively.
545
546       Lrecl  Specifies the record length (or maximum record length) for files
547              created on the host.
548
549       Blksize
550              Specifies the block size for files created on  the  host.   (TSO
551              hosts only.)
552
553       Allocation
554              Specifies   the   units   for  the  TSO  host  PrimarySpace  and
555              SecondarySpace options: tracks, cylinders or avblock.
556
557       PrimarySpace
558              Primary allocation for a file created on a TSO host.  The  units
559              are given by the Allocation option.
560
561       SecondarySpace
562              Secondary  allocation  for  a  file  created on a TSO host.  The
563              units are given by the Allocation option.
564
565       BufferSize
566              Buffer size for DFT-mode  transfers.   Can  range  from  256  to
567              32768.   Larger  values  give better performance, but some hosts
568              may not be able to support them.
569

SEE ALSO

571       expect(1)
572       ksh(1)
573       x3270(1)
574       c3270(1)
575       s3270(1)
576       ws3270(1)
577

VERSION

579       Version 3.3.10ga4
580
581
582
583                                02 October 2009                X3270-SCRIPT(1)
Impressum