Simtel MSDOS - Coast to Coast

home *** CD-ROM | disk | FTP | other *** search

/ Simtel MSDOS - Coast to Coast / simteldosarchivecoasttocoast2.iso / kermit / ker_scp3.zip / SCRIPTS.DOC < prev next >

Wrap

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.