C-Kermit / Kermit 95 Scripts Library Most recent update: Sat Oct 19 13:44:27 2002 NOTE: This is a plain-text dump of the web page: http://www.columbia.edu/kermit/ckscripts.html at the Kermit Project website. Most of the sample scripts described here are included on the CDROM but many of them have their name shortened to fit ISO 9660 CD-format rules, and have .KSD (Kermit SCript) added as a filetype. CONTENTS * Introduction * Tutorial * C-Kermit Initialization Files * Internet Scripts * Modem Scripts * Pager Scripts * Screen-Formatting Scripts * Screen-Scraping Scripts * File-Transfer Scripts * File-Management Scripts * Number-Crunching Scripts * Date-Time Arithmetic * Object-Oriented Programming * Script-Language Torture Tests INTRODUCTION The command and script language of C-Kermit and Kermit 95 is described in Using C-Kermit, 2nd Edition, as supplemented by the C-Kermit 7.0 Supplement and the C-Kermit 8.0 Supplement. Most of these scripts are intended to illustrate new features of C-Kermit 7.0 (released 8 Feb 2000), C-Kermit 8.0 (released 12 Dec 2001), K95 1.1.20 (March 2000) and K95 2.0 (June 2002). The scripts are listed below. Those marked with (*) are "kerbang" scripts which, in UNIX, can be used exactly like shell scripts if you give them execute permission: chmod +x scriptname Command-line arguments are accepted in the expected manner, e.g.: autotelnet xyz.com myuserid This makes the the command-line arguments available to the script in the variables \%0 (script name), \%1 (first argument), \%2 (second argument), etc. The first line of each kerbang script looks like: #!/usr/local/bin/wermit + (but without the indentation). This indicates the pathname of the C-Kermit executable that is to execute the script; change this line as needed. The trailing plus sign is required if command-line arguments are to be passed to the script (and doesn't hurt if they are not). The "kerbang" feature requires C-Kermit 7.0 or later. For more about kerbang scripts, see the C-Kermit 7.0 Supplement Section on this topic. On non-UNIX platforms, these scripts are executed by: 1. Giving a TAKE filename command to Kermit. In C-Kermit 7.0 and later, the filename can be followed by arguments, which are assigned to to the varables \%1, \%2, ..., \%9. 2. Including the script filename as the first command-line argument to the Kermit program, followed by a plus sign, followed by the arguments. In VMS and Windows, the plus sign seems to cause trouble with the shell, so in that case you can substitute an equal sign, but put it after the script file name instead of before it: kermit script.ksc = arg1 arg2 arg3 ... (VMS) k95 script.ksc = arg1 arg2 arg3 ... (Windows) This assigns arg1 to \%1, arg2 to \%2, and so on. 3. In Windows 95/98/ME/NT/2000/XP, by filetype association (when the script filename has the suffix ".ksc"), but in this case Windows does not provide a mechanism to pass arguments to the script. Outside of UNIX, the "kerbang" line has no effect, since it is a comment to Kermit. In VMS, any references to "environment variables" can be satisfied by logical names or DCL symbols. These scripts are for illustrative purposes only and carry no warranty, express or implied. TUTORIAL The Kermit scripting language is a programming language similar to Perl, but with different syntax (because the Kermit language predates Perl and most other scripting languages). The Kermit language is portable across UNIX (Linux, AIX, HP-UX, Solaris, FreeBSD, IRIX, SINIX, QNX, SCO, Tru64, and every other known UNIX variation), VMS, Stratus VOS, Data General AOS/VS, Windows 95/98/ME/NT/2000/XP, OS/2, Plan 9, OS-9/68000, the Commodore Amiga, and other platforms, and works uniformly on serial connections (direct or dialed) and network connections. Thus learning the language is a good investment of your time since it can be applied to almost any communications problem. The Kermit script language is documented in the book Using C-Kermit. The Kermit scripting language is easy to learn if you already use Kermit, since it is the same as Kermit's command language. A Kermit script program is simply a series of Kermit commands collected into a file or a macro. To execute the script, you tell Kermit to TAKE the file or DO the macro. Or in UNIX you can also execute it as if it was a shell script, as described at the top of this page. In either case you can pass parameters to the script in the command that invokes it. When using Kermit "manually", i.e. interacting with the host directly, you typically make a connection (TELNET, DIAL, etc), and then interact with the other computer directly, switching back and forth between the Kermit command screen and the terminal screen. The command to switch from the command screen to the terminal screen is CONNECT (C is a sufficient abbreviation). Returning from the terminal screen to the command screen requires a special "escape sequence" such as Ctrl-\C, Ctrl-]C, or Alt-x (Alt-x is used in Kermit 95 and MS-DOS Kermit). Note that Kermit's TELNET command is a shortcut for SET HOST followed by CONNECT; that is, TELNET includes an implied CONNECT command. When automating a session, you do not switch back and forth between "screens"; you do not CONNECT or escape back. In a script, everything is done in command mode. There is no terminal screen in a script. Instead of CONNECT (or TELNET), use the following commands, which tell Kermit to do what you would do "by hand": SET HOST [ switches ] hostname-or-address [ switches ] Open a network connection but remain in command mode, i.e. without entering the Terminal screen or CONNECT mode. INPUT timeout string Wait up to timeout seconds for the given string to arrive from the other computer. If it arrives, this command succeeds; otherwise the command fails. Example: INPUT 10 login: The INPUT command can accept not only simple strings but also patterns. An alternative form, MINPUT, accepts a list of match strings and/or patterns. SET INPUT ECHO ON Normally you don't see scripted dialogs on your screen. Use this command to let you see the what Kermit and the host are saying to each other. This doesn't affect the operation of the script, only what you can see. IF FAILURE command If the preceding command (SET HOST, INPUT, or any other command) failed, execute the given command. Example: IF FAIL EXIT 1 No login prompt IF SUCCESS command If the preceding command succeeded, execute the given command. STOP number string Stop the script and return to the Kermit prompt. The number is a success code: 0 for success, nonzero for failure; the command that invoked the current command file (TAKE) or macro (DO or "implied DO") can be tested for success or failure based on this code. If a message is given, it is printed. END number string Like STOP, but pops the command stack just one level instead of all the way back to the top. Use this for returning early from a macro or command file to its caller. Synonym: POP. EXIT number string Stop the script and exit from Kermit. The number is Kermit's exit status code, normally 0 for success, nonzero for failure. If a message is given, it is printed. OUTPUT string Send the given string to the other computer. Control characters may be included in the string using \ddd notation (where the d's are digits, and ddd represents the numeric code for the control character. Example: OUTPUT olga\13 LINEOUT string (C-Kermit 7.0 and later; Kermit 95 1.1.20 and later) Since it is so common to output a line with a carriage return on the end, this command does it for you, so you don't have to remember to include \13 on the end. lineout foo is equivalent to output foo\13. INPUT takes the place of your eyes, OUTPUT takes the place of your fingers, and IF takes the place of your brain. The rest is regular programming: FOR, WHILE, SWITCH, GOTO, variables, arrays, functions, block structure, nesting, scoping, and the rest, documented in the manual (just as any other programming language is documented in its own manual). Here is a very simple example of making a Telnet connection to UNIX and logging in: set host foo.bar.baz.com ; Make the connection if fail stop 1 Connection failed ; Check that it was made input 20 login: ; Wait 20 seconds for login: prompt if fail stop 1 No login prompt ; Check that it came output myuserid\13 ; or "lineout myuserid" input 5 Password: ; Wait 5 seconds for Password: prompt if fail stop 1 No Password prompt ; Check that it came output mypassword\13 ; or "lineout mypassword" This illustrates how your actions in the terminal screen are simulated by INPUT (eyes), OUTPUT (fingers), and IF (brain). It can be elaborated to any desired degree: to use variables instead of constants for host, username, or password; to prompt for the password so you don't have to store it in a file; to attempt some sort of recovery action if a command fails instead of just stopping, and so on. And of course you can add more steps -- have it transfer a file, send email, whatever you want. The syntax of the Kermit programming language should be familiar to anyone who uses other scripting languages such as Perl or the UNIX shell. It is a string substitution language, therefore an "escape character" (backslash) is used to indicate string substitution. Since many kinds of items can be substituted, the backslash is followed by a second character to indicate which kind of substitution is to be made: a scalar variable, an array element, a function result, a special character, and so forth. Examples: \%a A scalar user-defined variable, evaluated recursively \m(name) A scalar user-defined variable, evaluated one level deep \v(name) A built-in variable (such as \v(time), "show var" for a list) \&a[1] An array element, evaluated recursively \fname(args) A function invocation ("show func" for a list) \x0F A character whose code is the given hexadecimal number (0-255) \123 A character whose code is the given decimal number (0-255) \\ A literal backslash. This should give you an idea how to read the scripts in the library, and how to write a simple script or adapt one of them to your needs. For a brief description of a particular Kermit command or function, use Kermit's HELP command. For a description of a built-in function, type "help function xxx" at the prompt, where xxx is the function name. For a thorough treatment, please consult the manual. Finally, remember: * Do not put a CONNECT command in a script unless you really want to suspend execution of the script and turn manual control over to the user. * TELNET host is a shortcut for SET HOST host, IF SUCCESS CONNECT. Since TELNET includes an implied CONNECT command, don't put a TELNET command in your script unless you really want to suspend execution of the script and turn manual control over to the user. * For more examples, you can look through the C-Kermit case studies. C-Kermit Initialization Files * .kermrc The standard C-Kermit initialization file, slightly updated for version 7.0. C-Kermit 6.0 or later required. Includes definitions for the services directory with automatic login macros for various platforms and communication methods. * .mykermrc Sample C-Kermit customization file. C-Kermit 6.0 or later required. Internet Scripts: * Introduction to FTP Scripting How to automate FTP sessions with C-Kermit 8.0 and Kermit 95 1.1.21 or 2.0. * ibm_infoexchange Makes a secure FTP connection to IBM InfoExchange. A secure version of Kermit 95 1.1.21 or 2.0 or C-Kermit 8.0 (or later) is required. * ftprename Multiple Rename: Shows how to rename a list of files on an FTP server. Requires Kermit 95 1.1.21 or 2.0 or C-Kermit 8.0 (or later). * usend Shows how to send a file to an FTP server with a guaranteed unique name, even if the server does not support STOU. Requires Kermit 95 1.1.21 or 2.0 or C-Kermit 8.0 (or later). * rawhide Daily download of new RPMs from Red Hat Linux Rawhide server. Kermit 95 1.1.21 or 2.0 or C-Kermit 8.0 (or later). * skermit (*) Client for a C-Kermit file transfer and management SSH Subsystem: a more powerful, friendlier, scriptable alternative to SFTP. CLICK HERE for documentation. C-Kermit 8.0.201 or K95 1.1.21 or 2.0 required. * autossh (*) Conducts an automated SSH session. C-Kermit 8.0 or K95 2.0 or later required. * autotelnet (*) Makes an automated Telnet connection. C-Kermit 7.0 or K95 1.1.19 or later required. * autotelnet6 (*) Makes an automated Telnet connection. Same as "autotelnet" but does not use any new features of C-Kermit 7.0. C-Kermit 6.0 or K95 1.1.13 or later required. * portlog (Intrusion Detection) Harmlessly absorbs and logs attacks on TCP Port 80, such as Code Red and Nimba. Resets itself every hour, at which time it also (a) uploads the hour's log to a selected FTP site; (b) e-mails a summary to a selected address. It can listen on TCP Port 80 or any other desired TCP port. Works nicely on Port 80 with Code Red, Code Red II, and Nimda. Requires: C-Kermit 8.0. * pop3 (*) Retrieves e-mail from a POP3 server. C-Kermit 7.0 required. By Mark Sapiro. * netedit Edits a remote file using your local computer's editor. C-Kermit 7.0 or K95 1.1.19 required. * iksget (*) Gets a file or files from an Internet Kermit Server. C-Kermit 7.0 required. No scripts needed in C-Kermit 8.0 or K95 1.1.21 or 2.0, which support kermit:// URLs on the command line (FTP, HTTP, and Telnet URLs too). * iksdpy (*) The Internet Kermit Service Daemon realtime display monitor. C-Kermit 7.0 or K95 1.1.21 or 2.0 required. * timestamp (*) Adds timestamps to Telnet-based system log display. C-Kermit 7.0 or K95 1.1.19 required. Note: C-Kermit 8.0 and Kermit 95 1.1.21 and 2.0 have a built-in option for timestamped session logs. * linksys (*) Used with a Linksys Ethernet Cable/DSL Router to retrieve the IP address for use with Kerberos 5 authentication when Network Address Translation (NAT) is enabled. C-Kermit 8.0 required. Modem Scripts: * getline (*) Given a list of serial devices usable for dialing out, finds and assigns the first free one. C-Kermit 7.0 or K95 1.1.19 or later required. * mpservers Given a list of TCP/IP modem-pool servers, gathers a census of in-use and free ports by sending "finger" commands to them and accumulating the results, both per-server and per-phone-number, as well as cumulative. Runs in UNIX. C-Kermit 8.0 required. * callstats Given a list of modem pool phone numbers, makes repeated calls to each one and logs the results of each call (BUSY, CONNECT 48000, etc) by date and time in a format suitable for statistical analysis. Runs in UNIX, Windows 95/98/ME/NT/2000/XP, or VMS. C-Kermit 7.0 or K95 1.1.19 or later required. * modemtest2 (*) Given a list of modem pool phone numbers, makes repeated calls to each one; logs into a specified host, transfers files back and forth, and keeps a logfile of connection and performance statistics. Runs in UNIX, Windows 9x/ME/NT/2000/XP, or VMS. C-Kermit 8.0 or Kermit 95 1.1.21 or later required. CLICK HERE for an earlier version that works with C-Kermit 7.0 and K95 1.1.19. * dialout (*) Puts up a form for the user to fill out to select modem type, port, speed, and phone number, and then dials upon user command. C-Kermit 7.0 or K95 1.1.19 or later required. Note: This is also a screen-formatting script. * callbycall A dialing script that selects the most appropriate long-distance provider by time of day, and that also cycles through providers upon busy signals (in case the provider itself is busy, rather than the destination number). For use with SET DIAL MACRO. By Peter Eichhorn, Assyst GmbH, München. C-Kermit 7.0 or K95 1.1.19 required. Pager Scripts: * numpage (*) Script for beepers or numeric pagers. C-Kermit 7.0 or K95 1.1.19 or later required. * alphapage (*) TAP/IXO alphanumeric paging script. C-Kermit 7.0 or K95 1.1.19 or later required. * alphapage6 TAP/IXO alphanumeric paging script that can be used by C-Kermit 6.0 or K95 1.1.13 or later. Screen-Formatting Scripts: * bottom (*) A simple one-line script that uses C-Kermit to put the cursor on the bottom line of your screen. C-Kermit 7.0 or K95 1.1.19 required. * menu (*) Skeleton of a menu application. C-Kermit 7.0 or K95 1.1.19 required. * Also see the dialout script, which uses screen-drawing techniques. Screen-Scraping Scripts: * scrape In Kermit 95, scripts can interact with the terminal emulator to retrieve strings from specified locations on the terminal screen, similar to HLLAPI. In this script, screen forms are parsed to select and retrieve images from a database on the host computer. By Max Evarts. K95 1.1.17 or later required. File-Transfer Scripts: * deliver (*) A script that delivers the specified file or files to their destination, even if the connection is broken in mid-transfer. C-Kermit 6.0 or K95 1.1.8 or later required. * synchronize (*) A script that synchronizes directory trees on two Internet hosts over a Telnet connection. Only the files that are newer on the source than at the destination are transferred. Directories are created automatically as needed at the destination. Files that disappeared from the source are deleted at the destination. Any mixture of text and binary files can be handled. The two hosts need not have the same operating system or file system. The destination host is contacted and logged in to automatically (so this is also an Internet script); thus the entire operation can run unattended. C-Kermit 7.0 or K95 1.1.19 required. File-Management Scripts: * concatenate Concatenates all the files in the current directory into one big file. Useful (e.g.) after downloading a bunch of EDI transaction files that need to be combined so the computer can process them all at once. * rgrep (*) Answers the frequently asked question: "Where is recursive grep?" Searches through files in a directory tree whose names match the given pattern and prints all lines in all files that match the given pattern. C-Kermit 7.0 or K95 1.1.19 required. Note: In C-Kermit 8.0, a script is no longer needed since GREP (including a recursive option) is a built-in command. * rename (*) A one-line analog to the UNIX shell "for i in *; do blah; done" loop. C-Kermit 7.0 or K95 1.1.19 required. * changetype (*) Elaboration of rename to general-purpose file-type changing script; old and new filetypes and file list are given as command-line arguments, e.g. "changetype hlp txt *" renames *.hlp files to *.txt. C-Kermit 7.0 or K95 1.1.19 required. * delete (*) Answers the Frequently Asked Question "How do I delete files more than 5 days old?". C-Kermit 7.0 or K95 1.1.19 required. * review (*) Review files interactively. Everything you ever wanted in a text-mode file browser. C-Kermit 7.0 or K95 1.1.19 required. * logrotate Rotates connection logs on a monthly basis. C-Kermit 7.0 or K95 1.1.19 required. * cleandups (*) A rather complex file-management application (used, in fact, to manage the update and installation of C-Kermit 7.0 Beta-test binaries on our ftp server). C-Kermit 7.0 required. * install (*) Moves new C-Kermit Beta-test binaries from a staging area to the ftp site, deleting corresponding binaries from previous Beta tests as it goes, so as not to fill up the ftp server disk. C-Kermit 7.0 required. * merge (*) Merges any number of presorted files together into a single output file. Illustrates C-Kermit 7.0's new file i/o package operating on multiple files at once. C-Kermit 7.0 required. * ftplog (*) Analyzes a file-transfer log in wu-ftpd format, which is also created by C-Kermit 7.0's SET TRANSACTION-LOG FTP format. Lists the five most popular files and also prints a histogram of file count per number of accesses. Illustrates associative arrays. C-Kermit 7.0 required. Number-Crunching Scripts: * statistics (*) Given a file in which each line contains a pair of numbers, X and Y, computes and prints the maximum, mininum, mean, variance, and standard deviation of the X's and Y's, and the correlation coefficient of X and Y. The numbers in file may (but need not) have decimal points and fractional parts. Illustrates the floating-point arithmetic functions introduced in C-Kermit 7.0. * xstats (*) Like statistics, except implemented (much more simply) using C-Kermit 8.0 S-Expressions. Date-Time Arithmetic: * easter (*) Calculates the date of Easter for any year between 1900 and 2099 using S-Expressions. Requires C-Kermit 7.0 or later or K95 1.1.20 or later. * calendar (*) Like Unix 'cal' - prints a calendar for any month in any year between 1859 and 9999. Requires C-Kermit 8.0 or later or K95 1.1.21 or later. * deleteold How to delete files that are older than a given age. Object-Oriented Programming: (And other creative programming techniques.) This section by Dat Thuc Nguyen. * income_tax Income tax calculation. Illustrates S-Expressions, floating-point arithmetic. C-Kermit 8.0 required. * hanoi Towers of Hanoi. Illustrates S-Expressions, recursion. C-Kermit 8.0 required. hanoi2 A faster version of Towers of Hanoi. Illustrates how to speed up recursive functions. C-Kermit 8.0 required. class Hosts object-oriented programming in C-Kermit 8.0, it uses some S-Expression features. C-Kermit 8.0 required. account An application demo that uses the same example that most Smalltalk dialects use as an introduction to object oriented programming. To run this demo: C-Kermit> take class C-Kermit> take account C-Kermit 8.0 required. * shortcircuit Short-circuit execution of macros in series (a) while all of them succeed, (b) until one of them succeeds. C-Kermit 7.0 or K95 1.1.19 required. * lispops This small package defines a series of LISP-like arithmetic operators for C-Kermit and Kermit 95. C-Kermit 7.0 or K95 1.1.19 required (obsoleted by the built-in LISP syntax of C-Kermit 8.0). * matrix The matrix is an essential element in many computing areas. C-Kermit and Kermit 95 can do matrix operations easily. This script creates two matrices, A and B, then computes their sum: matrix C. * noswitch "SWITCH Considered Harmful" * oop Object-oriented programming in C-Kermit and Kermit 95. Fun with dogs and cats. * complex Complex numbers are not a built-in type of many programming languages. Here OOP comes to rescue with the user-defined type. This script defines a complex number class in C-Kermit, offering the familiar C++ interface. C-Kermit 7.0 required. * wordcount (*) Word frequency counting is the Excel of scripting languages such as awk and Perl. With OOP, C-Kermit also handles the task comfortably. This script defines and uses the class Words to count the occurrences of unique words of a plain-text text file. The class Words shields implementation details and promotes reuse, the flagship of OOP. C-Kermit 7.0 required. * inheritance No object-oriented programming language leaves home without inheritance. This script displays inheritance in C-Kermit and Kermit 95. * multiple Multiple inheritance enriches software design. Not all OOP languages have it: C++ does; Java and Smalltalk don't. This script implements multiple inheritance in C-Kermit. The famous animal class found in many C++ and Smalltalk references is used to present the subject. * bag The container is a key concept in object-oriented programming. Smalltalk, C++, etc. have standard libraries of containers. This script defines the class 'bag' in C-Kermit/Kermit 95. Bag offers a rich usage interface. * string A rudimentary string class based on the Smalltalk model. * semaphore We use semaphores to coordinate computing tasks, share resources, etc. This script defines semaphore classes in both the Smalltalk and C++ styles. C-Kermit 6.0 / K95 1.1.17 required. * singleton In the patterns community, the singleton is a class that can have only one instance. All objects instantiated from that class refer to the one and only singleton! The singleton is very useful where there is only one resource available and various user-defined functions access that resource under different refferences. The singleton class ensures that one and only one object can be instantiated from it, though under different names. * state The finite state machine is a useful concept in many applications. This script suggests a framework for a state machine. Script-Language Torture Tests: * demo (*) An interactive "torture test" for C-Kermit's script language. C-Kermit 7.0 or K95 1.1.19 required. * iftest (*) Exerciser for compound Boolean expressions. C-Kermit 7.0 or K95 1.1.19 required. * functions (*) Function exerciser. C-Kermit 7.0 or K95 1.1.19 required. * localarray (*) Local array exerciser. C-Kermit 7.0 or K95 1.1.19 required. * dates Exerciser for date-time formats and arithmetic. C-Kermit 8.0.206 or K95 2.1 required. Links: * Kermit script portability reference * Kermit script library (top) * Kermit home page * C-Kermit * C-Kermit manual * C-Kermit 7.0 Update Notes * Kermit 95 Kermit Script Library / Columbia University / kermit@columbia.edu / (end)