Simtel MSDOS 1992 September/Simtel20_Sept92.cdr/msdos/kermit/ker_scp3.arc/SCRIPTS.DOC

Text File | 1988-09-11 | 21KB | 460 lines

[Following script-specific information is extracted from MS-Kermit's users
 manual.  (V2.30 or so.)

1.8. SCRIPTS

A  script is a file or a macro containing Kermit commands to be executed.  What
distinguishes a script from ordinary TAKE files or macros is  the  presence  of
INPUT,  REINPUT,  OUTPUT,  PAUSE,  ECHO,  CLEAR, IF, GOTO, and WAIT commands to
automatically detect and respond to information flowing though the serial port,
actions  which  otherwise  would  be performed by the user during CONNECT.  The
login sequence of a host computer is a classical example.

It is a common, but incorrect, assumption that text to be sent  to  the  remote
computer can be included in a TAKE file after the CONNECT command:

    set speed 9600      ; MS-Kermit command
    connect          ; MS-Kermit command
    run kermit          ; Text to be sent to other system
    send foo.bar      ; Text to be sent to other system
    ^]c              ; Escape sequence to get back to MS-Kermit
    receive          ; MS-Kermit command

The  reason  this  doesn't  work is that during CONNECT, MS-Kermit always reads
from the real keyboard, and not from the take file.  Even if this technique did
work,  it  would  still  run  into  synchronization problems.  But these can be
avoided when there is a way to coordinate the commands that we  send  with  the
remote  system's  responses.    Kermit's  script commands provide this ability.
They may be freely intermixed in a TAKE file or macro  with  any  other  Kermit
commands to achieve any desired effect.  The OUTPUT command sends the specified
characters as if the user had typed them; the INPUT command reads the responses
and compares them with specified character strings, just as the user would do.

The  script commands include INPUT, REINPUT, OUTPUT, PAUSE, WAIT, ECHO, IF, and
GOTO.  These commands may be interrupted by typing Ctrl-C at the keyboard.  The
INPUT, REINPUT, PAUSE, and WAIT commands accept a following number as a timeout
value. The number is interpreted as seconds from the present or,  if  given  in
hh:mm:ss form, as a specific time of day.  In either case, the timeout interval
must be within 12 hours of the present to avoid it being considered as  in  the
past (expired).


The CLEAR Command

Syntax: CLEAR

The  CLEAR command empties the buffers of the serial port to forget any earlier
material.  This gets the INPUT command off to a clean start.  (This command was
called  CLRINP  in 2.29B and earlier, and CLEAR was used to erase macro and key
definition memory).


The ECHO Command

Syntax: Echo text

The ECHO command is useful for reporting progress of a script, or prompting the
user  for  interactive input.  The text is displayed on the screen, and may in-
clude backslash notation for control or 8-bit characters.  An implied  linefeed
is included at the beginning of the text.


SET INPUT

Syntax: SET INPUT {CASE, DEFAULT-TIMEOUT, ECHO, TIMEOUT-ACTION}

The SET INPUT command controls the behavior of the script INPUT command:

SET INPUT CASE {IGNORE, OBSERVE}
    Says whether or not to distinguish upper and lower case letters when  doing
    a  matchup  in the INPUT command.  OBSERVE causes upper and lower case let-
    ters to be distinguished.  The default is to IGNORE case distinctions.

SET INPUT DEFAULT-TIMEOUT seconds
    Changes  the  default  waiting time from one second to this new value.  The
    value is used when an INPUT command has no timeout specified.

SET INPUT ECHO {ON, OFF}
    Show  on  the screen characters read from the serial port during the script
    operation, or not.  Default is ON, show them.

SET INPUT TIMEOUT-ACTION {PROCEED, QUIT}
    Determines  whether  or not the current macro or TAKE command file is to be
    continued or exited if a timeout occurs.  PROCEED is the default and  means
    that  timeouts  are  ignored.    QUIT  causes the current script file to be
    exited and control passed to either the next higher level script  file  (if
    there is one) or to Kermit's main prompt.

The SHOW SCRIPTS command displays the SET INPUT values.


The INPUT command

Syntax: INPUT [timeout] {search-string, @filespec}

INPUT  is  the  most powerful of the script commands.  It reads characters from
the serial port continuously until one  of  two  things  occurs:  the  received
characters match the search string or the time limit expires.  Matching strings
is the normal use, as in:

    Kermit-MS>input 5 Login please:

to recognize the phrase "Login please:", or else time out after  trying  for  5
seconds.   A special binary character \255 or \o377 or \xFF stands for the com-
bination carriage return and a line feed, in either order, to simplify  pattern
matching.  The command reports a testable status of SUCCESS or FAILURE and sets
the DOS ERRORLEVEL parameter to 2 if it fails to match within the  timeout  in-
terval.    Characters  are stored in a 128 byte buffer for later examination by
REINPUT, discussed below.

Beware of characters arriving with parity set because the pattern matching con-
siders  all 8 bits of a byte unless the local parity is other than NONE and SET
DISPLAY is 7-BITS.  Arriving characters are  modified  by  first  removing  the
parity  bit, if parity is other than NONE, then they are passed through the SET
TRANSLATION INPUT converter, the high bit is again suppressed if SET DISPLAY is
7-BITs, the result is logged and stored for pattern matching.


The REINPUT command

Syntax: REINPUT [timeout] {search-string, @filespec}

The  REINPUT command is like INPUT except that characters are read from the 128
byte serial port history buffer rather than always seeking fresh input from the
port.    The purpose is to permit the current text to be examined several times,
looking for different match strings.  A common case is reading the results of a
connection  message  from  a  modem  which  might be "CONNECT 1200" or "CONNECT
2400", depending on the other modem.  If the history buffer has less  than  128
bytes then fresh input may be requested while seeking a match, until the buffer
is full.  REINPUT match searches begin at the start of the buffer whereas INPUT
searches  never  go  back  over examined characters.  REINPUT sets the testable
status of SUCCESS or FAILURE and DOS ERRORLEVEL, just as for INPUT.

The INPUT, REINPUT, and OUTPUT commands have a special syntax  to  replace  the
normal string with text obtained from a file or device:

    OUTPUT @filespec
    INPUT @filespec

Both  forms  read  one  line  of text from the file or device and use it as the
desired string.  A common use is to wait for a password prompt  and  then  read
the  password  from  the  console  keyboard.    A  string starts with the first
non-spacing character and ends at either the end of line or, if executed within
a  TAKE file, at a semicolon.  Indirectly obtained strings, the @filespec form,
read the first line of the file up to but not including the  explicit  carriage
return.    Note  if  a  trailing carriage return is needed it must be expressed
numerically, such as \13 decimal.  Example:

    input 7 Password:
    echo Please type your password:
    output @con
    output \13
    echo \13\10Thank you!

In this example, a TAKE file requests the user to type in the  password  inter-
actively,  so  that  it  does not have to be stored on disk as part of the TAKE
file.

When a script fails because an INPUT or REINPUT command did not  encounter  the
desired string within the timeout interval the message "?Timeout" is displayed.


The OUTPUT command

Syntax: OUTPUT {string, @filespec}

The  OUTPUT command writes the indicated character string to the serial port as
ordinary text.  The string may contain control or other special binary  charac-
ters  by  representing  them  in backslash form.  Carriage Return (CR), for ex-
ample, is \13 decimal, \o15 octal, or \x0D hexadecimal.   The  string  may  use
8-bit characters if the communications parity is type NONE.  A special notation
is also provided, \b or \B, which causes a BREAK signal to be transmitted.

The string to be transmitted starts with the first non-spacing character  after
the  OUTPUT command and ends at either the end of line or, if executed within a
TAKE file, at a semicolon (if you need to output a semicolon from within a TAKE
file,  use  backslash  notation, e.g. "\59").  Indirectly obtained strings, the
@filespec form, read the first line of the file up to but not including the ex-
plicit carriage return.

As a convenience, text arriving at the serial port during the OUTPUT command is
shown on the screen if SET INPUT-ECHO is ON, and stored in a 128-byte  internal
buffer for rereading by subsequent (RE)INPUT commands.


The PAUSE command

Syntax: PAUSE [{number, hh:mm:ss}]

PAUSE  simply  waits one or more seconds before Kermit executes the next script
command.  Pauses are frequently necessary to avoid overdriving the host and  to
let  a modem proceed through a dialing sequence without interruptions from Ker-
mit.  The default waiting time is set by SET INPUT DEFAULT-TIMEOUT and is  nor-
mally one second.  The optional integer number selects the number of seconds to
pause for this command, or a specific time of day.  An explicit value  of  zero
produces  a pause of just a few milliseconds which can be useful in some situa-
tions.

Text arriving during the  PAUSE  interval  is  shown  on  the  screen,  if  SET
INPUT-ECHO  is  ON, and stored in a 128-byte internal buffer for rereading by a
following INPUT command.

PAUSE is interrupted if there is any activity on the keyboard.  Thus PAUSE  can
be useful for operations like:

    echo "Type any key when ready..."
    pause 9999


The WAIT Command

Syntax: WAIT [{number, hh:mm:ss}] [\CD] [\CTS] [\DSR]

WAIT  performs  a  timed  PAUSE, as above, but also examines the optional modem
control signals Carrier Detect (\CD),  Clear  To  Send  (\CTS),  and  Data  Set
(modem)  Ready (\DSR).  If all of the specified signals is ON, or become ON be-
fore the timeout interval, the wait operation ceases with an indication of SUC-
CESS.     If  the time interval expires without all of the specified signals on,
the status is FAILURE.  Example:

    Kermit-MS> WAIT 12:45 \cd \dsr

This waits until 45 minutes past noon for both CD and DSR to  be  asserted,  or
fails.

If no modem signals are specified, then WAIT is the same as PAUSE.


Labels and the GOTO Command

Labels  and  the GOTO command work together in the same fashion as in DOS Batch
files.  A label is a line which starts with a colon (:) in the leftmost  column
followed immediately by a word of text (no intervening spaces); material on the
line after the label is ignored.  The GOTO command is followed by a label,  the
leading colon is optional in the GOTO command.  The label may be located either
before or after the GOTO command and is found by searching  the  TAKE  file  or
macro  from  the  beginning.  Thus, duplicated labels will always use the first
occurrence.  The target label must be in the current TAKE file  or  macro;  one
may not GOTO a label in another TAKE file or macro.  Example:

    :LOOP
    echo again and\13
    goto loop

will  print "again and again and again and..." forever (until you type Ctrl-C).
As a macro:

    define test :loop,echo again and\13,goto loop
    do test

Note that if a label follows a comma in a macro definition, there  must  be  no
intervening spaces:

    define test ..., :top, ..., goto top  ; bad, space before colon.
    define best ...,:top, ..., goto top   ; good, no space.

In this example, the best macro will work, the test macro won't.


The IF Command

Syntax: IF test-condition MS-Kermit Command

The  IF  command  gives  MS-Kermit scripts the ability to make a decision based
upon the criterion specified as the test-condition.  If the test  condition  is
true,  then  the command is executed.  Otherwise, it is skipped.  The test con-
ditions are:

    NOT     Modifier for other conditions below.

    ALARM   True if the current time of day is at or later than the alarm clock
        time.    The alarm clock time is set by the command SET ALARM time.
        IF ALARM distinguishes early from late with  a  12  hour  field  of
        view.

    COUNT   True  if the current COUNT variable is greater than zero.  COUNT is
        a special Kermit variable for each active TAKE file or macro.    It
        is  set by the command SET COUNT and it is both tested and modified
        by the IF COUNT command.  The intent is to construct simple  script
        loops  where the IF COUNT command first decreases COUNT by one (but
        never below zero) and then if COUNT is greater than zero  the  fol-
        lowing  Kermit  command is executed.  Because COUNT exists only for
        TAKE files and macros it cannot be used interactively.   Each  TAKE
        file  or  macro has its own distinct copy of COUNT, and nested TAKE
        files or macros do not interact through their  COUNTs.    Initially
        COUNT is zero.

    DEFINED symbol
        True if the named macro or variable is defined.  You can  use  this
        feature to remember things for future reference.

    ERRORLEVEL number
        True if the DOS errorlevel number  matches  or  exceeds  the  given
        (decimal) number.

    EXIST filespec
        True if the specified file exists.

    FAILURE True if  the  previous  status-returning  Kermit  command  reported
        failure.

    SUCCESS True  if the previous status-returning Kermit command reported suc-
        cess.  When using IF SUCCESS and IF FAILURE, it is important to SET
        INPUT  TIMEOUT  PROCEED, otherwise the script will quit immediately
        upon a failing INPUT or REINPUT, before getting to  the  IF  state-
        ment.

IF  commands  are closely modeled on those of DOS Batch files, for familiarity.
They consist of a test condition, perhaps modified by the leading word NOT, and
then  any  legal  Kermit command.  GOTO is an especially useful command here to
branch in the TAKE file or macro.

The "object" of an IF command is a Kermit command, which can be:

   - A regular, predefined Kermit command, like SEND FOO.BAR or SET  SPEED
     1200.

   - A GOTO, allowing subsequent statements to be skipped.

   - Another  IF  command,  as  in  IF  DEFINED  \%3 IF EXIST FOO.BAR SEND
     FOO.BAR.  The SEND command is executed only if both IF conditions are
     true.

   - A  macro.  This allows a semblence of structured programming, with an
     implied "begin" and "end" around the commands that compose the macro.
     For instance:

     define giveup echo I give up!, hangup, stop
     input 10 Login:
     if failure giveup
     output myusername

The  Kermit  commands which yield SUCCESS or FAILURE conditions are: GET, SEND,
RECEIVE, the REMOTE commands, INPUT, REINPUT, BYE, FINISH, LOGOUT, and WAIT.


Script Examples

A counting loop.  This TAKE file excerpt says  hello  three  times,  then  says
goodbye:

    set count 3            ; Prime the loop counter for three passes
    :TOP            ; A label for GOTO
    echo Hello\13        ; Something to see, with carriage return
    if count goto top        ; Loop if COUNT is greater than zero
    echo Goodbye!\13

Figure 1-2 shows a simple script file that logs in to a computer, prompting the
user for her password using the @con construction, and then connects as a  ter-
minal.

-------------------------------------------------------------------------------


    define ermsg echo %\1\13, stop     ; Define an error handling macro.
    clear                 ; Clear the input buffer.
    set speed 9600             ; Set the transmission speed.
    output \13                 ; Carriage return to awaken host.
    input 15 Login:             ; Wait up to 15 secs for prompt.
    if failure ermsg No login prompt!     ; Give up if none.
    output Sari\13             ; Send username and CR.
    set input echo off             ; Privacy, please.
    input 5 Password:             ; Quietly wait for this.
    if failure ermsg No password prompt! ; Give up if it doesn't come.
    echo Type your password now...     ; Make our own prompt.
    output @CON                 ; Send console keystrokes.
    output \13                 ; Add a real carriage return.
    input 30 $                 ; Wait for system prompt.
    if failure ermsg No system prompt!   ; Give up if none.
    connect                 ; Start terminal emulation.

         Figure 1-2:   MS-Kermit Script for Logging In

-------------------------------------------------------------------------------

Notice  the  semicolons used to indicate comments in TAKE files.  If these same
commands were typed by hand at the Kermit prompt the semicolon  material  would
be  considered  part  of  a string!  Typing a Control-C will interrupt and ter-
minate any of the commands.

Figure 1-3 illustrates some detailed control of the Hayes modem.   Some  under-
standing  of  the Hayes dialing language is helpful for deciphering this script
(consult your Hayes modem manual).  If the script is stored in  a  file  called
HAYES.SCR, then a DIAL macro can be defined like this:

    define dial take hayes.scr

The  trick  here is that any invocation of the "dial" or "do dial" command with
an operand will set the variable \%1, which is used in the TAKE file,  for  in-
stance:

    dial 765-4321

will set \%1 to "765-4321", the number to be dialed.

-------------------------------------------------------------------------------


    if defined %\1 goto start         ; Make sure number specified.
    echo Please supply a phone number!\13
    stop
    :START
    clear                 ; Clear the input buffer.
    set speed 2400             ; Dial at high speed.
    wait 10 \dsr             ; Is modem turned on?
    if success goto init
    echo Please turn on your modem.\13   ; It's not, complain,
    stop                 ; and exit the script.
    :INIT
    echo Initializing modem...\13\10     ; Modem is turned on.
    output ATZ F1 Q0 V1 X4 S0=0\13     ; Initialize the modem.
    input 5 OK                 ; Get its response.
    if success goto dial         ; If OK, go ahead and dial
    echo Can't initialize the modem!\13  ; Not OK, give up.
    stop
    :DIAL                 ; Ready to dial.
    set count 5                 ; Set the redial limit.
    define \%d \13Dialing         ; Initial dial message.
    :REDIAL
    echo \%d \%1...\13             ; Tell them we're dialing.
    output ATDT \%1\13             ; Dial the phone number.
    clear                 ; Clear away the command echo.
    input 30 CONNECT             ; Wait for CONNECT message.
    if success goto speed         ; Got it, go check speed.
    define \%m No dialtone or no answer. ; Make this the error message.
    reinput BUSY             ; Didn't connect.  Was it busy?
    if failure goto later         ; No, something else.
    Echo \13Busy...             ; It's busy, let them know.
    pause 60                 ; Wait one minute.
    define \%d \13Redialing         ; Change message to "Redialing".
    if count goto redial         ; Then go redial.
    define \%m \13Line busy.         ; After 5 tries set this message.
    :LATER                 ; Get here upon giving up.
    echo \%m\10\13Try again later.\13     ; Issue error message.
    stop                 ; Exit from the script.
    :SPEED                 ; Connected!
    pause 1                 ; Wait for text after CONNECT.
    define \%s 2400             ; Assume speed is 2400.
    reinput 1 2400             ; Rescan current text for "2400"
    if success goto done         ; It is.
    define \%s 1200             ; It isn't, so assume 1200.
    reinput 1 1200             ; Is it?
    if failure define \%s 300         ; It isn't, so it must be 300.
    :DONE                 ; We know the speed.
    set speed \%s             ; So set it.
    echo Connecting at \%s bps...\13     ; Tell the user.
    connect                 ; And start terminal emulation.

   Figure 1-3:   MS-Kermit Script for More Control of a Hayes 2400 bps Modem

-------------------------------------------------------------------------------

A  combination of DOS Batch and Kermit Script files is shown in Figures 1-4 and
1-5 (see your DOS manual for an explanation of the batch  file  syntax).    The
purpose  is  to allow a user to say "SEND filename" at the DOS prompt.  The DOS
batch shell, SEND.BAT, and the login script, KX, are combined to login to a VAX
through a data switch, run VMS Kermit in server mode, transfer the file, submit
it to VMS Mail, delete the disk file, shut down the server and logout from  the
VAX,  and  report  the overall transfer status.  The user is asked to provide a
password interactively.