Icon The Kermit Project   |   Now hosted by Panix.com
New York City USA   •   kermit@kermitproject.org
…since 1981
Home C-Kermit E-Kermit Kermit 95 Scripts Timeline About Archive
Translations  (see below for credits):
Belarusian | Беларуская French | Français German | Deutsch Italian | Italiano Polish | Polski Russian | Русский Spanish | Español Ukrainian | Українська
C-Kermit / Kermit 95 Scripting Tutorial and Library
New York City
Most recent update: Fri Feb 23 14:35:57 2024

C-Kermit Tutorial   Kermit 95 Tutorial   See the scripts  ...  Built-in variables   Built-in functions

Contents

RECENT SCRIPTS (details below)

PREFACE

As I write this, fewer and fewer people know what Kermit is; if that applies to you, you can click here for an overview. Kermit's heyday was in the 1980s and 90s when almost everybody who used computers to communicate with other computers used Kermit as a terminal emulator and for file transfer. C-Kermit for Unix and VMS and MS-DOS Kermit for DOS were developed in tandem. As we started to add automation capabilities, the scripting language was common to both programs. When Kermit 95 for Windows came out, it had the same scripting language, since it is built upon C-Kermit.

At first the script language was targeted at communications and file-transfer tasks, but over time is has developed into a general-purpose programming language on a scale somewhere between shell scripts and Perl, with bits of Unix shell scripting, C, Bliss, Lisp, Snobol, Algol, and PL/I mixed in, with loops, variables, arrays, functions, artithmetic, associative arrays, recursion, boolean logic, string manipulation, file i/o and management, pattern matching, list processing, and so on.

Today you can write Kermit script programs to do almost anything, no matter whether it involves communication or not (and if it does involve communication, it can be over serial connections, clear-text network connections, or secure network connections). Kermit's main uses now are system and website administration and website development, and you can see a lot of examples of production scripts in these areas below.

Speaking for myself, having programmed since the mid-1960s, I have been fluent in a lot of programming languages, and I wish that all of them except C had not died out (PL/I, Snobol, and Mainsail are sorely missed; they were powerful, stable, consistent, and well documented). Today's choices (C, shell scripts, etc) are moving targets; programs written in these language do not stay written; they decay over time as the languages and associated libraries and utilities are constantly redefined. That's why now I write all my programs (except C-Kermit itself of course) in Kermit language... Because the language itself does not change in backwards-incompatible ways so that "old" scripts never need to be "upgraded", they just keep working, even as new versions of Kermit itself are released. And also because whenever there is a bug in the language I can fix it myself, and when there is something I need to do that is not in the language, I can add it myself. Always in a backwards-compatible way.

As yet there is no coherent manual for the Kermit language. Everything is documented somewhere, but it's scattered over books (which are now online) and a series of web pages. In July 2019, I put together a comprehensive guide to all the information. It's like a Table of Contents; HERE IT IS. Meanwhile this page (the one you are reading) is a pretty good place to start: Find a script that does something similar to what you want to do and use it as guide. And when you see a command or function you don't understand, use C-Kermit's built-in HELP command to find out about it:

help ?
Shows the help topics

help command
Gives information about the given command

help set command
Gives information about the given SET command

help function name
Gives information about the given built-in function.
Also use the Google Search dialog on the home page, and try out the new "Table of Contents".

—Frank da Cruz, May Day 2017, updated 29 August 2019.

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.

Kermit software first appeared in 1981 for CP/M microcomputers and DECSYSTEM-20 and IBM mainframes. And shortly afterwards for IBM (and other) PCs with MS-DOS, and afterwards for more and more distinct computing platforms, notably Unix and Microsoft Windows. The command language, syntax, and (in most cases) command editing and assistance were adapted from the TOPS-20 EXEC, that is, the user interface (or "shell" in modern parlance) of the DECSYSTEM-20, which was the primary platform for academic computing at Columbia from 1977 to 1988. Notable features include per-field help upon '?', keyword and filename completion upon Tab or Esc, and built-in help. Programming capabilities were added to the command language beginning with C-Kermit 5A(190) for Unix, VMS, AOS/VS, Plan 9 (etc), and MS-DOS Kermit, and have been improved and expanded since then. A unique feature of Kermit scripting is that it is portable not only among different computing platforms (such as Unix and Windows) but also different communication methods (Telnet, FTP, secure Telnet, secure FTP, SSH, SSL, Kerberos IV/V, more than 100 different kinds of modems, and direct serial-port).

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: On Unix-based operating systems, 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/etc, 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.

The scripts in this page are for illustrative purposes only and carry no warranty, express or implied.

Top

SCRIPT FOR DOWNLOADING SCRIPTS

As of January 2014 a new script is available that simplifies the downloading of scripts from the Kermit Script Library and their installation on your own computer. It is called getkermitscript, CLICK HERE to see it (and download it). You can use this script on a Unix-based computer that has C-Kermit 8.0 or later installed to download and install Kermit scripts from here in one simple command such as ”getkermitscript photogallery.ksc”. Some things to bear in mind:

CLICK HERE for complete instructions.

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/7/8/10, 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, Version 8.0, and Version 9.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 with IF SUCCESS or IF FAILURE based on this code. If a string is included, 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 ] ]
Stops the script and exits 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.
  (CLICK HERE for a more detailed explanation of this notation.)

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

Recent Additions

FTP Scripts:

As of 2022, these are no longer useful in most cases, as FTP protocol and servers have been purged from the Internet.

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:

C-Kermit Initialization Files

Kermit Protocol Augmentation:

Key Maps:

HTML Scripts

Object-Oriented Programming:

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

Script-Language Torture Tests:

Top

Links:

  Translations of this page courtesy of...

Language Link Date Translator Organization
Belarusian Беларуская 2023/08/22 Vladyslav Byshuk | Владислав Бишук studycrumb.com
French Français 2023/08/25 Kerstin Schmidt Admission-Writer
German Deutsch 2023/08/25 Kerstin Schmidt Pro-Academic-Writers
Italian Italiano 2024/02/19 Priscilla Speranza Istruzione Messina
Polish Polski 2023/08/25 Kerstin Schmidt WriteMyEssay4Me
Russian Русский 2023/08/22 Vladyslav Byshuk | Владислав Бишук skyclinic.ua
Spanish Español 2024/01/03 Marglin Araujo chicksgold.com
Ukrainian Українська 2023/08/22 Vladyslav Byshuk | Владислав Бишук studybounty.com

Top

The Kermit Project hosted by Panix.com / kermit@kermitproject.org / 23 February 2024