EXPLORER KERMIT USER GUIDE Brian Carb Unisys Corporation and Steve Ford Texas Instruments Incorporated January 21, 1987 Copyright (c) 1987 Unisys Corporation Copyright (c) 1987 Texas Instruments Incorporated AN ADDENDUM TO KERMIT USER GUIDE Sixth Edition, Revision 2 Frank da Cruz, editor Columbia University Center for Computing Activities New York, New York 10027 May 26, 1986 Copyright (C) 1981,1986 Trustees of Columbia University in the City of New York Permission is granted to any individual or institution to use, copy, or redistribute this document so long as it is not sold for profit, and provided this copyright notice is retained. EXPLORER KERMIT Page A-i Table of Contents Introduction A-1 1. The Explorer File System A-2 1.1. Text Files and Binary Files A-3 2. Program Operation A-4 3. Remote Operation A-7 4. Interference A-7 5. Explorer Kermit Commands A-7 5.1. Get File(s) A-8 5.2. Receive File(s) A-10 5.3. Send File(s) A-11 5.4. Bye A-13 5.5. Finish A-13 5.6. Set Parameters A-13 5.6.1. Image Mode A-14 5.6.2. Debug Mode A-14 5.6.3. More Processing A-14 5.6.4. Maximum tries A-14 5.6.5. Maximum packet size A-14 5.6.6. Timeout seconds A-15 5.6.7. Number of pad characters A-15 5.6.8. Padding character A-15 5.6.9. EOL character A-15 5.6.10. Quote character A-15 5.6.11. Filename conversion A-16 5.6.12. Save partial files A-16 5.6.13. Reset parameters A-16 5.7. Begin Logging A-16 5.8. End Logging A-17 5.9. Server Mode A-17 5.10. Remote Commands A-17 5.10.1. Remote Copy A-17 5.10.2. Remote CWD A-18 5.10.3. Remote Delete A-19 5.10.4. Remote Directory A-19 5.10.5. Remote Help A-20 5.10.6. Remote Host A-20 5.10.7. Remote Kermit A-21 5.10.8. Remote Rename A-21 5.10.9. Remote Set A-22 5.10.10. Remote Show A-22 5.10.11. Remote Space A-23 5.10.12. Remote Type A-23 6. Installation of Explorer Kermit A-24 7. Known Deficiencies A-24 EXPLORER KERMIT Page A-1 Introduction Explorer Kermit is a program that implements the Kermit file transfer protocol for the Explorer system available from Texas Instruments Incorporated and Unisys Corporation. This implementation was developed as a joint effort between the two companies. It is written in Common Lisp and runs on Explorers running TI Software Release 2.0 or 2.1, or Unisys Software Release 2.0.1 or 2.1.1. This implementation has been successfully tested in conjunction with Kermit implementations for Unisys OS 1100, DEC Vax, DEC 2060, and Unisys 5000/50 Systems, and Unisys and IBM PCs (KERMIT-MS). This document describes the things you should know about the Explorer file system in order to make effective use of Kermit, and the special features of the Explorer Kermit program. Installation instructions are included at the end. The following list indicates which Kermit capabilities are available with Explorer Kermit. Local operation: Yes Remote operation: Yes Transfers text files: Yes Transfers binary files: Yes Wildcard send: Yes File transfer interruption: Yes Filename collision avoidance: Yes Timeouts: Yes 8th-bit prefixing: Yes Repeat character compression: Yes Alternate block check types: Yes Communication settings: Yes Transmit BREAK: Yes IBM mainframe communication: Yes Terminal emulation: Yes (VT100) Support for dialout modems: Yes Transaction logging: Yes Session logging: Yes Debug logging: Yes Raw transmit: Yes Login scripts: Yes Act as server: Yes Talk to server: Yes Advanced commands for servers: Most Local file management: Yes Command/init files: Yes Handle file attributes: No EXPLORER KERMIT Page A-2 1. The Explorer File System The features of the Explorer file system of greatest interest to Kermit users are the form of the file specifications, and the distinctions between text and binary files. Explorer file specifications are of the form: HOST:DIRECTORY;NAME.TYPE#VERSION HOST, if omitted, defaults to the local machine, DIRECTORY defaults to the logged-on user's directory, and VERSION defaults to > (latest). NAME.TYPE should normally be provided, since the defaults may be difficult to predict. The host, directory, name, and type fields may contain any ASCII character, except control characters (like the carriage return). The fields of the file specification are set off from one another by the punctuation indicated above. Explorer Kermit transmits the pathname as specified by the user to the target system, including host, device, and directory components. If the target system cannot handle all full pathnames, the user should only specify what can be handled. Explorer Kermit attempts to parse full pathnames sent to it, but they must be in legal Explorer format. The name is the primary identifier for the file. The type is an indicator which, by convention, tells what kind of file we have. For instance FOO.LISP is the source of a Lisp program named FOO; FOO.XFASL might be the object file produced by compiling FOO.LISP; FOO.TEXT might be a text file documenting FOO. The Explorer allows a group of files to be specified in a single file specification by including the special "wildcard" character, "*". A "*" matches any string of characters, including no characters at all. Here are some examples: *.LISP All files of type LISP in the default directory. 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 at least one X. 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. EXPLORER KERMIT Page A-3 1.1. Text Files and Binary Files The Explorer, like most computers, has a file system with its own peculiari- ties. Like many other systems, the Explorer makes a distinction between text files and binary files. Text files are generally those composed only of printing characters (letters, digits, and punctuation) and "carriage control" characters (carriage return, line feed, form feed, tab). Text files are designed to be read by people. Binary files are designed to be read by a computer program, and may contain any contents at all. If you view a text file in the Explorer's ZMACS editor, the result will be intelligible. If you view a binary file, you will probably see gibberish. You can not always tell a text file from a binary file by its name or directory information, although, in general, files with types like .TEXT, .DOC, .HELP are textual (as are "source files" for computer programs like text formatters and programming language compilers), and files with types like .XFASL, .QFASL, and .XLD are binary. The Explorer has a 32-bit word size. It stores text in 8-bit bytes. It uses a modified ASCII character set that is extended by use of the 8th bit and has most control characters in non-standard positions. When transferring textual information via Kermit, the non-standard characters are converted to standard ASCII. When transferring binary files (8-bit or 16-bit), Image Mode is provided to override the ASCII translations. The minimum unit of disk allocation on the Explorer is a page: 256 32-bit words, or 512 16-bit bytes, or 1024 8-bit bytes. Any file that contains at least one bit of information occupies at least a full page on the disk. The directory information for a file includes the number of pages occupied on the disk, the number of bytes in the file and the size of those bytes, the date and time the file was created, and the author. This information can be seen by using the Explorer DIRED command. For instance: (dired "D:KERMIT;*.*") D: KERMIT; *.*#* Free=16551, Reserved=47, Used=13402 (172 pages used in KERMIT;) 171 blocks in files listed -READ-ME-.TXT #7 5 4531(8) ! 09/24/86 10:48:01 KERMIT DEFSYSTEM.LISP #13 1 507(8) ! 08/21/86 12:10:52 KERMIT KERMIT.LISP #276 92 93681(8) ! 07/19/86 19:06:58 KERMIT KERMIT.XFASL #276 42 21099(16) ! 07/19/86 19:18:43 KERMIT MAKE-KERMIT.LISP #2 1 122(8) ! 07/19/86 18:25:00 KERMIT SERIAL-TELNET.LISP #48 16 15902(8) ! 09/25/86 12:11:03 KERMIT SERIAL-TELNET.XFASL #48 14 7037(16) ! 09/25/86 12:11:24 KERMIT EXPLORER KERMIT Page A-4 In this example, MAKE-KERMIT.LISP#2 occupies 1 page, and is composed of 122 8-bit bytes. This file is textual (a LISP source file), and 122 characters long. Although this file occupies an entire 1024-byte page of storage, any Explorer program which accesses this file, including Explorer Kermit, only deals with the first 122 characters. 2. Program Operation There are two ways to invoke Explorer Kermit; interactively, via the VT100 Terminal Emulator, or programmatically, via the KERMIT:KERMIT Lisp Function. To invoke Explorer Kermit interactively: Instantiate a new VT100 Emulator with a -V key sequence. After the prompt "VT100. Connect to host:", type PORT . Configure the Explorer's serial port by selecting the proper parameters from the menu. Select DO IT with the mouse. Either select AUTODIAL with the mouse from the menu beneath the VT100 window, and fill in your autodial modem's prefix and the destination host's phone number, or dial-up your host manually. Once a carrier is established, a generally gets the attention of the host. Login to the host as you normally would. Once you have established a session with the host, the easiest way to use Explorer Kermit is to put the other host in Kermit server mode, and control all file transfer from the Explorer end by selecting Kermit from the menu below the VT100 window. When you do, a menu pops up containing the various Kermit commands. Each entry is documented at the bottom of the screen when the mouse is over it. Select the appropriate one with the mouse and supply the additional information requested. A status window is displayed over the VT100 window so that the progress of your request can be monitored. The rate of transfer in characters per second is displayed in two forms; the first counts all packeted characters sent, including packet headers and trailers required by the protocol, and the second counts the data characters from the file processed by Kermit. Although the latter is generally slower than the former, it could be faster if prefix encoding for repeated characters is used. The operation being executed, the original and new file names, the total number of packets processed, and the number of packet resends required for this operation are also displayed. As always on the Explorer, the progress of file transfers can be monitored at the character count and percentage levels in the status line at the extreme lower right corner of the screen. ABORT or ABORT-SAVE with the mouse will abort your request. When your request is complete, a message so indicating is displayed in the window. To return to terminal emulation, press any key. Then take the destination host out of server mode by selecting BYE or FINISH from the Kermit menu. EXPLORER KERMIT Page A-5 To invoke Explorer Kermit from Lisp: Type (KERMIT:KERMIT :ARG1 :ARG2 :STREAM :VERBOSEP ), where is one of the following: :GET Transfer file(s) from a remote Kermit in server mode. :RECEIVE Wait for the arrival of file(s) transferred by a remote Kermit executing a Send command. :SEND Transfer file(s) to a remote Kermit in server mode or executing a Receive command. :BYE Shut down and logout a remote Kermit server. :FINISH Shut down a remote Kermit server without logging out the remote job. :SET Modify the local Kermit operating parameters. :LOG-BEGIN Begin logging local Kermit actions to a file. :LOG-END End logging local Kermit actions to a file. :SERVER Place local Kermit in server mode. :REMOTE-COPY Copy the specified file to another location on a remote Kermit server. :REMOTE-CWD Change the working directory of a remote Kermit server. :REMOTE-DELETE Delete a file on a remote Kermit server. :REMOTE-DIRECTORY Display names of files in a directory on remote Kermit server. :REMOTE-HELP Display a list of remote Kermit server help commands. :REMOTE-HOST Pass the given command to the remote Kermit server host for processing (the command must be in the remote Kermit host's own command level syntax). :REMOTE-KERMIT Pass the given command to the remote Kermit server for execution (the command must be in the remote Kermit's own interactive mode syntax). :REMOTE-RENAME Rename the specified file on a remote Kermit server. :REMOTE-SET Set a parameter to a given value on a remote Kermit server. :REMOTE-SHOW Obtain the value of a parameter on a remote Kermit serve. :REMOTE-SPACE Display information about disk usage for a directory on remote Kermit server. :REMOTE-TYPE Display the specified filename from a remote Kermit server. is a filename, directory, command or parameter, depending on . is a new filename, destination name or parameter, depending on is the serial stream to use (created with the function SI:MAKE-SERIAL-STREAM). is either T or NIL, depending on whether or not you want status messages printed. EXPLORER KERMIT Page A-6 If you are running Explorer Kermit programmatically, the Lisp function TELNET:RUN-SCRIPT might also be helpful in simulating an interactive user session with a remote host. To invoke TELNET:RUN-SCRIPT from Lisp: Type (TELNET:RUN-SCRIPT