Modula-2 Kermit Users-Manual Program & Documentation: Matthias Aebi, Inistitut fuer Informatik, University of Zuerich Language: Modula-2 Version: 1.0 (Lilith implementation) Date: March 1986 1. M2-KERMIT CAPABILITIES AT A GLANCE Local operation: Yes Remote operation: No Transfers text files: Yes Transfers binary files: Yes Wildcard send: Yes User interruption: Yes Filename collision avoidance: Yes Can time out: Yes 8th-bit prefixing: No Repeat count prefixing: No Alternate block checks: No Terminal emulation: Yes Communication settings: Yes Transmit BREAK: No Transaction logging: No Session logging: No Raw transmit: No Act as server: Yes Talk to server: Yes Advanced server functions: No Advanced commands for servers: No Local file management: Yes Handle file attributes: No Command/init files: No Command macros: No M2-Kermit is a program that implements the Kermit file transfer protocol mainly for the Lilith workstation. It is entirely written in Modula-2. Therefore it should be no problem to adabt it for other systems that have a Modula-2 compiler. In fact this has been done already for a CP/M computer. This section will describe the things you should know about Medos, the operating system of the Lilith, in order to make effective use of Kermit, and then it will describe breefly how to use the M2-Kermit program. For more information refer to the 'Kermit Users Guide' and the article 'Kermit, a simple file transfer protocol', both available from Columbia University. This manual is based on the MS-DOS Kermit users manual. 2. THE MEDOS FILE SYSTEM The feature of the Medos file system of greatest interest to Kermit users is the form of the file specifications. Medos file specifications are normally of the form DEVICE.NAME.TYPE If DEVICE is omitted, DK is assumed. The Medos filesystem is non-hierarchical and therefore no pathnames are possible. You will never have to specify the devicename because the current implementation of M2-Kermit will always use the system-disk (DK) as its working device. So NAME.TYPE is normally sufficient to specify a file, and only this information is sent along by M2-Kermit with an outgoing file. The NAME and TYPE fields may contain upper- and lowercase letters, digits, but no special characters. There may be no imbedded or trailing spaces. Other characters may not be included; there is no mechanism for "quoting" otherwise illegal characters in filenames. The fields of the file specification are set off from one another by the punctuation indicated above. Upper- and lowercase characters are treated as different by Medos but not by M2-Kermit. The NAME field is the primary identifier for the file. The TYPE, also called the extension or suffix, is an indicator which, by convention, tells what kind of file we have. For instance FOO.MOD is the source of a Modula-2 program named FOO; FOO.OBJ might be the executable program produced by compiling FOO.MOD. Medos allows a group of files to be specified in a single file specification by including the special "wildcard" characters, "*" and "%". A "*" matches any string of characters from the current position to the end of the field, including no characters at all; a "%" matches any single character. Here are some examples: *.MOD All files of type MOD (all Modula-2 source files) on the system-disk. FOO.* Files of all types with name FOO. F*.* All files whose names start with F. F%X*.* All files whose names start with F and contain X in the third position, followed by zero or more characters. %.* All files whose names are exactly one character long. Wildcard notation is used on many computer systems in similar ways, and it is the mechanism most commonly used to instruct Kermit to send a group of files. M2-Kermit users should bear in mind that other systems may use different wildcard characters. For instance MS-DOS uses "?" instead of "%" as the single character wildcard; when using M2-Kermit to request a wildcard file group from a MS-DOS server, the M2-Kermit "%" must be replaced by the MS-DOS "?". Non-Medos systems may well be confused by nonstandard ASCII files from M2-Kermit. Files produced by Lara for example, may need to be converted to conventional ASCII format prior to transmission by commonly available "exporter" programs. Spreadsheet or database files usually need special formatting to be meaningful to non-Medos recipients (though they can be transmitted between Lilith systems with M2-Kermit). 3. PROGRAM OPERATION M2-Kermit can be run interactively from Medos like any other program. To run M2-Kermit, invoke the program from Medos command level by typing M2Kermit. When you see the command's prompt, M2-Kermit> you may type Kermit commands repeatedly until you are ready to exit the program, for example: *M2Kermit Modula-2 Kermit, Version 1.0 / Lilith For a list of commands type 'Help' M2-Kermit>send foo.* (informational messages about the files being sent) M2-Kermit>get bar.* (informational messages about the files being received) M2-Kermit>exit * During interactive operation, you may edit the command you're currently typing. To erase the character most recently typed press the DEL key. In addition, you may use the help ("?") feature freely while typing M2-Kermit commands. A question mark typed at almost any point in a command produces a brief description of what is expected or possible at that point. 4. M2-KERMIT COMMANDS Modula-2 Kermit implements a subset of the commands of "ideal" Kermit. Here's a brief summary: BYE to remote server. CONNECT as terminal to remote system. DELETE local files. DIRECTORY listing of local files. EXIT from M2-Kermit. FINISH Shut down remote server. GET remote files from server. HELP about M2-Kermit. LOGOUT remote server. QUIT from M2-Kermit RECEIVE files from remote Kermit. SEND files to remote Kermit. SERVER mode of remote operation. SET various parameters. SHOW various parameters. TYPE display a local file. VERSION display M2-Kermit program version number. 4.1. COMMANDS FOR FILE TRANSFER The file transfer commands are SEND, GET, and RECEIVE. 4.1.1. THE SEND COMMAND Syntax: SEND filespec1 [filespec2] The SEND command causes a file or file group to be sent from the local system to the Kermit on the remote system. The remote Kermit may be running in either server or interactive mode; in the latter case, you should already have given it a RECEIVE command and escaped back to your machine. filespec1 may not contain a device designator but the wildcard characters "*" and/or "%". If filespec1 contains wildcard characters then all matching files will be sent, in the same order that M2-Kermit would show them in a directory listing. If filespec1 specifies a single file, you may direct M2-Kermit to send that file with a different name, given in filespec2. For instance, in the command M2-Kermit>send foo.bar framus.widget filespec2 begins with the first nonblank character after filespec1 and ends with the carriage return; thus it may contain blanks or other unusual characters that may be appropriate on the target machine. Lower case letters in filespec2 are raised to upper case for transmission. This feature may be disabled. See SET command. If a file can't be opened for read access, standard Medos error message will be displayed at the screen. For example: FOO.MOD not supported Files will be sent with their filename and filetype (for instance FOO.TXT, no devicename). Each file is sent as is, with no conversions done on the data. Once you give M2-Kermit the SEND command, the name of each file will be displayed on your screen as the transfer begins; packet, retry, and other counts will be displayed along with informational messages during the transfer. If the file is successfully transferred, you will see "Send successful", otherwise there will be an error message. To abort while a file transfer is in progress press the ESC key. This will cause M2-Kermit to return to command level after sending an Error packet to the remote Kermit in an attempt to bring it back to server or interactive command level. Press CR to simulate a timeout: resend the current packet, or NAK the expected one. 4.1.2. THE RECEIVE COMMAND Syntax: RECEIVE [filespec] The RECEIVE command tells M2-Kermit to receive a file or file group from the other system. M2-Kermit passively waits for the file to arrive; this command is not to be used when talking to a Kermit server (use GET for that). You should already have issued a SEND command to the remote Kermit and escaped back to M2-Kermit before issuing the RECEIVE command. If the optional filespec is provided, store the incoming file under that name. The filespec may not include a device designator. The incoming file is stored on the system-device. If no name was specified, the name from the incoming file header packet is used; if that name is not a legal Medos file name, M2-Kermit will delete excessive characters from it, and will change illegal characters to the letter X. If the optional filespec was provided, but more than one file arrives, the first file will be stored under the given filespec, and the remainder will be stored under their own names. If an incoming file does not arrive in its entirety, M2-Kermit will discard it; it will not appear in your directory. The same single-character commands are available as during SEND: ESC aborts a file transfer in progress and returns to command level after sending an Error packet to the remote Kermit in an attempt to bring it back to server or interactive command level. CR simulates a timeout: resend the current packet, or NAK the expected one. If the incoming file has the same name as a file that already exists, and WARNING is set ON, M2-Kermit will change the incoming name (and inform you how it renamed it) so as not to obliterate the pre-existing file. If WARNING is OFF, the original file will be overwritten. 4.4. THE GET COMMAND Syntax: GET [filespec] remote-filespec The GET command requests a remote Kermit server to send the file or file group specified by remote-filespec. This command can be used only when M2-Kermit has a Kermit server active on the other end of the connection. This means that you must have CONNECTed to the other system, logged in, run Kermit there, issued the SERVER command, and escaped back (e.g. ^\ C) to the local M2-Kermit. If the remote Kermit does not have a SERVER command, then you should use SEND and RECEIVE as described above. If you provide the optional filespec the incoming file will be stored under that name. The local file name may not contain a device field. If more than one file arrives, only the first will be renamed. The remote filespec is any string that can be a legal file specification for the remote system; it is not parsed or validated locally. It can contain whatever wildcard or file-group notation (including blanks) is valid on the remote system. As files arrive, their names will be displayed on your screen, along with packet traffic statistics and status messages. You may type ESC to return immediately to the M2-Kermit> prompt, exactly as described for the RECEIVE command. 4.2. COMMANDS FOR TERMINAL CONNECTION The CONNECT command connects your Lilith as a terminal to the remote system, so that you can start up Kermit there. The BYE, FINISH, and LOGOUT commands allow you to shut down a remote Kermit server: 4.2.1. THE BYE COMMAND When communicating with a remote Kermit server, use the BYE command to shut down the server, log out its job, and exit locally from M2-Kermit to Medos. 4.2.2. THE FINISH COMMAND Like BYE, FINISH shuts down the remote server. However, FINISH does not log out the server's job. You are left at M2-Kermit prompt level so that you can connect back to the job on the remote system. 4.2.3. THE LOGOUT COMMAND The LOGOUT command is identical to the BYE command, except you will remain at M2-Kermit prompt level, rather than exit to Medos, so that you can establish another connection. 4.2.4. THE CONNECT COMMAND Establish an interactive terminal connection to the system connected to the currently selected communications port (on the Lilith there is only one port) using full duplex (remote) echoing and no parity unless otherwise specified in previous SET commands. Get back to M2-Kermit by typing the escape character followed by the letter C. On most systems the escape character is Control-\ by default. You can use the SET ESCAPE command to define a different escape character and SET BAUD to change the baud rate, and SET PORT to switch between ports (SET PORT has no effect on a Lilith). For more information refer to the SET command description. 4.3. COMMANDS FOR FILE MANAGEMENT M2-Kermit offers three commands for managing local files. 4.3.1. THE DELETE COMMAND Syntax: DELETE filespec Deletes the specified file or files. As in Medos, the names of the deleted files are listed, and you are prompted for yes or no for each single file. Upper- and lower-case characters are treated equal. Wildcards are allowed. 4.3.2. THE DIRECTORY COMMAND Syntax: DIRECTORY [filespec] Lists the names of files that match the given file specification. If no filespec is given, the command is equivalent to DIR *. Upper- and lower-case characters are treated equal. 4.3.3. THE TYPE COMMAND Syntax: TYPE filespec Displays the specified local file on the screen. Do not try to display a binary file because this may lead to a system crash. The display of a file may be stopped and resumed by pressing any key. ESC aborts the command. 4.4. THE SERVER COMMAND M2-Kermit is capable of acting as a Kermit server, providing file transfer for users coming in through one of the communication ports. The current version of M2-Kermit can send files (the user on the other end types the GET command), receive files (the user types SEND), and terminate, giving control back to the console (user types BYE). To put M2-Kermit into server mode, first issue any desired SET commands to select and configure the desired port, and then type the SERVER command. M2-Kermit will await all further instructions from the user Kermit on the other end of the connection, which may be hardwired or connected through an autoanswer modem. For example: M2-Kermit>set baud 1200 M2-Kermit>set timer on M2-Kermit>set warning on M2-Kermit>server 4.5. THE SET COMMAND Syntax: SET parameter value Establish or modify various parameters for file transfer or terminal connection. You can examine their values with the SHOW command. The following SET commands are available in M2-Kermit: BAUD Communications port line speed CHECK-TYPE Level of error checking for file transfer DEBUG Display packet contents during file transfer END-OF-LINE Packet terminator ESCAPE Escape character for CONNECT FILE-TYPE Specify the type of file to be transmitted (Text or Binary) LOCAL-ECHO Specify which host does the echoing during CONNECT NAME-CONVERSION Specify whether filenames should be 'normalized' or not PACKET-LENTH Maximum length of a Kermit packet PADCHAR Use this character for padding PADDING How many padding characters should be sent PARITY Character parity to use PORT Select a communications port PREFIX Specify prefix character for 8-th bit prefixing PROMPT Change the "M2-Kermit>" prompt to something else RETRIES Maximum number of retries before abort SET QUOTE Specify character for prefixing (quoting) control characters START-OF-PACKET Strart each packet with this character (nomally ASCII 01) TIMEOUT Timeout after how many seconds TIMER Enable/disable timeouts during file transfer WARNING Specify how to handle filename collisions The SET commands are now described in greater detail. 4.5.1. THE SET BAUD COMMAND Syntax: SET BAUD rate Set the speed of the communications port to 300, 600, 1200, 2400, 4800, 9600 bit/s. M2-Kermit initializes the communication port baud rate to 9600 bit/s. 4.5.2. THE SET CHECK-TYPE COMMAND Syntax: SET CHECK-TYPE 1 or 2 or 3 Set the block check type to level 1 to 3. Check type 1 is a one byte checksum. This is currently the only level of block checking supported by M2-Kermit and therefore default. 4.5.3. THE SET DEBUG COMMAND Syntax: SET DEBUG ON or OFF ON Display the Kermit packet traffic on your screen during file transfer. OFF Don't display debugging information (this is the default). If debugging was in effect, turn it off. Be careful not to select debugging mode when transmitting binary files. The Screen I/O Module will not like characters with high bit on. Therefore do not set DEBUG ON while transferring binary data. 4.5.4. THE SET END-OF-LINE COMMAND Syntax: SET END-OF-LINE number If the remote system needs packets to be terminated by anything other than carriage return, specify the decimal value of the desired ASCII character. 4.5.5. THE SET ESCAPE COMMAND Syntax: SET ESCAPE character Specify the control character you want to use to "escape" from remote connections back to M2-Kermit. The default is normally ^\ (Control-Backslash). The character is entered literally, and should normally be chosen from the ASCII control range. 4.5.6. THE SET FILE-TYPE COMMAND Syntax: SET FILE-TYPE BINARY or TEXT If you specify the file type to be a text file, Kermit will automatically convert between the different end of line representations on different computer systems. Besides this it will also strip the high bit of each character which is necessary because this bit is used for parity information. If you specify a file to be binary, it will be sent or received without any changes. 4.5.7. THE SET LOCAL-ECHO COMMAND Syntax: SET LOCAL-ECHO ON or OFF Specify how characters are echoed during terminal emulation. ON specifies that characters are to be echoed by M2-Kermit (because neither the remote computer nor the communications circuitry has been requested to echo), and is appropriate for half-duplex connections. LOCAL-ECHO is OFF by default, for full-duplex, remote echo operation. 4.5.8. THE SET NAME-CONVERSION COMMAND Syntax: SET NAME-CONVERSION ON or OFF Because different computer systems have different rules for filenames, Kermit normally converts these names to a standard representation which means there are no special characters and only uppercase letters. If you transfer files between the two computers using the same operating system, they have the same filename rules anyway. In this case you may specify NAME-CONVERSION off to transmit the filenames without any changes. 4.5.9. THE SET PACKET-LENGTH COMMAND Syntax: SET PACKET-LENGTH value The maximal packetsize for a Kermit packet is normally 94 including the checksum bytes (always one for M2-Kermit). If you use a communications line without frequent distortions this will give you a minimum of overhead for packet frames. If the line you have to use isn't very reliable you may use shorter packets to reduce the overhead for retransmitting packets which have been corrupted. Normally, M2-Kermit uses whatever length the other Kermit requests. 4.5.10. THE SET PADCHAR COMMAND Syntax: SET PADCHAR value Use the specified character for interpacket padding. Some hosts may require some padding characters (normally NUL) before a packet. Specify the decimal value of the desired ASCII character. 4.5.11. THE SET PADDING COMMAND Syntax: SET PADDING value Specify the number of padding characters to be sent between packets. This is may be useful if the remote system is slow and needs some extra time to handle each packet sent to it. PADDING is normally zero. 4.5.12. THE SET PARITY COMMAND Syntax: SET PARITY keyword Specify the character parity to be used. The choices for SET PARITY are NONE (the default), ODD, EVEN, MARK, and SPACE. NONE means no parity processing is done, and the 8th bit of each character can be used for data when transmitting binary files. You will need to SET PARITY to ODD, EVEN, MARK, or possibly SPACE when communicating with a system, or over a network, or through modems, concentrators, multiplexers, or front ends that require or impose character parity on the communication line. For instance, GTE Telenet requires MARK parity. If you neglect to SET PARITY when the communications equipment requires it, the symptom may be that terminal emulation works partially, and file transfer does not work at all. If you have set parity to ODD, EVEN, MARK, or SPACE, then M2-Kermit will request that binary files will be transferred using 8th-bit-prefixing. If the other side knows how to do 8th-bit-prefixing (this is an optional feature of the Kermit protocol, and not all implementations of Kermit have it), then binary files can be transmitted successfully. If NONE is specified, 8th-bit- prefixing will not be requested. Note that there is no advantage to using parity; it only slows Kermit file transfer down. The SET PARITY command is provided only to allow Kermit to adapt to hardware that insists upon using parity. M2-Kermit does currently not allow 8-bit prefixing. Therefore if you want to transmit binary files you must set PARITY to NONE or the transmission will not work correctly. M2-Kermit is not yet able to handle 8-th bit prefixing. 4.5.13. THE SET PORT COMMAND Syntax: SET PORT number On machines with more than one communications port, select the port to use for file transfer and CONNECT. This command lets you use a different asynchronous adapter, or switch between two or more simultaneous remote sessions. Subsequent SET BAUD, PARITY and LOCAL-ECHO commands will apply to this port only. SET PORT has currently no effect for the Lilith which has only one port. 4.5.14. THE SET PREFIX COMMAND Syntax: SET PREFIX character Use the indicated printable character for 8th-bit prefixing. This has an effect only if you try to transmit a binary file over a 7 bit data path, i.e. a line which needs parity. Because M2-Kermit is not able to handle 8-th prefixing SET PREFIX has currently no effect. 4.5.15. THE SET PROMPT COMMAND Syntax: SET PROMPT character-string Change the prompt string (Kermit-M2) to the given character-string. 4.5.16. THE SET QUOTE COMMAND Syntax: SET QUOTE character Use the indicated printable character for prefixing (quoting) control characters and other prefix characters. The only reason to change this would be for sending a very long file that contains very many "#" characters (the normal control prefix) as data. 4.5.17. THE SET RETRIES COMMAND Syntax: SET RETRIES value Set the number of retries before a command is to be aborted. This is set to 13 by default. 4.5.18. THE SET START-OF-PACKET COMMAND Syntax: SET START-OF-PACKET value Mark the beginning of outbound packets with some control character other than Control-A. This will be necessary only if the remote host or the communication channel involved cannot accept a Control-A as data. 4.5.19. THE SET TIMEOUT COMMAND Syntax: SET TIMEOUT value Change M2-Kermit's normal timeout interval; this command is effective only if TIMER is set to be ON; it is normally ON so that M2-Kermit can control timeouts. The timeout interval is specified in seconds. 4.5.20. THE SET TIMER COMMAND Syntax: SET TIMER ON or OFF Enable or disable the timer that is used during file transfer to break the deadlock that occurs when an expected packet does not arrive. By default, the timer is ON. If M2-Kermit is used in conjunction with a mainframe that is doing its own timeouts it should be set OFF. During a file transfer, it is sufficient for one side to do the timing out and the mainframe is usually better equipped to adjust timeout intervals based on system load or other conditions. The timer should be set ON if you are communicating with a mainframe that cannot do timeouts, such as IBM VM/CMS Kermit. 4.5.21. THE SET WARNING COMMAND Syntax: SET WARNING ON or OFF Specify what to do when an incoming file has the same name as an existing file. If ON, Kermit will warn you when an incoming file has the same name as an existing file, and automatically rename the incoming file (as indicated in the warning message) so as not to destroy (overwrite) the pre-existing one. If OFF, the pre-existing file is destroyed, even if the incoming file does not arrive completely. The new name is formed by appending '.V' and a version number to the name until a unique name is found. For instance, ABC.TXT becomes ABC.TXT.V1, then ABC.TXT.V2, ABC.TXT.V3, ..., ABC.TXT.V10, ABC.TXT.V11, etc. 4.6. THE SHOW COMMAND Syntax: SHOW Most parameters that may be altered with SET commands are displayed by the SHOW command. 4.7 TERMINAL EMULATION When you issue the CONNECT command, your Lilth acts as a terminal connected to a remote computer through the serial I/O port. The characters you type are sent out the port, and characters that arrive at the port are displayed on your screen. If you have SET LOCAL-ECHO ON, then M2-Kermit will display characters on the screen as you type them. If LOCAL-ECHO is OFF, then XON/XOFF flow control will be done. If you have SET PARITY to anything other than NONE, M2-Kermit will add the appropriate parity to each outbound character, and strip any parity from incoming ones. While CONNECTed, you can also communicate with an autodialer or "smart modem" to control the communications line, hang it up, and the like; for instance, typing +++ to a Hayes-like modem will allow you to follow that by dialing or hangup commands. The terminal currently emulated by M2-Kermit is only a dumb terminal without any screen control features. The escape character is used to regain the attention of M2-Kermit. When you type the escape character, M2-Kermit waits for you to follow it with a single character command. For instance, the single-character-command "?" produces a list of available single character commands, such as this: ? Help -- prints the available single-character commands. C Close the connection and return to M2-Kermit prompt level. S Show the status of the connection. 0 (the digit zero) Transmit a NUL (ASCII 0). ^\ (or whatever you have set the escape character to be) Typing the escape character twice sends one copy of it to the connected host. The escape character can be changed to something other than Control-Backslash by using the SET ESCAPE command. 5. WHAT'S MISSING M2-Kermit has plenty of room for improvement. Features that may be improved or added include: % A built-in facility for sending files "raw" to the remote system, obeying current settings for parity, flow control, handshake, and so forth. This might include a script interpretation facility to allow remote sessions to be conducted automatically. % Additional functionality when running in server mode -- help, directory listings, file deletion, listing files, execution of local commands, etc. % Possibility to use remote commands when talking to servers -- REMOTE RENAME, HELP, DIR, COPY, STATUS, WHO, etc. % Allowance for file specifications, including device names, in all commands. % Transaction file logging. % Improved command parsing; for instance, accept default values for omitted trailing fields. % Support for Kermit file attribute packets. % 8-th bit prefixing % Repeat count prefixing % Alternate block checks % More sophisticated terminal emulation % Session logging % Allowance for command / init files % Command macros % Use of pulldown-menus and windows