Kermit68K user's and implementor's guide Roberto Bagnara Physics Department Bologna University July 1987 Page 2 **** WARNING *** *** WARNING *** This is a provisional help file extracted from the manual that is still in preparation, when finished it will be distributed without further delays. It is not checked at all and there are things, already implemented in the current release of Kermit68K, not described here. Furthermore some of the features here described are not fully implemented and checked. Note also that I and the OS9/68000 version implementor (Steve Williams, Texas University at Austin) are releasing now Kermit68K/OS9 because of the great need for beta-testers, we need user's feedback to go further. Furthermore this is the FIRST official release of the program, so probably a lot of bugs will be discovered, I and Steve apologize in advance for any inconvenience. Don't hesitate to contact me (Bitnet: Bagnara@Iboinfn) at any time for bugs reporting, suggestions, complaints and, why not, compliments. If you have problems in installing Kermit68K/OS9 on your system or if you are sure that an incovenience is due to the system dependent part you can write directly to Steve (Arpanet, Usenet: {seismo|gatech|ihnp4}!ut-sally!stevew). Finally remember that, in the version you have now, the macro command capability is implemented only at the embrional state that is there is no protection against a number of common situations (really it should not be included in this release but...), this facility will appear fully implemented in Kermit68K release 1.1 that will come soon. Page 3 1. Introduction Kermit is the name of a protocol for transferring files from one computer to another over ordinary asynchronous terminal connections. Kermit programs have been written for many different computers, and in general any two computers that have Kermit programs can exchange sequential files correctly. The Kermit file transfer protocol was designed at the Columbia University Center for Computing Activities (CUCCA) in 1981-82 mainly by Bill Catchings and Frank da Cruz. KERMIT is named after the famous reporter, Kermit the Frog, star of the television series "The Muppet Show". The name Kermit is used by permission of Henson Associates, Inc., New York. This manual describes a Kermit implementation for systems based upon the Motorola MC68000 microprocessors family. The language used for its implementation is assembly, and it may be processed, with a few modifications, by most assemblers following the syntax defined by Motorola [2,3]. This Kermit implementation has been written in order to be installed also on those MC68000 microprocessors family based machines, which have no or not-standard operating system (being often custom built for the solution of specific processing problems). At least in the high energy physics field, that frequently happens. The key principles of this Kermit implementation are: 1) MACHINE INDEPENDENCE, (obviously stated that the processor belongs to the Motorola MC68000 family). The system dependent part is kept in a separate module and it's composed by a few routines, containing all the knowledge about the system's file structure and I/O ports. 2) MINIMAL SYSTEM REQUIREMENTS, Kermit68K has been designed for portability among MC68000 operating systems and assemblers, particularly those of the sort that are sold as turnkey systems for lab work, with little or nothing in the way of utility software or operating system support for many of the functions often taked for granted. 3) MODULARITY, Kermit68K is higly modularized, users that need to use it for particular purposes can take advantage of this by using only the parts suitable for their project. 4) EASY CUSTOMIZATION, the program is thoroughly documented, thus allowing the implementors to modify it easily, according to their need. 5) EFFICIENCY, the program is coded for speed and it takes a really small memory space. Furthermore, it's ROMable so it can be used on embedded system for specific applications (e.g. automatic data transmission from a remote acquisition station to a database host computer). Page 4 PLEASE USE KERMIT68K ONLY FOR PEACEFUL AND HUMANE PURPOSES Page 5 2. Kermit68K at a glance Program: Roberto Bagnara, Physics Department, Bologna University Language: Motorola MC68000 Assembly Language Documentation: Roberto Bagnara Version: 1.0.00 Date: July 01, 1987 Capabilities: Local operation: Yes Remote operation: Yes Transfers text files: Yes Transfers binary files: Yes Wildcard send: Yes ^X/^Z interruption: Yes Filename collision avoidance: Yes Can time out: Yes 8th-bit prefixing: Yes Repeat count prefixing: Yes Alternate block checks: Yes Terminal emulation: No Communication settings: Yes Transmit BREAK: Yes IBM mainframe communication: Yes Transaction logging: No Session logging: No Raw transmit: No Act as server: No Talk to server: Yes Advanced server functions: No 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 Page 6 cc Kermit68K Interactive Operations cc.1 Entering commands Kermit68K's default interactive command prompt is "Kermit68K>". In response to this prompt, you may type any valid command. Kermit68K executes the command and then prompts you for another command. The process continues until you instruct the program to terminate. Kermit68K commands begin with a keyword, normally an English verb, that describe what you want the program to do. This command verb may be followed by one or more parameters that specify what the verb acts upon. At least one blank character must separate the command name from the first parameter, and at least one blank must separate each additional parameter from the previous parameter. Multiple spaces and tabs are permitted in all cases where a single blank is required. When you enter commands, you can use any combination of uppercase and lowercase because the command interpreter translates lowercase letters to uppercase letters when it tries to match command verbs and other parameter keywords. File specifications and other non-keyword parameters are left unchanged, so, if your operating system cares of letter cases, make sure you type these parameters in the correct way. A Kermit68K command can contain up to 132 characters, besides, each element in a command (for example, a file specification or keyword parameter) must be less or equal to 132 characters. You can abbreviate command verbs and parameter keywords omitting trailing characters as long as the truncation is unique, thus permitting the command interpreter to distinguish it from any other keyword valid in that field. For example, the HELP command is currently the only command that begins with the character "H". Therefore, the HELP command could be truncated to just one character. The RECEIVE and RETRY keywords, however, have the same first two characters, so these commands cannot be truncated to fewer than three characters. Certain commonly-used commands are exceptions to the minimum truncation rule because they can be truncated to just their first character, even though other commands begin with the same character. The commands that benefit of these non-unique abbreviations are SEND, RECEIVE, and CONNECT. Unless you specify an alternate radix, the Kermit68K command interpreter treats all numeric values as decimal integers. You can specify a radix by using the radix operators ("$" for hexadecimal, "" for octal, or "%" for binary). There cannot be any blanks between a radix operator and a value. Page 7 Certain characters have special functions during typein of interactive commands: DEL (Delete) Delete the most recently entered character. You may also use BS (Backspace, Control-H) for this function. Note that the key that performs the delete function is marked RUBOUT on some terminals. CAN (Control-X) Erase the entire command. Useful if you make several mistakes on a particular line and want to cancel the line and reenter it. CR (Carriage-Return) Enters the command for execution. LF (Linefeed) or FF (Formfeed) may also be used for this purpose. A command line beginning with a percent sign "%" is ignored. Such lines may be used to include illustrative commentary in Kermit command dialogs. Note that the command interpreter treats the "%" as any other command, so make sure that at least one space or tab follows it. Interactive Kermit68K accepts commands from files as well as from the keyboard. When you enter interactive mode, Kermit68K looks for the file KERMIT.INI in your current directory and executes any commands it finds there. A TAKE command is also provided for use at any time during an interactive session, to allow commands to be executed from a file; command files may be nested to a maximum of 20. Page 8 cc.2 Kermit68K commands in brief Here is a brief list of Kermit68K interactive commands: % Treat the rest of the line as a comment. ! Forward the rest of the line to system command processor. BYE Terminate and log out a remote Kermit server. CONNECT Establish a terminal connection to a remote system. COPY Make a copy of a local files. CWD Change Working Directory. DEFINE Define a macro command. DELETE Delete a local files. 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 brief command and macro list. LIST List a macro command text. PRINT Print local files. QUIT Same as EXIT. RECEIVE Passively wait for files to arrive. REMOTE Issue commands to a remote Kermit server. RENAME Rename local files. SEND Send files. SET Set various parameters. SHOW Display values of tha SETtable parameters. SPACE Display current disk space usage. STATISTICS Display statistics about most recent transaction. TAKE Execute commands from a file. TYPE Display local files on the screen. The SETtable parameters are: BAUD Same as SPEED. BLOCK_CHECK_TYPE Level of packet error detection. DELAY How long to wait before sending first packet. DUPLEX Specify which side echoes during CONNECT. ESCAPE 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_FILE_DISPOSITION Disposition for incompletely received files. LINE Communication line device name. PARITY Communication line character parity. PROMPT The Kermit68K program's interactive command prompt. RECEIVE Parameters for inbound packets. RETRY Set limits for retrying packets transmission. SEND Parameters for outbound packets. SPEED Communication line speed. The REMOTE commands are: COPY Copy remote files. CWD Change remote working directory. Page 9 DELETE Delete remote files. DIRECTORY Display a listing of remote file names. HELP Request help from a remote server. HOST Issue a command to remote host in its own command language. KERMIT Issue a command to remote Kermit in its own syntax. PRINT Print remote files. RENAME Rename remote files. SET Set parameters of the remote Kermit program. SPACE Display current disk space usage on remote system. SUBMIT Send a command to remote host for batch execution. TYPE Display a remote file on your screen. WHO Display who's logged in, or get information about a user. cc.pp The BYE command This command will cause Kermit68K (when in local mode) to tell the other Kermit (which should be in server mode) to exit from Kermit and, if applicable, terminate its job (or process, etc.). When Kermit68K receives the acknowledgement that this is being done, it will exit to the operating system. Kermit68K>BYE cc.pp The CONNECT command The CONNECT command will allow you to connect in as a virtual terminal over the default line or the one specified by the last SET LINE command. Kermit68K>CONNECT cc.pp.1 The CONNECT command Escape-Character This character is used to issue a limited set of commands to Kermit68K after using the CONNECT command. Its default value is CTRL-E (5 decimal, ASCII ENQ) and can be changed via the SET ESCAPE command. It is usually a good pratice to set this character to something which is not used (or at least not used very much) on the system to which Kermit68K is CONNECTing. The command that is issued is determined by the character that is typed after the escape character. The following characters are recognized by Kermit68K after the escape character: B - Send a BREAK C - Close the connection and return to Kermit68K H - Hangup and close the connection S - Show the connection status 0 - Send a NULL ? - Type help text Escape-Character - Send the Escape-Character Page 10 Any other character will cause Kermit68K to ring the bell at the local terminal. The Escape-Character S (show status) command displays the terminal line being used and the settings of local echo and parity. cc.pp The COPY command This causes Kermit68K to make a copy of the specified local file. The format of the command is: Kermit68K>COPY Where is the name of the file you wish to copy, and is the name for the copy. cc.pp The CWD command This command (short for "Change Working Directory") causes Kermit68K to change the default directory that will be used for files whose specification does not include the directory information. What happen if no device or directory is specified is implementation dependent. Kermit68K>CWD [] Where is the device and/or directory to set as default. cc.pp The DEFINE command This command allow the user to define a macro command. The format of the command is: Kermit68K>DEFINE [] Where is the name of the macro you are defining and should be specified when you want to define a one-command macro. In the case you want to define a multi-command macro, that is a macro that has a body composed of several lines, you shouldn't specify the optional string, Kermit68K will prompt you (really there is no prompt string) for macro body lines until you enter a blank line. For further information on macro commands see the section below. cc.pp The DELETE command This causes Kermit68K to delete the specified local file(s). The format of the command is: Kermit68K>DELETE Page 11 Where specifies the file(s) you wish to delete. cc.pp The DIRECTORY command This causes Kermit68K to display a listing of the current default directory or of the one specified in the command. Kermit68K>DIRECTORY [] Where allow, depending on system characteristics, the generation of a more selective listing. cc.pp The EXIT command The EXIT command will cause Kermit68K to return to command level. This command is the same as the QUIT command. Kermit68K>EXIT cc.pp The FINISH command This command will cause Kermit68K (when in local mode) to tell the other Kermit (which should be in server mode) to exit from Kermit. After receiving the acknowledgement that this is being done, Kermit68K will prompt for another command. Kermit68K>FINISH cc.pp The GET command The GET command is used to have a local mode Kermit68K request a file from a remote Kermit server. Kermit68K must be running as a local Kermit. Kermit68K will then request the other Kermit (which must be running in server mode) to transfer the specified file (or set of files) to Kermit68K. The file specification must be in the format of the system on which the server Kermit is running. The format of the command is: Kermit68K>GET Where is any valid file specification on the system on which the server Kermit is running. cc.pp The HELP command Prints a brief summary of the Kermit68K commands and user defined macros. Page 12 Kermit68K>HELP cc.pp The LIST command This command will cause Kermit68K to show the body of the specified user defined macro. Kermit68K>LIST Where is the name of the macro of wich you want the listing. cc.pp The QUIT command This command will cause Kermit68K to return to the operating system command level. This is the same as the EXIT command. Kermit68K>QUIT cc.pp The RECEIVE command The RECEIVE command is used to put Kermit68K into remote mode waiting for a single file transfer transaction. This is most useful if the other Kermit does not support local server commands. If no file specification is given, Kermit68K will use whatever file specification is supplied by the other Kermit (suitably altered to conform to the underlying operating system standards). If a file specification is given, Kermit68K will use that file specification instead of that supplied by the other Kermit. This is most useful when the file name on the other system is such that it does not map well into a local system file specification. Note that if the other Kermit sends more than one file, only the first one is renamed. Therefore, it is best to use a file-specification on this command only when transferring a single file. The format of the command is: Kermit68K>RECEIVE Where is any valid file specification on your system. cc.pp The REMOTE command This command allows the user of Kermit68K (in local mode) to give various commands to the other Kermit (which must be in server mode). These commands provide for listing the contents of a directory, deleting files, typing files, displaying the amount of disk space used, etc. Note that not all server Kermits support all commands, but all server Kermits should respond with a message saying the command is not implemented if it does not support it. Kermit68K>REMOTE [...] Page 13 Where is the name of the command, and is one optional argument for the command. cc.pp.1 The Remote COPY command This causes Kermit68K to request that the server Kermit make a copy of the specified file. Both the old and new files are files on the server's system - no file transfer between systems is done. The server Kermit should respond with some indication that either the file was successfully copied, or with an error message. Note that some Kermit's will allow wild-carded copies, while others will only allow a single file to be copied per command. Kermit68K>REMOTE COPY Where is the name of the file you wish to copy, and is the name for the copy. cc.pp.2 The Remote CWD command This command (short for "Change Working Directory") causes Kermit68K to request that the server Kermit change the default directory (path, device, etc.) that will be used for files whose specification does not include the directory information. For some systems a password can be supplied which will allow access to the new directory. If no directory is specified in the command, the server Kermit will set the default directory back to the users default. This may be either the directory which is the default when a job created, or the default directory which was in effect when the server Kermit was started. The server Kermit should respond with a message which indicates where the new default directory has been set, or with an error message. Kermit68K>REMOTE CWD [] [] Where is a string which is acceptable as a directory specification for the server system and is a string that could give you access to the specified mass-storage area. cc.pp.3 The Remote DELETE command This causes Kermit68K to request the server Kermit to delete the specified file (or files if the server Kermit supports wild-card deletes). The server Kermit should respond with a message indicating whether the file (or files) has been deleted. Kermit68K>REMOTE DELETE Where is a valid file specification for the remote Kermit's system. Page 14 cc.pp.4 The Remote DIRECTORY command This causes Kermit68K to request a directory listing from the server Kermit. The directory listing will be printed on the user's terminal. The format of the listing is determined by the server Kermit. Kermit68K>REMOTE DIRECTORY [] Where is a valid file specification for the server Kermit's system. cc.pp.5 The Remote SPACE command This causes Kermit68K to request the server Kermit to reply with an indication of the amount of disk space used and available for the given directory/device (or the default directory/device if none is given). Kermit68K>REMOTE SPACE [] Where is a specification for the server Kermit's system to allow, when possible, the generation of more selected information. cc.pp.6 The Remote HELP command This causes Kermit68K to request the server Kermit to reply with a short summary of what commands it supports in server mode. If an argument is given, help on the specific topic is requested. The resulting help message will be typed on the users terminal. Kermit68K>REMOTE HELP [] Where is a subject for more detailed help. If no topic is given, a general help message is requested. cc.pp.7 The Remote HOST command This command requests the server Kermit to perform the specified command as if it were typed by the user on a terminal. Any results of the command will be printed on the user's terminal. Note that this should only be used for commands which will not require any more user input, since there will be no way for the user to interact with the remote system to supply more input. Kermit68K>REMOTE HOST Where is any valid command to be processed by the remote system's standard command parser. cc.pp.8 The Remote RENAME command Page 15 This command causes Kermit68K to request that the server Kermit change the name of a file. The server Kermit should respond with an indication that the operation is completed successfully, or else with an error message. Some Kermit programs may allow wild-card file specifications to be used, and will respond with a list of files and new names. Kermit68K>REMOTE RENAME Where is the name of the file to be renamed, and is the new name for the file. cc.pp.9 The Remote TYPE command This causes Kermit68K to request the server Kermit to transmit the specified file (or files if the server supports wild-cards) so that the file(s) can be typed on the users terminal. Kermit68K>REMOTE TYPE Where is a valid file specification for the server Kermit's system. cc.pp.10 The Remote WHO command This requests the server Kermit to display a list of users of its system, along with other information about the users and/or system. A specific user-id may be supplied, which may result in more detailed information about the particular user. Kermit68K>REMOTE WHO Where is an optional string representing a specific user. cc.pp The RENAME command This command causes Kermit68K to change the name of a local file. Kermit68K>LOCAL RENAME Where is the name of the file to be renamed, and is the new name for the file. cc.pp The SEND command The SEND command will allow you to send a file(s) to the other Kermit. The SEND command will allow file wild-card processing depending on the underlying operating system. If Kermit68K is running in remote mode, the file will be sent on the controlling terminal line after waiting the number of seconds specified by the SET DELAY command. This gives the user time to escape back to the other Kermit and issue a receive command. If Kermit68K is running in local mode, the file will be sent immediately on the terminal line specified Page 16 by the SET LINE command. Kermit68K>SEND Where is any valid file specification. cc.pp The SET command The SET command is used to set various parameters in Kermit68K. cc.pp.1 The Set BLOCK_CHECK_TYPE command The SET BLOCK_CHECK_TYPE command is used to determine the type of block check sequence which will be used during transmission. The block check sequence is used to detect transmission errors. There are three types of block checks available. These are the single character checksum (default), the two character checksum, and the three character CRC (cyclic redundancy check). This command does not ensure that the desired type of block check will be used, since both Kermit's involved in the transfer must agree on the block check type. Kermit68K will request that the type of block check set by this command be used for a transfer. If the other Kermit has also had the same block check type requested, then the desired block check type will be used. Otherwise, the single character checksum will be used. (See the Kermit protocol manual for more information.) Kermit68K>SET BLOCK_CHECK_TYPE Where is one of 1, ONE, 2, TWO, 3, THREE. cc.pp.2 The Set DELAY command The DELAY parameter is the number of seconds to wait before sending data after a SEND command is given. This is used when Kermit68K is running in remote mode to allow the user time to escape back to the other Kermit and give a RECEIVE command. Kermit68K>SET DELAY Where is the number of seconds to wait before sending data. cc.pp.3 The Set ESCAPE command This command will set the escape character for the CONNECT processing. The command will take the decimal value of the character to use as the escape character. This is the character which is used to "escape" back to Kermit68K after using the CONNECT command. It defaults to 5 decimal (ASCII ENQ, CTRL-E). Page 17 It is usually a good idea to set this character to something which is not used (or at least not used very much) on the system to which Kermit68K is CONNECTing. Kermit68K>SET ESCAPE Where is the ASCII value of the character to use as the escape character. cc.pp.4 The Set FILE command The SET FILE command allows setting of parameters relating to the file format and file naming conventions used by Kermit68K. Kermit68K>SET FILE Where is one of DISPLAY, NAMES, TYPE, WARNING. cc.pp.4.1 The Set File DISPLAY command This command allows the user to enable/disable two features of Kermit68K when it runs in local mode: the file transfers progress display and the keyboard sampling to detect user interruptions. By default the file display parameter is ON. If OFF (this might be achieved also specifying -q on the command line) none of this is done, and, if the system support multitasking, the file transfer may proceed in the background oblivious to any other work concurrently done at the console terminal. Kermit68K>SET FILE DISPLAY Where is either ON or OFF. cc.pp.4.1 The Set File NAMES command This command sets the type of processing Kermit68K should do on file names that are being sent and received. Kermit68K can either send the complete file specification (including device, directories, file name, file type and version number) or only the file name and type. When receiving a file specification, Kermit68K can either attempt to use it as a normal file specification as is, or first perform some substitutions and truncations in order to force the received specification to be just a valid file name and type. Normally CONVERTED, which means that outbound filenames have path specifications stripped, strange characters and extra periods changed to X's and so on. LITERAL means that none of these conversions are done; therefore, 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. Page 18 Kermit68K>SET FILE NAMES Where is either CONVERTED or LITERAL. cc.pp.4.2 The Set File TYPE command This command will set the file type that Kermit68K is receiving. A file type of TEXT should be used to receive text files which are to be used as text files on the local system. The file type BINARY should be used for binary files, such as CP/M .COM files, which need to be kept in a format that allows the file to be returned without any changes. Furthermore, if the system uses a single character instead of a CRLF sequence for text file line delimitation (this is the case of OS9), that character will be converted to CRLF upon output, and CRLF will be converted to that character on input. When the BINARY file type is selected (this might be done also specifying the -i option in the command line) Kermit68K makes no conversion between newlines and CRLF line delimiters. Kermit68K>SET FILE TYPE Where is either TEXT or BINARY. cc.pp.ss The Set File WARNING command Normally OFF, which means that incoming files will silently overwrite existing files of the same name. When ON (this might be done also specifying the -w option on the command line) Kermit68K will check if an arriving file would overwrite an existing file; if so, it will construct a new name for the arriving file, in a form that is dependent from the the implementation. Kermit68K>SET File WARNING Where is either ON or OFF. cc.pp.ss The Set FLOW_CONTROL command 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. Kermit68K>SET FLOW_CONTROL Where is either NONE or XON/XOFF. cc.pp.5 The Set HANDSHAKE command Page 19 Sets the half duplex line turnaround handshake character Kermit68K will use. Normally required for communication with half duplex systems like IBM mainframes. Kermit68K>SET HANDSHAKE Where is one of NONE, BELL, LF, CR, XON, XOFF, ESC. The SET HANDSHAKE NONE command turns handshaking off. cc.pp.6 The Set INCOMPLETE_FILE_DISPOSITION command This command allows the user to determine what is done with a file that is not completely received. If the disposition is KEEP, all files received will be kept, even if only a portion of the file is received. If the disposition is DISCARD (the default), files which are not completely received are discarded. Kermit68K>SET INCOMPLETE_FILE_DISPOSITION Where is either DISCARD or KEEP. cc.pp.7 The Set LINE command This will set the terminal line that you are using. The terminal line must be one which is accessible to the users process. Kermit68K>SET LINE The device must be a terminal line. cc.pp.7 The Set DUPLEX command The SET DUPLEX command specifies whether characters should be echoed locally when CONNECTing to another system. If DUPLEX is set to HALF, any character typed on the terminal will be echoed immediately to the terminal, as well as being sent to the other system. If DUPLEX is set to FULL (the default), the characters typed on the terminal are only sent to the other system (which would normally be echoing the characters). Kermit68K>SET DUPLEX Where is either FULL or HALF. cc.pp.7 The Set PARITY command This command determines the type of parity to use on the transmission line. Kermit68K normally uses characters which consist of eight data bits with no parity bit. For systems or transmission media which require a specific parity type, Kermit68K can send characters as seven data bits plus a parity bit. Page 20 Kermit68K>SET PARITY Where is one of: NONE (default) eight data bits and no parity bit. MARK seven data bits with the parity bit set to one. SPACE seven data bits with the parity bit set to zero. EVEN seven data bits with the parity bit set to make the overall parity even. ODD seven data bits with the parity bit set to make the overall parity odd. cc.pp.8 The Set PROMPT command This command sets the string to be used for the command prompt. If no argument is given, the default prompt "Kermit68K>" is used. Kermit68K>SET PROMPT [] Where is the new prompt to use. cc.pp.9 The set RECEIVE command It is possible to set various parameters associated with the receiving of the data from the remote Kermit. SET RECEIVE will enable you to set the various receive parameters. cc.pp.9.1 The Set Receive END_OF_LINE command This will set the end-of-line character the Kermit68K expects to receive from the remote Kermit. This is the character which terminates a packet. The parameter must be a number in the range 1 to 31 decimal. The default value is 13 decimal (ASCII CR, CTRL-M). Kermit68K>SET RECEIVE END_OF_LINE Where is the ASCII value of the character to use for the end-of-line character. cc.pp.9.2 The Set Receive MARKER command This command will set the start of packet character for Kermit68K. The start of packet character must be in the range of 1 to 31 decimal. The default value is 1 (ASCII SOH, CTRL-A). This value should only be changed if absolutely necessary. It must be set the same in both Kermit's. Page 21 Kermit68K>SET RECEIVE MARKER Where is the ASCII value of the receive start-of-packet character to use. cc.pp.9.3 The Set Receive PACKET_LENGTH command This will set the receive packet length. The value for this parameter must be between 10 and 94. Packet lengths outside of this range are illegal. The default value is 80. Kermit68K>SET RECEIVE PACKET_LENGTH Where is the receive packet length to use. cc.pp.9.4 The Set Receive PADDING command Kermit68K normally does not need to have incoming packets preceded with pad characters. This command allows Kermit68K to request the other Kermit to send the specified number of pad characters before any packet. The default value is 0. Kermit68K>SET RECEIVE PADDING Where is the number of padding characters to request. cc.pp.9.5 The Set Receive PAD_CHARACTER command This parameter is the padding character that will be sent by the remote Kermit. The parameter must be in the range of 0 to 31 or 127 decimal. The default value is 0 (ASCII NUL, CTRL-@). Kermit68K>SET RECEIVE PAD_CHARACTER Where is the ASCII value of the character to be used by the remote Kermit as a pad character. cc.pp.9.6 The Set Receive TIMEOUT command This will set the number of seconds before Kermit68K will time out the attempt to receive a message. This time out is used to handle transmission errors which totally lose a message. The default value is 15 seconds. Kermit68K>SET RECEIVE TIMEOUT Where is the number of seconds to wait for a message. Page 22 cc.pp.10 The Set RETRY command This command sets the maximum number of times Kermit68K should try to send specific packets. There are two retry maximums, one for the initial connection packet (the "SEND-INIT"), the other for all other packets. The default value for initial connections is 5. The default value for all other packets is 16. Kermit68K>SET RETRY Where is either INITIAL_CONNECTION (for initial connection packet) or PACKET (for all other packets), and is the number of retries to attempt. cc.pp.11 The Set SEND command It is possible to set various parameters associated with the receiving of the data from the remote Kermit. SET SEND will enable you to set the various SEND parameters. These parameters should not normally be set, since as part of the transfer initialization process the two Kermit's exchange their RECEIVE parameters. The capability of setting these parameters is provided so that the transfer initialization can be completed even if the default parameters are not correct. cc.pp.11.1 The Set Send END_OF_LINE command This will set the end-of-line character the Kermit68K will send to the remote Kermit. This is the character which terminates a packet. The parameter must be a number in the range 1 to 31 decimal. The default value is 13 decimal (ASCII CR, CTRL-M). Kermit68K>SET SEND END_OF_LINE Where is the ASCII value of the character to use for the end-of-line character. cc.pp.11.2 The Set Send MARKER command This command will set the start of packet character for Kermit68K. The start of packet character must be in the range of 1 to 31 decimal. The default value is 1 (ASCII SOH, CTRL-A). This value should only be changed if absolutely necessary. It must be set the same in both Kermit's. Kermit68K>SET SEND MARKER Where is the ASCII value of the start-of-packet character to use. cc.pp.11.3 The Set Send PACKET_LENGTH command Page 23 This will set the SEND packet length. The value for this parameter must be between 10 and 94. Packet lengths outside of this range are illegal. The default value is 90. Kermit68K>SET SEND PACKET_LENGTH Where is the send packet length to use. cc.pp.11.4 The Set Send PADDING command This command will set the number of padding characters that will be sent to the other Kermit. The default value is 0. Kermit68K>SET SEND PADDING Where is the number of padding characters to use. cc.pp.11.5 The Set Send PAD_CHARACTER command This parameter is the padding character that is sent to the remote Kermit. The parameter must be a number in the range of 0 to 31 or 127 decimal. The default value is 0 (ASCII NUL, CTRL-@). Kermit68K>SET SEND PAD_CHARACTER Where is the ASCII value of the character to be used as a pad character. cc.pp.11.6 The Set Send TIMEOUT command This will set the number of seconds before Kermit68K will time out a message it has sent to the other Kermit. This time out is used to handle transmission errors which totally lose a message. The default value is 15 seconds. Kermit68K>SET SEND TIMEOUT Where is the number of seconds to wait for a message. cc.pp The SHOW command The SHOW command will allow you to show the various parameters that are set with the SET command. cc.pp.1 The Show PARAMETERS command The SHOW PARAMETERS command will cause all of the Kermit68K parameters to be listed. cc.pp.2 The Show VERSION command Page 24 Displays the version number of Kermit68K in use. cc.pp The SPACE command This causes Kermit68K to display the amount of disk space used and available in the current working directory or device. Kermit68K>SPACE [] Where specifies the mass-storage area for wich the usage statistics are wanted. cc.pp The TAKE command The TAKE command tells Kermit68K to execute commands from the specified file. Kermit68K>TAKE Where is any normal local file specification. cc.pp The TYPE command This causes Kermit68K to display the specified file(s) on the terminal. Kermit68K>LOCAL TYPE Where is a valid local file specification. Page 25 cc.pp The macro commands capability Concerning the macro commands capability, at the current development stage, it should be better named "command grouping capability", that is, you can define a commands group making reference to it by use of a single name. A little example, your computer is connected to two hosts, let say a VAX/VMS and an IBM mainframe, you frequently need to exchange files with both of the machines, maybe using your local computer as a temporary storage station. Given this scenario, when you want to connect to the IBM mainframe, you must issue the following command sequence: Kermit68K> SET LINE MyIBMLine Kermit68K> SET PARITY ODD Kermit68K> SET DUPLEX HALF Kermit68K> SET HANDSHAKE XON When you have finished your work with the IBM mainframe, maybe you need to exchange files with the VAX/VMS system, so again: Kermit68K> SET LINE MyVAXLine Kermit68K> SET PARITY NONE Kermit68K> SET DUPLEX FULL Kermit68K> SET HANDSHAKE NONE All this can cause you some frustration; command grouping helps you in this problem. You issue to Kermit68K the following command sequences (maybe included in a take file or in the initialization file KERMIT.INI) ONCE AND FOR ALL: Kermit68K> DEFINE IBM SET LINE MyIBMLine SET PARITY ODD SET DUPLEX HALF SET HANDSHAKE XON (the blank line above tells Kermit68K that the macro body is finished) Kermit68K> DEFINE VAX SET LINE MyVAXLine SET PARITY NONE SET DUPLEX FULL SET HANDSHAKE NONE (the same for this blank line) At this point, all that you need to switch the connection between the two systems back and forth is to type the commands IBM and VAX. If you want to define a one-command macro, you can do the job on a single line, another example: Kermit68K> DEFINE KEEP SET INCOMPLETE_FILE_DISPOSITION KEEP You can see the body of a macro by requiring its LISTing, for example: Kermit68K> LIST IBM Page 26 The command line expansion will come soon in a new Kermit68K release. By this new facility you'll be able to give aliases to Kermit68K commands and to do other interesting things. Two examples showing the FUTURE: Kermit68K> DEFINE LS DIR %1 where %1 stands for the 1st parameter, if you are UNIX-dependent, now you can use LS instead of DIR; Kermit68K> DEFINE MOVE echo Sending file %1 send %1 echo Deleting file %1 delete %1 now you have a command that will allow you to destroy your most important files, if the transfer fails. Page 27 cc Command Line Operation The Kermit68K command line syntax conforms to the Proposed Syntax Standards for Unix System Commands put forth by Kathy Hemenway and Helene Armitage of ATT Bell Laboratories in Unix/World, Vol.1, No.3, 1984. The rules that apply are: a) Command names must be between 2 and 9 characters ("kermit" is 6). b) Command names must include lower case letters and digits only. c) An option name is a single character. d) Options are delimited by '-'. e) Options with no arguments may be grouped (bundled) behind one delimiter. f) Option-arguments cannot be optional. g) Arguments immediately follow options, separated by whitespace. h) The order of options does not matter. i) A group of bundled options may end with an option that has an argument. Kermit68K command line options may specify either actions or settings. If Kermit68K 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. The command line may contain no more than one protocol action option. The following options are interpreted by Kermit68K. -s Send the specified file or files. If contains wildcard (meta) characters, Kermit68K will try to expand it into a file list. -r Receive a file or files. Wait passively for files to arrive. -k Receive (passively) a file or files, sending them to standard output. If the operating system supports IO redirection and/or pipes, this option can be powerfully used in several ways. -a If you have specified a file transfer option in the command line, you may give an alternate name for a single file with the -a ("as") option. When used with -s Kermit68K tells to the receiver that the file must be stored under the name , when used with -r or -g, Kermit68K stores the incoming file under the name . Note that if more than one file is sent or arrives, only the first file is affected by the -a option. -l Specify a terminal line to use for file transfer and terminal connection. When an external line is being used, you might also need some additional options for successful communication with the remote system. These options are -b (baud-rate), -p Page 28 (parity) and -t (turnaround). -b Specify the baud rate for the line given in the -l option. This option should always be included with the -l option, since the speed of an external line is not necessarily what you expect. is a number specification, possible values are 50, 110, 150, 300, 600, 1200, 2400, 4800, 9600, 19200 and 38400. -p Specify the parity to be used on the transmission line, possible values are 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 that the opposite Kermit agrees. The default parity is none. -t Specifies half duplex, line turnaround with XON as the handshake character. -g Actively request a remote server to send the named file or files, note that is a file specification in the remote host's own syntax. -f Send a 'finish' command to a remote server. -c Establish a terminal connection over the default communication line, before any protocol transaction takes place. Get back to the local system by typing the escape character (normally Control-E) 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. -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 for transfers between like systems (it must be given to both Kermit68k programs), where it will improve performance by circumventing the normal text-file conversions, and will allow mixture of text and binary files in a single file group. -w Avoid filename collisions for incoming files. Page 29 -q Suppress screen update during file transfer, for instance to allow a file transfer to proceed in the background. -h Display a brief synopsis of the command line options. Command Line Examples: kermit -l EPCI2 -b 1200 -cn -r This command connects you to the system on the other end of EPCI2 at 1200 baud, where you presumably log in and run Kermit with a 'send' command. After you escape back, Kermit68K waits for a file (or files) to arrive. When the file transfer is completed, you are reconnected to the remote system so that you can logout. kermit -l /T1 -b 4800 -cntp m -r -a format.s 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 format.s. 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 is invoked after -f (-c would have been invoked before). kermit -i -wl acia1 -b 9600 This command sets the communication line and speed. Files are transmitted as binary. Incoming files that have the same names as existing files are given new, unique names. Since no action is specified, Kermit68K issues a prompt and enters an interactive dialog with you. Any settings given on the command line remain in force during the dialog, unless explicitly changed. kermit This command starts up Kermit interactively with all default settings. cc.pp File Transfer If Kermit68K is in local mode and file display is on, the terminal screen is continously updated to show the progress of the file transfer. 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 F File Header G Generic Server Command C Remote Host Command N Negative Acknowledgement (NAK) E Fatal Error Page 30 T Indicates a timeout occurred Q Indicates a damaged, undesired, or illegal packet was received % Indicates a packet was retransmitted cc.pp Control Characters During a file transfer (GET, RECEIVE or SEND commands) with Kermit68K in local mode the following control characters can be used to affect the transfer in progress: CTRL-R - Force a protocol timeout, resend last packet CTRL-X - Abort the file currently being transfered CTRL-Z - Abort the file group currently being transfered Page 31 cc.pp References 1 Kermit, A File Transfer Protocol, ISBN 0-932376-88-6, 1986 Frank da Cruz, Digital Press, Bedford MA DEC order number EY-6705E-DP 2 M68000 16-Bit Microprocessor, User's Manual, MC68000UM(AD3), Third Edition, 1982 Motorola Inc. 3 MC68020 32-Bit Microprocessor, User's Manual, MC68020UM(AD1), First Edition, 1984 Motorola Inc. 4 68000/08/10 Cross Assembler for MSDOS & CP/M 86, Reference Manual 2500 A.D. Software, Inc. 5 M68000 Cross Macro Assembler, Reference Manual, M68KXASM(D3), September 1979 Motorola Inc. 6 M68MIL Cross Macro Assembler CERN 83-12, 22 December 1983 Horst von Eicken, CERN, Data Handling Division