The Columbia Crown The Kermit Project | Columbia University
612 West 115th Street, New York NY 10025 USA • kermit@columbia.edu
…since 1981
Home Kermit 95 C-Kermit Scripts Current New FAQ Support
C-Kermit / Kermit 95 Scripting Tutorial and Library
New York City
Most recent update: Thu Sep 29 16:25:41 2011

The Kermit Project at Columbia University is cancelled effective 1 July 2011

The Columbia University Kermit Project website is frozen effective 1 October 2011, but remains available as a public resource. A new Kermit Project website has been established outside of Columbia at www.kermitproject.org for the continued development of C-Kermit, E-Kermit, and Kermit 95.
New Kermit Project website   New Kermit Script Library

C-Kermit Tutorial   Kermit 95 Tutorial   FTP Scripting Tutorial

Contents

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, the C-Kermit 8.0 Supplement, and the C-Kermit 9.0 Supplement. You can also get overviews and tutorials HERE for Kermit in general and HERE for Kermit 95 in particular.

This page offers a brief introduction to Kermit scripting, and a library of sample Kermit scripts, 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 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.

WARNING: The script file must be in Unix text format for the Kerbang mechanism to work. That is, lines must be terminated and separated only by linefeed, not carriage return and linefeed (as would happen, for example, if you uploaded the file from Windows in binary mode rather than text mode). If the Kerbang line ends with CR and LF, the Unix shell will think the CR is part of the filename if no '+' is included, and will fail to find "a valid interpreter" (i.e. Kermit) for the script. If a + sign is included, the CR might prevent Kermit from recognizing it. These are characteristics of the Unix shell, and apply to shell scripts, Perl scripts, and any other kind of script that uses the "shebang" convention for invoking the appropriate interpreter. To strip carriage returns use the following Unix shell commands: 

  tr -d '\015' < scriptfilename > newfilename
  mv newfilename scriptfilename

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 the variables \%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.

Top

SCRIPTING TUTORIAL

The Kermit scripting language is a programming language similar to Perl, but with different syntax (because the Kermit language predates Perl and many 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 (clear text or secure). 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, but of course many improvements have been made since the book was published, which are explained in the updates for Version 7.0 and Version 8.0, and illustrated by sample scripts listed below.

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 (SSH, 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, or RLOGIN, or SSH), 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. Use this instead of TELNET, CONNECT, SSH, or other command that would enter the terminal screen. Synonym: OPEN HOST (which might be more evocative of the action performed).

For serial or modem connections, use:

SET MODEM TYPE [ name-of-modem or NONE ]
SET LINE device-name
SET SPEED interface-speed
[ DIAL phone-number ]
Open a direct or dialed serial connection but remain in command mode. Note that when the DIAL command is executed from a command file or macro, it does not automatically enter CONNECT mode.

Kermit's DIAL command places the call by sending the appropriate commands to the modem, normally AT commands, and reading the responses. The SET MODEM TYPE command, which must be given prior to the DIAL command, tells Kermit which kind of modem it is so it knows the specific command set to use. In C-Kermit and Kermit 95, it is normally not necessary to script the dialog with the modem; all that is already built into Kermit. For more information, see the manual or type HELP DIAL, HELP SET DIAL, and HELP SET MODEM.

If, however, you have a need to script such a dialog – e.g. to send alphanumeric pages or SMS messages – you can do so. The trick is that before executing the first INPUT or OUTPUT command (explained below), you must tell Kermit to SET CARRIER-WATCH OFF. Example: 

SET MODEM TYPE NONE
SET LINE /dev/ttyS0
IF FAIL EXIT 1 "Device not available"
SET SPEED 57600
SET FLOW-CONTROL RTS/CTS
SET CARRIER-WATCH OFF
OUTPUT AT\13
INPUT 3 OK

Type HELP SET CARRIER-WATCH for a brief explanation.

Once the connection is open, use the following commands to simulate what you would do interactively:

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". The command can be a list of commands enclosed in braces, and the IF statement can also have an ELSE part, which can also be a single command or a list of commands.

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, listed HERE and 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 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, "help func xxx" for details of function xxx)
  \x0F          A character whose code is the given hexadecimal number (00-ff)
  \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:

Top   Contents   C-Kermit   Kermit 95   Kermit Home

THE KERMIT SCRIPT LIBRARY

Note: As of 8 December 2010, script links are HTTP rather than FTP.

New Additions

C-Kermit Initialization Files

Kermit Protocol Augmentation:

Key Maps:

HTML Scripts

FTP Scripts:

Other Internet Scripts:

Logging 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:

(And other creative programming techniques.) This section by Dat Thuc Nguyen.

Script-Language Torture Tests:

Top

Links:

Top

C-Kermit/K95 Script Library / The Kermit Project" / Columbia University