VAX/VMS KERMIT Page 100 COMMUNICATIONS Parameters affecting the terminal line being used for com- munication. DEBUGGING Debugging mode in effect, if any. DELAY The number of seconds Kermit-32 will delay before starting a SEND or RECEIVE command when in remote mode. ESCAPE The current escape character for the CONNECT processing. FILE_PARAMETERS File type, file naming, and incomplete file disposition. INCOMPLETE_FILE_DISPOSITION The action to take when a transfer is aborted. LINE Terminal line in use. LOCAL_ECHO Whether characters should be echoed locally when CONNECTed. PACKET For incoming and outbound packets. PARITY The parity type in use. RECEIVE For inbound packets. RETRY The number of retries to be done on bad packets. SEND For outbound packets. 7.4.6. Program Management Commands THE HELP COMMAND Syntax: HELP [topic {subtopic}] Typing HELP alone prints a brief summary of Kermit-20 and its commands. You can also type HELP command for any Kermit-20 command, e.g. "help send" or "help set parity" to get more detailed information about a specific command. THE EXIT AND QUIT COMMANDS Syntax: EXIT Exit from Kermit-32. You can also exit from the Kermit-32 when it is waiting for a command by typing a control-Z. When Kermit-32 is running remotely, two control-Y's will abort the transfer, bringing Kermit-32 back to command mode. The two control-Y's must be typed together, as if a timeout occurs between them the first is ignored. When Kermit-32 is running locally, two control-Y's will stop Kermit-32 and return you to DCL. You will be able to CONTINUE if you do VAX/VMS KERMIT Page 101 not perform any command which runs a program. However, after continuing, control-A, control-X and control-Z will no longer be accepted as commands. QUIT is a synonym for EXIT. THE LOG COMMAND Syntax: LOG [option [filespec]] Log the specified option to the specified file: SESSION During CONNECT log all characters that appear on the screen to the specified file. During CONNECT, the session log can be temporarily turned off during the remote session by typing the escape character followed by Q (for Quit logging), and turned on again by typing the escape character followed by R (for Re- sume logging). TRANSACTIONS During file transfer, log the progress of each file. Trans- action logging is recommended for long or unattended file transfers, so that you don't have to watch the screen. The log may be inspected after the transfer is complete to see what files were transferred and what errors may have occurred. DEBUGGING Log debugging info to the specified file. If no SET DEBUGGING command was previously issued, the file will be opened and no information written. If DEBUGGING is turned on (either via the SET DEBUGGING command or by typed control-D during a local transfer), the packet debugging information will be written to the file. Packet format is described in the Kermit Protocol Manual. Any log files are closed when you EXIT or QUIT from Kermit. You may explicitly close a log file and terminate logging by using the LOG command without a file specification. 7.5. Raw Download "Raw Download" is the term commonly used to describe the capture of a remote file on the local system, without any kind of error detection or correction. This allows you to obtain files from remote systems that do not have Kermit, but with the risk of loss or corruption of data. Kermit-32 provides raw downloading via the LOG SESSION command during CONNECT to a remote system. The session log is described above. To use session log- ging to capture a file: 1. Run Kermit on the VAX/VMS system. 2. SET LINE to the terminal line through which you will be connected to the remote system. 3. Perform any required SET commands to condition Kermit for communica- tion with the remote system. VAX/VMS KERMIT Page 102 4. CONNECT to the remote system and log in. 5. Condition your job on the remote system not to pause at the end of a screenful of text, and give whatever commands may be necessary to achieve a "clean" terminal listing -- for instance, disable messages from the system or other users. 6. Type the appropriate command to have the desired file displayed at the terminal, but do not type the terminating carriage return. On most systems, the command would be "type", on Unix it's "cat". 7. Escape back to Kermit-32 and give the LOG SESSION command with the file specification where you wish to store the data. 8. CONNECT back to the remote system and type a carriage return. The file will be displayed on your screen and recorded in the session log file. 9. Escape back to Kermit-32 and give the LOG SESSION command without a file specification. The file you specified will contain everything that was typed on your screen. You will probably find that some editing necessary to remove extraneous prompts, messages, padding characters, or terminal escape sequences, or to fill in lost or garbled characters. 7.6. Installation of Kermit-32 Kermit-32 may be installed either by rebuilding the entire program from the sources, or by making use of the distributed copy of the program. When being built from sources, it may be built using either a BLISS-32 compiler or just the MACRO-32 assembler. FILES Kermit-32 is built from a number of BLISS-32 sources and one MACRO-32 source. In order to make it possible for sites without BLISS-32 to build, MACRO-32 sources generated by BLISS-32 are also included for all of the BLISS modules. In the normal distribution of Kermit-32, all of the files start with the prefix "VMS". This will need to be changed to "KER" in order to build the program properly. The following files are distributed as part of Kermit-32: VMSTT.BLI Common BLISS source for the terminal text output support. VMSGLB.BLI Common BLISS source for the global storage for VMSMSG.BLI. VMSMSG.BLI Common BLISS source for the protocol handling module. VMSCOM.REQ Common BLISS require file which defines various common parameters. This is required by VMSMSG.BLI. This file must be renamed to KERCOM.REQ. VMSMIT.BLI BLISS-32 source for the command parser, and some basic support routines. VAX/VMS KERMIT Page 103 VMSFIL.BLI BLISS-32 source for the file I/O. VMSTRM.BLI BLISS-32 source for the terminal processing. This handles the driving of the terminal line for the transfers and the connect command processing. VMSSYS.BLI System interface routines for the Kermit generic command processing. VMSGEN.MAR Macro-32 source file that contains the REMOTE command text that is given to VMS. Sites desiring to change what DCL commands are used to process the various generic server commands can make those changes in this source. This also contains the text of the help message returned in response to the server generic help command. VMSERR.MSG MESSAGE source for error messages used by VAX/VMS Kermit. VMSERR.REQ BLISS-32 require file which defines the error codes. This is REQUIREd by the BLISS-32 sources. VMSMIT.RNH RUNOFF source for the help files for VAX/VMS Kermit. When this is run through RUNOFF with /VARIANT=SYSTEM, it produces a .HLP (VMSSYS.HLP) file suitable for inserting into the system help library (SYS$HELP:HELPLIB.HLB) to provide a KERMIT topic for the system HELP command. When run through RUNOFF without the /VARIANT=SYSTEM, it produces a .HLP file (VMSUSR.HLP) to be stored on SYS$HELP: for use by the Kermit HELP command. VMSSYS.HLP RUNOFF output file for system wide Kermit HELP. VMSUSR.HLP RUNOFF output file for Kermit's HELP command. VMSINS.COM Command file to build and install VAX/VMS Kermit. VMSMIT.EXE The executable (binary) file of VAX/VMS Kermit. Note that this is only included when it is possible. This may be either a copy of the .EXE file which was transferred to a TOPS-10 or TOPS-20 system using Kermit with Kermit-10 (or -20) using FILE BYTE-SIZE 8-BIT, or a direct copy of the .EXE file (if the file is either on a native VAX/VMS tape or is residing on a VAX/VMS system). VMSMIT.HEX A hexifed version of .EXE file for VMS Kermit. This file can be dehexified using the supplied program. In the hexified form, the file should be transferrable over any medium which handles normal text. This is the most reliable copy of the ex- ecutable version of VMS Kermit. VMSHEX.MAR Source for the hexification program. This is the program which was used to produce VMSMIT.HEX. It can also be used to produce hexified version of any (or at least almost any) Files-11 file. The dehexification program should then be able to reproduce a copy of the original file with the file parameters correctly set. Note that the format used for the hexified files is basi- cally Intel hex format. There are some additional records used VAX/VMS KERMIT Page 104 to store the record format, etc. Also, the file name as typed to the prompt from VMSHEX is stored in the hexified version of the file for use by the dehexification program. By doing this, it is possible to store more than one binary file with a single hexified file. VMSDEH.MAR Source for the dehexification program. VMSV3.MEM Documentation on the changes between versions 2.0 and 3.0 of Kermit-32, and additional installation information. As distributed, Kermit-32 should work on any VAX/VMS system (version 3.0 and later). Customization is possible with or without a BLISS-32 compiler. Default parameter values may be changed by changing the appropriate LITERALs in the BLISS-32 source for VMSMSG, or the actual values which are stored in the routine MSG_INIT in the MACRO-32 source for VMSMSG. Sites can also easily change the commands which are used for processing the generic server functions (REMOTE commands when running as a server). The text which makes up these commands is in the file VMSGEN.MAR, along with the text of the REMOTE HELP message. This allows a site to make use of local programs for performing some of the commands (perhaps using FINGER to perform the WHO com- mand, etc.). BUILDING KERMIT-32 FROM SOURCES A command file is included which will build Kermit-32 from either the BLISS-32 or MACRO-32 sources and optionally install Kermit-32 on the system. This file (VMSINS.COM) has not been extensively tested, however it should work on most systems. It is also a good example of what needs to be done to compile each file and load the entire program. It also contains the commands necessary to install a version of Kermit-32 on the system once the .EXE and .HLP files are generated. USING KERMIT-32 TO INSTALL A NEW VERSION OF ITSELF If you already have a version of Kermit-32 running on a VAX/VMS system, you can use it to transfer a new version of itself from another system. If you have no need to build Kermit-32 from sources (because you have no local modifications), you can just transfer the new VMSMIT.EXE (or VMSMIT.HEX), and the new help file VMSMIT.RNH. If you have access to a system which has a copy of VMSMIT.EXE, you can transfer it simply by setting the FILE TYPE to FIXED on the receiving Kermit. Make sure that the sending Kermit is willing to send the file as a binary file. If the sending Kermit is another copy of Kermit-32, you don't need to do anything. If the sending Kermit is Kermit-10 or Kermit-20, make sure the file will be sent as an eight-bit binary file by using SET FILE BYTE-SIZE EIGHT. If some other Kermit is sending the file, make sure to give it whatever command is necessary to ensure that it sends eight-bit binary data from the file. Also, if the originating system is not a VAX/VMS, TOPS-10 or TOPS-20 system, make sure that the file was stored on that system correctly to start out with. Normally, the file VMSMIT.EXE will only be available from a VAX/VMS, TOPS-10 or TOPS-20 sys- tem. VAX/VMS KERMIT Page 105 If you only have access to a copy of VMSMIT.HEX, you will need to transfer that file (as a normal ASCII text file). You will also need a copy of VMSDEH.MAR. After you have obtained both files, you can produce a copy of the .EXE file as follows. First compile VMSDEH by using the command MACRO VMSDEH. Then load it by LINK VMSDEH. Now run VMSDEH and when it asks for a file name, type VMSMIT.HEX. The program will run for a short time and produce the .EXE file. The system wide and user help files are produced from VMSMIT.RNH by RUNOFF. To produce the user help file (the one used by Kermit-32's HELP command), type: $ RUNOFF VMSMIT.RNH/OUTPUT=KERUSR.HLP $ LIBARARY/CREATE/HELP SYS$HELP:KERMIT.HLB KERUSR.HLP To produce the system wide help file and install it in the system help library type: $ RUNOFF VMSMIT.RNH/OUTPUT=KERSYS.HLP/VARIANT=SYSTEM $ LIBRARY/REPLACE/HELP SYS$HELP:HELPLIB.HLB KERSYS.HLP This allows the DCL HELP command to provide information on Kermit-32. IBM VM/CMS KERMIT Page 106 8. IBM VM/CMS KERMIT Program: Daphne Tzoar, Columbia University; contributions from Bob Shields (U. of Maryland), Victor Lee (Queens U.), Gary Bjerke (U. of Texas at Austin), Greg Small (UC Berkeley) Language: CMS Assembler Documentation: Daphne Tzoar, Columbia University Version: 2.01 Date: May 1985 CMS Kermit Capabilities At A Glance: Local operation: No Remote operation: Yes Transfers text files: Yes Transfers binary files: Yes (fixed format) Wildcard send: Yes ^X/^Y interruption: Yes Filename collision avoidance: Yes Can time out: No 8th-bit prefixing: Yes Repeat count prefixing: Yes Alternate block checks: Yes Terminal emulation: No Communication settings: No Transmit BREAK: No Transaction logging: Yes Session logging: No Raw transmit: No Act as server: Yes Talk to server: No Advanced server functions: No Advanced commands for servers: No Local file management: Yes Handle Attribute Packets: No Command/init files: Yes Command macros: No Kermit-CMS is a program that implements the KERMIT file transfer protocol for IBM 370-series mainframes (System/370, 303x, 43xx, 308x, etc.) under the VM/CMS operating system. It is written in IBM 370 assembly language. This program runs only over ASCII (asynchronous) lines attached to a 3705-style front end or a Series/1 running the Yale ASCII Terminal Communication System. The program should also work on the IBM 7171 ASCII Device Control Unit and the 4994, al- though this has not been verified as of this writing. For more details on this, see the section SET SERIES1. These systems have several peculiarities that users should be aware of. These are half duplex systems; the communication line must "turn around" before any data can be sent to it. The fact that a packet has been received from the IBM system is no guarantee that it is ready for a reply. Thus any Kermit talking to this system must wait for the line turnaround character (XON) before trans- mitting the next character. It is up to the user to tell the other Kermit that it is talking to an IBM mainframe. IBM VM/CMS KERMIT Page 107 Also, a program running under VM/CMS is unable to interrupt a read on its "console". This means that the CMS version of Kermit cannot timeout. The only way to "timeout" CMS Kermit is from the other side: typing a carriage return to the local Kermit causing it to retransmit its last packet, or an automatic timeout as provided by most other Kermits. 8.1. The VM/CMS File System The features of the CMS file system of greatest interest to Kermit users are the format of file specifications and the concept of records. 8.1.1. File Specifications The VM/CMS file specification is in the form FILENAME FILETYPE FILEMODE (often abbreviated FN FT FM). FILENAME and FILETYPE are at most 8 characters in length each. The name field is the primary identifier for the file. The type is an indicator which, by convention, tells what kind of file we have. For instance TEST FORTRAN is the source of a FORTRAN program named TEST. MODULE is the normal suffix for executable programs. Although some operating systems consider the FILETYPE optional, VM/CMS requires a valid type. There- fore, Kermit-CMS supplies a default type of "X" if one is not provided by the remote system. The FILEMODE, which consists of a letter and a number, is similar to a device specification on microcomputer systems: FN FT FM would translate to FM:FN.FT in CP/M or MS-DOS. If FILEMODE is omitted from a file specification when sending, a FM of "*" is used. In this case, the users disks are scanned according to the search order and the first occurrence of the file is the one that is sent. If FILEMODE is omitted from a file spec when receiving, a default of "A1" is used. To provide compatibility with most other operating systems, Kermit-CMS sends only the FILENAME and FILETYPE. It also converts the intervening blank to a period. The FN and FT may contain, in any order, uppercase letters, digits, and the special characters "$" (dollar sign), "#" (pound sign), "@" (at sign), "+" (plus), "-" (dash), ":" (colon), and "_" (underscore). Other characters may be not be included. If an invalid character is found in the FN or FT field, it is replaced by the letter "X". VM/CMS 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, includ- ing no characters at all; a "%" matches any single character. Here are some examples: * COBOL A All files of type COBOL (all COBOL source files) on the A disk. F* * All files whose names start with F. IBM VM/CMS KERMIT Page 108 % * B All files on the B disk whose FN is exactly one character long. 8.1.2. File Formats Several differences exist between VM/CMS files and those of most other operat- ing systems. One distinction is that CMS encodes its data using the EBCDIC character set. The operating system, VM, translates all incoming characters from ASCII to EBCDIC. Kermit-CMS then translates the data it reads back to AS- CII (characters not representable in ASCII are replaced by a null). This is done in order to correctly calculate the checksum, the method used to guarantee error-free transfer. When Kermit-CMS sends packets, it converts all data back to EBCDIC. Note that the translate tables used by Kermit must correspond to the ones used by the system (VM). The ASCII to EBCDIC translations can be found in the Appendix. Another difference is that VM/CMS stores files as records rather than byte streams. VM/CMS Kermit has to worry about assembling incoming data packets into records and appending carriage return-linefeed to outgoing records. 8.2. Program Operation Kermit-CMS can be invoked at the command line or from an exec. Commands con- sist of one or more fields, separated by spaces. Each field must be eight characters or less. Fields longer than the maximum length are truncated. Upon initial startup, the program looks for two special initialization files, SYSTEM KERMINI and (USERID) KERMINI (that is, the userid of the person running CMS-Kermit.) These files can be placed on any disk. The purpose of these files is to allow Kermit to be customized for a particular system and for a user's specific settings without changing the source code. The file SYSTEM KERMINI should be placed on a publicly accessible disk by a systems programmer. The file would contain commands that all users would need to issue in order for Kermit to run on the system, such as commands to modify the ASCII-to-EBCDIC and EBCDIC-to-ASCII tables used by Kermit-CMS. The file (USERID) KERMINI would contain commands that the user generally issues every time Kermit is run. Kermit-CMS executes any commands found in these files as though they were typed at the terminal. Here is a sample init file: * Asterisk in column one is a comment. set debug on set warning on set block 3 Three CP SET parameters MSG, IMSG and WNG are always set OFF during the actual file transfer (and restored afterwards) to prevent CP from interrupting any I/O in progress. IBM VM/CMS KERMIT Page 109 Interactive Operation: To run Kermit-CMS interactively, invoke the program from CMS by typing "KERMIT". When you see the command's prompt, KERMIT-CMS>. you may type Kermit commands repeatedly until you are ready to exit the program, for example: .KERMIT Kermit CMS Version 2.01 Enter ? for a list of valid commands KERMIT-CMS>.send foo * Files with fn FOO are sent KERMIT-CMS>.receive test spss File is received and called TEST SPSS A1 KERMIT-CMS>.exit During interactive mode, you may use the help ("?") feature while typing Kermit-CMS commands. A question mark typed at almost any point in a command, followed by a carriage return, produces a brief description of what is expected or possible at that point. Command Line Invocation: Kermit-CMS may also be invoked with command line arguments from CMS. For in- stance: .KERMIT send test fortran or .KERMIT set debug on # set file binary # server Kermit will exit and return to CMS after completing the specified command or commands. Note that several commands may be given on the command line as long as they are separated by the linend character, which is pound sign in this case. The command line may contain up to 130 characters. Exec Operation: Like other CMS programs, Kermit-CMS may be invoked from a CMS EXEC. Kermit will not run under CMSBATCH or disconnected since the user does not actually have a console. Commands can be passed using TAKE files and/or command line arguments. For example, to start up Kermit-CMS and have it act as a server, include the line: IBM VM/CMS KERMIT Page 110 KERMIT server To pass more than one command, they must be stacked in the order in which they are to be executed. To start up a Kermit-CMS server with a three character CRC, include: &STACK set block 3 &STACK server KERMIT Prompts and messages will still be displayed on the screen. 8.3. Kermit-CMS Commands Here's a brief summary of CMS Kermit commands: CMS executes a CMS command. CP executes a CP command. EXIT from Kermit-CMS. HELP about Kermit-CMS. QUIT from Kermit-CMS RECEIVE files from other Kermit. SEND files to other Kermit. SERVER mode of remote operation. SET various parameters. SHOW various parameters. STATUS inquiry. TAKE commands from file. TDUMP dumps the contents of a particular table. The remainder of this section concentrates on the commands that have special form or meaning for CMS Kermit. THE SEND COMMAND Syntax: SEND filespec The SEND command causes a file or file group to be sent from the CMS system to the Kermit on the remote system. filespec takes the form: filename filetype [filemode] filespec may contain the wildcard characters "*" or "%". If filespec contains wildcard characters then all matching files will be sent. If, however, a file exists by the same name on more than one disk, only the first one CMS Kermit encounters, according to the disk search order, is sent. Although the file transfer cannot be cancelled from the CMS side, Kermit-CMS is capable of responding to "cancel file" or "cancel batch" signals from the local Kermit; these are typically entered by typing Control-X and Control-Z respec- tively. IBM VM/CMS KERMIT Page 111 THE RECEIVE COMMAND Syntax: RECEIVE [filespec] The RECEIVE command tells Kermit-CMS to receive a file or file group from the other system. You should then issue a SEND command to the remote Kermit. The format of the filespec is: filename filetype [filemode] If the optional filespec is not included, Kermit-CMS will use the name(s) provided by the other Kermit. If that name is not a legal CMS file name, Kermit-CMS will delete excessive characters from it, and will change illegal characters to the letter X. Use the file specification to indicate that the incoming file should be stored under a different name. The filespec may include a filemode to designate the destination disk. If none is provided, the file will be saved with fm A1. If you want to use the same name but a different filemode, specify = = FM. Wildcards may not be used in any field. If the optional filespec is 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 on the A disk. If, however, = = FM is used, all files will be placed onto the specified disk. When receiving files, if the record format is fixed, any record longer than the logical record length will be split up to as many records as necessary. If the record format is variable, the record length can be as high as 64K. For send- ing files, the maximum record length is 64K. See the SET LRECL and SET RECFM commands. If an error occurs during the file transfer, as much of the file as was received is saved on disk. If the sending of a file is cancelled by the user of the remote system, Kermit-CMS will discard whatever had arrived. If the incoming file has the same name as a file that already exists, and WARN- ING is OFF, the original file will be overwritten. If WARNING is set ON, Kermit-CMS will change the incoming name so as not to obliterate the pre-exist- ing file. It attempts to rename the file by replacing the first character with a dollar sign ($). If a file by that name exists, it also replaces the second character with a dollar sign. It continues in this manner for all characters of the filename and filetype. If the file cannot be renamed, the transfer fails. THE TAKE COMMAND Syntax: TAKE filespec Execute Kermit commands from the specified file, where filespec has the format fn ft [fm]. The command file may include TAKE commands. IBM VM/CMS KERMIT Page 112 THE SERVER COMMAND Kermit-CMS is capable of acting as a server. The user connects to the CMS sys- tem once to set various options and to start the server. From then on, he need not connect to the CMS system again. The current version of Kermit-CMS can send files (the user on the other end types the GET command, using either a space or a period as the delimiter between filename, filetype, and filemode), receive files (the user types SEND), and terminate by either returning to CMS (user types FINISH) or logging the user out (user types BYE). To put Kermit-CMS into server mode, first issue any desired SET commands to select various options and then type the SERVER command. Kermit-CMS will await all further instructions from the user Kermit on the other end of the connec- tion. For example: KERMIT-CMS>.set warning on KERMIT-CMS>.set debug on KERMIT-CMS>.set block 3 KERMIT-CMS>.server THE SET COMMAND Syntax: SET parameter [value] Establish or modify various parameters for file transfer. You can examine their values with the SHOW command. The following SET commands are available in Kermit-CMS: ATOE Modify ASCII-to-EBCDIC table used by Kermit-CMS BLOCK Level of error checking for file transfer DEBUG Log packets sent and received during file transfer END-OF-LINE Packet terminator ETOA Modify EBCDIC-to-ASCII table used by Kermit-CMS FILE Type of incoming or outgoing file LRECL Logical Record length for incoming file PACKET-SIZE Maximum receive packet size QUOTE Use to quote outgoing control characters RECFM Record format for incoming files SERIES1 Indicate if coming in via a Series/1 WARNING Specify how to handle filename collisions SET ATOE Syntax: SET ATOE num1 num2 This command allows you to modify the ASCII-to-EBCDIC translate table used by Kermit-CMS to conform to your system. Specify the offset of the ASCII value within the table and the new value for that location. Both num1 and num2 should be between 0 and 255 (decimal). Note that the table is twice as long as necessary because the translate instruction expects a table that contains 256 characters. IBM VM/CMS KERMIT Page 113 SET BLOCK SYNTAX: SET BLOCK number Determine the type of block check used during file transfer. Valid options for number are: 1 (for a one character checksum), 2 (for a two character checksum) and 3 (for a three character CRC). SET DEBUG Syntax: SET DEBUG ON or OFF ON Keep a journal of all packets sent and received in the file KER LOG A1. If the file already exists, it is overwritten. OFF Stop logging the packets. SET END-OF-LINE Syntax: SET END-OF-LINE number If the remote system needs packets to be terminated by anything other than car- riage return, specify the decimal value of the desired ASCII character. number must be between 0 and 31 (decimal). SET ETOA Syntax: SET ETOA num1 num2 This command allows you to modify the EBCDIC-to-ASCII translate table used by Kermit-CMS to conform to your system. Specify the offset of the EBCDIC value within the table and the new ASCII value for that location. Both num1 and num2 should be between 0 and 255 (decimal). SET FILE Syntax: SET FILE BINARY or TEXT BINARY Tells CMS Kermit to treat each character as a string of bits and not to perform translation on the data. Also, no carriage-return is added to the end of outgoing records. Incoming bytes are added to the end of the current record which is written out when the specified LRECL is reached. TEXT Tells CMS Kermit that the file is plain text. ASCII-to-EBCDIC and EBCDIC-to-ASCII translation is performed on the data. Carriage return-linefeed are appended to outgoing records and are used to deter- mine the end of incoming records. IBM VM/CMS KERMIT Page 114 SET LRECL Syntax: SET LRECL number Set the logical record length for incoming files to a number from 1 to 65536 (64K). This variable is used only for fixed format files. The default is 80. SET PACKET-SIZE Syntax: SET PACKET-SIZE number Use the specified number as the maximum length for incoming packets. The valid range is 26-94, where 94 is the default. SET QUOTE Syntax: SET QUOTE char Use the indicated printable character for prefixing (quoting) control charac- ters 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. It must be a single character in the range: 33-62, 96, or 123-126 (decimal). SET RECFM Syntax: SET RECFM option Set the record format to use for incoming files. Valid options are "F" for fixed format or "V" for variable format. The default is variable. SET SERIES1 Syntax: SET SERIES1 ON or OFF Kermit-CMS automatically determines whether you are connected via a Series/1 emulation controller or a TTY line. This command is provided though so you can override Kermit-CMS. When you SET SERIES1 ON, Kermit disables the 3270 protocol conversion function by putting the Series/1 into "transparent mode"; this allows Kermit packets to pass through the Series/1 intact. SET WARNING Syntax: SET WARNING ON or OFF ON If an incoming file has the same name as an existing file on the specified disk, Kermit will attempt to rename the incoming file so as not to destroy (overwrite) the pre-existing one. OFF Upon a filename collision, the existing file will be replaced by the incoming file. IBM VM/CMS KERMIT Page 115 THE SHOW COMMAND Syntax: SHOW option Use to display the values of all parameters that can be changed with the SET command, except for ATOE and ETOA (see the TDUMP command). option can be a particular parameter or the keyword "ALL". THE STATUS COMMAND Syntax: STATUS Returns the status of the previous command. The response will either display the message "Kermit completed successfully", or the last error encountered. THE TDUMP COMMAND Syntax: TDUMP table-name Display the contents of table-name since it can be modified using the SET com- mand. The ATOE and ETOA tables can presently be 'dumped'. CP AND CMS COMMANDS Syntax: CP text of command CMS text of command Although Kermit-CMS does not provide explicit commands for managing local files or interacting with the operating system, it is possible to do so. You can is- sue any CP or CMS command, though each word will be truncated to eight charac- ters. You can list, type, rename or delete files, send messages and so on. At this time, though, you cannot run another program from Kermit-CMS. 8.4. Before Connecting to the Mainframe When connecting to the CMS system as a TTY device ("line at a time" mode) several flags must first be set on the micro version of Kermit. You should set the LOCAL-ECHO flag to ON (this is used to indicate half-duplex). This is the norm but not true in every case; if each character appears twice, set the LOCAL-ECHO flag OFF. HANDSHAKE should be set to XON and FLOW-CONTROL should be set to NONE. The parity should be set according to the system's specifica- tions. On some micro versions of Kermit, all of the above is done in one step using the DO IBM macro (or SET IBM ON). Set the baud rate to correspond to the line speed. When connecting to the CMS system through the Series/1 terminal emulation con- troller ("full-screen" mode), certain flags must be set on the micro version of Kermit. You should set the LOCAL-ECHO flag to OFF (this is used to indicate full-duplex). HANDSHAKE should be set to OFF and FLOW-CONTROL should be set to XON/XOFF. For most systems, the PARITY should be set to EVEN. Set the baud rate to correspond to the line speed. Immediately after issuing a SEND, RECEIVE or SERVER command to Kermit-CMS, the screen will be cleared. This is IBM VM/CMS KERMIT Page 116 to make sure the terminal is not stuck in a MORE or HOLDING state before pack- ets are sent via the full-screen I/O operation. After the file transfer is complete, and you re-connect to Kermit-CMS, you should enter the Series/1 "Master Reset" sequence (probably "CTRL-G") so that the screen is refreshed. 8.5. How to build an executable version of Kermit-CMS Kermit-CMS is composed of three assembly language source files that are as- sembled separately and then linked together. They are: KERMIT, NEXTFST, and WILD. To create a runnable version: 1. GLOBAL the necessary MACLIBs. For SP, the MACLIBs used are DMSSP, CMSLIB and TSOMAC. 2. Make sure the source files are named as listed above and are saved on disk in fixed format with a logical record length of 80. 3. Assemble the three source files. 4. Load the files into memory via: LOAD KERMIT 5. Create a runnable version called KERMIT MODULE via: GENMOD KERMIT 6. If your site's ASCII/EBCDIC translation table does not conform to the one listed in the appendix (which in turn conforms to the one given in the IBM System/370 Reference Summary), then enter the ap- propriate SET ATOE/ETOA commands in the SYSTEM KERMINI file. Note that if the ASCII/EBCDIC translation is not invertible, Kermit will not and cannot work. To run CMS Kermit, simply type "KERMIT" to the CMS system prompt. 8.6. What's New Below is a list of the more important additions in Version 2.01 of CMS Kermit: 1. Add prefixing of the "8th bit". This allows CMS Kermit to send or receive fixed format binary data, such as microcomputer binary files. 2. The maximum record length allowed has been increased to 64K for both incoming and outgoing files. 3. Repeat count prefixing has been added to speed up transmission. In addition, Kermit-CMS now packs as much data as possible into an out- going packet rather than one packet per record (it makes a big difference). 4. Support for two character checksum and three character CRC. 5. If filetype is not supplied by the remote Kermit, use a default of "X" rather than failing. Also allow the option to rename an incom- ing file upon filename collision. IBM VM/CMS KERMIT Page 117 6. Add debugging mode to log packets and to acknowledge the attention if the user types a BREAK. Add a SHOW ALL command. 7. Allow input to command parser from command line. Multiple commands should be separated by the linend character. After execution of these commands, Kermit returns control to CMS. 8. Add support for Series/1 front end. 9. Add server support. 10. Upon startup, read commands from two init files: SYSTEM KERMINI and (USERID) KERMINI (that is the userid of the person running Kermit). Lines with an asterisk as the first character are comments. Add the TAKE command. The LRECL for these files must be 130 or less. 11. Implement skip file or file group when sending or receiving (in this case, discard incoming file). 12. Allow system manager to change ASCII/EBCDIC translation tables to conform to the various specifications of different systems. Also, bypass user translate tables when sending and receiving data. 8.7. What's Missing Work on Kermit-CMS will continue. Features that need to be improved or added include: - Allow timeouts so CMS Kermit does not wait forever if a packet does not arrive in a timely fashion. - Allow any binary file to be sent and received properly, not only fixed format binary files. - Better keyword parsing, which is rather crude at this time. - Support of the more advanced server functions. - Addition of a RUN command. - Ability to SET LINE, so that Kermit-CMS can be used as a local Ker- mit, connecting to a remote host over another communication port. UNIX KERMIT Page 118 9. UNIX KERMIT Program: Frank da Cruz, Bill Catchings, Jeff Damens, Columbia University; Herm Fischer, Encino CA; contributions by many others. Language: C Documentation: Frank da Cruz, Herm Fischer Version: 4C(057) Date: July 26, 1985 C-Kermit is a completely new implementation of Kermit, written modularly and transportably in C. The protocol state transition table is written in wart, a (non-proprietary) lex-like preprocessor for C. System-dependent primitive func- tions are isolated into separately compiled modules so that the program should be easily portable among Unix systems and also to non-Unix systems that have C compilers. This document applies to Unix implementations of C-Kermit, and in most ways also to the VMS implementation. Unix Kermit Capabilities At A Glance: Local operation: Yes Remote operation: Yes Login scripts: Yes Transfer text files: Yes Transfer binary files: Yes Wildcard send: Yes File transfer interruption: Yes Filename collision avoidance: Yes Can time out: Yes 8th-bit prefixing: Yes Repeat count prefixing: Yes Alternate block checks: Yes Terminal emulation: Yes Communication settings: Yes Transmit BREAK: Yes Support for dialout modems: Yes IBM mainframe communication: Yes Transaction logging: Yes Session logging: Yes Debug logging: Yes Packet logging: Yes Act as server: Yes Talk to server: Yes Advanced server functions: Yes Local file management: Yes Command/Init files: Yes UUCP and multiuser line locking: Yes File attributes packets: No Command macros: No Raw file transmit: No C-Kermit provides traditional Unix command line operation as well as inter- active command prompting and execution. The command line options provide ac- cess to a minimal subset of C-Kermit's capabilities; the interactive command set is far richer. UNIX KERMIT Page 119 On systems with dialout modems, C-Kermit can use its command file and login script facilities to replicate the file transfer functionality of UUCP among heterogeneous operating systems, including the use of scheduled (e.g. late night) unattended operation. 9.1. The Unix File System Consult your Unix manual for details about the file system under your version of Unix. For the purposes of Kermit, several things are worth briefly noting. Unix files generally have lowercase names, possibly containing one or more dots or other special characters. Unix directories are tree-structured. Directory levels are separated by slash ("/") characters. For example, /usr/foo/bar denotes the file bar in the directory /usr/foo. Wildcard or "meta" characters allow groups of files to be specified. "*" matches any string; "?" matches any single character. When C-Kermit is invoked with file arguments specified on the Unix command line, the Unix shell (Bourne Shell, C-Shell, etc) expands the meta characters itself, and in this case a wider variety is available. For example, kermit -s ~/ck[uvm]*.{upd,bwr}] is expanded by the Berkeley C-Shell into a list of all the files in the user's home directory (~/) that start with the characters "ck", followed by a single character "u", "v", or "m", followed by zero or more characters, followed by a dot, followed by one of the strings "upd" or "bwr". Internally, the C-Kermit program itself expands only the "*" and "?" meta characters. Unix files are linear streams of 8-bit bytes. Text files consist of 7-bit AS- CII characters, with the high-order bit off (0), and lines separated by the Unix newline character, which is linefeed (LF, ASCII 10). This distinguishes Unix text files from those on most other ASCII systems, in which lines are separated by a carriage-return linefeed sequence (CRLF, ASCII 13 followed by ASCII 10). Binary files are likely to contain data in the high bits of the file bytes, and have no particular line or record structure. When transferring files, C-Kermit will convert between upper and lower case filenames and between LF and CRLF line terminators automatically, unless told to do otherwise. When binary files must be transferred, the program must be instructed not to perform LF/CRLF conversion (-i on the command line or "set file type binary" interactively; see below). 9.2. File Transfer If C-Kermit is in local mode, the screen (stdout) is continously updated to show the progress of the file transer. A dot is printed for every four data packets, other packets are shown by type: I Exchange Parameter Information R Receive Initiate S Send Initiate UNIX KERMIT Page 120 F File Header G Generic Server Command C Remote Host Command N Negative Acknowledgement (NAK) E Fatal Error T Indicates a timeout occurred Q Indicates a damaged, undesired, or illegal packet was received % Indicates a packet was retransmitted You may type certain "interrupt" commands during file transfer: Control-F: Interrupt the current File, and go on to the next (if any). Control-B: Interrupt the entire Batch of files, terminate the transaction. Control-R: Resend the current packet Control-A: Display a status report for the current transaction. These interrupt characters differ from the ones used in other Kermit implemen- tations to avoid conflict with commonly used Unix shell interrupt characters. With Version 7, System III, and System V implementations of Unix, interrupt commands must be preceeded by the 'connect' escape character (e.g. normally-\). CAUTION: If Control-F or Control-B is used to cancel an incoming file, and a file of the same name previously existed, and the "file warning" feature is not enabled, then the previous copy of the file will dis- appear. EMERGENCY EXIT: When running Unix Kermit in remote mode, if you have started a protocol operation (sending or receiving a file, server command wait, etc), you will not be able to regain control of the terminal until the protocol operation has run its course (completed or timed out). In particular, you cannot stop the protocol by typing the normal Unix interrupt characters, since the terminal has been put in "raw mode". If you need to regain control quickly -- for in- stance, because the protocol is stuck -- you can type the following sequence of four characters directly to the Unix Kermit program ("connect" first if necessary): Control-A Control-C Control-C Carriage-Return This will cause the program to exit and restore the terminal to normal. 9.3. Command Line Operation The C-Kermit command line syntax has been changed from that of earlier releases of Unix Kermit to conform to the Proposed Syntax Standards for Unix System Com- mands put forth by Kathy Hemenway and Helene Armitage of AT&T Bell Laboratories in Unix/World, Vol.1, No.3, 1984. The rules that apply are: - Command names must be between 2 and 9 characters ("kermit" is 6). - Command names must include lower case letters and digits only. - An option name is a single character. - Options are delimited by '-'. - Options with no arguments may be grouped (bundled) behind one delimiter. - Option-arguments cannot be optional. - Arguments immediately follow options, separated by whitespace. UNIX KERMIT Page 121 - The order of options does not matter. - '-' preceded and followed by whitespace means standard input. A group of bundled options may end with an option that has an argument. The following notation is used in command descriptions: fn A Unix file specification, possibly containing the "wildcard" charac- ters `*' or `?' (`*' matches all character strings, `?' matches any single character). fn1 A Unix file specification which may not contain `*' or `?'. rfn A remote file specification in the remote system's own syntax, which may denote a single file or a group of files. rfn1 A remote file specification which should denote only a single file. n A decimal number between 0 and 94. c A decimal number between 0 and 127 representing the value of an ASCII character. cc A decimal number between 0 and 31, or else exactly 127, representing the value of an ASCII control character. [ ] Any field in square braces is optional. {x,y,z} Alternatives are listed in curly braces. C-Kermit command line options may specify either actions or settings. If C-Kermit is invoked with a command line that specifies no actions, then it will issue a prompt and begin interactive dialog. Action options specify either protocol transactions or terminal connection. -s fn Send the specified file or files. If fn contains wildcard (meta) characters, the Unix shell expands it into a list. If fn is '-' then kermit sends from standard input, which must come from a file: kermit -s - < foo.bar or a parallel process: ls -l | kermit -s - You cannot use this mechanism to send terminal typein. If you want to send a file whose name is "-" you can precede it with a path name, as in kermit -s ./- -r Receive a file or files. Wait passively for files to arrive. -k Receive (passively) a file or files, sending them to standard output. This option can be used in several ways: UNIX KERMIT Page 122 kermit -k Displays the incoming files on your screen; to be used only in "local mode" (see below). kermit -k > fn1 Sends the incoming file or files to the named file, fn1. If more than one file arrives, all are concatenated together into the single file fn1. kermit -k | command Pipes the incoming data (single or multiple files) to the indicated command, as in kermit -k | sort > sorted.stuff -a fn1 If you have specified a file transfer option, you may specify an alter- nate name for a single file with the -a option. For example, kermit -s foo -a bar sends the file foo telling the receiver that its name is bar. If more than one file arrives or is sent, only the first file is affected by the -a option: kermit -ra baz stores the first incoming file under the name baz. -x Begin server operation. May be used in either local or remote mode. Before proceeding, a few words about remote and local operation are necessary. C-Kermit is "local" if it is running on PC or workstation that you are using directly, or if it is running on a multiuser system and transferring files over an external communication line -- not your job's controlling terminal or con- sole. C-Kermit is remote if it is running on a multiuser system and transfer- ring files over its own controlling terminal's communication line, connected to your PC or workstation. If you are running C-Kermit on a PC, it is in local mode by default, with the "back port" designated for file transfer and terminal connection. If you are running C-Kermit on a multiuser (timesharing) system, it is in remote mode un- less you explicitly point it at an external line for file transfer or terminal connection. The following command sets C-Kermit's "mode": -l dev Line -- Specify a terminal line to use for file transfer and terminal connection, as in kermit -l /dev/ttyi5 When an external line is being used, you might also need some additional op- tions for successful communication with the remote system: -b n Baud -- Specify the baud rate for the line given in the -l option, as in kermit -l /dev/ttyi5 -b 9600 UNIX KERMIT Page 123 This option should always be included with the -l option, since the speed of an external line is not necessarily what you expect. -p x Parity -- e,o,m,s,n (even, odd, mark, space, or none). If parity is other than none, then the 8th-bit prefixing mechanism will be used for transferring 8-bit binary data, provided the opposite Kermit agrees. The default parity is none. -t Specifies half duplex, line turnaround with XON as the handshake character. The following commands may be used only with a C-Kermit which is local -- ei- ther by default or else because the -l option has been specified. -g rfn Actively request a remote server to send the named file or files; rfn is a file specification in the remote host's own syntax. If fn happens to contain any special shell characters, like '*', these must be quoted, as in kermit -g x\*.\? -f Send a 'finish' command to a remote server. -c Establish a terminal connection over the specified or default com- munication line, before any protocol transaction takes place. Get back to the local system by typing the escape character (normally Control-Backslash) followed by the letter 'c'. -n Like -c, but after a protocol transaction takes place; -c and -n may both be used in the same command. The use of -n and -c is illustrated below. On a timesharing system, the -l and -b options will also have to be included with the -r, -k, or -s options if the other Kermit is on a remote system. Several other command-line options are provided: -i Specifies that files should be sent or received exactly "as is" with no conversions. This option is necessary for transmitting binary files. It may also be used to slightly boost efficiency in Unix-to-Unix trans- fers of text files by eliminating CRLF/newline conversion. -w Write-Protect -- Avoid filename collisions for incoming files. -q Quiet -- Suppress screen update during file transfer, for instance to allow a file transfer to proceed in the background. -d Debug -- Record debugging information in the file debug.log in the cur- rent directory. Use this option if you believe the program is mis- behaving, and show the resulting log to your local kermit maintainer. -h Help -- Display a brief synopsis of the command line options. The command line may contain no more than one protocol action option. Files are sent with their own names, except that lowercase letters are raised UNIX KERMIT Page 124 to upper, pathnames are stripped off, certain special characters like (`~') and (`#') are changed to `X', and if the file name begins with a period, an `X' is inserted before it. Incoming files are stored under their own names except that uppercase letters are lowered, and, if -w was specified, a "generation number" is appended to the name if it has the same name as an existing file which would otherwise be overwritten. If the -a option is included, then the same rules apply to its argument. The file transfer display shows any trans- formations performed upon filenames. During transmission, files are encoded as follows: - Control characters are converted to prefixed printables. - Sequences of repeated characters are collapsed via repeat counts, if the other Kermit is also capable of repeated-character compression. - If parity is being used on the communication line, data characters with the 8th (parity) bit on are specially prefixed, provided the other Kermit is capable of 8th-bit prefixing; if not, 8-bit binary files cannot be successfully transferred. - Conversion is done between Unix newlines and carriage-return-linefeed sequences unless the -i option was specified. Command Line Examples: kermit -l /dev/ttyi5 -b 1200 -cn -r This command connects you to the system on the other end of ttyi5 at 1200 baud, where you presumably log in and run Kermit with a 'send' command. After you escape back, C-Kermit waits for a file (or files) to arrive. When the file transfer is completed, you are again connected to the remote system so that you can logout. kermit -l /dev/ttyi4 -b 1800 -cntp m -r -a foo This command is like the preceding one, except the remote system in this case uses half duplex communication with mark parity. The first file that arrives is stored under the name foo. kermit -l /dev/ttyi6 -b 9600 -c | tek This example uses Kermit to connect your terminal to the system at the other end of ttyi6. The C-Kermit terminal connection does not provide any particular terminal emulation, so C-Kermit's standard i/o is piped through a (hypothetical) program called tek, which performs (say) Tektronix emulation. kermit -l /dev/ttyi6 -b 9600 -nf This command would be used to shut down a remote server and then connect to the remote system, in order to log out or to make further use of it. The -n option UNIX KERMIT Page 125 is invoked after -f (-c would have been invoked before). kermit -l /dev/ttyi6 -b 9600 -qg foo.\* & This command causes C-Kermit to be invoked in the background, getting a group of files from a remote server (note the quoting of the `*' character). No dis- play occurs on the screen, and the keyboard is not sampled for interruption commands. This allows other work to be done while file transfers proceed in the background. kermit -l /dev/ttyi6 -b 9600 -g foo.\* > foo.log < /dev/null & This command is like the previous one, except the file transfer display has been redirected to the file foo.log. Standard input is also redirected, to prevent C-Kermit from sampling it for interruption commands. kermit -iwx This command starts up C-Kermit as a server. Files are transmitted with no newline/carriage-return-linefeed conversion; the -i option is necessary for bi- nary file transfer and useful for Unix-to-Unix transfers. Incoming files that have the same names as existing files are given new, unique names. kermit -l /dev/ttyi6 -b 9600 This command sets the communication line and speed. Since no action is specified, C-Kermit issues a prompt and enters an interactive dialog with you. Any settings given on the command line remain in force during the dialog, un- less explicitly changed. kermit This command starts up Kermit interactively with all default settings. The next example shows how Unix Kermit might be used to send an entire direc- tory tree from one Unix system to another, using the tar program as Kermit's standard input and output. On the orginating system, in this case the remote, type (for instance): tar cf - /usr/fdc | kermit -is - This causes tar to send the directory /usr/fdc (and all its files and all its subdirectories and all their files...) to standard output instead of to a tape; kermit receives this as standard input and sends it as a binary file. On the receiving system, in this case the local one, type (for instance): kermit -il /dev/ttyi5 -b 9600 -k | tar xf - Kermit receives the tar archive, and sends it via standard output to its own UNIX KERMIT Page 126 copy of tar, which extracts from it a replica of the original directory tree. A final example shows how a Unix compression utility might be used to speed up Kermit file transfers: compress file | kermit -is - (sender) kermit -ik | uncompress (receiver) Exit Status Codes: Unix Kermit returns an exit status of zero, except when a fatal error is en- countered, where the exit status is set to one. With background operation (e.g., `&' at end of invoking command line) driven by scripted interactive com- mands (redirected standard input and/or take files), any failed interactive command (such as failed dial or script attempt) causes the fatal error exit. 9.4. Interactive Operation C-Kermit's interactive command prompt is "C-Kermit>". In response to this prompt, you may type any valid command. C-Kermit executes the command and then prompts you for another command. The process continues until you instruct the program to terminate. Commands begin with a keyword, normally an English verb, such as "send". You may omit trailing characters from any keyword, so long as you specify suf- ficient characters to distinguish it from any other keyword valid in that field. Certain commonly-used keywords (such as "send", "receive", "connect") have special non-unique abbreviations ("s" for "send", "r" for "receive", "c" for "connect"). Certain characters have special functions during typein of interactive com- mands: ? Question mark, typed at any point in a command, will produce a message explaining what is possible or expected at that point. Depending on the context, the message may be a brief phrase, a menu of keywords, or a list of files. ESC (The Escape or Altmode key) -- Request completion of the current keyword or filename, or insertion of a default value. The result will be a beep if the requested operation fails. DEL (The Delete or Rubout key) -- Delete the previous character from the command. You may also use BS (Backspace, Control-H) for this function. ^W (Control-W) -- Erase the rightmost word from the command line. ^U (Control-U) -- Erase the entire command. ^R (Control-R) -- Redisplay the current command. SP (Space) -- Delimits fields (keywords, filenames, numbers) within a com- mand. HT (Horizontal Tab) may also be used for this purpose. UNIX KERMIT Page 127 CR (Carriage Return) -- Enters the command for execution. LF (Linefeed) or FF (formfeed) may also be used for this purpose. \ (Backslash) -- Enter any of the above characters into the command, literally. To enter a backslash, type two backslashes in a row (\\). A backslash at the end of a command line causes the next line to be treated as a continuation line; this is useful for readability in com- mand files, especially in the 'script' command. You may type the editing characters (DEL, ^W, etc) repeatedly, to delete all the way back to the prompt. No action will be performed until the command is entered by typing carriage return, linefeed, or formfeed. If you make any mis- takes, you will receive an informative error message and a new prompt -- make liberal use of `?' and ESC to feel your way through the commands. One impor- tant command is "help" -- you should use it the first time you run C-Kermit. A command line beginning with a percent sign "%" is ignored. Such lines may be used to include illustrative commentary in Kermit command dialogs. Interactive C-Kermit accepts commands from files as well as from the keyboard. When you enter interactive dialog, C-Kermit looks for the file .kermrc in your home or current directory (first it looks in the home directory, then in the current one) and executes any commands it finds there. These commands must be in interactive format, not Unix command-line format. A "take" command is also provided for use at any time during an interactive session. Command files may be nested to any reasonable depth. Here is a brief list of C-Kermit interactive commands: ! Execute a Unix shell command, or start a shell. bye Terminate and log out a remote Kermit server. close Close a log file. connect Establish a terminal connection to a remote system. cwd Change Working Directory. dial Dial a telephone number. directory Display a directory listing. echo Display arguments literally. exit Exit from the program, closing any open files. finish Instruct a remote Kermit server to exit, but not log out. get Get files from a remote Kermit server. help Display a help message for a given command. log Open a log file -- debugging, packet, session, transaction. quit Same as 'exit'. receive Passively wait for files to arrive. remote Issue file management commands to a remote Kermit server. script Execute a login script with a remote system. send Send files. server Begin server operation. set Set various parameters. show Display values of 'set' parameters. space Display current disk space usage. statistics Display statistics about most recent transaction. take Execute commands from a file. The 'set' parameters are: UNIX KERMIT Page 128 block-check Level of packet error detection. delay How long to wait before sending first packet. duplex Specify which side echoes during 'connect'. escape-character Prefix for "escape commands" during 'connect'. file Set various file parameters. flow-control Communication line full-duplex flow control. handshake Communication line half-duplex turnaround character. incomplete Disposition for incompletely received files. line Communication line device name. modem-dialer Type of modem-dialer on communication line. parity Communication line character parity. prompt The C-Kermit program's interactive command prompt. receive Parameters for inbound packets. send Parameters for outbound packets. speed Communication line speed. The 'remote' commands are: cwd Change remote working directory. delete Delete remote files. directory Display a listing of remote file names. help Request help from a remote server. host Issue a command to the remote host in its own command language space Display current disk space usage on remote system. type Display a remote file on your screen. who Display who's logged in, or get information about a user. Most of these commands are described adequately in the Kermit User Guide. Spe- cial aspects of certain Unix Kermit commands are described below. THE 'SEND' COMMAND Syntax: send fn - or - send fn1 rfn1 Send the file or files denoted by fn to the other Kermit, which should be run- ning as a server, or which should be given the 'receive' command. Each file is sent under its own name (as described above, or as specified by the 'set file names' command). If the second form of the 'send' command is used, i.e. with fn1 denoting a single Unix file, rfn1 may be specified as a name to send it un- der. The 'send' command may be abbreviated to 's', even though 's' is not a unique abbreviation for a top-level C-Kermit command. The wildcard (meta) characters `*' and `?' are accepted in fn. If `?' is to be included, it must be prefixed by `\' to override its normal function of provid- ing help. `*' matches any string, `?' matches any single character. Other notations for file groups, like `[a-z]og', are not available in interactive commands (though of course they are available on the command line). When fn contains `*' or `?' characters, there is a limit to the number of files that can be matched, which varies from system to system. If you get the message "Too many files match" then you'll have to make a more judicious selection. If fn was of the form usr/longname/anotherlongname/* then C-Kermit's string space will fill up rapidly -- try doing a cwd (see UNIX KERMIT Page 129 below) to the path in question and reissuing the command. Note -- C-Kermit sends only from the current or specified directory. It does not traverse directory trees. If the source directory contains subdirectories, they will be skipped. Conversely, C-Kermit does not create directories when receiving files. If you have a need to do this, you can pipe tar through C-Kermit, as shown in the example on page 125, or under System III/V Unix you can use cpio. Another Note -- C-Kermit does not skip over "invisible" files that match the file specification; Unix systems usually treat files whose names start with a dot (like .login, .cshrc, and .kermrc) as invisible. Similarly for "temporary" files whose names start with "#". THE 'RECEIVE' COMMAND Syntax: receive - or - receive fn1 Passively wait for files to arrive from the other Kermit, which must be given the 'send' command -- the 'receive' command does not work in conjunction with a server (use 'get' for that). If fn1 is specified, store the first incoming file under that name. The 'receive' command may be abbreviated to 'r'. THE 'GET' COMMAND: Syntax: get rfn or: get rfn fn1 Request a remote Kermit server to send the named file or files. Since a remote file specification (or list) might contain spaces, which normally delimit fields of a C-Kermit command, an alternate form of the command is provided to allow the inbound file to be given a new name: type 'get' alone on a line, and you will be prompted separately for the remote and local file specifications, for example C-Kermit>get Remote file specification: profile exec Local name to store it under: profile.exec As with 'receive', if more than one file arrives as a result of the 'get' com- mand, only the first will be stored under the alternate name given by fn1; the remaining files will be stored under their own names if possible. If a `?' is to be included in the remote file specification, you must prefix it with `\' to suppress its normal function of providing help. If you have started a multiline 'get' command, you may escape from its lower- level prompts by typing a carriage return in response to the prompt, e.g. C-Kermit>get Remote file specification: foo Local name to store it under: (Type a carriage return here) UNIX KERMIT Page 130 (cancelled) C-Kermit> THE 'SERVER' COMMAND: The 'server' command places C-Kermit in "server mode" on the currently selected communication line. All further commands must arrive as valid Kermit packets from the Kermit on the other end of the line. The Unix Kermit server can respond to the following commands: Command Server Response get Sends files send Receives files bye Attempts to log itself out finish Exits to level from which it was invoked remote directory Sends directory lising remote delete Removes files remote cwd Changes working directory remote type Sends files to your screen remote space Reports about its disk usage remote who Shows who's logged in remote host Executes a Unix shell command remote help Lists these capabilities Note that the Unix Kermit server cannot always respond to a BYE command. It will attempt to do so using "kill()", but this will not work on all systems or under all conditions. If the Kermit server is directed at an external line (i.e. it is in "local mode") then the console may be used for other work if you have 'set file dis- play off'; normally the program expects the console to be used to observe file transfers and enter status queries or interruption commands. The way to get C-Kermit into background operation from interactive command level varies from system to system (e.g. on Berkeley Unix you would halt the program with ^Z and then use the C-Shell 'bg' command to continue it in the background). The more common method is to invoke the program with the desired command line arguments, including "-q", and with a terminating "&". When the Unix Kermit server is given a 'remote host' command, it executes it using the shell invoked upon login, e.g. the Bourne shell or the Berkeley C-Shell. THE 'REMOTE', 'BYE', AND 'FINISH' COMMANDS: C-Kermit may itself request services from a remote Kermit server. In addition to 'send' and 'get', the following commands may also be sent from C-Kermit to a Kermit server: remote cwd [directory] If the optional remote directory specification is included, you will be prompted on a separate line for a password, which will not echo as you type it. remote delete rfn delete remote file or files. UNIX KERMIT Page 131 remote directory [rfn] directory listing of remote files. remote host command command in remote host's own command language. remote space disk usage report from remote host. remote type [rfn] display remote file or files on the screen. remote who [user] display information about who's logged in. remote help display remote server's capabilities. bye and finish: When connected to a remote Kermit server, these commands cause the remote server to terminate; 'finish' returns it to Kermit or system command level (depending on the implementation or how the program was invoked); 'bye' also requests it to log itself out. THE 'LOG' AND 'CLOSE' COMMANDS: Syntax: log {debugging, packets, session, transactions} [ fn1 ] C-Kermit's progress may be logged in various ways. The 'log' command opens a log, the 'close' command closes it. In addition, all open logs are closed by the 'exit' and 'quit' commands. A name may be specified for a log file; if the name is omitted, the file is created with a default name as shown below. log debugging This produces a voluminous log of the internal workings of C-Kermit, of use to Kermit developers or maintainers in tracking down suspected bugs in the C-Kermit program. Use of this feature dramatically slows down the Kermit protocol. Default name: debug.log. log packets This produces a record of all the packets that go in and out of the com- munication port. This log is of use to Kermit maintainers who are tracking down protocol problems in either C-Kermit or any Kermit that C-Kermit is connected to. Default name: packet.log. log session This log will contain a copy of everything you see on your screen during the 'connect' command, except for local messages or interaction with local escape commands. Default name: session.log. log transactions The transaction log is a record of all the files that were sent or received while transaction logging was in effect. It includes time stamps and statistics, filename transformations, and records of any errors that may have occurred. The transaction log allows you to have long unattended file transfer sessions without fear of missing some vital screen message. Default name: transact.log. The 'close' command explicitly closes a log, e.g. 'close debug'. Note: Debug and Transaction logs are a compile-time option; C-Kermit may be compiled without these logs, in which case it will run faster, it will take up less space on the disk, and the commands relating to them will not be present. UNIX KERMIT Page 132 LOCAL FILE MANAGEMENT COMMANDS: Unix Kermit allows some degree of local file management from interactive com- mand level: directory [fn] Displays a listing of the names, modes, sizes, and dates of files matching fn (which defaults to `*'). Equivalent to `ls -l'. cwd [directory-name] Changes Kermit's working directory to the one given, or to the default directory if the directory name is omitted. This command affects only the Kermit process and any processes it may subsequently create. space Display information about disk space and/or quota in the current directory and device. ! [command] The command is executed by the Unix shell. If no command is specified, then an interactive shell is started; exiting from the shell, e.g. by typing Control-D, will return you to C-Kermit command level. C-Kermit at- tempts to use your preferred, customary shell. Use the `!' command to provide file management or other functions not explicitly provided by C-Kermit commands. The `!' command has certain peculiarities: - At least one space must separate the '!' from the shell command. - A 'cd' command executed in this manner will have no effect -- use the C-Kermit 'cwd' command instead. THE 'SET' AND 'SHOW' COMMANDS: Since Kermit is designed to allow diverse systems to communicate, it is often necessary to issue special instructions to allow the program to adapt to peculiarities of the another system or the communication path. These instruc- tions are accomplished by the 'set' command. The 'show' command may be used to display current settings. Here is a brief synopsis of settings available in the current release of C-Kermit: block-check {1, 2, 3} Determines the level of per-packet error detection. "1" is a single- character 6-bit checksum, folded to include the values of all bits from each character. "2" is a 2-character, 12-bit checksum. "3" is a 3-character, 16-bit cyclic redundancy check (CRC). The higher the block check, the better the error detection and correction and the higher the resulting overhead. Type 1 is most commonly used; it is supported by all Kermit implementations, and it has proven adequate in most circumstances. Types 2 or 3 would be used to advantage when transferring 8-bit binary files over noisy lines. delay n How many seconds to wait before sending the first packet after a 'send' command. Used in remote mode to give you time to escape back to your local Kermit and issue a 'receive' command. Normally 5 seconds. UNIX KERMIT Page 133 duplex {full, half} For use during 'connect'. Specifies which side is doing the echoing; 'full' means the other side, 'half' means C-Kermit must echo typein itself. escape-character cc For use during 'connect' to get C-Kermit's attention. The escape character acts as a prefix to an 'escape command', for instance to close the connec- tion and return to C-Kermit or Unix command level. The normal escape character is Control-Backslash (28). The escape character is also used in System III/V implementations to prefix interrupt commands during file transfers. file {display, names, type, warning} Establish various file-related parameters: display {on, off} Normally 'on'; when in local mode, display progress of file transfers on the screen (stdout), and listen to the keyboard (stdin) for inter- ruptions. If off (-q on command line) none of this is done, and the file transfer may proceed in the background oblivious to any other work concurrently done at the console terminal. names {converted, literal} Normally converted, which mean that outbound filenames have path specifications stripped, lowercase letters raised to upper, tildes and extra periods changed to X's, and an X inserted in front of any name that starts with period. Incoming files have uppercase letters lowered. Literal means that none of these conversions are done; there- fore, any directory path appearing in a received file specification must exist and be write-accessible. When literal naming is being used, the sender should not use path names in the file specification unless the same path exists on the target system and is writable. type {binary, text} Normally text, which means that conversion is done between Unix newline characters and the carriage-return/linefeed sequences required by the canonical Kermit file transmission format, and in common use on non- Unix systems. Binary means to transmit file contents without conver- sion. Binary (`-i' in command line notation) is necessary for binary files, and desirable in all Unix-to-Unix transactions to cut down on overhead. warning {on, off} Normally off, which means that incoming files will silently overwrite existing files of the same name. When on (`-w' on command line) Kermit will check if an arriving file would overwrite an existing file; if so, it will construct a new name for the arriving file, of the form foo~n, where foo is the name they share and n is a "generation number"; if foo exists, then the new file will be called foo~1. If foo and foo~1 ex- ist, the new file will be foo~2, and so on. If the new name would be longer than the maximum length for a filename, then characters would be deleted from the end first, for instance, thelongestname on a system with a limit of 14 characters would become thelongestn~1. CAUTION: If Control-F or Control-B is used to cancel an incom- ing file, and a file of the same name previously existed, and UNIX KERMIT Page 134 the "file warning" feature is not enabled, then the previous copy of the file will disappear. flow-control {none, xon/xoff} Normally xon/xoff for full duplex flow control. Should be set to 'none' if the other system cannot do xon/xoff flow control, or if you have issued a 'set handshake' command. If set to xon/xoff, then handshake should be set to none. This setting applies during both terminal connection and file transfer. incomplete {discard, keep} Disposition for incompletely received files. If an incoming file is inter- rupted or an error occurs during transfer, the part that was received so far is normally discarded. If you "set incomplete keep" then such file fragments will be kept. handshake {xon, xoff, cr, lf, bell, esc, none} Normally none. Otherwise, half-duplex communication line turnaround hand- shaking is done, which means Unix Kermit will not reply to a packet until it has received the indicated handshake character or has timed out waiting for it; the handshake setting applies only during file transfer. If you set handshake to other than none, then flow should be set to none. line [device-name] The device name for the communication line to be used for file transfer and terminal connection, e.g. /dev/ttyi3. If you specify a device name, Kermit will be in local mode, and you should remember to issue any other necessary 'set' commands, such as 'set speed'. If you omit the device name, Kermit will revert to its default mode of operation. If you specify /dev/tty, Kermit will enter remote mode (useful when logged in through the "back port" of a system normally used as a local-mode workstation). When Unix Kermit enters local mode, it attempts to synchronize with other programs (like uucp) that use external communication lines so as to prevent two programs using the same line at once; before attempting to lock the specified line, it will close and unlock any external line that was previously in use. The method used for locking is the "uucp lock file", explained in more detail later. modem-dialer {direct, hayes, racalvadic, ventel, ...} The type of modem dialer on the communication line. "Direct" indicates ei- ther there is no dialout modem, or that if the line requires carrier detec- tion to open, then 'set line' will hang waiting for an incoming call. "Hayes", "Ventel", and the others indicate that 'set line' (or the -l argument) will prepare for a subsequent 'dial' command for the given dialer. Support for new dialers is added from time to time, so type 'set modem ?' for a list of those supported in your copy of Kermit. See the description of the 'dial' command parity {even, odd, mark, space, none} Specify character parity for use in packets and terminal connection, nor- mally none. If other than none, C-Kermit will seek to use the 8th-bit prefixing mechanism for transferring 8-bit binary data, which can be used successfully only if the other Kermit agrees; if not, 8-bit binary data cannot be successfully transferred. prompt [string] UNIX KERMIT Page 135 The given string will be substituted for "C-Kermit>" as this program's prompt. If the string is omitted, the prompt will revert to "C-Kermit>". If the string is enclosed in doublequotes, the quotes will be stripped and any leading and trailing blanks will be retained. send parameter Establish parameters to use when sending packets. These will be in effect only for the initial packet sent, since the other Kermit may override these parameters during the protocol parameter exchange (unless noted below). end-of-packet cc Specifies the control character needed by the other Kermit to recognize the end of a packet. C-Kermit sends this character at the end of each packet. Normally 13 (carriage return), which most Kermit implemen- tations require. Other Kermits require no terminator at all, still others may require a different terminator, like linefeed (10). packet-length n Specify the maximum packet length to send. Normally 90. Shorter packet lengths can be useful on noisy lines, or with systems or front ends or networks that have small buffers. The shorter the packet, the higher the overhead, but the lower the chance of a packet being cor- rupted by noise, and the less time to retransmit corrupted packets. This command overrides the value requested by the other Kermit during protocol initiation. pad-character cc Designate a character to send before each packet. Normally, none is sent. Outbound padding is sometimes necessary for communicating with slow half duplex systems that provide no other means of line turnaround control. It can also be used to send special characters to communica- tions equipment that needs to be put in "transparent" or "no echo" mode, when this can be accomplished in by feeding it a certain control character. padding n How many pad characters to send, normally 0. start-of-packet cc The normal Kermit packet prefix is Control-A (1); this command changes the prefix C-Kermit puts on outbound packets. The only reasons this should ever be changed would be: Some piece of equipment somewhere be- tween the two Kermit programs will not pass through a Control-A; or, some piece of of equipment similarly placed is echoing its input. In the latter case, the recipient of such an echo can change the packet prefix for outbound packets to be different from that of arriving pack- ets, so that the echoed packets will be ignored. The opposite Kermit must also be told to change the prefix for its inbound packets. timeout n Specifies the number of seconds you want the other Kermit to wait for a packet before timing it out and requesting retransmission. receive parameter Establish parameters to request the other Kermit to use when sending pack- ets. UNIX KERMIT Page 136 end-of-packet cc Requests the other Kermit to terminate its packets with the specified character. packet-length n Specify the maximum packet length to that you want the other Kermit to send. Normally 90. pad-character cc C-Kermit normally does not need to have incoming packets preceded with pad characters. This command allows C-Kermit to request the other Ker- mit to use cc as a pad character. Default cc is NUL, ASCII 0. padding n How many pad characters to ask for, normally 0. start-of-packet cc Change the prefix C-Kermit looks for on inbound packets to correspond with what the other Kermit is sending. timeout n Normally, each Kermit partner sets its packet timeout interval based on what the opposite Kermit requests. This command allows you to override the normal procedure and specify a timeout interval for Unix Kermit to use when waiting for packets from the other Kermit. If you specify 0, then no timeouts will occur, and Unix Kermit will wait forever for ex- pected packets to arrive. speed {0, 110, 150, 300, 600, 1200, 1800, 2400, 4800, 9600} The baud rate for the external communication line. This command cannot be used to change the speed of your own console terminal. Many Unix systems are set up in such a way that you must give this command after a 'set line' command before you can use the line. 'set baud' is a synomym for 'set speed'. THE 'SHOW' COMMAND: Syntax: show {parameters, versions} The "show" command with the default argument of "parameters" displays the values of all the 'set' parameters described above. If you type "show versions", then C-Kermit will display the version numbers and dates of all its internal modules. You should use the "show versions" command to ascertain the vintage of your Kermit program before reporting problems to Kermit maintainers. THE 'STATISTICS' COMMAND: The statistics command displays information about the most recent Kermit protocol transaction, including file and communication line i/o, timing and ef- ficiency, as well as what encoding options were in effect (such as 8th-bit prefixing, repeat-count compression). UNIX KERMIT Page 137 THE 'TAKE' AND 'ECHO' COMMANDS: Syntax: take fn1 echo [text to be echoed] The 'take' command instructs C-Kermit to execute commands from the named file. The file may contain any interactive C-Kermit commands, including 'take'; com- mand files may be nested to any reasonable depth. The 'echo' command may be used within command files to issue greetings, announce progress, ring the ter- minal bell, etc. The 'echo' command should not be confused with the Unix 'echo' command, which can be used to show how meta characters would be expanded. The Kermit echo command simply displays its text argument (almost) literally at the terminal; the argument may contain octal escapes of the form "\ooo", where o is an octal digit (0-7), and there may be 1, 2, or 3 such digits, whose value specify an ASCII character, such as "\007" (or "\07" or just "\7") for beep, "\012" for newline, etc. Of course, each backslash must be must be entered twice in order for it to be passed along to the echo command by the Kermit command parser. Take-command files are in exactly the same syntax as interactive commands. Note that this implies that if you want to include special characters like question mark or backslash that you would have to quote with backslash when typing interactive commands, you must quote these characters the same way in command files. Long lines may be continued by ending them with a single back- slash. Command files may be used in lieu of command macros, which have not been imple- mented in this version of C-Kermit. For instance, if you commonly connect to a system called 'B' that is connected to ttyh7 at 4800 baud, you could create a file called b containing the commands % C-Kermit command file to connect to System B thru /dev/ttyh7 set line /dev/ttyh7 set speed 4800 % Beep and give message echo \\007Connecting to System B... connect and then simply type 'take b' (or 't b' since no other commands begin with the letter 't') whenever you wish to connect to system B. Note the comment lines and the beep inserted into the 'echo' command. For connecting to IBM mainframes, a number of 'set' commands are required; these, too, are conveniently collected into a 'take' file like this one: % Sample C-Kermit command file to set up current line % for IBM mainframe communication % set parity mark set handshake xon set flow-control none set duplex half Note that no single command is available to wipe out all of these settings and return C-Kermit to its default startup state; to do that, you can either res- UNIX KERMIT Page 138 tart the program, or else make a command file that executes the necessary 'set' commands: % Sample C-Kermit command file to restore normal settings % set parity none set handshake none set flow-control xon/xoff set duplex full An implicit 'take' command is executed upon your .kermrc file upon C-Kermit's initial entry into interactive dialog. The .kermrc file should contain 'set' or other commands you want to be in effect at all times. For instance, you might want override the default action when incoming files have the same names as existing files -- in that case, put the command set file warning on in your .kermrc file. On some non-Unix systems that run C-Kermit, this file might have a different name, such as kermit.ini. NOTE: The initialization file is currently not processed if Kermit is invoked with an action command from the command line. The same effect can be achieved, however, by defining an alias or shell procedure that starts up Kermit with the desired command line options. Commands executed from take files are not echoed at the terminal. If you want to see the commands as well as their output, you could feed the command file to C-Kermit via redirected stdin, as in 'kermit < cmdfile' Errors encountered during execution of take files (such as failure to complete dial or script operations) cause termination of the current take file, popping to the level that invoked it (take file, interactive level, or the shell). When kermit is executed in the background, errors during execution of a take file are fatal. THE 'CONNECT' COMMAND: The connect command links your terminal to another computer as if it were a lo- cal terminal to that computer, through the device specified in the most recent 'set line' command, or through the default device if your system is a PC or workstation. All characters you type at your keyboard are sent out the com- munication line, all characters arriving at the communication port are dis- played on your screen. Current settings of speed, parity, duplex, and flow- control are honored. If you have issued a 'log session' command, everything you see on your screen will also be recorded to your session log. This provides a way to "capture" files from systems that don't have Kermit programs available. To get back to your own system, you must type the escape character, which is Control-Backslash (^\) unless you have changed it with the 'set escape' com- mand, followed by a single-character command, such as 'c' for "close connection". Single-character commands include: UNIX KERMIT Page 139 c Close the connection b Send a BREAK signal 0 (zero) send a null s Give a status report about the connection h Hangup the phone ^\ Send Control-Backslash itself (whatever you have defined the escape character to be, typed twice in a row sends one copy of it). Uppercase and control equivalents for these letters are also accepted. A space typed after the escape character is ignored. Any other character will produce a beep. The connect command simply displays incoming characters on the screen. It is assumed any screen control sequences sent by the host will be handled by the firmware in your terminal or PC. If terminal emulation is desired, then the connect command can invoked from the Unix command line (-c or -n), piped through a terminal emulation filter, e.g. kermit -l /dev/acu -b 1200 -c | tek 'c' is an acceptable non-unique abbreviation for 'connect'. THE 'DIAL' COMMAND: Syntax: dial telephone-number-string This command controls dialout modems; you should have already issued a "set line" and "set speed" command to identify the terminal device, and a "set modem" command to identify the type of modem to be used for dialing. In the "dial" command, you supply the phone number and the Kermit program feeds it to the modem in the appropriate format and then interprets dialer return codes and modem signals to inform you whether the call was completed. The telephone- number-string may contain imbedded modem-dialer commands, such as comma for Hayes pause, or `&' for Ventel dialtone wait and `%' for Ventel pause (consult your modem manual for details). At the time of this writing, support is included for the following modems: - Cermetek Info-Mate 212A - DEC DF03-AC - DEC DF100 Series - DEC DF200 Series - General DataComm 212A/ED - Hayes Smartmodem 1200 and compatibles - Penril - Racal Vadic - US Robotics 212A - Ventel Support for new modems is added to the program from time to time; you can check the current list by typing "set modem ?". The device used for dialing out is the one selected in the most recent "set line" command (or on a workstation, the default line if no "set line" command was given). The "dial" command calls locks the path (see the section on line UNIX KERMIT Page 140 locking below) and establishes a call on an exclusive basis. If it is desired to dial a call and then return to the shell (such as to do kermit activities depending on standard in/out redirection), it is necessary to place the dialed call under one device name (say, "/dev/cua0") and then escape to the shell within Kermit on a linked device which is separate from the dialed line (say, "/dev/cul0"). This is the same technique used by uucp (to allow locks to be placed separately for dialing and conversing). Because modem dialers have strict requirements to override the carrier-detect signal most Unix implementations expect, the sequence for dialing is more rigid than most other C-Kermit procedures. Example one: kermit -l /dev/cul0 -b 1200 C-Kermit>set modem-dialer hayes hint: abbreviate set m h C-Kermit>dial 9,5551212 Connected! C-Kermit>connect hint: abbreviate c logon, request remote server, etc. C-Kermit> ... C-Kermit>quit hint: abbreviate q this disconnects modem, and unlocks line. Example two: kermit C-Kermit>set modem-dialer ventel C-Kermit>set line /dev/cul0 C-Kermit>dial 9&5551212% Connected! C-Kermit> ... Example three: kermit C-Kermit>take my-dial-procedure Connected! file my-dial-procedure: set modem hayes set line /dev/tty99 dial 5551212 connect For Hayes dialers, two important switch settings are #1 and #6. #1 should be up so that the DTR is only asserted when the line is 'open'. #6 should be up so carrier-detect functions properly. Switches #2 (English versus digit result codes) and #4 (Hayes echoes modem commands) may be in either position. For any dialers in general, this Kermit program requires that the modem provide the "carrier detect" signal when a call is in progress, and remove that signal when the call completes or the line drops. If a switch setting is available to force carrier detect, it should not be in that setting. Secondly, this Kermit program requires that the modem track the computer's "data terminal ready" sig- UNIX KERMIT Page 141 nal (DTR). If a switch setting is available to simulate DTR asserted within the modem, then it should not be in that setting. Otherwise the modem will be unable to hang up at the end of a call or when interrupts are received by Ker- mit. If you want to interrupt a dial command in progress (for instance, because you just realize that you gave it the wrong number), type a Control-C to get back to command level. THE 'SCRIPT' COMMAND: Syntax: script expect send [expect send] . . . "expect" has the syntax: expect[-send-expect[-send-expect[...]]] This command facilitates logging into a remote system and/or invoking programs or other facilities after login on a remote system. This login script facility operates in a manner similar to that commonly used by the Unix uucp System's "L.sys" file entries. A login script is a sequence of the form: expect send [expect send] . . . where expect is a prompt or message to be issued by the remote site, and send is the string (names, numbers, etc) to return. The send may also be the keyword EOT, to send Control-D, or BREAK, to send a break signal. Letters in send may be prefixed by `~' to send special characters. These are: ~b backspace ~s space ~q `?'(trapped by Kermit's command interpreter) ~n linefeed ~r carriage return ~t tab ~' single quote ~~ tilde ~" double quote ~x XON (Control-Q) ~c don't append a carriage return ~o[o[o]] an octal character ~d delay approx 1/3 second during send ~w[d[d]] wait specified interval during expect, then time out As with some uucp systems, sent strings are followed by ~r unless they have a ~c. Only the last 7 characters in each expect are matched. A null expect, e.g. ~0 or two adjacent dashes, causes a short delay before proceeding to the next send sequence. A null expect always succeeds. As with uucp, if the expect string does not arrive, the script attempt fails. If you expect that a sequence might not arrive, as with uucp, conditional se- quences may be expressed in the form: UNIX KERMIT Page 142 -send-expect[-send-expect[...]] where dashed sequences are followed as long as previous expects fail. Timeouts for expects can be specified using ~w; ~w with no arguments waits 15 seconds. Expect/send transactions can be easily be debugged by logging transactions. This records all exchanges, both expected and actual. Note that `\' characters in login scripts, as in any other C-Kermit interactive commands, must be doubled up. A line may be ended with a single `\' for con- tinuation. Example one: Using a modem, dial a UNIX host site. Expect "login" (...gin), and if it doesn't come, simply send a null string with a ~r. (Some Unixes require either an EOT or a BREAK instead of the null sequence, depending on the particular site's "logger" program.) After providing user id and password, respond "x" to a question-mark prompt, expect the Bourne shell "$" prompt (and send return if it doesn't arrive). Then cd to directory kermit, and run the program called "wermit", entering the interactive connect state after wermit is loaded. set modem-dialer ventel set line /dev/tty77 set baud 1200 dial 9&5551212 script gin:--gin:--gin: smith ssword: mysecret ~q x $--$ \ cd~skermit $ wermit connect Example two: Using a modem, dial the Telenet network. This network expects three returns with slight delays between them. These are sent following null expects. The single return is here sent as a null string, with a return appended by default. Four returns are sent to be safe before looking for the prompt. Then the Telenet id and password are entered. Then telenet is instructed to connect to a host site (c 12345). The host has a data switch, and to "which system" it responds "myhost". This is followed by a TOPS-20 logon, and a request to load Kermit, set even parity, and enter the server mode. Files are then exchanged. The commands are in a take file; note the continuation of the 'script' command onto several lines using the `\' terminator. set modem-dialer hayes set line /dev/cul0 set baud 1200 dial 9,5551212 set parity even script ~0 ~0 ~0 ~0 ~0 ~0 ~0 ~0 @--@--@ id~saa001122 = 002211 @ \ c~s12345 ystem-c~s12345-ystem myhost @ joe~ssecret @ kermit \ > set~sparity~seven > server send some.stuff get some.otherstuff bye quit UNIX KERMIT Page 143 Since these commands may be executed totally in the background, they can also be scheduled. A typical shell script, which might be scheduled by cron, would be as follows (csh used for this example): # #keep trying to dial and log onto remote host and exchange files #wait 10 minutes before retrying if dial or script fail. # cd someplace while ( 1 ) kermit < /tonight.cmd >> nightly.log & if ( ! $status ) break sleep 600 end File tonight.cmd might have two takes in it, for example, one to take a file with the set modem, set line, set baud, dial, and script, and a second take of a file with send/get commands for the remote server. The last lines of tonight.cmd should be a bye and a quit. THE 'HELP' COMMAND: Syntax: help or: help keyword or: help {set, remote} keyword Brief help messages or menus are always available at interactive command level by typing a question mark at any point. A slightly more verbose form of help is available through the 'help' command. The 'help' command with no arguments prints a brief summary of how to enter commands and how to get further help. 'help' may be followed by one of the top-level C-Kermit command keywords, such as 'send', to request information about a command. Commands such as 'set' and 'remote' have a further level of help. Thus you may type 'help', 'help set', or 'help set parity'; each will provide a successively more detailed level of help. THE 'EXIT' AND 'QUIT' COMMANDS: These two commands are identical. Both of them do the following: - Attempt to insure that the terminal is returned to normal. - Relinquish access to any communication line assigned via 'set line'. - Relinquish any uucp and multiuser locks on the communications line. - Hang up the modem, if the communications line supports data terminal ready. - Close any open log files. After exit from C-Kermit, your default directory will be the same as when you started the program. The 'exit' command is issued implicitly whenever C-Kermit halts normally, e.g. after a command line invocation, or after certain kinds of interruptions. UNIX KERMIT Page 144 9.5. UUCP Lock Files Unix has no standard way of obtaining exclusive access to an external com- munication line. When you issue the 'set line' command to Unix Kermit, Unix would normally grant you access to the line even if some other process is making use of it. The method adopted by most Unix systems to handle this situation is the "UUCP lock file". UUCP, the Unix-to-Unix Copy program, creates a file in its directory (usually /usr/spool/uucp, on some systems /etc/locks) with a name like LCK..name, where name is the device name, for in- stance tty07. Unix Kermit uses UUCP lock files in order to avoid conflicts with UUCP, tip, or other programs that follow this convention. Whenever you attempt to access an external line using the 'set line' command or `-l' on the command line, Kermit looks in the UUCP directory for a lock file corresponding to that device. For instance, if you 'set line /dev/ttyi6' then Kermit looks for the file /usr/spool/uucp/LCK..ttyi6 If it finds this file, it gives you an error message and a directory listing of the file so that you can see who is using it, e.g. -r--r--r-- 1 fdc 4 May 7 13:02 /usr/spool/uucp/LCK..ttyi6 In this case, you would look up user fdc to find out how soon the line will be- come free. This convention requires that the uucp directory be publicly readable and writable. If it is not, the program will issue an appropriate warning message, but will allow you to proceed at your own risk (and the risk of anyone else who might also be using the same line). If no lock file is found, Unix Kermit will attempt create one, thus preventing anyone who subsequently tries to run Kermit, UUCP, tip, or similar programs on the same line from gaining access until you release the line. If Kermit could not create the lock file (for instance because the uucp directory is write- protected), then you will receive a warning message but will be allowed to proceed at your -- and everyone else's -- risk. When Kermit terminates nor- mally, your lock file is removed. Even when the lock directory is writable and readable, the locking mechanism depends upon all users using the same name for the same device. If a device has more than one path associated with it, then a lock can be circumvented by using an alias. When a lock-creating program abruptly terminates, e.g. because it crashes or is killed via shell command, the lock file remains in the uucp directory, spuriously indicating that the line is in use. If the lock file is owned by yourself, you may remove it. Otherwise, you'll have to get the owner or the system manager to remove it, or else wait for a system task to do so; uucp sup- ports a function (uuclean) which removes these files after a predetermined age -- uucp sites tend to run this function periodically via crontab. Locking is not needed, or used, if communications occur over the user's login terminal line (normally /dev/tty). UNIX KERMIT Page 145 It may be seen that line locking is fraught with peril. It is included in Unix Kermit only because other Unix communication programs rely on it. While it is naturally desirable to assure exclusive access to a line, it is also un- desirable to refuse access to a vacant line only because of a spurious lock file, or because the uucp directory is not appropriately protected. 9.6. C-Kermit under Berkeley or System III/V Unix: C-Kermit may be interrupted at command level or during file transfer by typing Control-C. The program will perform its normal exit function, restoring the terminal and releasing any lock. If a protocol transaction was in progress, an error packet will be sent to the opposite Kermit so that it can terminate cleanly. C-Kermit may be invoked in the background ("&" on shell commmand line). If a background process is "killed", the user will have to manually remove any lock file and may need to restore the modem. This is because the kill signal (kill(x,9)) cannot be trapped by Kermit. During execution of a system command ('directory', 'cwd', or `!'), C-Kermit can often be returned to command level by typing a single Control-C. (With System III/V, the usual interrupt function (often the DEL key) is replaced by Control-C.) Under Berkeley Unix only: C-Kermit may also be interrupted by ^Z to put the process in the background. In this case the terminal is not restored. You will have to type Control-J followed by "reset" followed by another Control-J to get your terminal back to normal. Control-C, Control-Z, and Control-\ lose their normal functions during terminal connection and also during file transfer when the controlling tty line is being used for packet i/o. If you are running C-Kermit in "quiet mode" in the foreground, then interrupt- ing the program with a console interrupt like Control-C will not restore the terminal to normal conversational operation. This is because the system call to enable console interrupt traps will cause the program to block if it's run- ning in the background, and the primary reason for quiet mode is to allow the program to run in the background without blocking, so that you can do other work in the foreground. If C-Kermit is run in the background ("&" on shell commmand line), then the in- terrupt signal (Control-C) (and System III/V quit signal) are ignored. This prevents an interrupt signal intended for a foreground job (say a compilation) from being trapped by a background Kermit session. 9.7. C-Kermit on the DEC Pro-3xx with Pro/Venix Version 1 The DEC Professional 300 series are PDP-11/23 based personal computers. Venix Version 1 is a Unix v7 derivative. It should not be confused with Venix Ver- sion 2, which is based on ATT System V; these comments apply to Venix Version 1 only. C-Kermit runs in local mode on the Pro-3xx when invoked from the con- sole; the default device is /dev/com1.dout. When connected to a remote system (using C-Kermit's 'connect' command), Pro/Venix itself (not Kermit) provides UNIX KERMIT Page 146 VT52 terminal emulation. Terminal operation at high speeds (like 9600 baud) requires xon/xoff flow control, which unfortunately interferes with applica- tions such as the EMACS that use Control-Q and Control-S as commands. When logging in to a Pro-3xx (or any workstation) through the "back port", it may be necessary to give the command "set line /dev/tty" in order to get C-Kermit to function correctly in remote mode (on a system in which it normally expects to be operating in local mode). 9.8. C-Kermit under VAX/VMS Version 4C of C-Kermit can be built using VAX-11 C to run under VMS. Most of the descriptions in this manual hold true, but it should be noted that as of this writing the VMS support is not thoroughly tested, and no explicit support exists for the various types of VMS files and their attributes. The C-Kermit init file for VMS is called KERMIT.INI. 9.9. C-Kermit on the Macintosh The "protocol kernel" of C-Kermit is also used by Columbia's Macintosh Kermit. The user and system interface is entirely different, and is covered in a separate document. 9.10. C-Kermit Restrictions and Known Bugs 1. Editing characters: The program's interactive command interrupt, delete, and kill characters are Control-C, Delete (or Backspace), and Control-U, respectively. There is currently no way to change them to suit your taste or match those used by your shell, in case those are different. 2. High baud rates: There's no way to specify baud rates higher than 9600 baud. Most Unix systems don't supply symbols for them (unless you use EXTA, EXTB), and even when they do, the program has no way of knowing whether a specific port's serial i/o controller supports those rates. 3. Modem controls: If a connection is made over a communication line (rather than on the controlling terminal line), and that line has modem controls, (e.g. data terminal ready and carrier detection implementation), returning to the shell level will disconnect the conversation. In that case, one should use interactive mode com- mands, and avoid use of piped shell-level operation (also see 'set modem-dialer' and 'dial' commands.) 4. Login Scripts: The present login scripts implementation follows the Unix conventions of uucp's "L.sys" file, rather than the normal Ker- mit "INPUT/OUTPUT" style, so there's no way to arbitrarily mingle script output with Kermit commands (e.g. changing parity or duplex in the middle of a script). 5. Dial-out vs dial-in communications lines: C-Kermit requires a UNIX KERMIT Page 147 dial-out or dedicated line for the "set line" or "-l" options. Most systems have some lines dedicated to dial-in, which they enable "loggers" on, and some lines available for dial-out. Where a line must be shared between dial-in and dial-out, several options are available (though they are, strictly speaking, outside the pervue of C-Kermit). A simple shell program can be used to change directionality of the line if your Unix has the enable(8) and disable(8) commands. In that case, the shell program could "grep" a "who" to see if anybody is logged onto the desired line; if not, it could "disable" the line. The shell program will need to be set-uID'ed to root. The shell program can be called from kermit prior to a dial command, e.g., "! mydisable.shellprog". Prior to the final "quit" from C-Kermit, another shell program could be executed to "enable" the line again. This program also needs to be set-uID'ed to root. If your Unix lacks the enable(8) and disable(8) commands, another common technique works if your system supports the /etc/ttys file. A shell program could call up an awk program to find the line in the file and set the enable byte to 0 (to directly disable the line). Likewise, it can be reenabled by a counterpart at the end. It may be necessary to pause for 60 seconds after modifying that file be- fore the logger sees it and actually disables the line. 6. Using C-Kermit on Local Area Networks: C-Kermit can successfully operate at speeds up to 9600 baud over LANs, provided the network buffers are big enough to accommodate Kermit packets (which are al- most always less than 100 characters long). When computers are connected to LAN's through asynchronous terminal interfaces, then the connection should be configured to do XON/XOFF flow control between the network interface and the computer, rather than passing these signals through transparently. This can help prevent Kermit from overrunning the LAN's buffers if they are small (or if the LAN is congested), and will can also prevent the LAN from overrunning a slow Kermit's buffers. If the network hardware cannot accept 100 characters at a time, and flow control cannot be done between the network and the computer, then Kermit's "set send/receive packet-length" command can be used to shorten the packets. 7. Resetting terminal after abnormal termination or kill: When C-Kermit terminates abnormally (say, for example, by a kill command issued by the operator) the user may need to reset the terminal state. If commands do not seem to be accepted at the shell prompt, try Control-J "stty sane" Control-J (use "reset" on Berkeley Unix). That should take the terminal out of "raw mode" if it was stuck there. 8. Remote host commands may time-out on lengthy activity: Using "remote host" to instruct the C-Kermit server to invoke Unix func- tions (like "make") that might take a long time to produce output can cause timeout conditions. UNIX KERMIT Page 148 9. XOFF deadlocks: When connecting back to C-Kermit after a trans- action, or after finishing the server, it may be necessary to type a Control-Q to clear up an XOFF deadlock. There's not much the program can do about this... 10. PC/IX Login Scripts -- Unfound Bug: Though login scripts appear to work properly on most processors, in the case of the PC/XT with PC/IX, it appears that longer scripts need to be broken up into shorter scripts (invoked sequentially from the take file). This is because the portion of the script handler which checks if an opera- tion timed out seems to leave the processor in a strange state (i.e. hung). 9.11. How to Build C-Kermit for a Unix System The C-Kermit files, as distributed from Columbia, all begin with the prefix "ck". You should make a directory for these files and then cd to it. A makefile is provided to build C-Kermit for various Unix systems (there are separate makefiles for VMS and the Macintosh). As distributed, the makefile has the name "ckuker.mak". You should rename it to "makefile" and then type "make xxx", where xxx is the symbol for your system, for instance "make bsd" to make C-Kermit for 4.x BSD Unix. The result will be a program called "wermit". You should test this to make sure it works; if it does, then you can rename it to "kermit" and install it for general use. See the makefile for a list of the systems supported and the corresponding "make" arguments. 9.12. Adapting C-Kermit to Other Systems C-Kermit is designed for portability. The level of portability is indicated in parentheses after the module name: "C" means any system that has a C compiler that conforms to the description in "The C Programming Language" by Kernighan & Ritchie (Prentice-Hall, 1978). "Cf" is like "C", but also requires "standard" features like printf and fprintf, argument passing via argv/argc, and so on, as described in Kernighan & Ritchie. "Unix" means the module should be useful un- der any Unix implementation; it requires features such as fork() and pipes. Anything else means that the module is particular to the indicated system. C-Kermit file names are of the form: ck. where the part before the dot is no more than 6 characters long, the part after the dot no more than 3 characters long, and: is the file type: c: C language source h: Header file for C language source w: Wart preprocessor source, converted by Wart (or Lex) to a C program nr: Nroff/Troff text formatter source mss: Scribe text formatter source doc: Documentation hlp: Help text bld: Instructions for building the program bwr: A "beware" file - list of known bugs UNIX KERMIT Page 149 upd: Program update log mak: Makefile is a single character to tell what system the file applies to: a: Descriptive material, documentation c: All systems with C compilers d: MS-DOS m: Macintosh u: Unix v: VAX/VMS w: Wart is mnemonic (up to 3 characters) for what's in the file: aaa: A "read-me" file, like this one cmd: Command parsing con: Connect command deb: Debug/Transaction Log formats, Typedefs dia: Modem/Dialer control fio: System-depdendent File I/O fns: Protocol support functions fn2: More protocol support functions ker: General C-Kermit definitions, information, documentation mai: Main program pro: Protocol scr: Script command tio: System-dependent terminal i/o & control and interrupt handing usr: User interface us2: More user interface us3: Still more user interface Examples: ckufio.c File i/o for Unix ckmtio.c Terminal i/o for Macintosh ckuker.mss Scribe source for for Kermit User Guide chapter ckuker.nr Nroff source file for Unix C-Kermit man page The following material discusses each of the C-Kermit modules briefly. ckcmai.c, ckcker.h, ckcdeb.h (Cf): This is the main program. It contains declarations for global variables and a small amount of code to initialize some variables and invoke the com- mand parser. In its distributed form, it assumes that command line ar- guments are passed to it via argc and argv. Since this portion of code is only several lines long, it should be easy to replace for systems that have different styles of user interaction. The header files define symbols and macros used by the various modules of C-Kermit. ckcdeb.h is the only header file that is included by all the C-Kermit modules, so it contains not only the debug format definitions, but also any compiler-dependent typedefs. ckwart.c (Cf), ckcpro.w (C): The ckcpro module embodies the Kermit protocol state table and the code to accomplish state switching. It is written in "wart", a language which may UNIX KERMIT Page 150 be regarded as a subset of the Unix "lex" lexical analyzer generator. Wart implements enough of lex to allow the ckprot module to function. Lex it- self was not used because it is proprietary. The protocol module ckcpro.w is read by wart, and a system-independent C program is produced. The syn- tax of a Wart program is illustrated by ckcpro.w, and is described in ckwart.doc. ckcfns.c (C): The module contains all the Kermit protocol support functions -- packet formation, encoding, decoding, block check calculation, filename and data conversion, protocol parameter negotiation, and high-level interaction with the communication line and file system. To accommodate small systems, this module has been split into two -- ckcfns.c and ckcfn2.c. ckutio.c: This module contains the system-dependent primitives for communication line i/o, timers, and interrupts for the various versions of Unix. Certain im- portant variables are defined in this module, which determine whether C-Kermit is by default remote or local, what the default communication device is, and so forth. The tio module maintains its own private database of file descriptors and modes for the console terminal and the file trans- fer communication line so that other modules (like ckcfns or the terminal connect module) need not be concerned with them. The variations among Unix implementations with respect to terminal control and timers are accom- modated via conditional compilation. ckufio.c: This module contains system-dependent primitives for file i/o, wildcard (meta character) expansion, file existence and access checking, and system command execution for the various versions of Unix. It maintains an inter- nal database of i/o "channels" (file pointers in this case) for the files C-Kermit cares about -- the input file (the file which is being sent), the output file (the file being received), the various logs, the screen, and so forth. This module varies little among Unix implementations except for the wildcard expansion code; the directory structure of 4.2bsd Unix is dif- ferent from that of other Unix systems. Again, variation among Unix sys- tems is selected using conditional compilation. ckuusr.h, ckuusr.c, ckuus2.c, ckuus3.c (Unix): This is the "user interface" for C-Kermit. It includes the command parser, the screen output functions, and console input functions. The command par- ser comes in two pieces -- the traditional Unix command line decoder (which is quite small and compact), and the interactive keyword parser (which is rather large). This module is fully replacable; its interface to the other modules is very simple, and is explained at the beginning of the source file. The ckuusr module also includes code to execute any commands directly which don't require the Kermit protocol -- local file management, etc. The module is rated "Unix" because it makes occasional use of the system() function. Note that while ckuusr is logically one module, it has been split up into three C source files, plus a header file for the symbols they share in com- mon. This is to accommodate small systems that cannot handle big modules. ckuusr.c has the command line and top-level interactive command parser; ckuus2.c has the help command and strings; ckuus3 has the set and remote commands along with the logging, screen, and "interrupt" functions. UNIX KERMIT Page 151 ckucmd.c, ckucmd.h (Cf): This is an interactive command parsing package developed for C-Kermit. It is written portably enough to be usable on any system that has a C compiler that supports functions like printf. The file name parsing functions depend upon primitives defined in the fio module; if these primitives can- not be supplied for a certain system, then the filename parsing functions can be deleted, and the package will still be useful for parsing keywords, numbers, arbitrary text strings, and so forth. The style of interaction is the same as that found on the DECSYSTEM-20. ckucon.c (Unix): This is the connect module. As supplied, it should operate in any Unix en- vironment, or any C-based environment that provides the fork() function. The module requires access to global variables that specify line speed, parity, duplex, flow control, etc, and invokes functions from the tio module to accomplish the desired settings and input/output, and functions from the fio module to perform session logging. No terminal emulation is performed, but since standard i/o is used for the console, this may be piped through a terminal emulation filter. The ckucon function may be en- tirely replaced, so long as the global settings are honored by its replace- ment. PC implementations of C-Kermit may require the ck?con module to do screen control, escape sequence interpretation, etc, and may also wish to write special code to get the best possible performance. ckudia.c (Unix): This is the dialer module. As supplied, it handles Hayes, Ventel, Penril, Racal-Vadic, and several other modems. ckuscr.c (Unix): This is the login script module. As supplied, it handles uucp-style scripts. Moving C-Kermit to a new system entails: 1. Creating a new ck?tio module in C, assembler, or whatever language is most appropriate for system programming on the new system. If the system is Unix-like, then support may be added within the ckutio.c module itself using conditional compilation. 2. Creating a new ck?fio module, as above. 3. If the system is not Unix-like, then a new ckuusr module may be re- quired, as well as a different invocation of it from ckcmai. 4. If the distributed connect module doesn't work or performs poorly, then it may be replaced. For instance, interrupt-driven i/o may be required, especially if the system doesn't have forks. Those who favor a different style of user/program interaction from that provided in ckuusr.c may replace the entire module, for instance with one that provides a mouse/window/icon environment, a menu/function-key environment, etc. A few guidelines should be followed to maintain portability: - Keep variable and function names to 6 characters or less. Don't use identifiers that are distinguished from one another only by al- UNIX KERMIT Page 152 phabetic case. - Keep modules small. For instance, on a PDP-11 it is necessary to keep the code segment of each module below 8K in order to allow the segment mapping to occur which is necessary to run programs larger than 64K on a non-I-and-D-space machine. - Keep strings short; many compilers have restrictive maximum lengths; 128 is the smallest maximum string constant length we've encountered so far. - Keep (f,s)printf formats short. If these exceed some compiler de- pendent maximum (say, 128) memory will be overwritten and the program will probably core dump. - Do not introduce system dependencies into ckcpro.w or ckcfn*.c. - If a variable is a character, declare as CHAR, not int, to prevent the various sign extension and byte swapping foulups that occur when characters are placed in integer variables. - Remember that different systems may use different length words for different things. Don't assume an integer can be used as a pointer, etc. - Don't declare static functions; these can wreak havoc with systems that do segment mapping. - In conditional compilations expressions, use #ifdef and #ifndef and not #if, which is not supported by some compilers. Also, don't use any operators in these expressions; many compilers will fail to un- derstand expressions like #ifdef FOO | BAR. - Don't define multiline macros. In general, remember that this program will have to be compilable by old com- pilers and runnable on small systems. MACINTOSH KERMIT Page 153 10. MACINTOSH KERMIT Program: Bill Catchings, Bill Schilit, Frank da Cruz (Columbia University), Davide Cervone, University of Rochester Language: C (SUMACC) Documentation: Frank da Cruz, Bill Schilit Version: 0.8(34) Date: March, 1986 Macintosh Kermit, or "MacKermit", is an implemtation of the Kermit file trans- fer protocol for the Apple Macintosh (and Macintosh-XL) computer, developed at Columbia University, based on C-Kermit (which also forms the nucleus of Unix Kermit). MacKermit Capabilities At A Glance: Local operation: Yes Remote operation: Yes (server mode only) Login scripts: No Transfer text files: Yes Transfer binary files: Yes Wildcard send: No File transfer interruption: Yes Filename collision avoidance: Yes Can time out: Yes 8th-bit prefixing: Yes Repeat count prefixing: Yes Alternate block checks: Yes Terminal emulation: Yes (VT100,VT102) Communication settings: Yes Transmit BREAK: Yes Support for dialout modems: No IBM mainframe communication: Yes Transaction logging: No Session logging: No Debug logging: No Packet logging: No Act as server: Yes Talk to server: Yes Advanced server functions: No Local file management: Yes Command/Init files: Yes File attributes packets: No Command macros: No Raw file transmit: No The main differences between MacKermit and other Kermit programs are: - In MacKermit you are always connected via a terminal emulator (VT102). - MacKermit commands are issued by means of pull-down menus that over- lay your terminal session. MACINTOSH KERMIT Page 154 The major menus are File, Settings, Remote, and Transfer. The File menu in- vokes Kermit's file transfer functions, allows settings to be saved and res- tored, and like most Macintosh applications, includes a "quit" selection for leaving the program. The Settings menu provides dialog boxes for file, communications, and protocol settings. The Remote menu has the commands that can be sent to Kermit servers, as well as an option to turn Macintosh Kermit itself into a server. The Transfer menu gives you a standard Macintosh file box, allowing you to transfer directly to the selected application. 10.1. The Macintosh File System The Macintosh file system consists of one or more disks, each disk containing files. All files on a disk must have a unique name. Files may be collected together into "folders", but folders are not analogous to directories on other file systems, and no two folders on the same disk may contain files of the same name. Macintosh file names may contain practically any printable characters, including space and punctuation -- but colon (":") should be avoided because it is used in device names. 10.2. File Transfer Glossary: - Mode - Text or Binary. Binary means the data is sent or stored with- out modification. Text means that every carriage return character (CR) in a Macintosh file is translated to a carriage-return-linefeed (CRLF) sequence when sending, and every CRLF in an incoming file is turned into a CR when stored on the Mac disk. A text file is produced when you save a file from MacWrite using the "text only" op- tion; text files are not associated with any particular Macintosh ap- plication and can be sent in a useful fashion to other kinds of com- puters. - Fork - Data or Resource. Macintosh files may have two "forks". The data fork contains data for an application; the resource fork con- tains icons, strings, dialog boxes, and so forth. For instance, a MacWrite document contains text and formatting information in the data fork, and fonts in the resource fork. For applications, the ex- ecutable code is stored in the resource fork. Macintosh Kermit supports the standard Kermit commands for transferring files -- Send, Receive, and Get. Invocation of any of these commands produces a MacKermit file dialog box in which you specify the file name, the mode, and the fork. Defaults are determined from the selected file or taken from the current file settings, described below. When you select the Send command, you get a MacKermit file open box, which in- cludes the standard Macintosh dialog items -- a file list, Disk and Eject but- tons, etc. You can only send one file at a time, by clicking on its name in the file list. Clicking the Disk button will switch the file list to another physical disk. If desired, you can type an alternate name to send the file un- der. When you select a file, MacKermit examines its type; if the type is APPL, MACINTOSH KERMIT Page 155 then MacKermit expects to send the resource fork in binary mode, otherwise the data fork in text mode. The Mode and Fork radio buttons will display these choices; you may change them before clicking the Send button. You can receive or get multiple files, providing the opposite Kermit is capable of sending multiple files in a single transaction (most are). As files arrive, they will be decoded according to the current mode (text or binary), and stored in the default fork (data or resource) under either the name they arrive with (overwriting existing files of the same names) or under new unique names (when name conflicts occur), according to the current default for name collisions. You may also elect to perform an "attended" receive, in which you have an op- portunity to override all file defaults on a per-file basis. But this option must be used with caution -- if you take too long (more than about a minute) to execute an incoming file's dialog box, the opposite Kermit could time out and terminate the transaction. The folder for new files is the same as the location of the settings file, or if no settings file was used then the new files appear on the desktop. If you are transferring a lot of files and want to keep them together, create a folder, drag the settings file into it, and double click on the settings file; all created files will appear in that folder. File transfers can be cancelled by clicking on the Cancel File or Cancel Group buttons. These will always work when sending. When receiving, they will work if the opposite Kermit honors this (optional) feature of the protocol. In any case, an "emergency exit" from any protocol operation can be taken at any time by typing "Command-." -- that is, hold down the Command (Fan, Cloverleaf) key and type period. 10.3. Remote Commands The Remote menu allows you to send commands to a Kermit server. The response from these commands (if any) is displayed in a special pop-up window. Responses to multiple Remote commands are separated by a dashed line. The response window can be scrolled, sized, and positioned, and can be hidden by clicking the menu item "Hide Response" or the window's go-away box; all text remains intact and will be appended to the next time you do a Remote command; it can also be brought to the foreground by clicking the Show Response menu item. Note that typein to the terminal emulator will not take effect when the response window -- or any other window -- is up front. If the response window gets too full (i.e. fills up the free memory available to the MacKermit application), the program will probably bomb. If the remote Kermit server is in binary mode, its responses to Remote commands may look strange. For instance, a Unix Kermit server in binary mode will send lines of text separated by only linefeeds, rather than CRLFs. A Remote command can be cancelled by taking the Emergency Exit (Command-.). MACINTOSH KERMIT Page 156 10.4. Settings You can change File, Communications, and Protocol settings by using the Set- tings pull-down menu. You can save and restore these settings by invoking the appropriate selection in the File menu. If the bundle bit has been correctly set on your version of MacKermit you can double-click on the resulting document to start MacKermit with those settings. The File settings establish the defaults for file transfer: - Mode: text or binary. Used for received files only. When sending, MacKermit tries to figure out an appropriate mode for the file being sent (but then lets you override it the Send File dialog). - Fork: which fork -- data or resource -- to send, or to store an in- coming file into. - Naming: Whether incoming files should supersede existing files of the same name, or a new unique name should be assigned to them. If the latter, the new name is formed by adding a dot and a number to the end. For instance, if a file called FOO exists and a file called FOO arrives, MacKermit will store the arriving file as FOO.1; if FOO.1 exists, then FOO.2, etc. - Attended versus Unattended operation for incoming files. The Communications settings allow you to set the baud rate (anywhere between 300 baud and 57.6K baud), parity (odd, even, mark, space, or none), and duplex (full - remote echo, half - local echo). The Protocol settings allow you to set packet parameters for both incoming and outbound packets. These include the block check type (1 or 2 character check- sum, 3-character 16-bit CRC-CCITT), line turnaround handshake character (for file transfer with half duplex systems), packet start and end characters, pad- ding, packet length, timeout interval, and so forth (Refer to Kermit User Guide). Characters are specified by entering their ASCII value in decimal, e.g. 1 for Control-A, 13 for Control-M (Carriage Return), etc. 10.5. Terminal Emulation MacKermit provides a subset of the features of the DEC VT102 terminal; the VT102 is a VT100 with line and character insert/delete functions added. The functions provided are sufficient to allow MacKermit to act as a terminal for EMACS as it exists on the DEC-20, VAX (CCA EMACS on VMS or UNIX), and for most host-resident display-oriented applications that expect to do cursor position- ing and editing on the VT100 screen. MacKermit does not currently support the following VT100/102 functions: - double height or double width lines - smooth scrolling - 132 columns - Interpretation of multiple parameters in a single escape sequence - etc (this is not an exhaustive list) MACINTOSH KERMIT Page 157 The keyboard is set up by default as follows: The COMMAND (Fan, Cloverleaf) key is used as the Control key. The CAPS LOCK key forces all alphabetic characters to upper case, and causes keys on the numeric keypad to send VT100 keypad es- cape sequences. The OPTION key is "Control-Meta" (explained below). The ter- minal emulator sends ESC (escape) when the "`" key is pressed unshifted. The character "`" can be sent by typing Control (Command) and the same key. The Backspace key sends a Delete (Rubout) and Control-Backspace sends a Backspace. The main keypad Enter key sends a "short" (250ms) BREAK signal. The Mac+ does not have a main keypad Enter key, so the BREAK function must be reassigned to another key. Use CKMKEY (see below) to do this. The short break is F126 (function number 126) and long break is F127. MacKermit (V0.8 and later) comes with a separate key configuration program, CKMKEY, which lets you change the behavior of the keys, define function keys, and so forth. CKMKEY is described in detail below. MacKermit (V0.8(43A) and later) includes a mouse-controlled cursor postioning feature for use during terminal emulation. When the mouse button is pressed while the Option and Command keys are held down, the program acts as if you typed the keypad arrow keys to move the terminal cursor to where the mouse cur- sor is. You must have already defined the keypad arrow keys to send the ap- propriate character sequences for your host application. The Catch-22 here is that if you don't have a keypad, there's no way for you to define the keypad keys using MacKermit's keyboard configurator. In that case, you can use the VT100 startup file provided with MacKermit, which assigns the normal VT100 ar- row key sequences to the keypad arrow keys, and therefore also to the mouse-cursor feature. MacKermit honors your parity communications setting by using built-in functions of the Mac's serial i/o chip. Unfortunately, the chip has an unpleasant quirk -- arriving characters that do not have the specified parity are discarded rather than passed to the requesting application. Thus, if you are connected as a terminal using MacKermit to a device that requires, say, odd parity on characters sent to it, but does not put odd parity on characters it sends to you, then many incoming characters will not appear on your screen. To allow useful coexistence of desk accessories and Kermit, the terminal emula- tion may be dragged using the drag bar. A desk accessory that overlays the Kermit window can be clicked upon to move it behind the Kermit window, and then the Kermit window can be dragged to reveal the hidden desk accessory so that it can be restored to the foreground. The same thing can be done with Kermit's own remote response window. Note that Kermit's terminal emulation window does not accept input when any other window is in the foreground. The following features are missing from the MacKermit terminal emulator, and may be added in subsequent releases: - capturing text from the screen (e.g. cutting to clipboard, saving off top) - screen rollback, sizing - modem or dialer control - login scripts - transmission of raw text to host (e.g. pasting to screen) - printer support MacKermit does not use XON/XOFF flow control during terminal emulation or file MACINTOSH KERMIT Page 158 transfer. The terminal emulator can normally keep up at 9600 baud, but after several continuous scrolling screens at this speed, some characters may be lost. In the present version, when running at high baud rates keep your ter- minal in page mode, or use "more", or view text with a non-scrolling screen editor. Also, don't drag the terminal emulation window while characters are arriving; if you do, the characters will be lost and the display will become confused. 10.6. Installation MacKermit is distributed in source form for building on Unix (or VMS/Eunice) systems that have the Stanford SUMACC Macintosh cross-development tools, in .HQX "binhex" form, and sometimes also as a binary resource file. Those who want to work from the source are referred to the file CKMKER.BLD for instruc- tions. If you have the binary resource file available (its name will be CKMKER.RSRC, ckmker.rsrc, CKMKER.RSR, ckmker.rsr, or some variation on these, depending on what system it's stored on and how it got there), AND if you have "MacPut" on your system and MacTerminal on your Mac, AND if you have an 8-bit-wide (no parity) data path between your Mac and your system, use MacPut to download the binary resource file to MacTerminal's XMODEM option on your Mac. After doing this you must use SetFile on the Mac to set the author to KERM, the type to APPL, and turn on the bundle bit. For CKMKEY, the author should be KERK. If you have an earlier release of Columbia MacKermit, you may use Kermit in place of MacTerminal and MacPut. If you don't have the binary resource file available, you can download the CKMKER.HQX file in the same manner, then run "binhex" (version 4) on it. 10.7. CKMKEY - Macintosh Kermit's Keyboard Configurator This describes CKMKEY V0.8(0), May 1985. The version number of CKMKEY indicates compatability with the like version of CKMKER -- Macintosh Kermit, referred to simply as "Kermit" from now on. Edit numbers (within parentheses) may differ. If Kermit is used with a settings file containing a key configuration produced by an incompatible version of CKMKEY, then that configuration will be ignored. 10.7.1. What is CKMKEY? CKMKEY is a keyboard configurator program for use with Macintosh Kermit (versions 0.8 and greater). CKMKEY allows: - Redefinitions of keys - Definitions of multicharacter function keys - Selection of long and short BREAK keys CKMKEY is a separate program from Kermit. It may be thought of as an editor MACINTOSH KERMIT Page 159 for Kermit's terminal emulator key definition resource, which is kept in a Ker- mit settings file. Before you can use CKMKEY, you must already have used Ker- mit to create a settings file to operate on. The reason CKMKEY is separate from Kermit is that there is not enough room in the memory of a 128K Macintosh to hold a program that can do both. CKMKEY dis- plays and changes key settings, Kermit uses them. Once you have started Kermit with a given set of key definitions, there is no way to examine or change them. Some familiarity with the ASCII alphabet is assumed in the following discus- sion. 10.7.2. Modifier vs Normal Keys The Macintosh keyboard is composed of normal keys and modifier keys. Modifier keys are SHIFT, CAPS LOCK, OPTION, and COMMAND (also known as APPLE, CLOVER, or FAN). Only one normal key can be selected at a time, but one or more modifier keys can be depressed along with it. 10.7.3. Key Maps When a key on the keyboard or numeric keypad is depressed the result is a scan code -- a number between 0 and 127 (see Inside Mac Event Manager for details if you're interested). A table indexed by scan code resulting in the character to be displayed or transmitted will be referred to as a "keymap" or "key mapping." On the standard Mac many keymaps exist -- the modifier keys (such as SHIFT) specify which keymap is selected. For example, when no modifer keys are depressed the keymap contains the lowercase alphabet, numbers and some punctua- tion. The keymap in use when the SHIFT modifer is depressed contains the capi- tal letters and special characters. All in all it is possible to select 16 different keymaps by depressing from zero to four modifier keys. Normally however, 6 or so distinct keymaps will suffice. CKMKEY allows you to redefine 6 keymaps: shifted and unshifted combinations of keymaps named "normal", "capslock", and "control". These keymaps are predefined with the expected values -- the control map is preloaded with con- trol codes, the capslock preloaded with the unmodifed keymap but with all let- ters uppercase. In this document modifier keys are written in capital letters and key map names are written in lowercase. SHIFT, CAPS LOCK, COMMAND, and OPTION are modifier keys, "normal" "capslock" and "control" are key maps internal to CKMKER. Since one of the major functions of CKMKEY is to change maps invoked by modifier keys, it is important to keep this distinction in mind. MACINTOSH KERMIT Page 160 10.7.4. What's in CKMKEY's Keymaps A keymap is a list of 128 numbers. Which keymap is selected depends upon which modifier keys are depressed, and the entry within the key map is determined by the scan code. A keymap entry is an 8-bit quantity: if the high order bit is 0, then the entry is the 7-bit ASCII character to be transmitted through the serial port; if the high bit is 1, then the remaining 7 bits are an index into the function-key table. Notice that only single 7-bit values can be directly translated through the CKMKEY keymap. If you want a single key to transmit multiple characters, then you can designate that key to be a "function key", and the key map will contain an indirect reference to the function-key table. If you want a key to transmit an 8-bit value, assign the "meta" operation to one of the modifier keys and use the meta key together with the desired key (see below). Functions are numbered 0-127 with the highest few being reserved for special use. Currently functions 126 and 127 send a short 250 millisecond BREAK signal and a long 3.5 second BREAK respectively. In the future more special functions may be allocated so (since it is arbitrary anyway) please use low numbered functions when defining your own. 10.7.5. Menus CKMKEY has two menus, File and Set. First you must use the File menu to select and open a Macintosh Kermit settings file, which in turn has been created using the Kermit Save Settings option from its own File menu. Then use the Set menu to establish or alter key definitions, then use the File menu again to save the settings file back for Kermit. A variety of Kermit settings files can be kept, each with its own collection of settings and key definitions; Kermit can be started with the desired settings by double clicking on one of these settings files from the Macintosh desktop. Menus consist of options. If an option is followed by an ellipsis (three dots...) then clicking it will produce a dialog box of some kind; otherwise, clicking it causes the indicated action to be performed immediately. If an op- tion is dimmed then it is not available for some reason -- for instance, you can't set any keys until you open a settings file. 10.7.6. MENU: Set The Set menu includes dialogs for setting keys, defining functions, and reas- signing modifier keys. 10.7.6.1. DIALOG: Set Modifer Keys Background: Skip ahead to the next section if you already know about things like SHIFT, CAPS LOCK, CONTROL, and META. On a typewriter the only modifier key is SHIFT. Typing a character with no modifier key depressed selects a lowercase letter or the character printed on MACINTOSH KERMIT Page 161 the lower face of the keytop (say, the digit "4"). Typing a character with SHIFT depressed selects an uppercase letter or the character printed on the up- per face of the keytop (say, a dollar sign). Some keyboards also have a SHIFT LOCK key, which stays down once pressed and pops up the next time it's pressed; its operation is equivalent to holding down SHIFT. And some keyboards have a CAPS lock key which operates like SHIFT LOCK, but only upon letters. Computer terminals also have a modifier key called CONTROL (or CTRL). Its function is a little less obvious: it is intended to produce one of the 33 characters in the "control range" of the ASCII alphabet. Control characters are not graphic -- they are intended for use as format effectors (like carriage return, formfeed, tab, backspace), for transmission control, or for device con- trol. The remaining 95 characters -- letters, digits, and punctuation -- are the graphic characters. When a character is typed with the CONTROL modifier pressed, its "control equivalent" is transmitted. By convention, the control equivalent of A is Control-A, B is Control-B, etc, and there are also seven special control characters generally associated with punctuation characters or special keys. For the "alphabetic" control characters Control-A through Control-Z, SHIFT or CAPS LOCK modifiers are ignored; for the others, operation varies from terminal to terminal. The SHIFT and CONTROL modifiers allow all 128 ASCII characters to be sent from a normal typewriter-like keyboard that has about 50 keys. However, certain host-resident computer applications -- notably the full screen text editor EMACS and its descendents -- can be used to greater advantage with a 256 character alphabet (EMACS responds to single-character commands, and the more characters a terminal can send, the more commands are directly available). For this purpose, some terminals also provide a META modifier key. This key simply causes the high-order ("8th") bit of the selected ASCII value to be set to 1 upon transmission. META characters can only be transmitted when the communica- tion path allows all 8 bits to pass transparently; when this is not possible, software like EMACS allows a sequence of two 7-bit ASCII characters to represent a single meta character. The advantage of having a real META modifier key is that it can be held down while the actual key is struck repeatedly or even autorepeats, whereas a use of a "meta prefix" requires much more typing. To illustrate, suppose META-F is the command to go forward one word. If you want to execute this operation repeatedly, just hold down META and F and let it autorepeat. If you don't have a META key, then you have to use a "meta prefix" character (usually escape), and to enter META-F repeatedly in this case, you'd have to type FFF...etc. Macintosh Kermit Modifier Keys: You can define the modifier key to keymap correspondence in CKMKEY by selecting the "Modifer Keys..." menu item under SET, or by double clicking on a modifier key while in the SET KEYS dialog. The SET MODIFIERS dialog lets you define what map OPTION, CAPS LOCK and COMMAND refer to. Notice that SHIFT is missing -- SHIFT always references the shifted equivalents to the normal, control and caps lock maps. The dialog is layed out in columns with the three modifier keys as column head- ings and the three map names below. Also under each column is a "pseudo" key map for "meta." Meta is not a map, but an operation: it augments the value being transmitted MACINTOSH KERMIT Page 162 after it has been read from its map. Meta can either be set to send a prefix string before the character or to turn the high order (8th) bit on in the transmitted character. The default prefix for meta is set to be 033 (escape). If a meta modifier key is depressed and the key results in a function reference then no modification occurs; functions are not "metized". However, functions can be defined to include 8-bit values. Notice that meta can be set in conjunction with a key map. Since meta is an operation as described above there is no ambiguity. Consider for example set- ting OPTION to reference the "control" map and selecting "meta" for this modifier key as well. The result is a control-meta key. CAUTION: If you have used Kermit's communications settings menu to select any parity other than "none", then any high order bits that may be set by CKMKER's key mapping will be superseded when Kermit applies the selected parity to outbound characters. The SET MODIFIER KEYS dialog also lets you select your meta preferences: whether you want to use the 8th bit toggled on, or a prefix string. The prefix string is entered in the same manner as a function definition (backslash fol- lowed by 3 octal digits for non-printable characters, see below). Note that it is possible to cause ambiguities when selecting and using modifier keys. For example say you set OPTION to refer to the control map, and you set CAPS LOCK to refer to the caps map; at this point if you hold both OPTION and CAPS LOCK down it is unclear which map you want your character to come from. To try to prevent this type of ambiguity the SET KEY dialog will beep when you are holding down or mousing an ambigous set of modifier keys. The Kermit code itself references maps in this precendence: if a control map modifier is depressed then use control map, else if a capslock modifier is depressed use capslock, otherwise use the normal map. A sample modifier key configuration is shown in Figure 10-1. ------------------------------------------------------------------------- OPTION COMMAND CAPS LOCK o Normal * Normal o Normal * Control o Control * Control o Caps o Caps o Caps [X] Meta [X] Meta [ ] Meta Figure 10-1: Macintosh Kermit Modifier Key Dialog ------------------------------------------------------------------------- Here the CAPS LOCK key is used to reference "control", the COMMAND key to do the "meta" operation, and OPTION is "control-meta". Holding down COMMAND and CAPS LOCK together will also result in control-meta. MACINTOSH KERMIT Page 163 10.7.6.2. DIALOG: Set Function Definitions Background: Skip to next section if you know what function keys are. Many popular terminals have "function keys" in addition to the alpabetic, numeric, punctuation, and modifier keys described above. Function keys are usually labeled F0, F1, F2, ..., or PF1, PF2, ... On some terminals, like the DEC VT100, the function keys send predefined sequences of characters -- for in- stance PF1 sends three characters: ESCAPE (ASCII 033), followed by "O", and "P". On others, the function keys may have arbitrary strings assigned to them. For instance, if you find yourself typing "Aaaarrrgggghhh!!! Sigh..." a lot, you can assign this string to function key F1, and then pressing the F1 key will cause this entire character string to be transmitted. Macintosh Kermit Function Keys: The Macintosh has no physical function keys -- no keys are marked F0, F1, F2, etc. However, any key (modified by any combination of modifier keys) may be designated as a "soft" function key. Selecting "Function Definitions..." from the SET menu brings you to the SET FUNCTIONS dialog (it would be nice if you could double click on a function key in the SET KEYS dialog but that is not yet available). Use SET FUNCTIONS to declare a function definition string. Scroll through the function definition list and select a function to define, preferably starting with F0, though this is not required (high numbered functions are reserved for special uses). Type in the function definition; non printable characters must be entered with a backslash ("\") followed by exactly (yes exactly) three octal characters representing the ASCII value, for instance "\015" for carriage return. A backslash itself is entered as "\134". The function definition has to fit in the box. Having defined a function, you must use SET KEYS to actually associate it with a key. Note that it is possible to associate a function with more than one key. 10.7.6.3. DIALOG: Set Keys Selecting the "Keys..." menu item under SET initiates the SET KEYS dialog for redefining individual keys. SET KEYS displays a picture of the keyboard. You can either hold down the modifier and key you wish to define or click on the displayed picture with the mouse (double clicking on one of the modifier keys brings up the SET MODIFIER KEYS dialog). Once a key is selected, it and any modifiers are highlighted, the name of the key and its value are displayed in the lower portion of the dialog. You may enter the new value in the little box by selecting the box with the mouse and then typing a DECIMAL (yes decimal) number from 0 to 127. Then you should click on either SET KEY or else SET FUNCTION KEY. Clicking on SET KEY means that the key should transmit the ASCII character corresponding to the given value (subject to modification by the meta key); clicking SET FUNC- TION KEY means the number you entered in the box is a function number and that MACINTOSH KERMIT Page 164 the key should transmit the character string associated with that function. SET KEYS does not display a picture of the numeric keypad, but may be used with the keypad anyway -- just select the desired key by pressing it and then define it as above. 10.7.7. MENU: File The File menu must be used to Open a Kermit settings file before CKMKEY will allow you do perform any other operations. You may also Quit from CKMKEY through the File menu, and you can save your work. The Save option allows you to save the settings file back under its own name, replacing the previous copy. If you need to make copies of settings files, you can use Kermit itself to save them under different names, or else you can use the Finder. There is also a Decompile option, that is of use only to programmers working on Macintosh Kermit -- it decompiles the key definition resource into a form that can be included in a C program. 10.7.8. CKMKEY Known Limitations, Restrictions, Bugs - There is no picture of the numeric keypad in Set Keys. - In Set Keys, when you strike a key on the numeric keypad, its name is not displayed. You can still make assignments to the key. - There is no way to define a key from the numeric keypad unless you actually have a numeric keypad. - You can't save from CKMKEY under a different name. Use the Finder or Kermit to do that. - You must use decimal numbers in the SET KEY dialog, and backslash followed by 3 octal digits in function definitions, which can be con- fusing. - You may have problems on a 128K mac if you define many long func- tions. - CKMKEY doesn't deal with write protected diskettes very well. 10.7.9. Unlocking CAPS LOCK (Adapted from directions posted by David Chase on INFO-MAC@SUMEX-AIM, Friday 14 December 1984. Follow these instructions at your own risk. Not the authors, nor David Chase, nor Columbia University, nor Rice University provide any warranty, nor acknowledge any liability or respon- sibility for damage, injury, inconvenience, or loss of Apple or other service warranty sufferred as a result of the publication of these directions.) A major impediment to using the Macintosh as a terminal is that the CAPS LOCK key is where you would normally expect to find the CONTROL key. A key redefinition package, such as CKMKEY, can assign the CONTROL function to the MACINTOSH KERMIT Page 165 COMMAND or OPTION keys but these keys are not easy to reach. CONTROL can also be assigned to the CAPS LOCK key using software, but the CAPS LOCK key includes a mechanical locking device. The following directions tell how to remove the locking device so that the CAPS LOCK key will go up and down like the other keys. PROCEED AT YOUR OWN RISK. Tools you'll need: - Phillips screwdriver for screws on bottom of the keyboard. - Solder sucker/wick. - Soldering iron. - Small prying tools (jewelers screwdrivers, small knife blade, etc). - Tweezers/small needlenose pliers. - Some paper clips or straight pins. Now follow these steps: 1. Remove the five screws. The keyboard should fall into three pieces. 2. GENTLY pry off the Caps Lock keycap. This takes a little patience. 3. Remove the restoring spring so it doesn't get in the way. 4. Locate the two connections to the Caps Lock key on the back of the PC board, and remove all solder from them using wick or sucker. Be careful not to overheat the solder pads, since they can be damaged (come loose from the PC board). 5. Pry back the plastic locking clips holding the key in, and remove it. (All the keys are clipped into a metal frame. Removing the metal frame is not possible, since all the keys are soldered to the PC board, and clipped to the frame. The clips are located "north" and "south" of the key, where the number row is "north" and the space bar "south".) There are four clips holding the bottom of the key on; pry these back, and, WHILE HOLDING THE KEY BOTTOM UP, remove the bottom of the key. You may have to use some makeshift tools, like a couple of unbent paper clips, to hold the four clips open. 6. Two pieces should be ready to fall out; a small piece of PC-board-like material (about 7/16 by 3/32 inch, with two notches on one edge and a tiny hole in the center), and a tiny piece of wire (a small, beefy staple with short legs). Let them fall out. (It may help to toggle the key). These two pieces are the locking device, they should be removed and left out of the reassembly. 7. Replace the restoring spring, snap the key back into place, resolder the two leads, screw the keyboard back together, and replace the key cap. You may wish to experiment with the spring to reduce the key's springiness (this can be done with the keyboard assembled, though removing the cap is more difficult). For those who want to map the CAPS LOCK key to CTRL, but don't want to alter the keyboard as described in the manual, but still want to inhibit the locking function, the following suggestion is offered: Pry off the key using a small screwdriver. There is a spring whose end goes MACINTOSH KERMIT Page 166 through the plastic support. Stick a very small wad of paper or soft putty be- tween the tip and the bottom of the keyboard. This will prevent the key from depressing all the way and locking, but still allow contact of the key. Even- tually, the paper will work loose and you will need to find it and repeat the procedure. MS-DOS KERMIT Page 167 11. MS-DOS KERMIT Program: Daphne Tzoar and Jeff Damens (Columbia University), Joe R. Doupnik (Utah State University), James Harvey (Indiana/Purdue University), contributions by many others. Language: Microsoft Macro Assembler (MASM) Documentation: Frank da Cruz and Christine Gianone (Columbia University) Version: 2.29 Date: May 26, 1986 Kermit-MS Capabilities At A Glance: Local operation: Yes Remote operation: Yes Transfers text files: Yes Transfers binary files: Yes Wildcard send: Yes ^X/^Y interruption: Yes Filename collision avoidance: Yes Can time out: Yes 8th-bit prefixing: Yes Repeat count prefixing: Yes Alternate block checks: Yes Terminal emulation: Yes Communication settings: Yes Transmit BREAK: Yes IBM mainframe communication: Yes Transaction logging: No Session logging: Yes Raw transmit: No Act as server: Yes Talk to server: Yes Advanced server functions: Yes Advanced commands for servers: Yes Local file management: Yes Command/init files: Yes Command macros: Yes Attribute packets: No Extended-length packets: No Sliding windows: No Kermit-MS is a program that implements the Kermit file transfer protocol for the IBM PC family, IBM compatibles, and several other machines using the Intel 8086 processor series (8088, 80286, etc) and operating system family (PC-DOS or MS-DOS, henceforth referred to collectively as MS-DOS or simply DOS). Kermit-MS version 2.29 runs in as little as 60K of memory (about 55K contiguous), but will occupy up to 100K, if it can be found, for extra screen rollback memory. It will also try to leave 24 Kbytes free for a second copy of COMMAND.COM which is needed for the SPACE command and others. Versions not using screen rollback memory will not require the additional space. On the IBM PC, Kermit-MS 2.29 performs almost complete emulation of the DEC VT-102 terminal at speeds up to 19,200 baud (lacking only smooth scrolling, 132 MS-DOS KERMIT Page 168 column mode, and ANSI printer control). Much of the speed is accomplished via direct writes to screen memory, but this is done in a "TopView" aware manner to allow successful operation in windowing environments like TopView, MS-Windows, and DesqView. Speed is also due to direct access of the serial port UART (8250) chip, with buffered, interrupt-driven receipt of characters and select- able XON/XOFF flow control. Full-speed 9600 baud operation is possible on 4.77Mhz systems without flow control, but flow control is required on these systems for 19,200 baud or higher rates. As of version 2.28, MS-DOS Kermit requires version 2.0 or later of DOS. Older versions of IBM PC Kermit are no longer distributed, but if you have version 2.27 or earlier, it can run under version 1.0 or 1.1 of PC-DOS. Kermit-MS 2.29 runs on a wide variety of MS-DOS systems, including the entire IBM PC family (the PC, XT, AT, PCjr, Portable PC, PC Convertible) and com- patibles (Compaq, Z150, etc), the DEC Rainbow, NEC APC, Sanyo MBC, Victor 9000, HP-110, HP-150, HP Portable Plus, and many others. This document will describe the things you should know about the MS-DOS file system in order to make effective use of Kermit, and then it will describe the Kermit-MS program itself. In system-specific areas like terminal emulation, most discussion focuses on the IBM PC version. It is assumed you are already familiar with the general ideas of Kermit file transfer. If you are not, con- sult the Kermit User Guide, or Kermit, A File Transfer Protocol, by Frank da Cruz, Digital Press (1986). 11.1. The MS-DOS File System The features of the MS-DOS file system of greatest interest to Kermit users are the form of the file specifications, and the formats of the files themselves. 11.1.1. File Specifications MS-DOS file specifications (in version 2.0 or later of DOS) are of the form DEVICE:\PATHNAME\NAME.TYPE where the DEVICE is a single character identifier (for instance, A for the first floppy disk, C for the first fixed disk, D for a RAM disk emulator), PATHNAME is up to 63 characters of identifier(s) (up to 8 characters each) sur- rounded by reverse slashes, NAME is an identifier of up to 8 characters, and TYPE is an identifier of up to 3 characters in length. Device and pathname may be omitted. The first backslash in the pathname may be omitted if the specified path is relative to the current directory. In the path field, "." means the current directory, ".." means the parent directory. Some DOS im- plementations (like Wang) may use slash "/" rather than backslash as a direc- tory separator. Pathname is normally omitted, but can be specified in all Kermit-MS commands (as of version 2.29). Device and directory pathnames, when omitted, default to either the user's current disk and directory, or to the current directory search path as specified in the DOS PATH environment variable, depending on the context in which the file name appears. MS-DOS KERMIT Page 169 When this document says that a file is searched for "in the current path," it means that the PATH is searched first, and if the file is not found, then Kermit-MS looks on the current disk and directory. If the PATH environment variable is empty, Kermit looks only at the current disk and directory. NAME.TYPE is normally sufficient to specify a file, and only this information is sent along by Kermit-MS with an outgoing file. The device, path, name, and type fields may contain uppercase letters, digits, and the special characters "-" (dash), "_" (underscore), and "$" (dollar sign). When you type lowercase letters in filenames, they are converted automatically to uppercase. There are no imbedded or trailing spaces. Other characters may not be included; there is no mechanism for "quoting" otherwise illegal charac- ters in filenames. The fields of the file specification are set off from one another by the punctuation indicated above. 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.BAS is the source of a BASIC program named FOO; FOO.OBJ might be the relocatable object module produced by compiling FOO.BAS; FOO.EXE could be an executable program produced by loading FOO.OBJ, and so forth. .EXE and .COM are the normal suffixes for executable programs. The MS-DOS allows a group of files to be specified in a single file specifica- tion 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: *.BAS All files of type BAS (all BASIC source files) in the current direc- tory. 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 posi- tion, followed by zero or more characters. *.? All files whose types 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. Users of Kermit-MS should bear in mind that other (non-MS-DOS) systems may use different wildcard characters. For instance the DEC-20 uses "%" instead of "?" as the single character wildcard; when using Kermit-MS to request a wildcard file group from a Kermit-20 server, the DOS "?" must be replaced by the DEC-20 "%". MS-DOS KERMIT Page 170 11.1.2. File Formats MS-DOS systems store files as bulk collections of 8-bit bytes, with no par- ticular differences between text, program code, and binary files. ASCII text files consist of lines separated by carriage-return-linefeed sequences (CRLFs), which conforms exactly to the way Kermit represents text files during transmis- sion. Since a non-MS-DOS receiving system might need to make distinctions as to file type, you may need to use various SET functions on the remote system to inform it that the incoming file is of some particular (non-default) type, such as binary. In transmitting files between Kermit-MS programs, regardless of file contents, the receiving MS-DOS system is equally capable of processing text, code, and data, and in fact requires no knowledge of how the bytes in the file are to be used. Unlike most other Kermit programs, MS-DOS Kermit does not require a command like SET FILE TYPE BINARY to switch from text to binary file transfer. MS-DOS (unlike CP/M) is capable of pinpointing the end of file with precision by keeping a byte count in the directory, so one would expect no particular confusion in this regard. However, certain MS-DOS programs continue to use the CP/M convention of terminating a text file with a Control-Z character, and won't operate correctly unless this terminating byte is present. Therefore, you should be aware of a special SET EOF option for both incoming and outbound files, described later. Non-MS-DOS systems may well be confused by nonstandard ASCII files from Kermit-MS: - Files containing any of the 8-bit "extended ASCII" characters will probably need conversion (or translation) to 7-bit ASCII. - Files produced by word processing programs like Easywriter or Word Star may may contain special binary formatting codes, and could need conversion to conventional 7-bit ASCII format prior to transmission, using commonly available "exporter" programs. - Files created by word processors that store formatting data at the end of the file, after the Control-Z and before physical end, may re- quire special processing via SET EOF to strip the formatting data, lest they confuse non-MS-DOS recipients. - Spreadsheet or database files usually need special formatting to be meaningful to non-MS-DOS recipients (though they can be transmitted between MS-DOS systems with Kermit-MS). 11.2. Program Invocation Kermit-MS can be run interactively, from a batch file, or as an "external" DOS command. Commands consist of one or more fields, separated by "whitespace" -- one or more spaces or tabs. Upon initial startup, the program executes any commands found in the file MSKERMIT.INI in the current path. This initialization file may contain command macro definitions, communications settings for one or more ports, or any other Kermit-MS commands. Here is a sample MSKERMIT.INI file: MS-DOS KERMIT Page 171 comment -- MSKERMIT.INI, MS-DOS Kermit initialization file comment -- Don't overwrite my files! set warning on comment -- Define macros for the systems I use... define unix set local-echo off, set flow xon, set timer off def ibm set par odd, set loc on, set hands xon, set flo off, set tim on def modem set port 2, set baud 1200 comment -- Define a macro for quickly adapting to noisy connections... def noisy set block-check 3, set send packet-length 40, set retry 20 comment -- I always start out by connecting to my UNIX system... set port 1 set baud 4800 do unix connect Interactive Operation: To run Kermit-MS interactively, invoke the program from DOS command level by typing its name. When you see the command's prompt, Kermit-MS> you may type Kermit commands repeatedly until you are ready to exit the program, for example: A> A>kermit IBM PC Kermit-MS V2.29 Type ? for help Kermit-MS>send foo.* The files are sent. Kermit-MS>get bar.* The requested files are received. Kermit-MS>exit A> During interactive operation, you may edit the command you're currently typing using BACKSPACE to erase the character most recently typed, Ctrl-W to delete the most recent field, or Ctrl-U to delete the entire command. The editing characters may be used in any combination until the command is finally entered by typing RETURN (Carriage Return, Enter) or Ctrl-L. While typing commands, you may the help ("?") and keyword completion (ESC) features freely while typing Kermit-MS commands. A question mark typed at al- most any point in a command produces a brief description of what is expected or MS-DOS KERMIT Page 172 possible at that point (for this reason, Kermit-MS uses "#" for the single- character match wildcard in the first position of the local filenames and "?" thereafter, and ?-help is not available from within a filename). ESC typed at any point, except in a local filename, will cause the current field to be filled out if what you have typed so far is sufficient to identify it, and will leave you in position to type the next field (or to type a "?" to find out what the next field is); otherwise, the program will beep at you and wait for you to type further characters. Some Kermit-MS commands, like GET, SHOW KEY, SET KEY, may prompt for additional information on subsequent lines. If you have reached one of these prompts and then wish to cancel the command, you may type Control-C. Summary of Kermit-MS Command Editing Characters: SPACE Separates fields within the command. TAB Same as Space, and echoes as Space. You may also use Ctrl-I for Tab. BACKSPACE Deletes the character most recently typed. May be typed repeatedly to delete all the way back to the prompt. You may also use DELETE, RUBOUT, Ctrl-H, or equivalent keys. Ctrl-W Deletes the most recent "word", or field, on the command line. May be typed repeatedly. Ctrl-U Deletes the entire command line, back to the prompt. Ctrl-C Cancels the current command and returns to the "Kermit-MS>" prompt. ESC If enough characters have been supplied in the current keyword to identify it uniquely, supply the remainder of the field, and posi- tion to the next field of the command. Otherwise, sound a beep. ESC does not provide filename completion in version 2.29. ? Displays a brief message describing what may be typed in the cur- rent command field. Also, wildcard character for matching any single character in all but the first position of a filename. # Wildcard character for matching single characters in filenames. Equivalent to MS-DOS "?", but used in the first position of a filename only, so that "?" may be used to get help at the beginning of a filename field. RETURN Enters the command. On most keyboards, you may also use ENTER or Ctrl-M. Ctrl-L Clears the screen and enters the command. Liberal use of "?" allows you to feel your way through the commands and their fields. This feature is sometimes called "menu on demand" -- unlike systems that force you to negotiate menus at every turn, menu-on-demand provides help only when it is needed. MS-DOS KERMIT Page 173 Command Line Invocation: Kermit-MS may also be invoked with command line arguments from DOS command level, for instance: A>kermit send foo.bar or A>kermit set port 1, set baud 9600, connect In this case, help and completion are not available (because the program that provides them won't start running until after you type the entire command line), and Kermit-MS will exit back to DOS after completing the specified com- mand or commands. Therefore, when invoked with command line arguments, Kermit-MS will behave as if it were an external DOS command, like MODE. Note that several commands may be given on the command line, separated by commas. Batch Operation: Like other MS-DOS programs, Kermit-MS may be operated under batch with command line arguments. If you invoke it without command line arguments, it will run interactively, reading commands from the keyboard and not the batch file. When it exits, batch processing will continue to the end of the batch file. Remote Operation: The MS-DOS CTTY command allows an MS-DOS system to be used from a terminal con- nected to its communication port. Such sessions must be conducted with great care, since many programs assume that they are running on the real console, and explicitly reference screen memory or keyboard scan codes. Kermit can be used in this manner too, but before you give it any file transfer commands, you must inform it that it is running in "remote mode" rather than its normal "local mode." Use the SET REMOTE ON command for this purpose, to prevent the file transfer display from being sent out the port. MS-DOS KERMIT Page 174 11.3. Kermit-MS Commands MS-DOS Kermit implements a large subset of the commands of "ideal" Kermit. Here's a brief summary: BYE to remote server. CLEAR key redefinitions. CLOSE log file and stop logging remote session. COMMENT a command file. CONNECT as terminal to remote system. CWD change local working directory. DEFINE macros of Kermit-MS commands. DELETE local files. DIRECTORY listing of local files. DO a macro expansion. EXIT from Kermit-MS. FINISH Shut down remote server. GET remote files from server. HANGUP the phone. HELP about Kermit-MS. LOCAL prefix for local file management commands. LOG remote terminal session. LOGOUT remote server. PUSH to MS-DOS command level. QUIT from Kermit-MS RECEIVE files from remote Kermit. REMOTE prefix for remote file management commands. RUN an MS-DOS program. SEND files to remote Kermit. SERVER mode of remote operation. SET various parameters. SHOW various parameters. SPACE inquiry (about disk space). STATUS inquiry (about settings). TAKE commands from file. TYPE display a local file. VERSION display Kermit-MS program version number. The remainder of this section concentrates on the commands that have special form or meaning for MS-DOS Kermit. Not all of the following commands are necessarily available on all MS-DOS systems, and some of the commands may work somewhat differently between DOS versions. The notation used is as follows: Optional fields are in [square brackets], lists of alternatives are in {curly braces}. Parameters, such as numbers or filenames, are shown in italics (providing the printer is capable of printing italics), and in dialog examples user typein is underlined (on printers that can show it) to distinguish it from computer typeout. MS-DOS KERMIT Page 175 11.3.1. Commands for Terminal Connection The CONNECT command connects your PC as a terminal to the remote system, so that you can start up Kermit there. The CONNECT Command The CONNECT command establishes an interactive terminal connection to the sys- tem connected to the currently selected communications port (e.g. COM1 or COM2) using full duplex (remote) echoing and no parity unless otherwise specified in previous SET commands. You can type the escape character followed by the let- ter C to get back to Kermit-MS. On most MS-DOS systems the escape character is Ctrl-] by default. You can use the SET ESCAPE command to define a different escape character, and on most systems you can SET BAUD (or SPEED) to change the baud rate, and SET PORT to switch between ports. Read about the SET COMMAND in section 11.3.6 for more information on these and other settings. Terminal emulation is described in greater detail in section 11.4 below. The HANGUP Command HANGUP command attempts to lower the modem signals DTR and RTS. It may be used to hang up the phone when dialed up through a modem, or to get the attention of port contention units or terminal concentrators that operate in this manner. 11.3.2. Commands for File Transfer The file transfer commands are SEND, GET, and RECEIVE. The SEND Command Syntax: SEND filespec1 [filespec2] The SEND command causes a file or file group to be sent from the local MS-DOS 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 PC. filespec1 may contain the wildcard characters "*" to match zero or more charac- ters within a field, and/or "#" (first position) or "?" (elsewhere) to match any single character. If filespec1 contains wildcard characters then all matching files will be sent, in the same order that MS-DOS would show them in a directory listing. If filespec1 specifies a single file, you may direct Kermit-MS to send that file with a different name, given in filespec2. For in- stance, in the command Kermit-MS>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 charac- MS-DOS KERMIT Page 176 ters that may be appropriate on the target machine. The alphabetic case of text in filespec2 is preserved in transmission. If the SEND command is specified by itself on the command line, then you will be prompted separately for the name of the file to send, and the name to send it under: Kermit-MS>send Local Source File: c:\chris\xcom1.txt Remote Destination File: com1.txt If a file can't be opened for read access, standard MS-DOS recovery procedures will take place. For example: Not ready error reading drive A Abort, Retry, Ignore? If you select "Abort," you will be returned to DOS. Files will be sent with their MS-DOS filename and filetype (for instance FOO.TXT, no device or pathname). If there is no filetype, then only the name will be sent, without the terminating dot. Each file is sent as is, with no conversions done on the data, except for possibly adding or deleting a ter- minating Control-Z character (see the SET EOF command). Once you give Kermit-MS the SEND command, the name of each file will be dis- played 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 "Complete", otherwise there will be an error message. When the specified operation is done, the program will sound a beep. Several single-character commands may be given while a file transfer is in progress: ^X (Control-X) Stop sending the current file and go on to the next one, if any. ^Z Stop sending this file, and don't send any further files. ^C Return to Kermit-MS command level immediately without sending any kind of notification to the remote system. ^E Like ^C, but send an Error packet to the remote Kermit in an attempt to bring it back to server or interactive command level. CR Simulate a timeout: resend the current packet, or NAK the expected one. Control-X, Control-Z, and Control-E send the proper protocol messages to the remote Kermit to bring it gracefully to the desired state. Control-C leaves the remote Kermit in whatever state it happens to be in, possibly retransmit- ting its last packet over and over, up to its retry limit. You should only have to use Control-C in dire emergencies (the remote Kermit is stuck, the remote system crashed, etc), or at those times when you realize that you have given a file transfer command to Kermit-MS without first having told the remote Kermit about it. MS-DOS KERMIT Page 177 The RECEIVE Command Syntax: RECEIVE [filespec] The RECEIVE command tells Kermit-MS to receive a file or file group from the other system. Kermit-MS 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 Kermit-MS before issuing the RECEIVE command. If the optional filespec is provided, the first incoming file will be stored under that name. The filespec may include any combination of the following fields: Device designator Store the file on the designated device. If no device designator is given, store it on the current default device. Directory path Store the file in the designated directory. If no path given, store the file in the current directory. File name Store the file under the name given. If no name is given, store it under the name it was sent under, converted, if necessary, to suit DOS conven- tions, and modified, if desired, to avoid overwriting any file of the same name in the same directory. 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, but on the specified device and directory. If an incoming file does not arrive in its entirety, Kermit-MS will normally discard it and it will not appear in your directory. You may change this be- havior by using the command SET INCOMPLETE KEEP, which will cause as much of the file as arrived to be saved on the disk. The same single-character commands are available as during SEND: ^X Request that the remote Kermit stop sending the current file, and proceed to the next one immediately. Since this is an optional feature of the Kermit protocol, the remote Kermit might not honor the request. ^Z Request that the remote Kermit terminate the entire transfer; this is also an optional feature that may or may not be supported by the remote Kermit. ^C, ^E, and CR operate in the same way as they do during SEND. In this case, ^E should always do what ^Z is supposed to do. If the incoming file has the same name as a file that already exists, and WARN- ING is set ON, Kermit-MS 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; if you type ^X or ^Z to interrupt the transfer, you'll either get a partial new file, or else both the old and the new file of that name will be lost, depending on SET INCOMPLETE. In any case, MS-DOS KERMIT Page 178 when WARNING is off, files with the same name as incoming files will not sur- vive. Caution: If an incoming file's name (the part before the dot) corresponds to an MS-DOS device name, such as NUL, COM1, CON, AUX, or PRN, output will go to that device, rather than to a file with that name. This is a feature of MS-DOS. The GET Command Syntax: GET 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 Kermit-MS 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 Kermit-MS. If the remote Kermit does not have a SERVER command, then you should use SEND and RECEIVE as described above. You may use the GET command in a special way to specify a different name for storing the incoming file. Just type GET alone on a line, and you will be prompted separately for the remote filespec and the local filespec: Kermit-MS>get Remote Source File: com1 txt Local Destination File: a:xcom1.txt The local file name may contain a device field, and/or a directory specifica- tion. If more than one file arrives, only the first will be renamed. Device and directory specifications in the local destination file name work the same way as in the RECEIVE command. 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 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 ^X to request that the current incoming file be cancelled, ^Z to request that the entire incoming batch be cancelled, and ^C or ^E to return immediately to the Kermit-MS> prompt, exactly as described for the RECEIVE command. 11.3.3. Commands for Controlling Remote Kermit Servers The BYE, FINISH, and LOGOUT commands allow you to shut down a remote Kermit server: BYE When communicating with a remote Kermit server, use the BYE command to shut down the server, log out its job, and exit locally from Kermit-MS to DOS. FINISH Like BYE, FINISH shuts down the remote server. However, FINISH does not log out the server's job. You are left at Kermit-MS prompt level so that you can connect back to the job on the remote system. MS-DOS KERMIT Page 179 LOGOUT The LOGOUT command is identical to the BYE command, except you will remain at Kermit-MS prompt level, rather than exit to DOS, so that you can establish or use another connection. Other functions may be also requested of a server, described under the REMOTE command, immediately below. 11.3.4. Commands for File Management Kermit-MS provides commands or managing both local and remote files. The REMOTE Commands The REMOTE keyword is a prefix for a number of commands. It indicates that the command is to be performed by the remote Kermit, which must be running as a server. Note that not all Kermit servers are capable of executing all these commands, and some Kermit servers may be able to perform functions for which Kermit-MS does not yet have the corresponding commands. In case you send a command the server cannot execute, it will send back a message stating that the command is unknown to it. If the remote server can execute the command, it will send the results to your screen (or whatever device you have specified in your most recent SET DESTINATION command). Here are the REMOTE commands that Kermit-MS may issue: REMOTE CWD [directory] Ask the server to Change your Working Directory on the remote host, that is, the default source and destination area for file transfer and management. You will be prompted for a password, which will not echo as you type it. If you do not supply a password (i.e. you type only a carriage return), the server will attempt to access the specified directory without a password. If you do not supply a directory name, your default or login directory on the remote system will be assumed and you will not be prompted for a password. REMOTE DELETE filespec Ask the server to delete the specified file or files on the remote sys- tem. In response, the server may display a list of the files that were or were not successfully deleted. REMOTE DIRECTORY [filespec] Ask the server to display a directory listing of the specified files. If no files are specified, then the list should include all files in the the current working directory. REMOTE HELP Ask the server to list the services it provides. REMOTE HOST [command] Ask the server to send the command to the remote system's command processor for execution. KERMIT command Send the command to the remote Kermit for interpretation as a Kermit MS-DOS KERMIT Page 180 command itself, in the remote Kermit server's own command syntax. Most Kermit servers, including Kermit-MS, do not yet recognize such com- mands. REMOTE SPACE [directory] Ask the server to provide a brief summary of disk usage in the specified area on the remote host or, if none specified, the default or current area. REMOTE TYPE filespec Ask the server to display the contents of the specified remote file or files on your screen. The LOCAL Command The LOCAL keyword is a prefix for a number of commands. It indicates that the specified command is to be executed on the local MS-DOS system. The LOCAL prefix may be omitted. All file specifications may include device and/or directory fields. The local commands are: CWD path Changes the current working directory to the given path. All references to local file names without explicit paths will refer to that path. DELETE filespec Deletes the specified file or files. As in DOS, the names of the deleted files are not listed, only the message "file(s) deleted" or "file(s) not found", and if you give the command "delete *.*", Kermit-MS will prompt "Are you sure?", like DOS. DIRECTORY [filespec] Lists the names, sizes, and creation dates of files that match the given file specification. If no filespec is given, the command is equivalent to DIR *.*. SPACE Performs the MS-DOS CHKDSK function by running the CHKDSK program from the current path. RUN command Passes the command line to COMMAND.COM for execution. Thus, any legal DOS operation is permitted: running a program (with command line ar- guments or i/o redirection), executing a DOS command, or executing a batch file. COMMAND.COM should be in the current path. Kermit is suspended while the command is executed and automatically resumes af- terward. Yes, one may nest RUN KERMIT several times if memory is available; but that just wastes memory. If the command is a DOS com- mand (like DIR or REN) it will be executed directly by COMMAND.COM. Otherwise, the specified file will be executed, which must be in .EXE or .COM format, or a .BAT file containing DOS commands, from the specified path or according to the value of the PATH variable if no path was included in the filespec. Example: Kermit-MS>run more < foo.txt MS-DOS KERMIT Page 181 TYPE filespec Displays the specified local file on the screen. Automatic pause is not available at the end of a page (but see above example for how to accomplish this). On most systems, Ctrl-S can be used to stop scroll- ing and Ctrl-Q to continue scrolling. PUSH Invokes an MS-DOS command processor "under" Kermit-MS, either COMMAND.COM or whatever shell you have specified with COMSPEC (or SHELL, depending on the system) in your CONFIG.SYS file. You can return to Kermit-MS by typing the MS-DOS EXIT command, and you will find Kermit-MS as you left it, with all settings intact. The same function is accomplished by the CONNECT escape-level command P. The local RUN command has various uses, one of which is to supplement the fea- tures of Kermit-MS. A common complaint about Kermit-MS, for instance, is that it lacks login scripts, autodialer control, and phone directories. While wait- ing for these features to appear in a generally useful form in some future release, you might be able to provide the specific functions you need by writ- ing a program in any compiled language (assembler, Pascal, C, etc) and then in- voking from within Kermit-MS using the RUN command. For instance, if you have a Hayes-like modem, you could write a short program to operate the dialer with AT commands, accepting the phone number to dial on the command line. If this program were called DIAL, then you could "run dial 7654321" from within Kermit. The TAKE Command Syntax: TAKE filespec The TAKE command instructs Kermit-MS to execute commands from the specified file, which may include an explicit path; if no path is specified, the value of the PATH variable is used; if PATH has no value, then the current disk and directory are searched. The command file may include any valid Kermit-MS com- mands, including TAKE, but it cannot include characters to be sent to a remote host during terminal emulation (i.e. after a CONNECT command). Commands within TAKE files, unlike interactive commands, may include trailing comments, preceded by semicolons: set port 2 ; Select the modem port set speed 1200 ; Set the baud rate for the modem Warning: since TAKE file processing discards all characters from a line begin- ning with the first semicolon, it is not possible to include semicolons in remote filespecs within TAKE files, e.g. get dska:foo.bar;6 Commands from the TAKE file will normally not be displayed on your screen. If you want to see them as they are executing, you can SET TAKE-ECHO ON. MS-DOS KERMIT Page 182 The LOG and CLOSE Commands Syntax: LOG filespec CLOSE Specifies that your terminal session during CONNECT will be recorded in the specified file; the filespec may include a device specification and/or direc- tory path. The LOG command allows you to "capture" files from a remote system that doesn't have Kermit, as well as to record remote command typescripts. The log is closed when you EXIT from Kermit-MS or when you issue an explicit CLOSE command. During terminal emulation, the LOG command records all the characters that ar- rive from the remote host in the specified file, including escape sequences. If you have SET LOCAL-ECHO ON, it will also record the characters you type. And if you have also SET DEBUG ON, then during file transfer it will also record the packets in the log. You may LOG PRN to cause the logging information to be printed directly on your printer. Note that any escape sequences that are sent to the screen are also sent to the printer. If you want to record information without imbedded escape sequences, use the screen dump feature, invoked by the CONNECT escape-level command F, which is described in more detail in the terminal emulation section. 11.3.5. The SERVER Command Kermit-MS is capable of acting as a full-fledged Kermit server, providing file transfer and management for users coming in through one of the communication ports. To put Kermit-MS into server mode, first issue any desired SET commands to select and configure the desired port, and then type the SERVER command. Kermit-MS 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: Kermit-MS>set port 1 Kermit-MS>set baud 1200 Kermit-MS>set timer on Kermit-MS>set warning on Kermit-MS>server Kermit 2.29 server mode supports the following requests: SEND REMOTE DELETE REMOTE CWD GET REMOTE DIRECTORY REMOTE HOST FINISH REMOTE SPACE BYE REMOTE TYPE The REMOTE HELP command is not implemented. Remote CWD can be used to change both directories and devices. CAUTION: The method used for most of the REMOTE commands is to invoke a task with the user's command line, redirect standard output to a tem- MS-DOS KERMIT Page 183 porary file, $KERMIT$.TMP, send that file back to the remote end, and then delete the file. Sufficient space must be available to store this file. To service DOS commands or user tasks the boot drive must hold a copy of COMMAND.COM. PATH will not be searched (this can be dis- asterous on a floppy disk based system). FURTHER CAUTION: Any of these DOS tasks or programs may encounter an error, and in that case, DOS will generally put the familiar "Abort, Retry, Ignore?" message on the screen, and will wait for an answer from the keyboard. This will hang the server until a human comes to the keyboard and gives a response. The same thing will happen when any program is invoked that interacts with the real console. For instance, REMOTE SPACE works by running CHKDSK; if CHKDSK finds something wrong with the disk while tallying up the space, it will ask (at the console) if you want to it to be fixed. This, too, will hang the server. MORAL: The MS-DOS Kermit server should probably not be used for REMOTE commands unless someone is around to take care of it when it gets stuck. 11.3.6. The SET Command Syntax: SET parameter value or: SET parameter parameter value The SET command establishes or modifies various parameters for file transfer or terminal connection. You can examine their values with the STATUS and SHOW commands. The following SET commands are available in Kermit-MS: BAUD Communications port line speed (synonym for SPEED) BELL Whether to beep at the end of a transaction BLOCK-CHECK-TYPE Level of error checking for file transfer DEBUG Display packet contents during file transfer DEFAULT-DISK Default disk drive for file i/o DESTINATION Default destination device for incoming files DISPLAY For selecting the type of file transfer display DUMP Screen dump file (or device) name END-OF-LINE Packet termination character EOF Method for determining or marking end of file ESCAPE Escape character for CONNECT FLOW-CONTROL Enable or disable XON/XOFF HANDSHAKE Half-duplex line turnaround option INCOMPLETE What to do with an incompletely received file KEY Specify key redefinitions, or "keystroke macros" LOCAL-ECHO Specify which computer does the echoing during CONNECT MODE-LINE Whether to display a mode line during terminal emulation PARITY Character parity to use PORT Select a communications port PROMPT Change the "Kermit-MS>" prompt to something else RECEIVE Request remote Kermit to use specified parameters REMOTE For running Kermit-MS interactively from back port RETRY Packet retransmission threshold SEND Use the specified parameters during file transfer SPEED Communications port line speed (synonym for BAUD) MS-DOS KERMIT Page 184 TAKE-ECHO Control echoing of commands from TAKE files TERMINAL Emulation and parameters TIMER Enable/disable timeouts during file transfer WARNING Specify how to handle filename collisions The SET commands are now described in greater detail. SET BAUD Syntax: SET BAUD rate Set the speed of the currently selected terminal communications port (COM1 by default) to 300, 1200, 1800, 2400, 4800, 9600, 19200, or other common baud rate. Some implementations do not support this command. In any case, Kermit-MS leaves the current communication port settings alone unless you issue explicit SET commands to change them. SET SPEED is an acceptable synomym for SET BAUD. Note that on certain systems, when you first run Kermit after power- ing the system up, you may get a message "Unrecognized baud rate". This means that Kermit tried to read the baud rate from the port and none was set. Simply use SET BAUD (if available) or the DOS MODE command to set the desired baud rate. SET BELL Syntax: SET BELL {ON, OFF} Specifies whether the bell (beeper) should sound upon completion of a file transfer operation. Normally ON. SET BLOCK-CHECK Syntax: SET BLOCK-CHECK {1, 2, 3} Selects the error detection method: a 1-character checksum (the normal case), a 2-character checksum, or a 3-character 16-bit cyclic redundancy check (CRC). If the other Kermit program is not capable of type 2 or 3 checking methods, automatic fallback to type 1 will occur. SET DEBUG Syntax: SET DEBUG {ON, OFF} When debugging is ON, Kermit will display packet traffic on your screen during file transfer. If the debugger is loaded, control will be transferred to it when Ctrl-C is typed. During terminal emulation (on the IBM PC only), control characters are displayed in uparrow notation. If logging is being done, file transfer packets are included in the log. When OFF (this is the default), debugging information is not displayed, and packets are not logged. MS-DOS KERMIT Page 185 SET DEFAULT-DISK Syntax: SET DEFAULT-DISK x: Specify the default disk drive to use for file transfer, directory listings, and so forth. Equivalent to typing the DOS command for changing disks (A:, B:, etc). Affects Kermit and all inferior processes, but when you exit from Ker- mit, you will still have the same default disk as when you entered. SET DESTINATION Syntax: SET DESTINATION device Specify the device for incoming files during file transfer: DISK, PRINTER, or SCREEN. SET DESTINATION PRINTER will cause incoming files to be spooled directly to the printer; SCREEN will send output normally destined for the disk to the screen. The normal destination is DISK. SET DESTINATION affects only files transferred with SEND, GET, or RECEIVE; it cannot be used to reroute the output from REMOTE server commands. SET DISPLAY Syntax: SET DISPLAY {QUIET, REGULAR, SERIAL} During file transfer, MS-DOS Kermit's regular display is a formatted screen whose fields randomly updated with file names, packet numbers, error counts, percent done, error messages, and so forth: File name: FOO KBytes transferred: 7 Sending: In progress Percent done: 52% Number of packets: 74 Number of retries: 2 Last error: None Last warning: None The items in the right-hand column are updated more or less at random. If you wish to run Kermit-MS interactively through the back port, for instance after the operator has done CTTY COM1, you must give the command SET REMOTE ON (which, currently at least, is equivalent to SET DISPLAY QUIET); this sup- presses the file transfer display screen, so that the display won't interfere with the file transfer itself. You can also use this command to suppress the display in local mode, in case you are using a system that allows you to do other work while file transfer proceeds in the background. If you have your PC connected to a speaking device (a common practice for visually impaired people), or you are logging the display screen to a printer (using DOS ^P or kermit > prn), the random nature of the regular display will make the results of little use. SET DISPLAY SERIAL is provided for this pur- pose; it causes the program to report progress "serially" on the screen. In serial mode, error messages are preceeded with the word "Error" and repeat mes- sages with the word "Retry". Packets are numbered as dots with every tenth be- MS-DOS KERMIT Page 186 ing a plus sign. The packet display is automatically broken across lines at every 70th packet. The serial display makes much more sense when spoken than does the regular display. The serial display does not show the percent and kilobytes transferred. It is the default display style for generic MS-DOS Kermit; REGULAR is the default for all others. SET DUMP Syntax: SET DUMP path On those systems that support this feature, change the file or device name of the screen dump file. The normal file name is KERMIT.SCN. See the section on terminal emulation for details about screen dumps. END-OF-LINE Syntax: SET END-OF-LINE number If the remote system needs packets to be terminated by anything other than car- riage return, specify the decimal value of the desired ASCII character. SET EOF Syntax: SET EOF {CTRL-Z, NOCTRL-Z} Controls how the end of file is handled. CTRL-Z specifies a Control-Z charac- ter should be appended to the end of an incoming file, unless it already ends with a Control-Z. Certain MS-DOS text editors and other applications require files to be in this format. For outbound files, treat the first Control-Z as the end of the local file, and do not send it or any subsequent characters. NOCTRL-Z is the default; incoming files are stored, and MS-DOS files are sent, exactly as is, in their entirety. SET ESCAPE Syntax: SET ESCAPE character Specify the control character you want to use to "escape" from remote connec- tions back to Kermit-MS. The default is normally ^] (Control-Rightbracket). The character is entered literally, and should normally be chosen from the AS- CII control range. It is not possible to use non-ASCII characters (e.g. func- tion keys) for this purpose. SET FLOW-CONTROL Syntax: SET FLOW-CONTROL {XON/XOFF, NONE} Specify the full duplex flow control to be done on the currently selected port. The options are XON/XOFF and NONE. The specified type of flow control will be MS-DOS KERMIT Page 187 done during both terminal emulation and file transfer. By default, XON/XOFF flow control is selected. XON/XOFF should not be used on half-duplex (local echo) connections. If XON/XOFF is used, HANDSHAKE should be set to NONE. SET HANDSHAKE Syntax: SET HANDSHAKE {CODE number, BELL, CR, LF, NONE, XOFF, XON} Specify any half-duplex line turnaround handshake character for the currently selected port. The CODE number form allows any ASCII character to be specified by its decimal ASCII code. The specified handshaking is done during file transfer only. Handshake is NONE by default; if set to other than NONE, then FLOW-CONTROL should be set to NONE. SET INCOMPLETE Syntax: SET INCOMPLETE {DISCARD, KEEP} Specifies what to do with files that arrive incompletely: discard them or keep them. They are normally discarded. SET KEY Syntax: SET KEY key-specifier Specifies that when the designated key is struck during terminal emulation, the associated character string is sent. The key-specifier is one of the keywords F1, F2, ..., or else SCAN followed by a scan code. Systems that have a BACK- SPACE key also include BACKSPACE as a keyword. If SCAN is used, it is followed by a decimal number to indicate the scan code of the key, which you would ascertain from your system reference manual, or else by using the Kermit-MS SHOW KEY command. SET KEY prompts you on a new line for the definition string. Certain characters, like ESC and CR, may not be entered literally into the string, but can be included by inserting escape codes of the form \ooo, a backslash followed by a 2- or 3-digit octal number corresponding to the ASCII value of the desired character. If some other key redefinition package, like ProKey, has been loaded, then its redefinitions will take precedence over Kermit's. The SET KEY command is illustrated in the terminal emulation section below. Note that key redefinitions occur only during terminal emulation, and not at Kermit-MS command level, or outside of Kermit. SET LOCAL-ECHO Syntax: SET LOCAL-ECHO {ON, OFF} Specify how characters are echoed during terminal emulation on the currently selected port. ON specifies that characters are to be echoed by Kermit-MS (because neither the remote computer nor the communications circuitry has been requested to echo), and is appropriate for half-duplex connections. LOCAL-ECHO MS-DOS KERMIT Page 188 is OFF by default, for full-duplex, remote echo operation. When using Kermit to connect two PCs "back to back," use local echo so that when you CONNECT to the other PC to send messages to its operator, you can see what you are typing. Depending on the system, you may have to type a carriage return and a linefeed at the end of each line in order to make the display look right. SET MODE-LINE Syntax: SET MODE-LINE {ON, OFF} On systems, like the IBM PC family, which are capable of displaying a status, or "mode" line on the 25th line during terminal connection, disable or enable this function. Has no effect on systems that do not display a mode line during connect. When the mode line is enabled, it may be turned on and off using the CONNECT escape-level command M. Refer to the terminal emulation section, 11.4, for further details. SET PARITY Syntax: SET PARITY {EVEN, ODD, MARK, SPACE, NONE} Specify the character parity to be used on the currently selected port. NONE means no parity processing is done, and the 8th bit of each character can be used for data when transmitting binary files. This is the normal case. You will need to SET PARITY to ODD, EVEN, MARK, or possibly SPACE when com- municating with a system, or over a network, or through modems, concentrators, multiplexers, or front ends that require or impose character parity on the com- munication line. For instance, GTE Telenet normally uses MARK parity. If you neglect to SET PARITY when the communications equipment requires it, the symptom may be that terminal emulation works (well or maybe only partially), but file transfer does not work at all. If you have set parity to ODD, EVEN, MARK, or SPACE, then Kermit-MS will re- quest that binary files will be transferred using 8th-bit-prefixing. If the other Kermit 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 bi- nary 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 reduces Kermit's file transfer efficientcy without providing any ad- ditional error detection. The SET PARITY command is provided only to allow Kermit to adapt to conditions where parity is required, or 8-bit transmission is otherwise thwarted. SET PORT Syntax: SET PORT {number, COM1, COM2} 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. Sub- MS-DOS KERMIT Page 189 sequent SET BAUD, PARITY, HANDSHAKE, FLOW, and LOCAL-ECHO commands will apply to this port only. SET PORT 1 selects COM1, SET PORT 2 selects COM2. All ver- sions default to port 1, except for the IBM PCjr, which uses port 2 by default (since Kermit does not know how to control its port 1, an internal modem). In "generic" MS-DOS Kermit, the following alternate forms allow you to experi- ment with device names or numbers until you find the communication port: SET PORT {DEVICE, FILE-HANDLE} Just type a carriage return after either of these commands, and you will be prompted for a device name or a numeric port-handle. Keep trying till you find one that works. SET PROMPT Syntax: SET PROMPT string This command allows you to change the MS-DOS Kermit program's prompt. SET RECEIVE Syntax: SET RECEIVE parameter value At the beginning of a protocol operation, request the remote Kermit to use the given value specified parameter, or inform Kermit-MS that the remote Kermit will be using it. PACKET-LENGTH number Ask the remote Kermit to use the specified maximum length for packets that it sends to Kermit-MS. The normal (and maximum) length is 94. Use this command to shorten packets if the communication line is noisy; this will decrease the probability that a particular packet will be corrupted, and will reduce the retransmission overhead when corruption occurs, but it will increase the protocol overhead. PADCHAR number Ask the remote Kermit to use the given control character (expressed as a decimal number 0-31, or 127) for interpacket padding. Kermit-MS should never require any padding. PADDING number Ask the remote Kermit to insert the given number of padding characters before each packet it sends. This should never be necessary. START-OF-PACKET number If the remote Kermit will be marking the beginning of packets with a control character other than Control-A, use this command to tell Kermit-MS about it (the number should be the decimal ASCII value of a control character). This will be necessary only if the hosts or com- munication equipment involved cannot pass a Control-A through as data, or if some piece of communication equipment is echoing packets back at you. MS-DOS KERMIT Page 190 TIMEOUT number Ask the remote Kermit to time out after the given number of seconds if a packet expected from Kermit-MS has not arrived. Use this command to change the normal timeout interval. SET REMOTE Syntax: SET REMOTE {ON, OFF} SET REMOTE ON removes the file transfer display (as if you had given the com- mand SET DISPLAY QUIET). It should be used when you are running Kermit-MS in remote mode (i.e. when coming in from another PC through the Kermit-MS's "back port", to which the console has been reassigned using the DOS CTTY command). It is necessary to issue this command because (a) Kermit-MS has no way of know- ing that its console has been redirected, and (b) when the console is the same as the port, the file transfer display will interfere with the file transfer itself. SET REMOTE OFF returns the file transfer display to its preferred style (REGULAR or SERIAL). SET RETRY Syntax: SET RETRY number Sets the number of times a packet is retransmitted before the protocol gives up. The number of retries can be between 1 and 63, and is 5 by default. This is an especially useful parameter when the communications line is noisy or the remote host is very busy. SET SEND Syntax: SET SEND parameter value PACKET-LENGTH number Use the specified maximum length for outbound packets. Normally, Kermit-MS uses whatever length the other Kermit requests. PADCHAR number Use the specified control character for interpacket padding. Some hosts may require some padding characters (normally NUL or DEL) before a packet, and certain front ends or other communication equipment may need certain control characters to put them in the right modes. PADDING number How many copies of the pad character to send before each packet, nor- mally zero. PAUSE number How many milliseconds to pause between sending the next packet, 0-127, normally zero. This helps half-duplex systems prepare for reception of our packet. Padding characters are sent only after the time limit ex- pires. QUOTE number MS-DOS KERMIT Page 191 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. START-OF-PACKET number Mark the beginning of outbound packets with some control character other than Control-A. This will be necessary if the remote host or the communication channel involved cannot accept a Control-A as data, or if it echoes back your packets. The remote host must have been given the corresponding SET RECEIVE START-OF-PACKET command. TIMEOUT number Change Kermit-MS's normal timeout interval; this command is effective only if TIMER is set to be ON; it is normally OFF so that the remote Kermit can control timeouts. When the timer is ON, the default timeout interval is 13 seconds. SET SPEED Syntax: SET SPEED rate Same as SET BAUD, q.v. SET TAKE-ECHO Syntax: SET TAKE-ECHO {ON, OFF} Specifies whether screen display should occur during implicit or explicit TAKE operations on MSKERMIT.INI or other Kermit-MS command files, and during evalua- tion of macro definitions. Handy for finding errors. SET TERMINAL Syntax: SET TERMINAL parameter [value] This command controls most aspects of terminal emulation. Most of the parameters are only settable (or meaningful) on the IBM PC family and com- patibles. (Programmers who are proficient on other MS-DOS systems are invited to fill in these functions for those systems and send the results back to Columbia.) The first group of parameters tells which kind of terminal to emulate. When Kermit-MS uses its built-in software for emulation, incoming characters are ex- amined for screen control commands (escape sequences) specific to that ter- minal, and if encountered, the commands are executed on the PC screen. NONE Act as a dumb terminal. All incoming characters will be sent to the screen "bare", as-is, through DOS. If you have loaded a device driver into DOS for the CON device, such as ANSI.SYS, then that driver will be able to interpret the codes itself. Many non-IBM systems have their own screen control code interpreter built into DOS or firmware, or available as a loadable device driver. MS-DOS KERMIT Page 192 VT52 The DEC VT-52 terminal. HEATH The Heath/Zenith-19 terminal (H19), which supports all the VT52 com- mands, plus line and character insert/delete editing functions, and a 25th line. VT102 The DEC VT102 (ANSI) terminal, which is the same as a VT100 but also supports line/character insert/delete editing functions. TEKTRONIX A Tektronix 4010 graphics terminal. Only available on TI and Victor PCs. The specific escape sequences supported by Kermit for each of these terminal types are listed in section 11.10. The remaining SET TERMINAL commands specify setup options for the selected ter- minal: CHARACTER-SET {UK, US} UK displays # as a pound sterling sign, US displays # as #. COLOR number [, number [, number]] Several numbers, applied in left to right sequence, separated by com- mas or spaces: 0 Reset the colors to normal intensity white characters on a black background and use the "no-snow" mode on the IBM Color Graphics Adapter (CGA). 1 High intensity foreground 10 Request fast screen updating for use on the IBM EGA or PGA, and some non-IBM CGAs. 3x Foreground color 4x Background color where x is a single digit from 0 to 7, which is the sum of the desired colors: 1 Red 2 Green 4 Blue Example: 0, 1, 34, 40 on an IBM CGA would produce blue characters on black field with no snow. The snow removal business has to do with whether the program should synchronize with vertical retrace when up- dating screen memory. This is necessary with certain color adaptors (like the CGA) and unnecessary for others (like the EGA). CURSOR-STYLE {BLOCK, UNDERLINE} Sets the cursor rendition to your preference. Note that on some early IBM PCs and compatibles, the cursor may not be restored correctly after escape back from CONNECT because of a bug in the early IBM BIOS. KEYCLICK {ON, OFF} Turns electronic keyclick ON or OFF. If your keyboard has a mechani- cal clicker (as IBM boards do), you may not notice the effect of this MS-DOS KERMIT Page 193 command. MARGIN-BELL {ON, OFF} Controls whether the bell should be sounded when the cursor passes column 72 near the right screen margin. NEWLINE-MODE {ON, OFF} ON sends a carriage-return-linefeed combination (CRLF) when you type carriage return (CR) during terminal emulation; OFF (default) just sends a CR when you type CR. SCREEN-BACKROUND {NORMAL, REVERSE} NORMAL means dark background, light characters. REVERSE means light background, dark characters. TAB {AT n, CLEAR AT n, CLEAR ALL} Sets tab stops or clears one or all tab stops. n is the numeric posi- tion of the tab to be set or cleared. By default, tabs are every 8 spaces, at positions 9, 17, 25, etc. Only meaningful when emulating a terminal that has settable tabs (the VT52 doesn't). More than one tabstop may be specified by separating column numbers with commas, spaces, or tabs. WRAP {ON, OFF} ON automatically breaks screen lines (by inserting a CRLF) when they reach the the right margin; OFF disables wrapping -- if a line is too long, the excess characters go off the screen. SET TIMER Syntax: SET TIMER {ON, OFF} This command enables or disables the timer that is used during file transfer to break deadlocks that occur when expected packets do not arrive. By default, the timer is ON. SET WARNING Syntax: SET WARNING {ON, OFF} Specify what to do when an incoming file has the same name as an existing file in the default directory of the default device. 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) any existing one. If OFF, the pre-existing file is destroyed, even if the incoming file does not arrive completely. WARNING is OFF by default. The new name is formed by adding numbers to the part of the name before the dot. For instance, ABC.TXT becomes ABC00001.TXT, then ABC00002.TXT, etc. MS-DOS KERMIT Page 194 11.3.7. The SHOW Command Syntax: SHOW option Most parameters that may be altered with SET commands are displayed by the STATUS command. The SHOW command is used for displaying macro definitions and key redefinitions. The SHOW MACROS command displays the definitions of all currently defined mac- ros, as well as the amount of space left for new macro definitions. The SHOW KEY command allows you to determine the scan code produced by pressing a given key, so that you can construct a SET KEY SCAN command to redefine the key. If the key already has a redefinition in effect, that too will be dis- played. This can be done either interactively or in a macro command. Refer to the terminal emulation section for examples. The SHOW KEY command only works on certain systems. 11.3.8. Command Macros Kermit-MS provides a facility for combining commands into "macros." Command macro definitions may be included in your MSKERMIT.INI file, TAKEn explicitly from a specified file, or typed interactively. Macros are invoked with the DO command. The DEFINE Command Syntax: DEFINE macro-name [command [, command [, ...]]] Kermit-MS command macros are constructed with the DEFINE command. Any Kermit-MS commands may be included. Example: define telenet set parity mark, set baud 1200, connect A macro can be undefined by typing an empty DEFINE command for it, like define telenet A macro definition may be no longer than 128 characters. Longer definitions can be accomplished by "chaining." Example: define setup set port 1, set speed 19200, set parity even, do setup2 define setup2 set port 2, set speed 1200, set parity none, do setup3 define setup3 set warning on, set incomplete keep, connect The SHOW MACROS command displays the value of all currently defined macros, and tells how much space is left for further definitions. MS-DOS KERMIT Page 195 The DO Command A Kermit-MS command macro is invoked using the DO command. For instance, Kermit-MS comes with a predefined macro to allow convenient setup for IBM mainframe line-mode communications; to invoke it, you would type do ibm The IBM macro is defined as "set timer on, set local-echo on, set parity mark, handshake xon, set flow none". You can use the DEFINE command to redefine this macro or remove the definition altogether. There is no automatic way to undo the effect of a macro. If you need to ac- complish this effect, you should define another macro for that purpose. For instance, to undo the effect of "do ibm" so that you could connect to, say, a VAX, you could: define vax set par no, set hand no, set flo x, set tim off, set loc off Then you can "do ibm" whenever you want to use the IBM system, and "do vax" whenever you want to use the VAX. If you wish to view the macro expansion whenever you issue a DO command, you can SET TAKE-ECHO ON. 11.4. Terminal Emulation When you issue the CONNECT command, your PC acts as a terminal connected to a remote computer through the currently selected port. The characters you type are sent out the port, and characters that arrive at the port are displayed on your screen, or interpreted according to whatever type of terminal is being emulated. If you have not previously issued a SET PORT command, COM1 is used except on systems (like the IBM PCjr) where some other port is the default. If you have SET LOCAL-ECHO ON for the selected port, then Kermit-MS will display characters on the screen as you type them, otherwise it will rely on the remote system to echo them. XON/XOFF flow control will be done unless you have SET FLOW-CONTROL OFF. If you have SET PARITY to anything other than NONE, Kermit-MS will add the appropriate parity to each outbound character. While CONNECTed, you can also communicate directly with an autodialer or "smart modem" to control the communications line, hang it up, and the like, for instance, by typing AT com- mands to a Hayes-like modem. When you CONNECT, the program attempts to raise the DTR and RTS RS-232 signals, and it takes no specific action to lower them unless you explicitly issue the HANGUP command. The IBM PC version of Kermit-MS emulates the DEC VT102 terminal by default, and may also be instructed to emulate the DEC VT52, the Heath/Zenith-19, or no ter- minal at all, via the SET TERMINAL command. Emulation of each of these ter- minals is nearly complete. VT102 emulation lacks only smooth scroll, 132 column mode, and ANSI printer control. Double-height, double-width characters are supported, but simulated using ordinary characters. On color monitors, the foreground and background colors may be set using SET TERMINAL COLOR, and MS-DOS KERMIT Page 196 inverse/normal video display may also be selected, along with many other ter- minal parameters. A complete list of the commands, default key configurations, and escape sequences accepted by the IBM PC Kermit terminal emulator is given in section 11.10. The Escape Character The escape character is used to regain the attention of Kermit-MS during CON- NECT, i.e. terminal emulation. When you type the escape character, Kermit-MS waits for you to follow it with a single character command. For instance, the single character command "?" produces a list of available single character com- mands. This command is executed immediately; it may not be edited, and the program does not wait for a carriage return to confirm it. Here are the CON- NECT escape-level commands available in Kermit-MS: ? Help -- prints the available single-character commands. 0 (the digit zero) Transmit a NUL (ASCII 0). B Transmit a BREAK signal. C Close the connection and return to Kermit-MS prompt level. F File the current screen in the screen dump file. M Toggle the mode line, i.e. turn it off if it is on & vice versa. P Push to DOS; get back to CONNECT by typing EXIT. Q Temporarily quit logging the remote session. R Resume logging the remote session. S Show the status of the connection. ^] (or whatever you have set the escape character to be) Typing the escape character twice sends one copy of it to the connected host. Typing any other character (except the space bar, which is the "null command") after the escape character will cause Kermit-MS to beep, but will do no harm. The escape character can be changed to something other than Control- Rightbracket by using the SET ESCAPE command. The Mode Line When you first issue the CONNECT command, a message (on some systems, an in- verse video "mode line") will display the most important facts about the con- nection you've just established, so that you can quickly diagnose any problems. Here's what the IBM PC mode line looks like: +--------------------------------------------------------------------------+ | Esc-chr:^] help:^]? port:1 speed:9600 parity:odd echo:rem VT102 .... PRN | +--------------------------------------------------------------------------+ This shows that the escape character is Ctrl-Rightbracket, that you would type Ctrl-rightbracket followed by question mark (^]?) to get help during CONNECT, that you are connected on port 1 at 9600 baud with odd parity and remote echo, and that a VT102 terminal is being emulated. The four dots represent the VT102s LEDs (they turn into the digits 1,2,3,4 when "lit") and PRN will show up if the printer is activated (e.g. by Ctrl-PrintScreen). The mode line occupies the 25th line of those systems that have such a thing, and is not affected by scrolling. When emulating a VT102 or Heath-19, Kermit MS-DOS KERMIT Page 197 will allow the host to address the 25th line directly using cursor positioning commands. If this happens, Kermit will remove its mode line and relinquish control of the 25th line to the host (as if you had typed SET MODE OFF). When no terminal is being emulated, the 25th line (if any) is available for scroll- ing. If the mode line is disabled by an application or by the command SET MODE OFF then the only way to revive Kermit's mode line display is to give the com- mand SET MODE ON. Screen Scroll On certain systems, Kermit-MS provides several pages of screen memory, which may be scrolled up and down using keys as shown in Table 11-1. ------------------------------------------------------------------------------- System Screen Down Line Down Screen Up Line Up IBM PC PgUp Ctrl-PgUp PgDn Ctrl-PgDn Rainbow PrevScreen Ctrl-PrevScreen NextScreen Ctrl-NextScreen HP-150 Prev Shift-UpArrow Next Shift-DownArrow NEC APC Uparrow Ctrl-UpArrow DownArrow Ctrl-DownArrow Table 11-1: Kermit-MS Screen Scroll Keys ------------------------------------------------------------------------------- There is no way to assign these functions to other keys. The IBM PC also allows use of the Home key to get to the top of its display memory and End key to get to the bottom, and the keypad plus (+) key to toggle the mode line on and off. The Rainbow uses Shift-Next-Screen to get to the bottom of its display memory, but provides no key for moving directly to the top. Screen Dump The screen dump feature writes the contents of the screen to a file (KERMIT.SCN unless another file was selected by the SET DUMP command) when the CONNECT escape-level command F is typed. The screen dump file is appended to on each successive screen dump, with each screen separated by a formfeed (Ctrl-L). This feature may be used in conjunction with screen rollback -- a handy way to recapture screenfuls of laboriously typed-in text after a remote host has crashed without saving your work. A screen dump differs from a session log in two ways. First, each desired screen must be manually filed, and second, the screen dump file has been stripped of any escape sequences, whereas the session log records them. MS-DOS KERMIT Page 198 Printer Control During terminal emulation, a locally attached printer may be controlled in the normal manner, on most systems. Pushing the "Print Screen" key (shifted on some systems) will cause the current contents of the screen to be printed or spooled; holding down CTRL while depressing Print Screen will start or stop the spooling of incoming characters to the printer. On the IBM PC, the mode line will show PRN when the printer is activated in this manner. ^P or ^N are sent to the host during terminal emulation, and do not toggle printing, as they do when you're talking directly to DOS. CTRL-Print-Screen can be simulated with the Kermit-MS LOG PRN and CLOSE com- mands. Key Redefinitions Key redefinitions are useful for defining "keystroke macros" of login se- quences, frequently issued commands, and so forth, and for setting up the ter- minal for use with host resident software designed to work with terminals that send predefined sequences from their function keys. For instance, here's a key redefinition file for arranging the DEC Rainbow keyboard into the normal ASCII keyboard layout: ; Make shift-comma send a left angle bracket set key scan 556 < ; Shift-period sends a right angle bracket set key scan 558 > ; Accent grave is where ESC is supposed to be set key scan 96 \33 ; Put accent grave on the ESC function key set key f11 ` Since SET KEY is a two-line command, a special trick is necessary in order to include it in a single-line macro definition: just use a comma where you would have typed carriage return after the first line, for instance: define bar set key scan 261, foo The CLEAR command may be used to eliminate all key redefinitions. The SET KEY facility may be used provide the PC with a "meta" key for use with editors like EMACS or TVEDIT that can use "meta characters" as commands. A meta key is a shift key whose effect is to turn on the 8th (parity) bit of the character. For instance, on the IBM PC the scan codes produced by holding down ALT together with other keys can be determined using SHOW KEY, and then 8-bit ASCII equivalents with the 8th bit turned on can be defined using SET KEY; if the scan code produced by typing ALT-a, i.e. the letter "a" (ASCII 141, octal) with the ALT key held down, is 2078 (decimal), you would set the META equivalent to 141+200=341 (octal), or "\341" in octal SET KEY notation: Kermit-MS>sho key Press a key: ALT-a MS-DOS KERMIT Page 199 Scan Code: 2078 Definition: Kermit-MS>set key scan 2078 Definition String: \341 Whenever you type ALT-a with this definition in effect, Kermit-MS will transmit octal 341, rather than 141. Summary of Kermit-MS Terminal Emulation Features Table 11-2 shows the terminal emulation options for the systems presently sup- ported by Kermit-MS. ------------------------------------------------------------------------------- System EscChar Cabilities Terminal Service ACT Apricot ^] K ??? DEC Rainbow ^] R P K D VT102 firmware DECmate/DOS ^] ??? Generic DOS ^] Depends on system Grid Compass ^] ??? HP-110 ^] Dumb terminal HP-150 ^] R HP-2623 firmware IBM PC,XT,AT ^] R M P K D H19,VT52,VT102 emulation Intel 300 ^] ??? NEC APC ^] R P K VT100, ADM3A firmware Olivetti M24 ^] R M P K D VT100 emulation Sanyo MBC550 ^] ??? Wang PC ^A Wang firmware TI Pro ^] M P K VT100/Tektronix Victor 9000 Alt-] VT100 and/or Tek4010 Zenith Z100 ^] Heath-19 emulation R=Rollback, M=Modeline, P=Printer control, K=Key redefinition, D=screen Dump Table 11-2: Kermit-MS Terminal Emulation Options ------------------------------------------------------------------------------- 11.5. Installation of Kermit-MS If you already have Kermit on your PC, you can use it to obtain new versions of Kermit-MS when they appear on the central system at your site. If you do not have Kermit or any other reliable file capture facility on your PC, and there is no one from whom you can borrow a floppy disk to copy Kermit, then you should read the following instructions for initially "bootstrapping" Kermit-MS from a mainframe where it is stored onto your microcomputer. There are at least three methods of initially getting Kermit-MS onto your PC: 1. Try again to find a copy on diskette.