1. CYBER 170 KERMIT Authors: Jim Knutson, University of Texas Version: 2.2 Date: September 1984 Cyber Kermit was written for a Cyber 170/750 in FTN5, CDC's FORTRAN 77 com- piler. It should run on any NOS or NOS/BE system with only minor changes to the I/O routines. This is a necessary evil since every Cyber site seems to run a different front end. 1.1. Cyber File Systems The features of a Cyber file system of greatest interest to KERMIT users are storage class, file structure, file specifications and character sets. Cyber Storage Classes The NOS and NOS/BE operating systems use the concept of local and permanent file storage. This means that files that are to be kept around after a job is finished must be moved to permanent storage first. Jobs that wish to use a file from permanent storage must copy to local storage first before using it (actually, direct access permanent files help alleviate this problem). Most Kermit users will only want to use local files. Cyber File Structure Many Cyber files use internal structure information much like VMS files. These internal structures are mainly used in executable binary files or certain CRM record types. The internal structure of files is not currently supported by Cyber Kermit. Cyber executable binaries, and multi-record files are not trans- ferable using Kermit. Cyber File Specification A Cyber file name consists of from 1 to seven alphanumeric characters. NOS systems allow the first character to be numeric but most Cyber processors do not support this. Cyber Kermit allows the first character to be a digit on NOS systems. Special characters are not allowed in the file name. File names beginning with ZZ or SCR should be avoided, since these are commonly used scratch file names. The Cyber Kermit command processor does not support wild cards at this time. Cyber Character Sets Until the recent Cyber 800 Series mainframes, the character set used by most Cyber systems was a six bit Display Code character set. The six bit character sets supported by Cyber Kermit are the 63 character, 64 character and UT 64 character sets. These character sets not only differ in their ordering but also in the characters they use. Some use the underscore and percent sign, others do not. ASCII characters received by Cyber Kermit are translated to the appropriate display code when possible. A character that can not be translated will be set to a blank. Users of the 64 character set may have problems with colons at the end of a line being truncated or lines with sequential colons being split into two or more lines since the character value of a colon is 00B (half of an End-Of-Line). There are also several ASCII character sets in use on the various Cyber sys- tems. One set, called 6/12, uses 6 bit display code characters with certain characters set aside as flags to indicate case (upper/lower) or control charac- ters. Cyber Kermit does not support the 6/12 character set. Another ASCII character set is the 8/12 character set. This stores ASCII characters as 8 bits in a 12 bit byte. The exception to this is that an EOL (End-Of-Line) is indicated by the usual CDC convention of at least twelve bits of 0 (0000B) in the low order bits of the word. NUL characters are represented as 4000B to prevent interpretation as an EOL sequence. Cyber Kermit also support UT 8/12 ASCII. The difference between this and NOS 8/12 ASCII is UT 8/12 ASCII uses the NEL character (205B) from the 256 character ASCII set to represent an End-Of-Line. 1.2. Program Operation Cyber Kermit's prompt is "Kermit-170>". It must be run interactively and with- out any parameters. Commands can then be typed in like this: .kermit Kermit-170>send foobar [file foobar sent] Kermit-170>status [performance statistics are printed] Kermit-170>receive [files are received] Kermit-170>exit . Cyber Kermit mimics the DEC-20 style command parser in that a question mark followed by a carriage return may be placed anywhere on the command line. This will display the options available at that point. Unfortunately, the entire command will have to be retyped afterwards. Command keywords may be abbreviated to their shortest unique combination. This comes in very handy since Cyber Kermit does not support command completion. Cyber Kermit may only be run as a remote Kermit. It must be watched during transfer if the local Kermit has no timeout since it has no timeout capabilities. A Cyber filename is restricted to 7 alphanumeric characters with the first character being an alpha. Kermit will use the first 7 valid characters of any file being sent to the Cyber. If a file under that name already exists, an Er- ror packet stating so will be sent back and Cyber Kermit will abort the trans- fer. If you are having trouble transferring files with Kermit, it may be due to the parity. Cyber Kermit has no way of determining the parity of the connection so it just guesses that it will be NONE. If you are having problems getting the first packet to transfer, then this is probably the problem. If you are run- ning with a parity other than NONE, then you must use the SET PARITY command every time you enter Cyber Kermit. 1.3. Cyber Kermit Commands The following is a list of Cyber Kermit commands and their description. ! command Execute a Cyber control command and then return to Kermit. EXIT, QUIT Exit from Kermit-170. You may also stop Kermit-170 in the midst of a transfer or during server operations by aborting the program (CTRL-C or CTRL-G ABORT); the program traps them and puts your terminal back to normal before halting. HELP [topic] Give Help. There's a general help text, plus separate help texts for each Kermit-170 command. PUSH Exit to control command level saving the current Kermit en- vironment. The environment will be restored when Kermit is reentered. RECEIVE Receive a file or group of files from the other host. If the name in the header packet is not a legal Cyber file name, the first 7 legal characters will be used. If the file already exits as a local file, Kermit will abort the transfer. If an error occurs during transfer, the file being received will be removed from the local file list to al- low the transfer to be retried. You should escape back to your local Kermit after entering RECEIVE mode and give the SEND com- mand. SEND filename Send a file to the other host. The name of the file is passed to the other host in a file header packet, so that the file can be stored there with the same name. You should escape back to your local Kermit and give the RECEIVE command. If you don't do this fast enough the "send-init" packet may arrive prema- turely. To prevent this, use SET DELAY or hit the RETURN key on your microcomputer if it does not timeout. SERVER Act as a server for another Kermit. Whatever options were previously SET will be used. The server may be shut down from the local Kermit by using the BYE or FINISH commands, or by connecting back to the Cyber, and typing Control-C or Control-G ABORT. SET keyword value Establish system-dependent parameters. You can examine their values with the SHOW command. Numeric values may be decimal, octal (postfixed with a B), or hexadecimal (postfixed by an H). The following may be SET: DATA-MODE ctype Set the character code to use for files received by Kermit-170. Allowable values for ctype are: ASCII, DISPLAY-CODE, IMAGE-ASCII, NOS-ASCII. The interpreta- tion of these is dependent on the system. DISPLAY-CODE will be the six bit character set in use at the site (63 or 64). ASCII will be NOS 8/12 ASCII for all sites except the University of Texas. NOS-ASCII is used to describe NOS 8/12 ASCII at UT while ASCII describes UT 8/12 ASCII. The default character set in use when Ker- mit starts up is DISPLAY-CODE. Automatic character set recognition is used for sending files unless IMAGE-ASCII is set. DEBUG option Show packet traffic explicitly. Options are: ALL Set all debug options. LOG-FILE filename Log states and packets to the specified file. The default log-file is file KERMLOG. OFF Don't display debugging information (this is the default). If debugging was in effect, turn it off and close any log file. PACKETS Display each incoming and outgoing packet (lengthy). STATES Show kermit state transitions and packet num- bers (brief). DELAY decimal-number How many seconds to wait before sending the first packet. This gives you time to "escape" back and issue a RECEIVE command. DUPLEX keyword Changes the method of echoing characters when being prompted for commands. The choices are FULL and HALF. Full means the Cyber will echo the characters you type. Half means the local systems echoes them. Full is the default, and is used by most hosts. INIT-RETRY decimal-number Set the maximum number of retries allowed for the in- itial connection before giving up. PARITY keyword Allows you to adjust the parity on characters sent or received by Kermit-170 to another system's require- ments. The possibilities are NONE, EVEN, ODD, SPACE, or MARK. If NONE, then the 8th bit can be used for data when sending and receiving binary files. If other than NONE, the 8th bit on outgoing characters will be set to achieve the desired parity, and the 8th bit on incoming characters will be discarded. The default is NONE. RECEIVE parameter value These commands allow you to specify to the other Kermit what the packets it sends should look like, or to in- form this Kermit what to expect. Value may be specified as a decimal number, an octal number (B suffix), or a hexadecimal number (H suffix). Charac- ters values are specified as the numeric equivalent of the ASCII character. END-OF-LINE value The octal value of the ASCII character to be used as a line terminator or packets, if one is required by the other system. Carriage return (15B) is the default. PACKET-LENGTH value Maximum packet length to send, decimal number, between 20 and 94, 94 by default. PAD-CHARACTER value Character to use for padding. Default is NUL. PAD-LENGTH value How much padding to send before a packet. Default is no padding. QUOTE-CHARACTER value What printable character to use for quoting of control characters. SYNC-CHARACTER value The control character that marks the beginning of the packet. Normally SOH (Control-A, ASCII 1). There should be no reason to change this. TIME-OUT value How many seconds the other Kermit should wait for a packet before asking for retransmission. RDELAY millisec Set up a delay of millisec seconds before each TTY read. This can be used for performance tuning by caus- ing enough delay that data will be ready when the read is issued. If data is not ready when the read is issued, the job will be swapped out. The delay should be specified as a multiple of 100. The default delay is 100 milliseconds. RETRY value Set the maximum number of retries for a given packet before giving up. SEND parameter value These commands allow you to specify how outgoing pack- ets should look, in case the other Kermit has nonstan- dard requirements. END-OF-LINE value The octal value of the ASCII character to be used as a line terminator for packets, if one is required by the other system. Carriage return (15B) by default. PACKET-LENGTH value Maximum packet length to send, decimal number, between 20 and 94, 94 by default. PAD-CHARACTER value Character to use for padding. Default is NUL. PAD-LENGTH value How much padding to send before a packet. Default is no padding. QUOTE-CHARACTER value What printable character to use for quoting of control characters. The default is "#" (43B). there should be no reason to change this. SYNC-CHARACTER value The control character that marks the beginning of the packet. Normally SOH (Control-A, ASCII 1). There should be no reason to change this. TIME-OUT value How many seconds the other Kermit should wants before being asked for retransmission. Unfor- tunately, the Cyber has no way of timing out so this parameter is ignored. SHOW Display current SET parameters, version of Kermit-170, and other information. STATUS Give statistics about the most recent file transfer. 1.4. Installation Cyber Kermit is distributed in two forms. If you received it from Columbia University, the sources are in UPDATE source format. If you received it from the University of Texas, it will be in UPDATE program library format. Other formats may be written by the University of Texas upon request. The Cyber Kermit source comes in two files. One file (KERMUPL) will contain the FTN5 source code for Kermit itself. The other file (AZLBUPL) contains the COMPASS I/O and low level support routines supplied by the University of Arizona. Many of these routines are FORTRAN interface routines to the COMPASS system macros. These should run as is on NOS/BE systems and most should run as is on NOS systems. The routines that are needed from AZLIB (the library produced from AZLBUPL) are: CPU.BTZ, CPU.MFS, CPU.VFN, CLOSE, CPU.MVC, CPU.SCS, CPU.SXT, CPU.TXS, OPEN, READ, WRITER, READC, READW, WRITEW, ENDRUN, RECALL, RTIME, MOVECH, XSCS, XSXT, XTXS, XVFN, RETFILE, XCON, EXCST, and MACREL. These routines should be assembled and placed in the file AZLIB and tested to make sure they work on your system. The normal command sequence for this would be: .UPDATE,P=AZLBUPL,F. .COMPASS,I. .LIBGEN,P=AZLIB. The next thing to do is start building Kermit. There are several things to do first, though. Cyber Kermit uses conditional compilation for the different operating systems and site dependent routines. Modify the parameter defini- tions in common deck COMCKER to reflect your operating system and site. Note that the site definition is only usefull if you need to have site specific routines or code. Currently, the only site specific routines are used to change the duplex from FULL to HALF and back again (ECHOPLX used at UA, BELLC used at UT). Site specific code is used at UT due to our strange character sets, and for setting ASCII mode for I/O in subroutine FOPEN. The display code character set parameter must also be modified in common deck COMCKER to reflect the appropriate character set (63, 64) in use at your site. NOS sites will probably have to modify subroutine RDELAY to accomodate the dif- ferent format returned by the RTIME macro. If a NOS site would send it's mods back to the University of Texas, then this could be conditionally compiled and other NOS sites would no longer have to worry about this. Once the duplex changing (not neccessary at half duplex sites, but be sure to change the default duplex in subroutine BLOCK DATA to HALFDUP) and the code for setting ASCII I/O has been set up debugging can take place. Decide on which version of Cyber Kermit you wish to run (OVCAP or SEGLOAD). Most sites are running the OVCAP version and installing it in the system nucleus. To build the OVCAP version place the following lines in file UPDMODS: *IDENT,moddeck *DEFINE,OVCAP and run the commands: .UPDATE,P=KERMUPL,F,I=UPDMODS. .FTN5,I,OPT=2. COMPILE KERMIT SOURCE .FTN5,I,OPT=2,B=LIBREL. COMPILE LIBRARY SOURCE .LIBGEN,P=KERMLIB. BUILD KERMIT LIBRARY .LDSET,MAP=SBEX. .LOAD,LGO. LOAD KERMIT, KERMLIB AND AZLIB .NOGO,KERMIT. To build the segload version, place the following segload directives into file KERMSEG: TREE KERMIT-(SET,HLPCMD,EXECMD,SERVER-(RECEIVE,SEND)) SET INCLUDE SHOW,STATUS,MATCH,SETVAL RECEIVE INCLUDE RINIT,RFIEL,RDATA SEND INCLUDE SINIT,SFILE,SDATA,SEOF,SBREAK KERMIT GLOBAL PROTO,PACKET,DEBUG,MESSAGE,FILEIO,FILEIOC END KERMIT and run the commands: .UPDATE,P=KERMUPL,F. .FTN5,I,OPT=2. COMPILE KERMIT SOURCE .LDSET,LIB=AZLIB .LDSET,MAP=SBEX. .SEGLOAD,I=KERMSEG,B=KERMIT. LOAD KERMIT, AZLIB .LOAD,LGO. .NOGO. To aid in debugging of the OVCAP version, remove the line: LDSET OMIT=SYSERR. from the COMPASS main program. This was put there to remove uneeded (hopefully) code and reduce field length. Be sure to read the implementation notes in the program source. These notes are likely to be the more upto date. Planned further enhancements to Kermit-170 being done at the University of Texas include: - Addition of new server functions: directory, type, delete, etc. - Two and Three character checksums. - 8th-bit quoting, to allow transfer of binary files with systems that can't use the parity bit for data. - Repeat processing for data compression. - Badly needed performance tuning. Currently we have been experiencing 700-900 baud effective data throughput on a 2400 baud line. Index ! 2 CDC 0 Character Set 3 Control-C 2 CYBER 0 Debugging 3 Duplex 3 EXIT 2 Help 1, 2 NOS 0 NOS/BE 0 Parity 2, 3 Performance Tuning 4 PUSH 2 QUIT 2 RECEIVE 2 SEND 2 SERVER 2 SET 2 SHOW 5 STATUS 5 Table of Contents 1. CYBER 170 KERMIT 0 1.1. Cyber File Systems 0 1.2. Program Operation 1 1.3. Cyber Kermit Commands 2 1.4. Installation 5 Index 8