Scripting Facilities for x3270, s3270 and c3270


SYNOPSIS

       x3270 -script [ x3270-options ]
       s3270 [ x3270-options ]
       Script ( command [ ,arg... ] )


DESCRIPTION

       The  x3270 scripting facilities allow the interactive 3270
       emulators x3270 and c3270 to be operated under the control
       of another program, and form the basis for the script-only
       emulator s3270.

       There are two basic scripting methods.  The first  is  the
       peer script facility, invoked by the x3270 -script switch,
       and the default mode for s3270.  This runs x3270 or  s3270
       as  a child of another process.  Typically this would be a
       script using expect(1), perl(1), or the co-process  facil­
       ity  of  the Korn Shell ksh(1).  Inthis mode, the emulator
       process looks for commands  on  its  standard  input,  and
       places the responses on standard output and standard error
       output.

       The second method is the child script facility, invoked by
       the  Script action in x3270, c3270, or s3270.  This runs a
       script as a child process of the emulator.  The child  has
       access  to  pipes  connected to the emulator; the emulator
       look for commands on one pipe, and places the responses on
       the  other.  (The file descriptor of the pipe for commands
       to the emulator is  passed  in  the  environment  variable
       X3270INPUT;  the file descriptor of the pipe for responses
       from the emulator is passed in  the  environment  variable
       X3270OUTPUT.)

       It  is  possible  to  mix  the  two methods.  A script can
       invoke another script with the Script action, and may also
       be  implicitly  nested  when  a script invokes the Connect
       action, and the ibm_hosts file specifies  a  login  script
       for that host name.

       Commands  are  emulator actions; the syntax is the same as
       for the right-hand side of an Xt translation  table  entry
       (an  x3270  or  c3270 keymap).  Unlike translation tables,
       action names are case-insensitive, can be uniquely  abbre­
       viated, and the parentheses may be omitted if there are no
       parameters.

       Any emulator action may be  specified.   Several  specific
       actions  have  been  defined  for  use by scripts, and the
       behavior of certain other actions (and of the emulators in
       general)  is  different  when  an action is initiated by a
       script.

       until  the certain external events occur, such as the host
       unlocking the keyboard.  The completion of  every  command
       is  marked  by  a two-line message.  The first line is the
       current status of the emulator, documented below.  If  the
       command is successful, the second line is the string "ok";
       otherwise it is the string "error".


STATUS FORMAT

       The status message consists of 11 blank-separated fields:

       1 Keyboard State
              If the keyboard is unlocked, the letter U.  If  the
              keyboard  is locked waiting for a response from the
              host, or if not connected to a host, the letter  L.
              If  the  keyboard  is locked because of an operator
              error (field overflow, protected field, etc.),  the
              letter E.

       2 Screen Formatting
              If  the  screen  is  formatted,  the  letter F.  If
              unformatted or in NVT mode, the letter U.

       3 Field Protection
              If the field containing the  cursor  is  protected,
              the  letter  P.  If unprotected or unformatted, the
              letter U.

       4 Connection State
              If connected to a  host,  the  string  C(hostname).
              Otherwise, the letter N.

       5 Emulator Mode
              If  connected  in 3270 mode, the letter I.  If con­
              nected in NVT line mode, the  letter  L.   If  con­
              nected in NVT character mode, the letter C.  If not
              connected, the letter N.

       6 Model Number (2-5)

       7 Number of Rows
              The current number of rows defined on  the  screen.
              The  host can request that the emulator use a 24x80
              screen, so this number may be smaller than the max­
              imum  number  of  rows  possible  with  the current
              model.

       8 Number of Columns
              The  current  number  of  columns  defined  on  the
              screen,  subject  to  the same difference for rows,
              above.

       9 Cursor Row
              The current cursor row (zero-origin).

              The current cursor column (zero-origin).

       11 Window ID
              The X window identifier for the main x3270  window,
              in  hexadecimal  preceded  by  0x.   For  s3270 and
              c3270, this is zero.


DIFFERENCES

       When an action is initiated by  a  script,  the  emulators
       behave in several different ways:

       If an error occurs in processing an ection, the usual pop-
       up window does not appear.  Instead, the text  is  written
       to standard error output.

       If end-of-file is detected on standard input, the emulator
       exits.  (A script can exit without killing the emulator by
       using  the  CloseScript  action,  below.)   Note that this
       applies to peer scripts only; end-of-file on the pipe con­
       nected  to  a  child  script simply causes the pipes to be
       closed and the Script action to complete.

       The Quit action always causes the emulator to exit.  (When
       called  from  the  keyboard, it will exit only if not con­
       nected to a host.)

       The Clear, Enter, PF, and PA  actions  will  not  complete
       until  the host unlocks the keyboard.  If the parameter to
       a String action includes a code for one these actions,  it
       will  also wait for the keyboard to unlock before complet­
       ing.  Similarly, the Script action does not complete until
       end-of-file  is  detected  on  the pipe or the CloseScript
       action is called by the child process.


SCRIPT-SPECIFIC ACTIONS

       The following actions have been defined  or  modified  for
       use  with  scripts.   (Note that unlike the display on the
       status line, row and col coordinates used in these actions
       use [0,0] as their origin, not [1,1]).

       AnsiText
              Outputs  whatever  data that has been output by the
              host in NVT mode since the last time that  AnsiText
              was  called.   The  data  is preceded by the string
              "data: ",  and  has  had  all  control   characters
              expanded into C backslash sequences.

              This is a convenient way to capture NVT mode output
              in a synchronous manner without  trying  to  decode
              the screen contents.

       Ascii(row,col,rows,cols)


       Ascii(length)

       Ascii  Outputs  an ASCII text representation of the screen
              contents.  Each line  is  preceded  by  the  string
              "data: ", and there are no control characters.

              If  four parameters are given, a rectangular region
              of the screen is output.

              If three parameters are  given,  length  characters
              are  output, starting at the specified row and col­
              umn.

              If only the length parameter is  given,  that  many
              characters are output, starting at the cursor posi­
              tion.

              If no parameters are given, the  entire  screen  is
              output.

       AsciiField
              Outputs  an  ASCII text representation of the field
              containing the cursor.  The text is preceded by the
              string "data: ".

       Connect(hostname)
              Connects  to  a  host.  The command does not return
              until the emulator is successfully connected in the
              proper mode, or the connection fails.

       CloseScript(status)
              Causes  the  emulator to stop reading commands from
              the script.  This is useful to allow a peer  script
              to  exit,  with  the  emulator  proceeding interac­
              tively.  (Without this command, the emulator  would
              exit  when  it  detected  end-of-file  on  standard
              input.)  If the script was invoked  by  the  Script
              action,  the  optional status is used as the return
              status of Script; if nonzero, Script will  complete
              with  an  error,  and if this script was invoked as
              part of login through the ibm_hosts file, the  con­
              nection will be broken.

       ContinueScript(param)
              Allows  a  script  that is waiting in a PauseScript
              action, below, to continue.   The  param  given  is
              output by the PauseScript action.

       Disconnect
              Disconnects from the host.


       Ebcdic(row,col,length)

       Ebcdic(length)

       Ebcdic The  same  function  as  Ascii  above,  except that
              rather than generating ASCII text,  each  character
              is output as a hexadecimal EBCDIC code, preceded by
              0x.

       EbcdicField
              The same function as AsciiField above, except  that
              it generates hexadecimal EBCDIC codes.

       Info(message)
              Pops up an informational message.

       Expect(text[,timeout])
              Pauses  the script until the specified text appears
              in the data stream from the host, or the  specified
              timeout  (in  seconds)  expires.   If no timeout is
              specified, the default is  30  seconds.   Text  can
              contain   standard  C-language  escape  (backslash)
              sequences.   No  wild-card  characters  or  pattern
              anchor  characters are understood.  Expect is valid
              only in NVT mode.

       MoveCursor(row,col)
              Moves the cursor to the specified coordinates.

       PauseScript
              Stops a script  until  the  ContinueScript  action,
              above,  is  executed.  This allows a script to wait
              for user input and continue.   Outputs  the  single
              parameter to ContinueScript.

       Snap   Equivalent to Snap(Save) (see below).

       Snap(Ascii,...)
              Performs  the  Ascii  action  on  the  saved screen
              image.

       Snap(Cols)
              Returns the number of columns in the  saved  screen
              image.

       Snap(Ebcdic,...)
              Performs  the  Ebcdic  action  on  the saved screen
              image.

       Snap(Rows)
              Returns the number of  rows  in  the  saved  screen
              image.

              Saves  a  copy  of the screen image and status in a
              temporary buffer.  This copy can  be  queried  with
              other  Snap  actions to allow a script to examine a
              consistent screen image, even when the host may  be
              changing  the image (or even the screen dimensions)
              dynamically.

       Snap(Status)
              Returns the status line from when  the  screen  was
              last saved.

       Snap(Wait[,timeout],Output)
              Pauses the script until the host sends further out­
              put, then updates the  snap  buffer  with  the  new
              screen  contents.   Used  when the host unlocks the
              keyboard (allowing the script to proceed  after  an
              Enter,  PF  or  PA  action),  but  has not finished
              updating  the  screen.   This  action  is   usually
              invoked  in  a  loop  that  uses the Snap(Ascii) or
              Snap(Ebcdic) action to scan  the  screen  for  some
              pattern that indicates that the host has fully pro­
              cessed the last command.

              The optional timeout parameter specifies  a  number
              of  seconds to wait before failing the Snap action.
              The default is to wait forever.

       Transfer(keyword=value,...)
              Invokes IND$FILE file transfer.  See FILE  TRANSFER
              below.

       Wait([timeout,] 3270Mode)
              Used  when  communicating with a host that switches
              between NVT mode and 3270 mode.  Pauses the  script
              or  macro until the host negotiates 3270 mode, then
              waits for a formatted screen as above.

              The optional timeout parameter specifies  a  number
              of  seconds to wait before failing the Wait action.
              The default is to wait forever.

              For backwards compatibility, Wait(3270) is  equiva­
              lent to Wait(3270Mode)

       Wait([timeout,] Disconnect)
              Pauses  the  script  until  the  host  disconnects.
              Often used to after sending a logoff command  to  a
              VM/CMS  host,  to  ensure  that  the session is not
              unintentionally set to disconnected state.

              The optional timeout parameter specifies  a  number
              of  seconds to wait before failing the Wait action.
              The default is to wait forever.

              A useful  utility  for  use  at  the  beginning  of
              scripts  and  after  the  Connect  action.  In 3270
              mode, waits until the screen is formatted, and  the
              host  has  positioned  the  cursor  on a modifiable
              field.  In NVT mode, waits until the host sends  at
              least one byte of data.

              The  optional  timeout parameter specifies a number
              of seconds to wait before failing the Wait  action.
              The default is to wait forever.

              For  backwards compatibility, Wait is equivalent to
              Wait(InputField).

       Wait([timeout,] NVTMode)
              Used when communicating with a host  that  switches
              between  3270 mode and NVT mode.  Pauses the script
              or macro until the host negotiates NVT  mode,  then
              waits for a byte from the host as above.

              The  optional  timeout parameter specifies a number
              of seconds to wait before failing the Wait  action.
              The default is to wait forever.

              For  backwards compatibility, Wait(ansi) is equiva­
              lent to Wait(NVTMode).

       Wait([timeout,] Output)
              Pauses the script until the host sends further out­
              put.   Used  when  the  host  unlocks  the keyboard
              (allowing the script to proceed after an Enter,  PF
              or  PA  action),  but has not finished updating the
              screen.  This action is usually invoked in  a  loop
              that  uses  the  Ascii or Ebcdic action to scan the
              screen for some pattern  that  indicates  that  the
              host has fully processed the last command.

              The  optional  timeout parameter specifies a number
              of seconds to wait before failing the Wait  action.
              The default is to wait forever.


FILE TRANSFER

       The  Transfer  action  implements  IND$FILE file transfer.
       This  action  requires  that  the  IND$FILE   program   be
       installed  on  the  IBM  host, and that the 3270 cursor be
       located in a field that will accept a TSO or  VM/CMS  com­
       mand.

       Because  of  the complexity and number of options for file
       transfer, the parameters to the Transfer action  take  the
       unique  form of option=value, and can appear in any order.
       The options are:

       ------------------------------------------------------------------
       Direction           No       send      receive
       HostFile            Yes
       LocalFile           Yes
       Host                No       tso       vm
       Mode                No       ascii     binary
       Cr                  No       remove    add, keep
       Exist               No       keep      replace, append
       Recfm               No                 fixed, variable, undefined
       Lrecl               No
       Blksize             No
       Allocation          No                 tracks, cylinders, avblock
       PrimarySpace        No
       SecondarySpace      No

       The option details are as follows.

       Direction
              send (the default) to send  a  file  to  the  host,
              receive to receive a file from the host.

       HostFile
              The name of the file on the host.

       LocalFile
              The name of the file on the local workstation.

       Host   The  type  of  host (which dictates the form of the
              IND$FILE command): tso (the default) or vm.

       Mode   Use ascii (the default) for a text file, which will
              be  translated  between  EBCDIC and ASCII as neces­
              sary.  Use binary for non-text files.

       Cr     Controls how Newline characters  are  handled  when
              transferring   Mode=ascii   files.    remove   (the
              default) strips Newline characters in  local  files
              before  transferring  them  to  the host.  add adds
              Newline characters to each host file record  before
              transferring  it  to  the  local workstation.  keep
              preserves Newline characters  when  transferring  a
              local file to the host.

       Exist  Controls  what  happens  when  the destination file
              already exists.  keep (the default)  preserves  the
              file, causing the Transfer action to fail.  replace
              overwrites the destination  file  with  the  source
              file.  append appends the source file to the desti­
              nation file.

       Recfm  Controls the record format of files created on  the
              host.   fixed  creates  a  file  with  fixed-length
              records.  variable creates a  file  with  variable-

              undefined-length records  (TSO  hosts  only).   The
              Lrecl  option controls the record length or maximum
              record length for  Recfm=fixed  and  Recfm=variable
              files, respectively.

       Lrecl  Specifies  the  record  length  (or  maximum record
              length) for files created on the host.

       Blksize
              Specifies the block size for files created  on  the
              host.  (TSO hosts only.)

       Allocation
              Specifies  the  units for the TSO host PrimarySpace
              and SecondarySpace options:  tracks,  cylinders  or
              avblock.

       PrimarySpace
              Primary  allocation  for  a  file  created on a TSO
              host.   The  units  are  given  by  the  Allocation
              option.

       SecondarySpace
              Secondary  allocation  for  a file created on a TSO
              host.   The  units  are  given  by  the  Allocation
              option.


SEE ALSO

       expect(1)
       ksh(1)
       x3270(1)
       c3270(1)
       s3270(1)


VERSION

       Version 3.2.16


Man(1) output converted with man2html