@part(20KERMIT,root="kuser") @string{-20version="@q<5.1(263)>"} @Chapter @label<-k20> @Index[TOPS-20] @Index[DECSYSTEM-20] @begin @i(Authors:)@\Frank da@ Cruz, Bill Catchings, Columbia University @i(Language:)@\MACRO-20 @i(Version:)@\@value(-20version) @i(Date:)@\January 2001 @end @subheading @begin @tabclear()@tabset(3.5inches,4.0inches) Local operation:@\Yes Remote operation:@\Yes Transfers text files:@\Yes Transfers binary files:@\Yes Wildcard send:@\Yes @q<^X/^Y> 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 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:@\Yes Local file management:@\Yes Command/init files:@\Yes Long packets:@\Yes Sliding windows:@\No Handle file attributes:@\No @end Kermit-20 is a program that implements the Kermit file transfer protocol for the Digital Equipment Corporation DECSYSTEM-20 mainframe computer. It is written in MACRO-20 assembly language and should run on any DEC-20 system with version 4 of TOPS-20 or later. The Kermit-20 section will describe the things you should know about the DEC-20 file system in order to make effective use of Kermit, and then it will describe the special features of the Kermit-20 program. @Section The features of the DEC-20 file system of greatest interest to Kermit users are the form of the file specifications, and the distinctions between text and binary files. @Subheading DEC-20 file specifications are of the form @example(DEVICE:NAME.TYPE.GEN;ATTRIBUTES) where the DIRECTORY, NAME, and TYPE may each be up to 39 characters in length, GEN is a generation (version number), and various attributes are possible (protection code, account, temporary, etc). Generation and attributes are normally omitted. Device and directory, when omitted, default to the user's own (or "connected") disk and directory. Thus @q is normally sufficient to specify a file, and only this information is sent along by Kermit-20 with an outgoing file. The device, directory, name, and type fields may contain uppercase letters, digits, and the special characters "@q<->" (dash), "@q<_>" (underscore), and "@q<$>" (dollar sign). There are no imbedded or trailing spaces. Other characters may be included by prefixing them (each) with a Control-V. The fields of the file specification are set off from one another by the punctuation indicated above. The device field specifies a physical or "logical" device upon which the file is resident. The directory field indicates the area on the device, for instance the area belonging to the owner of the file. Kermit-20 does not transmit the device or directory fields to the target system, and does not attempt to honor device or directory fields that may appear in incoming file names; for instance, it will not create new directories. The name is the primary identifier for the file. The type, also called the "extension", is an indicator which, by convention, tells what kind of file we have. For instance @q is the source of a Fortran program named FOO; @q might be the relocatable object module produced by compiling @q; @q could an executable program produced by LOADing and SAVing @q, and so forth. @index The DEC-20 allows a group of files to be specified in a single file specification by including the special "wildcard" characters, "@q<*>" and "@q<%>". A "@q<*>" matches any string of characters, including no characters at all; a "@q<%>" matches any single character. Here are some examples: @Begin(Description,spread 0.5,leftmargin +8, indent -8) @q<*.FOR>@\All files of type @q (all Fortran source files) in the connected directory. @q@\Files of all types with name @q. @q@\All files whose names start with F. @q@\All files whose names start with F and contain at least one X. @q<%.*>@\All files whose names are exactly one character long. @q<*.%%%*>@\All files whose types are at least three characters long. @End(Description) 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. @heading The DEC-20, like most computers, has a file system with its own peculiarities. Like many other systems, the DEC-20 makes a distinction between @i and @i. 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 have any contents at all. If you use the DEC-20 TYPE command to display a text file on your terminal, the result will be intelligible. If you type a binary file on your terminal, you will probably see mainly gibberish. You can not always tell a text file from a binary file by its name or directory information, though in general files with types like @q<.TXT>, @q<.DOC>, @q<.HLP> are textual (as are "source files" for computer programs like text formatters and programming language compilers), and files with types like @q<.EXE>, @q<.REL>, @q<.BIN> are binary. The DEC-20 has an unusual word size, 36 bits. It differs from most other systems by storing text in 7-bit, rather than 8-bit, bytes. Since text is encoded in the 7-bit ASCII character set, this allows more efficient use of storage. However, the word size is not a multiple of the normal byte size. The DEC-20 therefore stores five 7-bit characters per word, with one bit left over. It is also possible to store files with other byte sizes. The common layouts of bytes within a word are shown in Figure @ref<-20bsfig>. @begin(figure) @bar() @blankspace(1) @Begin(Description,leftmargin +8,indent -4,group) @ @u(7):@\Text Files: Five 7-bit bytes per word. @Begin(Example,leftmargin +1) +------+------+------+------+------++ | | | | | || +------+------+------+------+------++ 0 7 14 21 28 35 @End(Example) Normally, bit 35 is unused and set to zero. However, in EDIT (or SOS, or OTTO) line-@|numbered files, bit 35 is set to 1 when the word contains a line number. @End(Description) @Begin(Description,leftmargin +8,indent -4,group) @ @u(8):@\"Foreign" binary files: Four 8-bit bytes per word. @Begin(Example,leftmargin +1) +-------+-------+-------+-------+---+ | | | | | | +-------+-------+-------+-------+---+ 0 8 16 24 32 35 @End(Example) Bits 32-35 are unused. @End(Description) @Begin(Description,leftmargin +8,indent -4,group) @u(36):@\"Native" binary files: One 36-bit byte per word. @Begin(Example,leftmargin +1) +-----------------------------------+ | | +-----------------------------------+ 0 35 @End(Example) All bits are used. @End(Description) @caption(DECSYSTEM-20 Word/Byte Organization) @tag<-20bsfig> @bar() @end(figure) @Index[Word Size]@Index[Byte Size] The minimum unit of disk allocation on the DEC-20 is a @i, 512 36-bit words, or 2560 7-bit characters, or 2048 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 bytesize of the file, and the number of bytes of that size which are in the file. This information can be seen by using the DEC-20 VDIRECTORY command, for instance @Begin(Example) @@vdir foo.* PS: Name Protection Pages Bytes(Size) Creation FOO.COM.1;P774242 1 384(8) 27-Dec-83 MAC.1;P774242 1 152(7) 27-Dec-83 .REL.1;P774242 1 39(36) 27-Dec-83 .EXE.1;P774242 2 1024(36) 27-Dec-83 Total of 5 pages in 4 files @End(Example) In this example, @q occupies 1 page, and is composed of 152 7-bit bytes. This file is textual (program source for the MACRO assembler), 152 characters long. Programs which read text files (such as text editors, program compilers, the TYPE command, etc) determine the end of a file from the byte count specified in the directory. Kermit-20 determines the end of file in the same way, so although @q occupies an entire 2560-@|byte page of storage, only the first 152 characters are transmitted. Binary files, such as @q (an executable DEC-20 program), tend to occupy full pages. In this case too, Kermit-20 uses the byte count to determine the end of file. Why do you need to know all this? In most cases, you don't. It depends on whether you are using the DEC-20 as your "home base". @heading Most computers (other than the DEC-10 and DEC-20) store characters in 8-bit bytes. Let's call any such system an 8-bit-@|byte system. Microcomputers that run CP/M or MS-DOS or PC-DOS, and any computers than run Unix, store these 8-bit bytes in a linear sequence. Certain other 8-bit-@|byte systems (PDP-11 or VAX systems with FILES-11, IBM mainframes) have more complex file formats. This discussion applies to all linear 8-bit-@|byte systems, including most popular microcomputers. Kermit can send any "native" DEC-20 sequential file, text or binary, to an 8-bit-@|byte system and bring it back to the DEC-20 restored to its original form. If you are using a microcomputer to archive your DEC-20 files, you need never concern yourself with details of byte size or file format. The same holds true between two DEC-20s, or a DEC-10 and a DEC-20. @index@index There is, however, one special complication of which you should be aware. Certain microcomputer operating systems, notably CP/M, do not have an entirely satisfactory way of indicating the end of file. The file length is recorded in blocks rather than bytes. For text files, the end of file is marked within a block by inserting a Control-Z after the last data character. Binary files, however, might easily contain Control-Z characters as data. Therefore, in order not to lose data, these systems must transmit binary files in complete blocks. If the binary file is of foreign origin (for instance, from a DEC-20), and it did not happen to fill up the last block when it was transferred to the micro, then when that file is sent back to the system of origin in "binary mode," junk will appear at the end (if it is sent back in "text mode," it could be truncated at the first data byte that happened to correspond to Control-Z). For DEC-20 programs in @q<.EXE> format, this generally has no effect on the runnability or behavior of the program. But for other binary files, particularly internal format numerical data or relocatable program object (@q<.REL>) files, the junk could have bad effects. For instance, extraneous data at the end of a @q<.REL> file will generally cause LINK to fail to load the file. Most microcomputer Kermit programs have commands to control end-@|of-@|file detection -- commands like SET FILE TEXT, SET FILE BINARY, SET EOF CTRLZ. @heading You can use Kermit to send textual files from a microcomputer or any 8-bit system to the DEC-20 with no special provisions, since Kermit-20 stores incoming characters in 7-bit bytes as text unless you explicitly instruct it otherwise. But Kermit-20 has no automatic way of distinguishing an incoming binary file from an incoming text file.@foot Binary files from 8-bit-@|byte systems generally contain significant data in the 8th bit, which would be lost if the incoming characters were stored in 7-bit bytes, rendering the file useless when sent back to the original system. Thus if you want to use Kermit to store foreign 8-bit binary data on the DEC-20, you must tell it to store such files with a bytesize of 8 rather than 7. This can be the source of much confusion and inconvenience. In particular, you cannot use a "wildcard send" command to send a mixture of text and binary files from an 8-bit-@|byte system to the DEC-20; rather, you must send all text files with Kermit-20's file bytesize set to 7, and all 8-bit binary files with the bytesize set to 8. Once you get the foreign binary file into the DEC-20, stored with the correct bytesize (as @q is stored in the example above), you need take no special measures to send it back to its system of origin. This is because Kermit-20 honors the bytesize and byte count from the directory. For instance, if you told Kermit-20 to @q, every file in the example above would be transmitted in the correct manner, automatically. The previous discussion assumes you want to store text files in usable form on the DEC-20. However, if you are using the DEC-20 purely as a repository for your microcomputer files, and you have no desire to display or share the contents of those files on the DEC-20, you can SET FILE BYTESIZE 8 for all incoming files, both text and binary. When the files are sent back to a microcomputer, they will be stored correctly. @heading The Kermit protocol can only accommodate transfer of @i files, files which are a linear sequence of bytes (or words). Some files on the DEC-20 are not sequential, and cannot be successfully sent or received by Kermit-20. These include directory files, files with holes (missing pages), ISAM files, and RMS files. These files require external information (kept in the DEC-20's file descriptor block and/or index table) in order to be reconstructed; when sending files, Kermit-20 presently transmits only the file name and the contents of the file. External control information and file attributes are not transmitted. @Section Kermit-20's prompt is "@q(Kermit-20>)". Kermit-20 will accept a single command on the Exec command line, like this: @begin[example] @@ @@@ux[Kermit send foo.bar] @i(the file is sent) @@ @End(Example) or you can run the program interactively to issue several commands, like this: @Begin(Example) @@ @@@ux[Kermit] TOPS-20 Kermit version @value(-20version) Kermit-20>@ux[send foo.*] @i(files are sent) Kermit-20>@ux[statistics] @i(performance statistics are printed) Kermit-20>@ux[receive] @i(files are received) Kermit-20>@ux[exit] @@ @end[example] @index During interactive operation, you may use the TOPS-20 help ("?") and @indexrecognition (ESC) features freely while typing commands. A question mark typed at any point in a command displays the options available at that point; typing an ESC character causes the current keyword or filename to be completed (or default value to be supplied), and a "guide word" in parentheses to be typed, prompting you for the next field. If you have not typed sufficient characters to uniquely specify the keyword or filename (or if there is no default value) then a beep will be sounded and you may continue typing. Command keywords may be abbreviated to their shortest prefix that sets them apart from any other keyword valid in that field. If you have a file called @q in your login directory, Kermit-20 will execute an automatic TAKE command on it upon initial startup. @q may contain any Kermit-20 commands, for instance SET commands, or DEFINEs for SET macros to configure Kermit-20 to various systems or communications media. Kermit-20 provides most of the commands possible for an "ideal" Kermit program, as described in the main part of the @i(Kermit User Guide). The following sections will concentrate on system-@|dependent aspects of Kermit-20. @Section Kermit-20 normally runs in remote mode, with the user sitting at a PC. But Kermit-20 can also run in local mode. Local operation of Kermit-20 is useful if the DEC-20 has an autodialer, or a hardwired connection to another computer. When in local mode, file transfer takes place over an assigned TTY line, and Kermit-20 is free to update your screen with status information, and to listen to your keyboard for interrupt characters. @Begin(Figure) @bar() @blankspace(1) @Begin(Example) @i DECSYSTEM-20 +---------------------------------------+ | | | +--------------------+ | | | Your Job | | | | | | | | +------------+ | <--Commands | Your Job's | | | Kermit-20 +---+--------------+----------------- (-: You | | | | | Display---> | Controlling TTY | | | | | | | | | | | | | | | | | <--Packets | Kermit's | | | +---+--------------+-----------------> Remote | | +------------+ | Packets--> | Assigned TTY System | | | | | +--------------------+ | | | +---------------------------------------+ @End(Example) @caption(DEC-20 Kermit Local Operation) @tag(-20localfig) @bar() @End(Figure) Kermit-20 enters local mode when you issue a SET LINE @i command, where @i is the octal TTY number of any line other than your own controlling terminal. @section @index @index Kermit-20 does as much as it can to condition your line for file transfer. It saves all your terminal and link settings, and restores them after use. However, there are some sources of interference over which Kermit-20 can have no control. In particular, messages issued by superior or parellel forks could become mingled with Kermit packets and slow things down or stop them entirely. For this reason, before using Kermit-20 for any extended period, you should: @begin Type the Exec commands SET NO MAIL-WATCH and SET NO ALERTS Make sure you don't have any print or batch jobs pending that were submitted with the /NOTIFY option. Make sure you don't have any superior or parallel forks that have enabled terminal interrupts on Control-A; these could prevent Kermit packets (which start with Control-A) from getting through. @end After running Kermit, you can restore your mail-watch and alerts by hand. Alternatively, you could have an Exec command file for invoking Kermit like this: @begin set no alerts set no mail-watch kermit set mail-watch set alert 1:00PM Go to lunch set alert 6:00PM Go to dinner set alert 11:30PM Go to sleep @end @Section This section describes the Kermit-20 commands -- in detail where they differ from the "ideal" Kermit, briefly where they coincide. Kermit-20 has the following commands: @Begin(Format,spread 0) @tabclear()@tabset(1.25inches) @>BYE@\ to remote server. @>CLEAR@\ a stuck connection @>CLOSE@\ log file and stop logging remote session. @>CONNECT@\ as terminal to remote system. @>CWD@\ change local working directory. @>DEFINE@\ macros of Kermit-20 commands. @>DELETE@\ local files. @>DIRECTORY@\ listing of local files. @>ECHO@\ a line of text. @>EXIT@\ from Kermit-20. @>FINISH@\ Shut down remote server. @>GET@\ remote files from server. @>HELP@\ about Kermit-20. @>INPUT@\ characters from communication line. @>LOCAL@\ prefix for local file management commands. @>LOG@\ remote terminal session. @>OUTPUT@\ characters to communication line. @>PAUSE@\ between commands. @>PUSH@\ to TOPS-20 command level. @>QUIT@\ from Kermit-20 @>RECEIVE@\ files from remote Kermit. @>REMOTE@\ prefix for remote file management commands. @>RUN@\ a DEC-20 program. @>SEND@\ files to remote Kermit. @>SERVER@\ mode of remote operation. @>SET@\ various parameters. @>SHOW@\ various parameters. @>SPACE@\ inquiry. @>STATISTICS@\ about most recent file transfer. @>TAKE@\ commands from a file. @>TRANSMIT@\ a file "raw". @>TYPE@\ a local file. @End(format) @subsection Kermit-20 provides the standard SEND, RECEIVE, and GET commands for transferring files using the Kermit protocol. @Heading @Index[Initial Filespec]@Index[SEND] Syntax: Sending a single file: @display(@q) Sending multiple files: @display(@q) The SEND command causes a file or file group to be sent from the DEC-20 to the other system. There are two forms of the command, depending on whether @i{filespec1} contains wildcard characters ("@q[*]" or "@q[%]"). Kermit-20 automatically recognizes the two cases and issues the appropriate guide word, (AS) or (INITIAL), depending on the form of @i{filespec1}. @subheading<@ @ Sending a File Group> If @i{filespec1} contains wildcard characters then all matching files will be sent, in alphabetical order (according to the ASCII collating sequence) by name. If a file can't be opened for read access, it will be skipped. @IndexThe initial file in a wildcard group can be specified with the optional @i{filespec2}. This allows a previously interrupted wildcard transfer from where it left off, or it can be used to skip some files that would be transmitted first. @subheading<@ @ Sending a Single File> If @i{filespec1} does not contain any wildcard characters, then the single file specified by @i{filespec1} will be sent. Optionally, @i{filespec2} may be used to specify the name under which the file will arrive at the target system; @i{filespec2} is not parsed or validated in any way by Kermit-20, but lower case letters are raised to upper case, and leading "whitespace" (blanks and tabs) are discarded. If @i{filespec2} is not specified, Kermit-20 will send the file with its own name.@foot[Control-V's, which are used to quote otherwise illegal characters in DEC-20 file specifications, are stripped.] @Subheading<@ @ SEND Command General Operation:> @Index Files will be sent with their DEC-20 filename and filetype (for instance @q, no device or directory field, no generation number or attributes). If you expect to be sending files whose names contain characters that would be illegal in filenames on the target system, and you know that the Kermit on the target system does not have the ability to convert incoming filenames, you can issue the SET FILE NAMING NORMAL-FORM command to have Kermit-20 replace suspect characters by @q's. Each file will be sent according to its bytesize and byte count from the directory unless you specify otherwise using SET FILE BYTESIZE, or unless the file has an "ITS Binary" header. If the bytesize is 8, then four 8-bit bytes will be sent from each DEC-20 36-bit word, and the low order four bits will be skipped. If other than 8, then five 7-bit bytes will be sent from each word, with the 8th bit of the 5th character set to the value of the remaining bit ("bit 35") from the word.@foot @Index@Index@Index @Index If communication line parity is being used (see SET PARITY), Kermit-20 will request that the other Kermit accept a special kind of prefix notation for binary files. This is an advanced feature, and not all Kermits have it; if the other Kermit does not agree to use this feature, binary files cannot be sent correctly. This includes executable programs (like DEC-20 @q<.EXE> files, CP/M @q<.COM> files), relocatable object modules (@q<.REL> files), as well as text files with line sequence numbers. @Index Kermit-20 will also ask the other Kermit whether it can handle a special prefix encoding for repeated characters. If it can, then files with long strings of repeated characters will be transmitted very efficiently. Columnar data, highly indented text, and binary files are the major beneficiaries of this technique. If you're running Kermit-20 locally, for instance dialing out from the DEC-20 to another system using an autodialer, you should have already run Kermit on the remote system and issued either a RECEIVE or a SERVER command. Once you give Kermit-20 the SEND command, the name of each file will be displayed on your screen as the transfer begins; a "@q<.>" will be displayed for every 5 data packets sucessfully sent, and a "@q<%>" for every retransmission or timeout that occurs (you may also elect other typeout options with the SET DEBUG command). If the file is successfully transferred, you will see "@q<[OK]>", otherwise there will be an error message. When the specified operation is complete, the program will sound a beep. If you see many "@q<%>" characters, you are probably suffering from a noisy connection. You may be able to cut down on the retransmissions by using SET SEND PACKET-LENGTH to decrease the packet length; this will reduce the probability that a given packet will be corrupted by noise, and reduce the time required to retransmit a corrupted packet. During local operation, you can type Control-A@Index at any point during the transfer to get a brief status report. @index@index@Index You may also type Control-X or Control-Z to interrupt the current file or file group. @Heading @Index[RECEIVE] Syntax: @q The RECEIVE command tells Kermit-20 to receive a file or file group from the other system. If only one file is being received, you may include the optional @i{filespec} as the name to store the incoming file under; otherwise, the name is taken from the incoming file header. Even if the name in the header is not a legal TOPS-20 file name, Kermit-20 will store it under that name, in which case you can refer to it later only by quoting each illegal character (spaces, control characters, etc) with Control-V@Index. If for some reason an incoming filename simply cannot be converted to legal form, the file will be saved as @q<-UNTRANSLATABLE-FILENAME-.KERMIT> (new generation). You may also use SET FILE NAMING NORMAL-FORM to have Kermit-20 choose more conventional names for incoming files. @index@index@index If an incoming file has the same name as an existing file, Kermit-20 just creates a new generation of the same name and type, for instance @q. The oldest generation will be automatically deleted, but you can still UNDELETE it. Incoming files will all be stored with the prevailing bytesize, 7 by default, which is appropriate for text files. @Index If you are asking Kermit-20 to receive binary files from a microcomputer or other 8-bit system, you must first type SET FILE BYTESIZE 8. Otherwise, the 8th bit of each byte will be lost and the file will be useless when sent back to the system of origin. @Index@Index@Index If you have SET PARITY, then 8th-bit prefixing will be requested. If the other side cannot do this, binary files cannot be transferred correctly. In all cases, Kermit-20 will request the other Kermit to compress repeated characters; if the other side can do this (not all Kermits know how) there may be a significant improvement in transmission speed. If an incoming file does not arrive in its entirety, Kermit-20 will normally discard it; it will not appear in your directory. You may change this behavior @Index by using the command SET INCOMPLETE KEEP, which will cause as much of the file as arrived to be saved in your directory. If you are running Kermit-20 locally, you should already have issued a SEND command @foot(@i SERVER -- use the GET command to receive files from a Kermit server.) to the remote Kermit, and then escaped back to DEC-20 Kermit. As files arrive, their names will be displayed on your screen, along with "@q<.>" and "@q<%>" characters to indicate the packet traffic; you can type Control-A during the transfer for a brief status report. @Index@Index@Index If a file arrives that you don't really want, you can attempt to cancel it by typing Control-X; this sends a cancellation request to the remote Kermit. If the remote Kermit understands this request (not all implementations of Kermit support this feature), it will comply; otherwise it will continue to send. If a file group is being sent, you can request the entire group be cancelled by typing Control-Z. @Heading Syntax: @q The GET command requests a remote Kermit server to send the file or file group specified by @i. This command can be used only when there is a Kermit server on the other end of the line. This means that you must have CONNECTed to the other system, logged in, run Kermit there, issued the SERVER command, and escaped back to the DEC-20, or else you Kermit-20 is in remote mode, TAKEing commands from a file, and interacting with a local Kermit server. The remote filespec is any string that can be a legal file specification for the remote system; it is not parsed or validated locally. You should not put a trailing comment on the GET command, since this will be sent as part of the remote filespec. If you need to include otherwise illegal characters such as "@q" or "@q<;>" (the normal command comment delimeters), "@q" (the command help character), "@q<@@>" (the indirect command file indicator), or certain control characters, then you should precede each such character by a Control-V. Kermit-20 will discard these Control-V quoting prefixes before sending the file specification to the remote host. If you want to store the incoming file name with a different name than the remote host sends it with, just type GET alone on a line; Kermit-20 will prompt you separately for the source (remote) and destination (local) file specification. If more than one file arrives, only the first one will be stored under the name given; the rest will be stored under the names they are sent with. Example: @begin(example) Kermit-20>@ux[get] Remote Source File: @ux[profile exec a1] Local Destination File: @ux[profile.exec] @end(example) As files arrive, their names will be displayed on your screen, along with "@q<.>" and "@q<%>" characters to indicate the packet traffic. As in the RECEIVE command, you may type Control-A to get a brief status report, ^X to request that the current incoming file be cancelled, ^Z to request that the entire incoming batch be cancelled. If the remote Kermit is not capable of server functions, then you will probably get an error message back from it like "Illegal packet type". In this case, you must connect to the other Kermit, give a SEND command, escape back, and give a RECEIVE command. @Heading Give statistics about the most recent file transfer. For instance, here's what Kermit-20 displayed after transmitting a short binary file, using repeated-@|character compression: @Begin(Example) Maximum number of characters in packet: 80 received; 80 sent Number of characters transmitted in 2 seconds Sent: 34 Overhead: 34 Received: 107 Overhead: -408 Total received: 141 Overhead: -374 Total characters transmitted per second: 70 Effective data rate: 2570 baud Efficiency: 214.1667 per cent Interpacket pause in effect: 0 sec Timeouts: 0 NAKs: 0 @End(Example) Note that the data compression allowed the effective baud rate to exceed the actual speed of the communication line, which in this case happened to be 1200 baud. The efficiency is displayed only if the actual baud rate is known. @subsection @Heading @Index The SERVER command puts a remote Kermit-20 in "server mode", so that it receives all further commands in packets from the local Kermit. The Kermit-20 server is capable (as of this writing) of executing the following remote server commands: SEND, GET, FINISH, BYE, REMOTE DIRECTORY, REMOTE CWD, REMOTE SPACE, REMOTE DELETE, REMOTE TYPE, REMOTE HELP. @Index Any nonstandard parameters should be selected with SET commands before putting Kermit-20 into server mode, in particular the file bytesize. The DEC-20 Kermit server can send most files in the correct manner automatically, by recognizing the DEC-20 file bytesize. However, if you need to ask the DEC-20 Kermit server to receive binary files from an 8-bit-@|byte system (that is, from almost any system that's not a DEC-10 or DEC-20) you must issue the SET FILE BYTESIZE 8 command before putting it into server mode, and then you must only send 8-bit binary files. You cannot send a mixture of text files and 8-bit binary files to a Kermit-20 server. @Heading When running in local mode, Kermit-20 allows you to give a wide range of commands to a remote Kermit server, with no guarantee the that the remote server can process them, since they are all optional features of the protocol. Commands for servers include the standard @q, @q, @q, and @q commands, as well as the @q command. These commands are generally issued when Kermit-20 is in local mode, i.e. you have already connected to another system, run Kermit there and put it into server mode, and escaped back to Kermit-20. However, Kermit-20 also allows you to operate in the opposite direction, i.e. Kermit-20 is the remote Kermit, and the local Kermit is in server mode. This is handy when, for instance, you want to transfer a disparate collection of files that can't be readily specified by a wildcard group, all in a single, unattended operation. In this case, you can create a TAKE command file for Kermit-20 that SENDs and/or GETs the desired files, and then shuts down local server when done, e.g.: @begin set delay 0 ; No need to pause before sending ; Connect to own directory, leave a blank line for password. cwd me: log transactions ; Keep a log ; Change directories on the PC. remote cwd \kermit send ker:mskerm.doc ; Send the MS-DOS Kermit manual send ker:mskerm.bwr ; Send the MS-DOS Kermit "beware file" ; Now change to the MS-DOS binaries area remote cwd \bin send kb:msvibm.exe ; Send the executable DOS Kermit program ; Put DOS back in default directory remote cwd \chris ; Connect back to default directory on the DEC-20 cwd me: close transactions ; Close transaction log send transaction.log ; Send it finish ; Shut down DOS Kermit server @end Commands to servers (GET, BYE, FINISH, REMOTE) can be issued from a remote Kermit-20 only by means of a TAKE file. When Kermit-20 is local (i.e. after SET LINE), you can issue these commands interactively as well. @subheading Send the specified command to the remote server. If the server does not understand the command (all of these commands are optional features of the Kermit protocol), it will reply with a message like "Unknown Kermit server command". If does understand, it will send the results back, and they will be displayed on the screen. The REMOTE commands are: @begin CWD [@i]@\Change Working Directory. If no directory name is provided, the server will change to the default or home directory. Otherwise, you will be prompted for a password, and the server will attempt to change to the specified directory. The password is entered on a separate line, and does not echo as you type it. If access is not granted, the server will provide a message to that effect. Do not put trailing comments after a REMOTE CWD command, or after the password. DELETE @i@\Delete the specified file or files. The names of the files that are deleted will appear on your screen. DIRECTORY [@i]@\The names of the files that match the given file specification will be displayed on your screen, perhaps along with size and date information for each file. If no file specification is given, all files from the current directory will be listed. HELP@\Provide a list of the functions that are available from the server. HOST [@i]@\Pass the given command to the server's host command processor, and display the resulting output on your screen. SPACE@\Provide information about disk usage in the current directory, such as the quota, the current storage, the amount of remaining free space. TYPE @i@\Display the contents of the specified file on your screen. @end @Subsection Syntax: @q Execute the specified command on the local system -- on the DEC-20 where Kermit-20 is running. These commands provide some local file management capability without having to leave the Kermit-20 program. @begin CWD [@i]@\Change working directory, or, in DEC-20 terminology, CONNECT to the specified directory. If a password is required, you will be prompted for one. Do not include a trailing comment after the password. DELETE @i@\Delete the specified file or files, but do not expunge them (unless you have SET EXPUNGE ON). DIRECTORY [@i]@\Provide a directory listing of the specified files. RUN [@i]@\Attempts to run the specified file, which must be in "@q<.EXE>" format (@q<.EXE> is the default filetype), in an inferior fork. Control returns to Kermit-20 when the program terminates. Once you have used this command, you can restart the same program by issuing a RUN command with no arguments. If you RUN @q, then you will be able to issue TOPS-20 commands without leaving Kermit; you can get back to Kermit from the EXEC by typing the EXEC POP command. SPACE@\Show how much space is used and remaining in the current directory. TYPE@\Display the contents of the specified file or files at your terminal. This works like the DEC-20 TYPE command, except that if a file has a bytesize of 8, Kermit-20 will do 8-bit input from it rather than 7-bit. Also, the DEC-20 Control-O command discards output only from the file currently being displayed; if multiple files are being typed, then output will resume with the next file. @end The LOCAL commands may also be used without the "LOCAL" prefix. @Subsection Syntax: @q Establish a terminal connection to the system connected to the octal TTY number specified here or in the most recent SET LINE command, using full duplex echoing and no parity unless otherwise specified in previous SET commands. Get back to Kermit-20 by typing the escape character followed by the letter C. The escape character is Control-Backslash (@q<^\>) by default. When you type the escape character, several single-@|character commands are possible: @Begin(Description,leftmargin +6,indent -4, spread 0) @q@\Close the connection and return to Kermit-20. @q@\Show status of the connection; equivalent to SHOW LINE. @q

@\Push to a new Exec. POP from the Exec to get back to the connection. @q@\If a session log is active, temporarily Quit logging. @q@\Resume logging to the session log. @q@\Send a simulated BREAK signal. @q@\List all the possible single-character arguments. @q<^\> (or whatever you have set the escape character to be):@\Typing the escape character twice sends one copy of it to the connected host. @End(Description) You can use the SET ESCAPE command to define a different escape character, and SET PARITY, SET DUPLEX, SET HANDSHAKE, SET FLOW, and SET SPEED to change those communication-@|line-@|oriented parameters. In order for the simulated BREAK signal to work, TOPS-20 must know the speed of the terminal. If it does not, you may use the SET SPEED command. Type the SHOW LINE command for information about your current communication settings. Kermit-20 does not have any special autodialer interface. It assumes that the connection has already been made and the line assigned. @Subsection SET is used for establishing or changing parameters, DEFINE lets you group several SET commands together into a single "macro" command, and SHOW lets you examine current settings or macro definitions. @Heading Syntax: @q Establish or modify various parameters for file transfer or terminal connection. You can examine their values with the SHOW command. The following parameters may be SET: @Begin(Format,spread 0) @tabclear()@tabset(2.0inches) @>BREAK@\ Adjust the BREAK simulation parameter @>BLOCK-CHECK@\ Packet transmission error detection method @>DEBUGGING@\ Record or display state transitions or packets @>DELAY@\ How long to wait before starting to send @>DUPLEX@\ For terminal connection, FULL or HALF @>ESCAPE@\ Character for terminal connection @>FILE@\ For setting file parameters like byte size @>FLOW-CONTROL@\ For enabling or disabling XON/XOFF flow control @>HANDSHAKE@\ For turning around half duplex communication line @>IBM@\ For communicating with an IBM mainframe @>INCOMPLETE@\ What to do with an incomplete file @>INPUT@\ For specifying behavior of the INPUT command @>ITS-BINARY@\ For recognizing a special 8-bit binary file format @>LINE@\ TTY line to use for file transfer or CONNECT @>PARITY@\ Character parity to use @>PROMPT@\ Change the program's command prompt @>RECEIVE@\ Various parameters for receiving files @>RETRY@\ How many times to retry a packet before giving up @>SEND@\ Various parameters for sending files @>SPEED@\ Baud rate of communication line @>TVT-BINARY@\ For negotiating binary mode on ARPANET @end(Format) The DEFINE command may be used to compose "macros" by combining SET commands. Those SET commands which differ from the "ideal" Kermit are now described in detail. @Subheading @Index Syntax: @q Specify the number of nulls to be sent at 50 baud to simulate a BREAK signal when connected to a remote host via SET LINE and CONNECT. @Subheading @Index Syntax: @q Record the packet traffic, either on your terminal or in a file. Some reasons for doing this would be to debug a version of Kermit that you are working on, to record a transaction in which an error occurred for evidence when reporting bugs, or simply to vary the display you get when running Kermit-20 in local mode. Options are: @Begin(Description) STATES@\Show Kermit state transitions and packet numbers (brief). PACKETS@\Display each incoming and outgoing packet (lengthy). OFF@\Don't display or record debugging information (this is the normal mode). If debugging was in effect, turn it off and close any log file. @End(Description) The debugging information is recorded in the file specified by the most recent LOG DEBUGGING command, @q by default. @Subheading @Index @q Specify the control character you want to use to "escape" from remote connections back to Kermit-20. The default is 34 (Control-\). The number is the octal value of the ASCII control character, 1 to 37 (or 177), for instance 2 is Control-B. After you type the escape character, you must follow it by a one of the single-@|character "arguments" described under the CONNECT command, above. @Subheading @Index @q Tell whether you want a DELETE command (either the LOCAL DELETE command or a REMOTE DELETE command sent to a Kermit-20 server) to expunge files as it deletes them. On the DEC-20, a deleted file continues to take up space, and may be "undeleted" at a later time in the same session. To expunge a deleted file means to remove it completely and irrevocably, freeing its space for further use. EXPUNGE is OFF by default; deleted files are not automatically expunged. SET EXPUNGE applies only to files that are deleted explicitly by Kermit-20, and not to files that are implicitly deleted when new generations of existing files are created. @Subheading Syntax: @q Establish file-related parameters: @Begin(Description,leftmargin +8,indent -8) BYTESIZE @i{keyword or number}@\@IndexByte size for DEC-20 file input/output. The choices are SEVEN (7), EIGHT (8), and AUTO. @Begin(Description,leftmargin +8,indent -8) SEVEN@\(or 7) Always store or retrieve five 7-bit bytes per word. When sending a file, ignore the file bytesize and do 7-bit input from the file. There would be no reason to use this option except to explicitly force an 8-bit file to be treated as a 7-bit file. EIGHT@\(or 8) Always store or retrieve four 8-bit bytes per word. When sending a file, ignore the file bytesize and do 8-bit input from the file. This command is necessary when receiving binary files from 8-bit-@|byte systems, such as most microcomputers. AUTO@\Equivalent to SEVEN for incoming files, and for outgoing files means to use EIGHT if the DEC-20 file bytesize (as shown by the Exec VDIR command) is 8, otherwise use SEVEN. The default is AUTO. @End(Description) The DEC-20 can send any mixture of file types in the correct way automatically, but you @i set the file bytesize to 8 for any incoming 8-bit binary files, and to AUTO (i.e. 7) for any incoming text files or DEC-20 binary files. @Index NAMING UNTRANSLATED @i NORMAL-FORM@\If NORMAL-FORM the names of incoming or outgoing files will be converted to contain only uppercase letters, digits, and at most one period; any other characters will be translated to "@q". If UNTRANSLATED, filenames will be sent and used literally. UNTRANSLATED is the default. @End(Description) @subheading @index Syntax: @q SET IBM is really a predefined SET macro rather than a "hardwired" SET command; it can be redefined or undefined (see DEFINE); as distributed from Columbia, Kermit-20 defines IBM to be "parity mark, handshake XON, duplex half". SET IBM should be used when running Kermit-20 in local mode, connected to an IBM or similar mainframe. If you have redefined the SET IBM macro, then your parameters will be used instead. @Subheading @Index Syntax: @q OFF> Specify whether ITS-Binary file headers are to be recognized or ignored. By default, they are recognized. ITS binary format is a way (devised at MIT) of storing foreign 8-bit binary data on a 36-bit machine to allow automatic recognition of these files when sending them out again, so that you don't have to depend on the file byte size, or to issue explicit SET FILE BYTESIZE commands to Kermit. An ITS format binary file contains the sixbit characters "DSK8" left-adjusted in the first 36-bit word. If ITS-BINARY is ON, then Kermit-20 will send any file starting with this "header word" using 8-bit input from the file even if the file bytesize is not 8, and will not send the header word itself. Kermit-20 will also store any incoming file that begins with that header word using 8-bit bytesize, again discarding the header word itself. If ITS-BINARY is OFF, then the header word, if any, will be sent or kept, and i/o will be according to the setting of FILE BYTESIZE. This facility is provided for compatibility with the file formats used on certain public-@|access CP/M libraries. @Subheading @index@index Syntax: @q The INPUT command is used in TAKE command files or DEC-20 Batch control files as part of the login script facility, which is explained in greater detail later. SET INPUT controls the behavior of the INPUT command. The parameters are as follows: @begin SET INPUT DEFAULT-TIMEOUT @i@\@i is the number of seconds for an INPUT command to time out after not receiving the requested input, when no interval is explicitly given in the INPUT command. For instance, if the default timeout interval is 10 seconds, then the command @example will look for the "@q" prompt for 10 seconds. The default may be overriden by including an explicit interval in the INPUT command: @example The default timeout interval is 5 seconds. @index@index SET INPUT TIMEOUT-ACTION PROCEED @i QUIT@\If the INPUT command comes from a Kermit-20 command file (see TAKE command) or a TOPS-20 Batch control file, then use this command to specify whether processing of the command file should proceed or quit after a timeout occurs. For TAKE files, the current command file is terminated and control returns to the invoking level (Kermit-20 prompt level, or a superior TAKE file). The default action is PROCEED. SET INPUT CASE IGNORE @i OBSERVE@\Specify whether alphabetic case should be ignored ("a" matches "A") or observed ("a" does not match "A") when scanning the input for the specified search string. By default, aphabetic case is ignored. @end SET INPUT commands are "global"; the settings are not "pushed" and "popped" when entering or leaving TAKE command files. @Subheading Syntax: @q Specify the octal TTY number to use for file transfer or CONNECT. If you issue this command, you will be running Kermit-20 @i, and you must log in to the remote system and run Kermit on that side in order to transfer a file. If you don't issue this command, Kermit-20 assumes it is running @i, and does file transfer over its job's controlling terminal line. You can also select the line directly in the CONNECT command; the command @example(CONNECT 12) is equivalent to @begin SET LINE 12 CONNECT @end If you type SET LINE with no number argument, you will deassign any previous assigned line and revert to remote mode. The SHOW LINE command will display the currently selected communication line and its charactistics, including parity, duplex, handshake, flow control, the speed if known, whether carrier is present (if it is a modem-@|controlled line), and whether Kermit-20 is in local or remote mode. @subheading In addition to the full complement of SET RECEIVE commands described in the main part of the Kermit User Guide, you may also SET RECEIVE SERVER-TIMEOUT to a value between 0 and 94. This specifies the number of seconds between timeouts during server command wait, 0 specifies that no timeouts should occur during server command wait. When a Kermit server times out, it sends a NAK packet. Some systems cannot clear piled-@|up NAKs from their input buffers; if you're using such a system to communicate with a Kermit-20 server, and you expect to be leaving the server idle for long periods of time, you should use this command to turn off server command-@|wait timeouts. @subheading Syntax: @q @index@index Set the baud rate of the currently selected communication to @i(n), the decimal baud rate, for instance 300, 1200, 4800. When operating in local mode, it may be necessary to issue this command in order to enable BREAK simulation. @subheading Syntax: @q @i @q @index@index@index Only for users running Kermit-20 on an ARPANET DEC-20, signed on to an ARPANET virtual terminal (TVT) from another host or through an ARPANET TAC. SET TVT ON causes Kermit-20 to negotiate binary mode (8-bit) communication with the ARPANET during file transfer. Without this command, file transfer through a TVT would not work in most cases. TVT-BINARY is OFF by default. If you normally use Kermit-20 through the ARPAnet, you can put the command SET TVT-BINARY ON into your @q file. @i: This facility requires certain features in the Release 5 TOPS-20 ARPANET monitor, which may not be present in releases distributed by DEC. See the Kermit-20 source code for details. @heading Syntax: @q [@i [, @i [...]]]> @Index The DEFINE command is available in Kermit-20 for building "macros" of SET commands. The macro name can be any keyword-@|style character string, and the set options are anything you would type after SET in a SET command; several set options may be strung together, separated by commas. Example: @example Macro definitions may not include macro names. You can list all your macros and their definitions with the SHOW MACROS command. You can list a particular macro definition with HELP SET @i. @Heading @Index Syntax: @q [@i