PREFACE Most of this short introduction to C-Kermit is by Jack Rouse of the Software Distillery and SAS Institute. The current supporter of Amiga Kermit is Stephen Walton, reachable via email as "stephen.walton@csun.edu" on the Internet. INTRODUCTION This version of Amiga Kermit is a port of the Unix C-Kermit which attempts to reproduce as much of the functionality of Unix version as possible. I had two main goals in porting C-Kermit: I wanted a reliable remote file transfer utility, and I wanted to investigate the use of the AmigaDOS and Exec environments. Amiga Kermit currently provides a line oriented user interface. I currently have no specific plans to implement menuing, but there are several places in Kermit where a menu interface would be an asset. In this version of Kermit, I have concentrated on the functional aspects. As I have stated before, this is a port of the Unix C-Kermit. The definitive documentation is the book, "Using C Kermit," by Frank da Cruz and Christine Gianone. Therefore, only Amiga specific features are noted below. INVOKING C-KERMIT Amiga Kermit is usually invoked from a CLI process. However, you can also start it from a Tool type icon. Create a Tool icon, called Kermit.info, and make sure that it contains a ToolType entry for WINDOW= followed by some window specification. This is actually a small dummy window, as C Kermit will open and use its own window. From a CLI window, you generally enter: KERMIT or RUN KERMIT to execute Kermit and start up the Kermit command interpreter. Make sure you set your stack to at least 10000 with the AmigaDOS Stack command first. Kermit will create its own window and greet you with: Executing s:CKERMIT.INI for Amiga... Services directory is s:CKERMIT.KSD Executing s:CKERMOD.INI... Good Evening. C-Kermit 6.0.192, 6 Sep 96, for Commodore Amiga (SAS/C) Copyright (C) 1985, 1996, Trustees of Columbia University in the City of New York. Default file-transfer mode is TEXT Type ? or HELP for help. [Work:src/kermit/ck/192] C-Kermit> assuming that you are using the default distributed S:CKERMIT.INI file. The cursor will appear following the C-Kermit> prompt. Typing ? will produce a list of the items that can be entered at any point. Typing ? here will produce a list of commands: add directory introduction quit stop answer disable kermit read suspend apc do local receive switch ask echo log redial take askq eightbit lookup reget translate assign enable mail reinput transmit bug end minput remote type bye evaluate mmove rename undefine cd exit move resend version check finish msend retrieve wait clear for msleep return while close get news run who comment getc open save write connect getok output script write-line date goto pause send xecho declare hangup pdial server xif decrement help print set define if psend show delete increment push space dial input pwd statistics or one of the tokens: !#;:@ Typing ? at various points during command entry will help you navigate through the command processor. The 'help' command is also quite useful. Typing 'help' alone gets information about command entry: C-Kermit 6.0.192, 6 Sep 96, Copyright (C) 1985, 1996, Trustees of Columbia University in the City of New York. Type INTRO for a brief introduction to C-Kermit. Type VERSION for version and copyright information. Type HELP followed by a command name for help about a specific command. Type NEWS for news about new features. Type BUG to learn how to get technical support. Press ? (question mark) at the prompt, or anywhere within a command, for a menu (context-sensitive help, menu on demand). From system level, type "kermit -h" for help about command-line options. DOCUMENTATION: "Using C-Kermit" by Frank da Cruz and Christine M. Gianone, 2nd Edition, Digital Press / Butterworth-Heinemann 1997, ISBN 1-55558-164-1. To order: +1 212 854-3703 or +1 800 366-2665. PLEASE PURCHASE THE MANUAL. It shows you how to use C-Kermit and answers your questions; sales of this book are the primary source of funding for C-Kermit development and support. but 'help' can be used with command lines to get command descriptions. For example: C-Kermit>help bye Shut down and log out a remote Kermit server The Kermit command processor is normally exited with the 'EXIT' command. During Kermit protocol, you can type CTRL-C or CTRL-D to interrupt and exit Kermit. Depending on the version of the C runtime libraries used to link Kermit, the interrupt may also be active during command input, but it is disabled during connect mode. You will get a requestor when the interrupt is activated to allow you to choose to continue Kermit. However, any serial read or write that was interrupted will still be aborted. Kermit can also be used without the command processor by specifying an action on the command line. You can enter 'kermit -h' at the CLI prompt to get a list of command line options. However, unless input is redirected, or the -q (quiet) option is specified, Kermit will still create a window for protocol monitoring and interruption. 'KERMIT <*' can be used to run Kermit completely within the CLI window; however, this does not allow you to enter control characters, and no console input is seen until you enter return. Input and output can be redirected to files to take advantage of C-Kermit command line file transfer options. Unfortunately, AmigaDOS does not implement pipes (yet). KERMIT INITIALIZATION AND SERIAL SETTINGS Amiga Kermit uses the serial device or a reasonable emulation thereof. Three sources are used to initialize the serial parameters. First, the default serial configuration, as set by Preferences, is copied. This includes baud rate, and under version 1.2 of the Workbench, parity, modem control (7-wire vs. 3-wire), and flow control. Second, command line parameters can be used to override these settings. For example: kermit -b 1200 -p e can be used to select 1200 baud and even parity independently of the Preferences settings. Finally, if the command processor is used, Kermit looks for a "CKERMIT.INI" initialization file, first in the "s:" directory, then in the current directory, providing that the disk containing each directory is present in the Amiga. The "CKERMIT.INI" file contains C-Kermit commands which can be used to initialize the C-Kermit environment as desired. C Kermit is distributed with a default CKERMIT.INI file which you should always use. It includes some Amiga-specific initialization; sugggestions for more are welcome. CKERMIT.INI also executes the commands contained in the file CKERMOD.INI, which is searched for along the same path as CKERMIT.INI itself. Your personal customization commands should be done here. The Kermit SET LINE command has a special form in Amiga Kermit, namely: SET LINE device/unit where "device" is the name of a device (including the .device extension) and "unit" is the unit number. The default setting is equivalent to C-Kermit>SET LINE serial.device/0 to give a simple example. Kermit allows you to set any baud rate between 110 and 292000 baud; however, it will complain if the baud rate is nonstandard (I added this feature after several attempts to use my modem at 12000 baud). Rates of 110 and 111 baud are implemented as 112 baud. Rates above 38400 baud can be used for connect mode, but they are not very useful for file transfer. The file transfer rate is limited by packet retries due to transfer errors, and the overhead time spent constructing packets. Amiga Kermit opens the serial device in exclusive mode by default. However, an open in shared mode can be forceed by following the name and unit number on the SET LINE command with "/S"; for example: C-Kermit>SET LINE SERIAL.DEVICE/0/S This allows other programs, like dialers, to use the serial line at the same time, without exiting Kermit. This could also allow in theory a terminal emulator to be used simultaneously with Kermit. However, if two programs are reading from the serial line at the same time, the results are unpredictable. Any such program, therefore, would have to be disabled from reading while Kermit is performing file transfer or is in connect mode. For these reasons, Commodore-Amiga strongly recommends against sharing the serial port, but Amiga Kermit includes the capability should you need it. Note that Kermit since does its own parity generation and stripping, so it always sets the serial device to use eight bit characters with no parity. WILDCARDING Both the SEND command invoked from the Amiga and a GET sent to an Amiga in server mode use allow wildcarding, in the Unix style. Thus, '*' wildcard matches an arbitrary string while '?' matches an arbitrary character. Therefore, to get all the C source files which begin with 'cki' from the Amiga server, you could use the command: C-Kermit>GET cki*.c Multiple '*' wildcards can be used in a pattern; however, beware that most Unix C-Kermit's may not completely support this form. Also, the wildcarding that is used in local and remote server commands that invoke AmigaDOS commands is the AmigaDOS form. LOCAL AND REMOTE COMMANDS Amiga Kermit provides several ways to invoke AmigaDOS commands from within Kermit. Entering '!' at the Kermit prompt will create a CLI process running in its own window, and wait for it to terminate. The form '! command' will invoke the given command command with its output going to Kermit's window. There is currently no way to pause the output of commands invoked his way, other than the stopgap use of the right mouse button. The form 'REMOTE HOST command' can be sent to the Amiga server to execute the given command remotely on the Amiga. Because of the way AmigaDOS Execute() function works, commands invoked in either the '! command' or 'REMOTE HOST command' forms have NIL: as their standard input. Some AmigaDOS commands that require input, such as DiskCopy and Format, do not recognize the immediate end of file that they receive under this condition, causing them to hang. In addition to the methods given above, various AmigaDOS commands are invoked by local Kermit commands, and generic remote commands. These are listed below: AmigaDOS command Local command Remote generic command DELETE files --none-- REMOTE DELETE files TYPE files --none-- REMOTE TYPE files INFO SPACE REMOTE SPACE LIST obj DIRECTORY obj REMOTE DIRECTORY STATUS --none-- REMOTE WHO Any parameters to these commands are expected to use AmigaDOS conventions, including AmigaDOS wildcarding. Note that in order to pass a '?' through the C-Kermit command processor, it must be prefixed with a '\'. You can change the current directory of the Kermit process locally with the CWD command and remotely with REMOTE CWD. The local CWD command prints out the name of the current directory afterwards. If no new directory is given, the current directory is not changed, so CWD alone can be used to determine where the current directory is. (The default CKERMIT.INI supplied with Kermit creates a prompt with the current dirrectory in it.) SERVER MODE Amiga Kermit completely implements server mode, including the ability to execute CLI commands remotely. Currently CLI commands are executed with their standard output directed to RAM:PIPE-HOLDER, which is then written back to the commanding Kermit after the command completes. There are a few limitations on the commands that can be executed remotely. First of all, if they produce voluminous output, the output should be redirected (redirection is supported on the REMOTE HOST command line) to avoid using all free memory for the output file. However, the commanding Kermit will probably timeout in the middle of the execution of any such command. The best way to use these commands is to REMOTE HOST RUN command >outfile parameters then use REMOTE WHO (which invokes STATUS) to monitor the command for completion. The input stream for remote commands is NIL:, which is not handled intelligently by all Amiga commands. For example, 'REMOTE HOST diskcopy df0: to df1:' hangs indefinitely while waiting for NIL: to press return. Finally, since each command is executed in a separate CLI, commands that set unshared process parameters, like 'cd', will have null effect (but 'REMOTE CWD dir' can be used instead). While server mode is active, AmigaDOS requestors are disabled. This avoids requiring operator intervention to reset a requestore when the Amiga server is told to use a file on a disk that does not exist or is write protected. However, disabled requestors are currently not inherited by the CLI processes that the server creates to execute remote commands. Therefore, a remote AmigaDOS command can still cause the server to become hung. To shut down the Amiga server, enter BYE or FINISH at the commanding Kermit. FINISH exits to whatever level the server was invoked from, while BYE exits Amiga Kermit altogether. CONNECT MODE Connect mode on Amiga Kermit currently provides you with a standard AmigaDOS console device window. Using the default Preferences setting, this gives a 23 row by 77 column screen. However, the MoreRows program allows you to increase the size of the Workbench window beyond the 640 by 200 default size; increasing the number of rows by 8 and the number of columns by 16 will allow a 24 row by 80 column Kermit window. The Amiga console device is used to provide ANSI terminal emulation. While you are in connect mode, you can give single character commands which are prefixed by an escape character which can be set from within C-Kermit. By default, the escape character is CTRL-\. You can use 'H' to close the serial device and exit connect mode, which makes the DTR line drop causing most modems to hang up the phone line. You can currently get a 25 by 80 screen in Kermit by means of a kludge. Entering the Kermit command line echo \27[25t\27[80u\27[3x\27[10y\12 activates console device private escape sequences that cause the console to use a 25 by 80 region, overwriting the borders of the Kermit window. Using window gadgets will cause the borders to be redisplayed, but the display can be cleaned up by typing ctrl-L in command mode. To reset the window to its normal condition, allowing resizing, use: ECHO \\033[t\\033[u\\033[x\\033[y\\014 and then activate a window gadget to refresh the borders. These commands can be placed into Kermit TAKE files. In addition to the standard connect mode commands, extra logging control has been added. If a session log file is open, the 'Q' sequence allows you to temporarily suspend logging. The 'R' sequence resumes logging if it has been suspended. Features have also been added to prevent deadlocks while in connect mode due to spurious XOFF's or bad modem control line states. When connect mode is unable to send serial output, keyboard characters are queued until they can be transmitted. Queuing continues as long as space is available in the output buffer. If the buffer, which is 64 characters long, fills up, the next keyboard input is discarded and the display 'beeps'. To get out of a deadlock situation, you can either exit connect mode, or send a break. In either case, the output queue is flushed, and current serial output character is given one second to finish transmitting. If it does not complete, the output is aborted, and XOFF mode reset as appropriate. Then connect mode is exited or a break is sent, as specified. When output characters are queued, connect status (accessed by 'S') will indicate the number of queued output characters.