{
                            {COMMAND REFERENCE
                            {=================

       The commands that comprise the Scripting Language are described
       below in alphabetical order.  For each command described in this
       section, the following information is provided:

           o What you can do with each scripting language command

           o Scripting language command syntax

           o Scripting language examples

           o Other commands used in conjunction with each script command

           o Potential pitfalls

       You select the Script Compiler commands from the "Command" menu in
       the Script Compiler application.

{  APPEND
{  ======

{    Syntax
{    ------

          APPEND "<string : integer>" TO <string_variable>
       {OR}
          APPEND <string variable : integer variable> TO <string_variable>

{    Purpose
{    -------

       Use {APPEND} to append a string or integer to a previously defined
       string variable.

       You can also append the contents of a string or integer variable to
       a string variable.  (See Example #2 below.)

{    Examples
{    --------

       Example #1:

              STRING listcommand /LENGTH=10 /VALUE="ls "
              listcommand = "ls "
              APPEND "-alt" TO listcommand

       Example #2:

              STRING optionstr /LENGTH=10 /VALUE="-alt"
              APPEND optionstr TO listcommand

       Example #3:

              STRING str /LENGTH=20 /VALUE="abc"
              APPEND p0 TO str

       Example 4:

              STRING command1 /length=40
              APPEND "ls " to command1
              APPEND "-l" to command1

{    Comments
{    --------

           o You must have declared the variable earlier with a {STRING}
             or {NUM} statement.

           o A script can call another script and pass certain arguments
             to it.  The called script refers to those arguments as P0
             through P9.

       Also see:   {STRING}

{    Diagnostics
{    -----------

       Make sure that the new value for a string does not exceed the
       declared length of the string.  This may cause the program to
       terminate unexpectedly or cause other unexpected behavior.

{  ASSIGN
{  ======

{    Syntax
{    ------

              <string variable> = <string : string variable>
            {OR}
              <num variable> = <num : num variable>

{    Purpose
{    -------

       Use the {ASSIGN} operator to assign a value to a string or number
       variable at any point in the script by using an "=" sign.  You can
       also assign a value to a string or number.  You must have declared
       the variable earlier with a {STRING} or {NUM} statement.

{   Example
{   -------

              unix_list = "ls -alF"
            {OR}
              loop_var = 10

{    Comments
{    --------

       For integer arithmetic, you must still use the {LET} command; for
       example, {LET x = y + z}.

{    Diagnostics
{    -----------
       Make sure that the new value for a string does not exceed the
       declared length of the string.  This may cause the program to
       terminate unexpectedly or cause other unexpected behavior.

{  CALL
{  ====

{    Syntax
{    ------

              CALL <script file> (<arg1,arg2...,arg10>)

{    Purpose
{    -------

       Use {CALL} to invoke another script.  Optionally, you may use
       {CALL} to pass up to ten (10) command line arguments to another
       script.  In the called script, arguments are referred to as P0
       through P9.  No type checking is performed.

       It is up to the user to use the parameters in the called script
       correctly as either {STRING} or {NUM} values.  The called script
       file must have the file extension ".SCO"  for it to be found at
       execution time.

{    Examples
{    --------

              CALL script.sco(arg1, arg2, arg3, "UNIX", arg4)
              CALL mscript.sco(arg1, arg2, "mail")
              CALL myscript.sco
              CALL myscript.sco(  )

{    Comments
{    --------

       Specify the complete name of the script being called; for example,
       {MYSCRIPT.SCO}, not just {MYSCRIPT}.

       A script file can be called by another script file.  Thus, scripts
       themselves can be nested.  Be careful when creating a script that
       calls itself; this can result in an infinite loop.

{    Diagnostics
{    -----------

       The number of passed parameters in a {CALL} statement is not
       checked.

{  ECHO
{  ====

{    Syntax
{    ------

              ECHO [/CONTINUE] <string/number variable>
           {OR}
              ECHO [/CONTINUE] <string : number>

{    Purpose
{    -------

       Use {ECHO} to display the contents of a string or number variable.
       You can also use it to echo a string or number constant.  To echo
       both a string and an integer at the same time, use the {APPEND}
       command to build the string, then echo it with the {ECHO} command.

       Use the {/CONTINUE} option when you want the script to continue
       executing while a status message displays on the screen.  This is
       referred to as a "modeless dialog box." The user must still click
       OK on the status message dialog box to clear the screen.

       You would not use the {/CONTINUE} option if you want to display a
       "modal dialog box," such as an error message, on the screen.  In
       this case, the script will stay in this mode (thus the script will
       not continue to execute) until the user reads the error message,
       then clicks OK to clear the error message from the screen.  This is
       the recommended use.

{    Example
{    -------

              ECHO /CONTINUE my_string
              ECHO /CONTINUE "Checking your mail..."
              ECHO loop_variable
              STRING DEBUGSTR /LENGTH = 20
              /VALUE = "The value of "num1 is"
              APPEND NUM1 TO DEBUGSTR
              ECHO DEBUGSTR

{    Comments
{    --------

       You may use up to a maximum of twenty (20) {ECHO /CONTINUE}
       statements in a script.

{  EXIT
{  ====

{    Syntax
{    ------

              EXIT

{    Purpose
{    -------

       Use {EXIT} to exit the user from the script.  The {EXIT} command is
       optional, and can be used in more than one place in a script.

{    Example
{    -------

              IF VALUE .EQUALNUM. 0
              THEN GOTO FINISH
              .
              .
              .
              FINISH:
              ECHO "ENDING SCRIPT"
              EXIT
              .
              .

{  FIND
{  ====

{    Syntax
{    ------

              FIND <string : string variable>  IN <string variable>

{    Purpose
{    -------

       Use {FIND} to check if a string variable contains a particular
       string.  It is used in the {IF} condition only.

{    Examples
{    --------

              IF FIND "New mail" IN recvdstring
              THEN
              ECHO "We have new mail!"
              ENDIF

{    Comments
{    --------

       Also see:  {GETSTRING}, {READ_FROM_SCREEN}

{  GETSTRING
{  =========

{    Syntax
{    ------

              GETSTRING /LENGTH=<number> /TIMEOUT=<timeout value>
              /ERRJMP = <label> <string : string variable>

       where {timeout value} is in XX:YY.ZZ format, and denotes minutes,
       seconds, and hundredths of a second.


{    Purpose
{    -------

       Use the {GETSTRING} command to copy data received from the remote
       host into a string variable.  You can specify how many characters
       to copy.

{    Examples
{    --------

              STRING line /length=10
              STRING line /length=10
              SEND "ls -l"
              GETSTRING  line
              GETSTRING  line1
              GETSTRING /length=5 /timeout=00:15.00 /errjmp=error line
              ECHO line
              ECHO line1
              error:
              EXIT

{    Comments
{    --------

       Use {GETSTRING} for VT emulation scripts only; do not use for
       TN3270 scripts.

       If the length value is greater than the defined length of the
       string variable, the defined length is used.

       Also see:  {READ_FROM_SCREEN}, {STRING}

{  GOTO
{  ====

{    Syntax
{    ------

              GOTO <label_name>

{    Purpose
{    -------

       Use {GOTO} to transfer control ("jump") to a statement other
       than the next statement in the script.

{    Example
{    -------

              GOTO start_loop

{    Comments
{    --------

       Also see:  {LABEL}

{  IF
{  ==

{    Syntax
{    ------

              IF <condition>
              THEN <statement1> <statement2> ...
              ELSE   <statement1> statement2> ...
              ENDIF

{    Purpose
{    -------

       Allows you to evaluate a condition.  Based on whether the condition
       is true or false, different lines in the script will be executed.
       You can nest {IF} statements.

       The condition can take the following forms:

              <variable_name> <comparator> <variable_name>

              <variable_name> <comparator> <quoted-string>

              <variable_name> <comparator> <integer>

              a FIND command

       The condition ~cannot` take the following forms:

              <quoted_string> <comparator> <anything>

              <integer> <comparator> <anything>

       The following comparators are supported:

       .EQS.       String comparison       True if equal
       .EQUALNUM.  Integer comparison      True if equal
       .NE.        Integer comparison      True if not equal
       .GE.        Integer comparison      True if greater than or equal
       .GT.        Integer comparison      True if greater than
       .LE.        Integer comparison      True if less than or equal
       .LT.        Integer comparison      True if less than

{    Example
{    -------

              IF machine_type .eqs. "UNIX"
              THEN
              SEND "ls -alt"
              ELSE
              SEND "dir /full"
              ENDIF
              NUM LOOP /value=5
              START:
              CALL DO_IT.sco (LOOP)
              LET LOOP= LOOP-1
              IF LOOP .GT. 0
              THEN GOTO START
              ENDIF
              EXIT

       The only other valid construct that can be used with {IF} is the
       {FIND} command.  For example:

       Example #1:

              IF FIND "unix" IN HOST
              THEN
                  SEND "ls -alt"
              ELSE
                  SEND "dir /full"
              ENDIF

       Example #2:

              INQUIRE /PROMPT="Logout:Answer Y or N" logoutstr
              IF logoutstr .EQS. "Y"
              THEN
                  SENDKEY CTRL+D
              ENDIF

{  INQUIRE
{  =======

{    Syntax
{    ------

              INQUIRE [/NOECHO] [/PROMPT=  "<prompt>"] <string variable>

{    Purpose
{    -------

       Use the {INQUIRE} command to accept a string from the user at
       execution time and store it in a string variable.  If you do not
       supply the {/NOECHO} option, the user text will be echoed as it is
       typed.  You may also supply a prompt string that will be displayed
       to the user.

       If you supply a {/NOECHO} option, the text typed in by the user
       will be echoed as asterisks (***) instead of the actual string.

{    Example
{    -------

              INQUIRE /PROMPT="Please enter your password" passwd_var

{    Comments
{    --------

       The string variable must have previously been defined using the
       {STRING} command.

{  LABEL
{  =====

{    Syntax
{    ------

              <label_name>:

       Use a {LABEL} statement to mark the following statement.  This
       statement is used by the {GOTO} statement.

{    Example
{    -------

              end_of_script:
              exit

{    Comments
{    --------

       See {GOTO}.

       You can use up to a maximum of 20 labels in a script.

{  LET
{  ===

{    Syntax
{    ------

              LET <integer variable> = <expression>

{    Purpose
{    -------

       Use {LET} to do integer arithmetic.  The operations supported are
       addition, multiplication, division and subtraction.

       Only binary expressions are supported; that is, an expression can
       only be of the form:

              <operand> <operator> <operand>

       for example, {x + y OR loop + 1}.

       It ~cannot` be of the form:

              <operand> <operator> <operand> <operator> <operand> ...

       for example, {x + y + z OR  loop + 1 + 2}.

{    Example
{    -------

              LET loop = loop + 1

{    Diagnostics
{    -----------

       The compiler will not catch any integer overflow.

{  MOVECURSOR
{  ==========

{    Syntax
{    ------

              MOVECURSOR <row>,<column>

{    Purpose
{    -------

       Moves the cursor to a specified position.  row and column refer to
       the position to which the cursor is to be moved.  This command
       assumes that the top left corner of the screen is (1,1), as shown
       in the status line position display.

       In an automated logon script, {READ} can look for the host's login
       prompt, but the cursor may not be in the correct field.  You need
       to use the {MOVECURSOR} command to move the cursor to the correct
       field.  You can find the proper position for the cursor by running
       a session manually and noting the required positions on the
       display.

{    Example
{    -------

              SEND "Fred"
              MOVECURSOR 10,8
              SEND "1129 Briar Patch Lane"

{    Comments
{    --------

              {MOVECURSOR} is typically used for TN3270 scripts.

{  NUM
{  ===

{    Syntax
{    ------

              NUM <variable_name> [/VALUE=<number>]

{    Purpose
{    -------

       Use {NUM} to declare a number (integer) and initialize it at the
       same time.  {VALUE} is optional; if no {VALUE} is provided, the
       value defaults to 0.

{    Example
{    -------

              NUM loop_var /VALUE=5
              NUM loop_var

{    Comments
{    --------

       {<num_variable>} can be initialized at this point, but does not
        have to be.

       Also see:  {STRING}, {ASSIGN}

{  READ
{  ====

{    Syntax
{    ------

         READ /TIMEOUT=<timeout value> /ERRJMP=<label> <string : variable>

       where {<string : variable>} may be either a quoted string (for
       example, "Please log in:") or a variable that has been previously
       defined using the {STRING} or {NUM} command.

{    Purpose
{    -------

       {READ} searches the screen buffer for the specified string.
       Reading from the screen ensures that TN3270 code sequences have
       been parsed.

       Typically, you should use the {/TIMEOUT} and {/ERRJMP} options
       together because the {/ERRJMP} option tells you where to jump if a
       timeout is reached.

{      Example
{      -------

              string userprompt /length=20 /value="User"
              read /timeout=00:20.00 /errjmp=oops userprompt

{    Comments
{    --------

       Use {READ} for TN3270 scripts only.  Do not use {WAITFOR} for
       TN3270 scripts.

{  READ_FROM_SCREEN
{  ================

{    Syntax
{    ------

              READ_FROM_SCREEN /POS=row#,column# /LENGTH=<read_length>
                <string_variable_name>

{    Purpose
{    -------

       Similar to {GETSTRING} except that a string is copied from the
       screen buffer to a string variable.  Use the {MOVECURSOR} command
       to position the cursor and then use {READ_FROM_SCREEN}.  You can
       alternatively specify that reading from the screen begins at a
       position defined by row# and column#.

{    Examples
{    --------

              READ_FROM_SCREEN /POS=20,5 mailaddress
              READ_FROM_SCREEN /POS=12,40 /LENGTH=20 nextstring

{    Comments
{    --------

       You can use {/POS} or {/LENGTH}, or both. If the {/LENGTH}
       parameter is not used, the defined length of the string is used.

       Also see:  {MOVECURSOR}

{  SEND
{  ====

{    Syntax
{    ------

              SEND [/NOCR_LF] <string_variable : string>

{    Purpose
{    -------

       Use {SEND} to send a string variable or string to the remote host.
       It can be a quoted-string like "{ls -l}", the name of a string
       variable like {MY_PASSWORD} or a system variable like
       {SYS_USERNAME}.

       The following script illustrates the use of the {SEND} command:

              string str /LENGTH=20
              NUM num1 /VALUE=15
              APPEND "The value of num1 is" TO str
              APPEND num1 to str
              #Now str contains
              #"The value of num1 is 15"
              SEND str
              EXIT

{    Examples
{    --------

              SEND "ls -l"
              SEND /NOCR_LF  SYS_USERNAME
              SEND MY_PASSWORD
              SEND "Fred"
              MOVECURSOR 10,8
              SEND "1129 Briar Patch Lane"

{    Comments
{    --------

       If you use the {/NOCR_LF} option the string is sent without a
       terminating carriage return and line feed.

       For TN3270 sessions the {/NOCR_LF} option is unnecessary.

{  SENDKEY
{  =======

{    Syntax
{    ------

              SENDKEY <key constant>

{    Purpose
{    -------

              Use {SENDKEY} to send a particular escape sequence or
              control sequence to the host.

{    Example
{    -------

       You can use the following command to advance to the next field in a
       TN3270 environment by sending a tab:

           SENDKEY  TN_TAB

{    Comments
{    --------

       Keynames with "VT_xxx" are for VT emulation and keynames with
       TN_xxx" are for TN3270 emulation.

{    List of SENDKEY Functions
{    -------------------------

       Use the {SENDKEY} command with one of the functions listed below:

       VT_PF1               VT_PF2                 VT_PF3
       VT_PF4               VT_FIND                VT_REMOVE
       VT_SELECT            VT_NEXT                VT_PREVIOUS
       VT_F6                VT_F7                  VT_F8
       VT_F9                VT_F10                 VT_F11
       VT_F12               VT_F13                 VT_F14
       VT_HELP              VT_DO                  VT_F17
       VT_F18               VT_F19                 VT_F20
       VT_UP_ARROW          VT_DOWN_ARROW          VT_LEFT_ARROW
       VT_RIGHT_ARROW       VT_KEYPAD_0            VT_BACKSPACE
       VT_KEYPAD_1          VT_KEYPAD_2            VT_KEYPAD_3
       VT_KEYPAD_4          VT_KEYPAD_5            VT_KEYPAD_6
       VT_KEYPAD_7          VT_KEYPAD_8            VT_KEYPAD_9
       VT_ENTER             VT_KEYPAD_MINUS        VT_KEYPAD_COMMA
       VT_KEYPAD_PERIOD     VT_SHIFT_F6            VT_SHIFT_F7
       VT_SHIFT_F8          VT_SHIFT_F9            VT_SHIFT_F10
       VT_SHIFT_F11         VT_SHIFT_F12           VT_SHIFT_F13
       VT_SHIFT_F14         VT_SHIFT_HELP          VT_SHIFT_DO
       VT_SHIFT_F17         VT_SHIFT_F18           VT_SHIFT_F19
       VT_SHIFT_F20         VT_COMPOSE
       TN_PF1               TN_PF2                 TN_PF3
       TN_PF4               TN_PF5                 TN_PF6
       TN_PF7               TN_PF8                 TN_PF9
       TN_PF10              TN_PF11                TN_PF12
       TN_PF13              TN_PF14                TN_PF15
       TN_PF16              TN_PF17                TN_PF18
       TN_PF19              TN_PF20                TN_PF21
       TN_PF22              TN_PF23                TN_PF24
       TN_PA1               TN_PA2                 TN_PA3
       TN_ATTN              TN_BACK_TAB            TN_CLEAR
       TN_CURSOR_SEL        TN_DELETE              TN_DEVICE_CANCEL
       TN_DUP               TN_UP_ARROW            TN_DOWN_ARROW
       TN_LEFT_ARROW        TN_RIGHT_ARROW         TN_ENTER
       TN_ERASE_EOF         TN_ERASE_INPUT         TN_FIELD_MARK
       TN_HOME              TN_INS                 TN_PRINT
       TN_RESET             TN_RETURN              TN_SYSTEM_REQ
       TN_BACKSPACE         TN_TAB

       You can also use {SENDKEY} to send the following control codes to
       the remote host.

       {Note...} Remember that the effect of the control codes are
       determined by the remote application and operating system.

       CTRL+A
       .
       .
       .
       CTRL+Z

{  STRING
{  ======

{    Syntax
{    ------

              STRING <string variable> /LENGTH=<number> [/VALUE=<string>]

{    Purpose
{    -------

       Use {STRING} to declare a string and initialize it at the same
       time.  You ~MUST` provide the {LENGTH} argument. The {/VALUE}
       argument is optional.

       Note that you must follow the above syntax exactly; that is, you
       cannot switch the order of the options {/LENGTH} and {/VALUE}.  For
       example, you could give the command:

              STRING haha /length=80 /value=" "

       If the {/VALUE} parameter is omitted, the string will be
       initialized to have a {NULL} value.

{    Example
{    -------

              STRING unix_list /LENGTH=10 /VALUE="ls -l"
              STRING my_name /LENGTH=40

{    Comments
{    --------

              {/LENGTH} is required; {/VALUE} is optional.

       Also see:  {NUM}, {ASSIGN}

{  WAIT
{  ====

{    Syntax
{    ------

              WAIT XX:YY.ZZ

       where the time (XX:YY.ZZ) is specified in minutes, seconds and
       hundredths of a second.

{    Purpose
{    -------

       {WAIT} delays execution of the next command for the specified time
       interval.

{    Example
{    -------

              WAIT 00:05.00

{  WAITFOR
{  =======

{    Syntax
{    ------

              WAITFOR /TIMEOUT = <timeout value> /ERRJMP = <label>
                 <string : variable> where:

       {<string : variable>} may be either a quoted string (for example,
       "Please log in:") or a variable that has been previously defined
       with the {STRING} command.

{    Purpose
{    -------

       Use the {WAITFOR} command to examine the data coming from the
       remote host and to compare it with the string specified by
       {<string : variable>}.  If the comparison is successful within the
       time period specified by the {/TIMEOUT} value, the {WAITFOR}
       command terminates successfully and the next command in the script
       is executed.  Otherwise, if you use the {/ERRJMP} option, control
       is transferred to the instruction immediately following the label
       specified by {/ERRJMP}.  If you do not use the {/ERRJMP} option,
       the next instruction in the script is executed. Example

              WAITFOR /TIMEOUT=00:05.00 /ERRJMP=err_exit "login:"

{    Comments
{    --------

       The {TIMEOUT} parameter is of the form: minutes:seconds.hundredths
       of a second.

       {WAITFOR} should be used for a VT terminal session only.

{  # (Comment Line)
{  ================

{    Syntax
{    ------

              #

{    Purpose
{    -------

       Use the {#} symbol to designate a "comment line," which contains
       descriptions for code documentation purposes only; they have no
       effect on the processing.

       The {#} symbol can appear only at the beginning of a line with
       only the comment on the line.  A comment line can contain anything
       but it MUST begin with a {#}.

