NOVATERM 9.6 Documentation pages Contents | Introduction | Getting Started | Getting Familiar | On-line Activities | Configuration | Disk Utilities | Scripts | Utility Modules | Appendices ___________________________________________________________ 6. SCRIPTS Scripts are a powerful tool for making Novaterm perform functions automatically. Scripts can do everything from load modules to download files to respond to specific text received from an on-line service. Scripts can log you into a service, collect electronic messages, download files, and do a variety of other things, all unattended. You write a script using Novaterm's script language. The language is just a set of one-line instructions that Novaterm recognizes to perform different functions. A script consists of a series of these one-line instructions. Novaterm executes each instruction in order. When you write a script, you are just telling Novaterm what to do, one step at a time. To actually create a script and run it, you'll follow these steps: 1. Load Novaterm's Text editor program from the Utility Modules menu. 2. Type in your script, line by line. 3. Save the script source to a file. The "source" is the text you just typed. This isn't the actual script yet... 4. Compile the script. "Compiling the script" means to convert the text you typed into an encoded form that Novaterm can recognize. You compile the script by pressing the RUN/STOP key in the Text Editor, while your source is there on the screen. 5. Return to Novaterm, and execute the script by pressing C= G in Terminal Mode (see 3.1.3, Commodore key commands, C= G). Each of these steps is described in more detail below. 6.1 Creating a sample script To illustrate how scripts work, let's create a sample script and execute it. 6.1.1 Determining the sequence of responses Suppose we want to create a script that automatically logs us into our Internet provider, a bulletin board called "Eskimo North". In order to automatically log us in, the script must watch the text sent by Eskimo North as it comes in, and output our login name and password at the right time. To set up our script to do this, we must examine the text that displays during a normal login procedure (i.e. when we dial and log in manually). To do this, we can capture the text in the buffer and look at it later. Listed below is a sample buffer capture of the text sent from Eskimo North during the login procedure. Any text that we had to type, in response to a prompt, is shown in bold. SAMPLE LOGIN TO ESKIMO NORTH Eskimo North Connection Selection 0) Apply for a 2-week free trial 1) Connect to Eskimo [general login sessions] 2) Connect to Eskinews [uqwk uucp and mud maintenance] 3) Connect to Isumataq [irc bots and moo maintenance only] 4) Connect to Tia1 [use this host for TIA slip] 5) Connect to Mail [use for UUCP mail connections] 8) Western Washington BBS List 9) Exit Your Selection ==> 1 New Users - please type "new". Type your login in lower case (small letters). Passwords are case-sensitive THISPW != thispw. Passwords will not echo. login: voyager Password: ********** Last login: Mon Jun 26 13:55:30 from tia1.eskimo.com SunOS Release 4.1.4 #2: Tue Apr 18 04:07:39 PDT 1995 North Everett : (206) 258-0759 300 bps - 14.4kbps South Everett : (206) 742-1150 300 bps - 14.4kbps Seattle/Maple Vlly: (206) 367-3837 300 bps - 14.4kbps Des Moines / Kent : (206) 838-9513 300 bps - 14.4kbps Tacoma / Auburn : (206) 927-3218 300 bps - 14.4kbps East Side Line : (206) 451-8876 300 bps - 14.4kbps Enumclaw/Blk Dmnd : (206) 939-5992 300 bps - 14.4kbps Buckley : (360) 802-0992 300 bps - 14.4kbps Eskimo North Users Meeting: Sunday July 16th 2:30PM @ Ballard Godfathers (63rd Street and 15th Ave N.W.) You have new mail. [?] short menu [*] long menu Main Command? END OF SAMPLE LOGIN Notice that there were three places we had to type in a response: 1. In response to the string Your Selection ==> we typed a 1 and pressed RETURN. 2. In response to the string login:, we typed the user name voyager and pressed RETURN. 3. In response to the string Password:, we typed our password and pressed RETURN. After responding to those three prompts, we were logged in. Therefore, we want our script to automatically respond to these three prompts for us. After responding to the prompts, we want the script to end. To do this, we'll find a fourth string that, when detected, ends the script. The string Command?, at the end of the sample capture file, is Eskimo North's command prompt, which is where we want to take back control. Therefore, in response to the string Command?, we'll end the script. Now that we know what to look for, let's start writing the script. First of all, suppose that we use the VT102 terminal emulation with Eskimo North. This means the first line of our script must be: .opt ansi We would need this line if we were using ANSI, ANSI-40, VT102, or VT52 for terminal emulation. It specifies a special conversion for uppercase characters in the text we search for. Now, let's have our script monitor the incoming text for the four strings we identified above. In a Novaterm script, we may specify up to six strings to search for at one time, and then we put the script into a loop that enters terminal mode and waits until one of those strings is detected. To set up our four search strings, we use the check script command. The next four lines of our script are: check 1 "Your Selection ==>" check 2 "login:" check 3 "Password:" check 4 "Command?" The check command takes two arguments. The first is a number between one and six; this identifies an index number for the string. The second argument is the string itself. You must put quotation marks around the string to identify it. The above four commands merely set up our search strings. Now, we must put Novaterm into a loop and wait for the first occurrence of one of the strings. To do this, the following line of the script must be: wait The wait command puts Novaterm into terminal mode. Novaterm displays incoming text until one of the search strings is detected. The script will not continue beyond this line until one of the strings is found. When one of the strings is found, the script continues on to the next line. Therefore, our next few lines must figure out which of the strings was detected, and respond to it appropriately. First, let's check to see if the string Your Selection ==> was found: if check 1 then output "1^m" There's a lot to this statement, so let's look at it in pieces. The if command is a conditional statement. It checks to see if the specified condition is true, and if it is, the command following the word then is executed. If the condition is false, the command following then is not executed, and the script continues on to the next line. In this case, the condition check 1 is telling Novaterm to check if string number 1 (Your Selection ==>) was detected. If it was, the script should execute the command: output "1^m" The output command simply sends the specified string (which must be surrounded by quotation marks) to the modem. In this case, the string consists of the character 1 and a RETURN. (The sequence ^m represents the equivalent of the RETURN key, or CTRL-M. This notation is identical to the way control characters may be embedded in function key definitions. See 3.1.4, Function keys for a detailed explanation of this.) Now, since we don't know which string was detected by the wait command, we must include conditions for the other two strings: if check 2 then output "voyager^m" if check 3 then macro 1 if check 4 then end After the wait command exits, if the detected string was not string #1, the script falls through to the above statements. If the detected string was string #2, the login prompt, the script responds with our login name, followed by a RETURN. If the detected string was string #3, the password prompt, the script executes the macro command. The macro command outputs the contents of the specified function key, as it is defined in the Edit Function Keys menu. The command macro 1 outputs the contents of function key #1, or F1. Remember that the F1 macro key is automatically defined with the password of the on-line service during the dialing process. If we have our password specified in the dialing entry for Eskimo North, then macro 1 will output that password. If the detected string was string #4, the script executes the end command, which ends the script. The last line of our script must re-enter the loop to search for the remaining strings if the fourth string was not found. To do this, we will first modify the line with the wait command to read: loop wait The word loop is not a script command; it is a label that functions as a placeholder at a certain line in the script. We can now use the label loop in our last line: jump loop The jump command tells the script to continue execution at the line identified by the label loop. In our script, this command jumps back to the wait command, continuing the search process. Note that if string #4 is detected, the script ends (by way of the previous line, if check 4 then end) before it can get to the jump command. Let's do one more thing. Suppose we want to make sure Eskimo North is going to respond to us after we connect. Sometimes, you have to press the RETURN key a couple of times to get an on-line service to respond. To cover this contingency, we insert the following line at the beginning of our script: output "^m" This sends a carriage return before doing anything else. Let's list out the entire script: START OF SCRIPT ; Novaterm 9.6 auto-login script for Eskimo North ; (comments may be inserted in the script by placing a semicolon ; before them) .opt ansi ; set ANSI strings output "^m" ; force Eskimo North to respond check 1 "Your Selection ==>" ; set up four strings check 2 "login:" check 3 "Password:" check 4 "Command?" loop wait ; wait in terminal mode if check 1 then output "1^m" ; respond to "Selection" if check 2 then output "voyager^m" ; respond with user name if check 3 then macro 1 ; respond with password if check 4 then end ; exit if "Command?" found, jump loop ; otherwise continue searching END OF SCRIPT 6.1.2 Typing in the script Now that we know our script line by line, we can type it in and compile it. To do this, we'll run the Text Editor program by selecting Text editor from Novaterm's Utility Modules menu. If you are unfamiliar with how the text editor works, see Appendix A, Text Editor for a description. First, we'll type in the script just as it appears above. It's very important that you use lowercase letters for all of the script commands. Strings that are enclosed in quotes (such as the search strings) may contain both upper and lowercase letters. (To save time in typing the script, you may leave out all of the comments.) Now, we'll save the script we just typed to a text file so we can look at or change it later. Use the CTRL-S command, and choose a file name. This script could be called eskimo.ss. I use the extension .ss to denote script source files (the "ss" stands for "script source"). It's important to understand that the file you just saved is the "source code" for the script, not the actual script that Novaterm can execute. To convert this source code into a form that Novaterm can recognize, we must first "compile" the script. This conversion process, or compilation, is built into the Text Editor. To do this, press RUN/STOP in the Text Editor (it won't break out of the program!). The Text Editor compiles the script quickly, and asks you for a file name for the compiled script. The compiled script could be called eskimo.sc. I use the extension .sc to denote executable scripts (the "sc" stands for "script compiled"). 6.1.3 Executing the script Since this is a script that must be executed after we are connected to Eskimo North (after all, checking for the login: prompt won't do much good if we aren't connected), we want to specify this script as the "Connect script" for Eskimo North. If you edit the dial entry for Eskimo North from the dialing directory menu, you'll see an item for specifying the Connect script. Select this item, and type in the name of the compiled script, eskimo.sc. Now, when we dial Eskimo North from the dialing directory, our new script is executed immediately after the connection is established. If all goes well, you'll see Novaterm automatically respond to each of the prompts we identified. 6.1.4 A slight variation In the above example, we had to dial Eskimo North ourselves from the dialing directory to execute our script. Suppose now we want our script to do the dialing for us. We can insert the following line at the beginning of our script (after the .opt ansi command): dial "Eskimo North" The dial command searches our dialing directory for Eskimo North and dials it. The rest of the script continues after the connection is made. Now, instead of putting our script in the Connect script field for Eskimo North, we can execute the script directly. Press C= G in Terminal Mode, and type in the name of the script, eskimo.sc. The script will now take care of the dialing for us. 6.1.5 Starting Novaterm with the script Suppose we use this script so often that we would like to have it execute automatically when we start up Novaterm. Each time we load up Novaterm, the script would automatically dial Eskimo North and log us in, without any help from us! To do this, select Configuration from the main menu, press the cursor-right key, and then select Startup script. Type in the name of the script, eskimo.sc. Then, save your configration file by selecting Save configuration so that the script will be executed the next time Novaterm is started. 6.2 Script commands by category Listed below is the entire set of Novaterm script commands. Remember that the commands must be typed in lowercase! If script commands are typed in uppercase, they will not compile correctly. Any arguments that go along with a command are placed next to it. Numeric arguments are given in brackets [ ], and string arguments are in quotes " ". Optional arguments are given inside < and > symbols. The description of the argument is in lowercase. 6.2.1 Modem and screen input/output check [string number] "string" Works in conjunction with the wait command to detect incoming strings. For example, check 2 "Password" defines string number 2 as Password. Up to 6 strings may be defined. When the script encounters a WAIT command, it goes to terminal mode and wait until one of these defined strings is received. The ordering of these commands in a script should be as follows: check 1 "Username" check 2 "Password" wait if check 1 then output"My name^M" if check 2 then output"My password^M" Set up the strings with a series of check commands, and then execute the wait command to go into terminal mode and begin looking for those strings. When one of the strings is detected, the wait command ends, and the script must determine which string was received with an if/then statement. Strings defined with the check command are case sensitive, so you must include capital letters where necessary. If a received string pattern matches more than one string specified by check commands, the lowest number is returned. For example, if string 1 is `>` and string 2 is Lobby>, and the string Lobby> is received, the script recognizes string 1 because it is a lower string number, even though both strings match the received data. download "filename,type" Downloads the specified file using the installed protocol. The one-letter type specification is optional. If used, it must be either a p, s, or u for prg, seq, or usr file types, respectively. For batch protocols, the file name specified here is ignored, but be sure to at least put a pair of quotation marks to force the command to compile. hangup Hangs up the phone. minit Initializes the modem if no carrier is present. macro [function key number] Sends a function key string. This is equivalent to manually pressing one of the 16 function keys. offhook Takes the phone off the hook. output "string" Outputs a string to the modem. Control characters are entered as they are in macro keys, with a caret ^ preceding the corresponding letter. For example, a carriage return (CTRL-M) would be entered as ^M. screen "string" Prints a text message on the screen. send "filename" Sends an ASCII file to the modem (equivalent to Textfile to modem on the Disk menu). uncheck [string number] Clears the string in the specified string number. For example, if the command check 2 "Password" were previously executed, uncheck 2 gets rid of the definition for string #2. upload "filename" Uploads a file using the installed protocol. wait Goes into terminal mode and receives data (and prints it to the screen) while waiting for the strings specified with the check command. When one of the strings is found, Novaterm stops waiting and continues with the script. 6.2.2 Dialing dial "entry name" Dials the entry with the given name. The autodialer keeps redialing until either a carrier is found or the redial count is exhausted (see redial). dial# "phone number" Dials the phone number specified. dialn [location in phone list] Dials the entry in the phone list corresponding to the specified number. The numbers don't show up on the autodial menu, but, for example, the command dialn 3 would dial the third entry from the top. redial [number of tries] Sets the number of times to redial a number before quitting. If a number is dialed this many times without finding a carrier, Novaterm aborts the script. 6.2.3 Communication parameters baud [baud rate] Changes the baud rate to the specified number. If the baud rate given is greater than the maximum baud rate allowed by the modem and serial drivers, the maximum baud rate is used instead. param "setting" Changes the current word length and parity setting. Valid arguments for the setting are: param "8n1"8 bits, no parity param "7e1"7 bits, even parity param "7o1"7 bits, odd parity 6.2.4 Buffer commands buffer <"filename"> The following commands are valid with BUFFER: buffer closeCloses a capture file. buffer kill "filename"Deletes a file from the buffer. buffer load "filename"Loads a file from disk into the buffer. buffer open "filename"Opens a capture file. buffer print "filename"Outputs a buffer file to the printer. buffer save "filename"Saves a buffer file to disk. buffer send "filename"Sends a buffer file to the modem. 6.2.5 Installing drivers For commands which install drivers, omit the prefix from the file name. (For example, the command prot"Xmodem" would work, but prot"prt.Xmodem" would not.) asc "ASCII table"Loads the specified ASCII translation table. font "font file"Loads a font. font80 "font file"Loads an 80-column font. modem "modem type"Loads a modem driver. prot "protocol"Loads a protocol. term "terminal emulator" Loads a terminal emulator driver. Note that this only loads the term file specified, not the asc and font80 files associated with it. go40 Changes to 40-column mode, if the installed terminal emulator allows it. (If ANSI, VT102, or VT52 is installed, this will have no effect.) go80 Changes to 80 column mode. 6.2.6 Disk operations disk [device number] Changes the current disk device to the specified device number. If the device is not present, the script halts with an error. diskc "disk command" Sends the specified disk command to the current disk device. The extra disk commands added by Novaterm are also valid here. drive [drive number] Changes the current drive number (not device number). print "filename" Sends a disk file to the printer. If the printer is not turned on or connected, the script aborts. printer [device number] Changes the printer device to the specified number. If the device is not present, the script aborts with an error. secaddr [secondary address] Changes the printer secondary address. 6.2.7 Script program control end Terminates the script program. if (condition) then (command) Used to test various conditions. Any one of the conditions below may be substituted into the command, and if the condition is true, the command after then is executed. Any command may be put after then. if carrierChecks for a carrier. if check [string#]Checks to see if the specified string number was received. There must be a number after check, or the command is invalid. if receiveChecks to see if data is being received. if ringChecks to see if the phone is ringing. jump label Jumps to the specified label in the program. Labels are non-command words which are placed before commands to identify a location in the script. For example: loop check 1 "Username:" .. .. jump loop Another example: carchk if no carrier then jump carchk Labels may contain any characters other than quotes, but a label may only be one word. link "script program" Loads and executes a new script program. Execution does not return to the current script. .opt (parameter) Changes a compiler option. These commands are not included in the program when it is compiled. Instead, they direct the compiler to take certain actions or set flags. The only parameters currently supported are: .opt ansiConverts uppercase characters in all following check strings to uppercase characters with lower ASCII values. This command is necessary if the script will run in ANSI, VT52, or VT102 mode. .opt noansiDo not convert uppercase characters. This is the default. 6.2.8 Time commands gettime Attempts to read the current time from the real-time clock device (see 1.1.10, Selecting a real-time clock device). If the clock device selected is Manual, this command requests the user to input the current time. If your script program uses the until command to wait for a certain time of day, you should include this command at the start of your program to make sure the clock is set correctly. pause [number of seconds] Pauses the program for a specified number of seconds. until "24-hour time" Pauses execution of the script until the system clock reaches the specified time. The time must be in 24-hour form. For example: until "22:35"waits until 10:35 PM until "11:50:25"waits until 11:50 AM and 25 seconds ___________________________________________________________ Contents | Introduction | Getting Started | Getting Familiar | On-line Activities | Configuration | Disk Utilities | Scripts | Utility Modules | Appendices