Columbia Kermit

home *** CD-ROM | disk | FTP | other *** search

/ Columbia Kermit / kermit.zip / d / modcmp.doc < prev next >

Wrap

Text File | 2020-01-01 | 24KB | 881 lines

MODCOMP MAXIV KERMIT USER'S MANUAL by Richard D. Burke Robert A. Borgeson of SETPOINT Inc. 10245 Brecksville Rd. Brecksville, Ohio 44141 KERMIT is a copyrighted protocol of Columbia Univ. The authors of this version hereby grant permission to copy this document provided that it is not used for any explicitly commercial purpose and that proper credit be given. SETPOINT Inc. makes no warranty whatsoever regarding the accuracy of this document or the software described within and will assume no liability resulting from its use. TABLE OF CONTENTS ________ Page No. Introduction .......................... I.1 Overview .......................... II.1 KERMIT commands .......................... III.1 HELP .......................... III.1 STATUS .......................... III.1 SET .......................... III.1 DELAY .......................... III.2 EOL .......................... III.2 ESCAPE .......................... III.2 MYQUOTE .......................... III.2 PACKET .......................... III.2 SOH .......................... III.2 USL .......................... III.3 QUIT / EXIT .......................... III.3 SEND .......................... III.3 RECEIVE .......................... III.3 Technical Appendix .......................... A.1 I.1 A. INTRODUCTION KERMIT provides an easy, reliable way to transfer text files between a MODCOMP Classic running under MAXIV and other machines which have a KERMIT implementation on them. KERMIT is a packet-oriented telecommunications protocol copyright by Columbia University. Documentation available from them thoroughly covers the formal details of the protocol.(1) The purpose of this manual is to detail the specific features of this implementation and to provide instruction on how to use KERMIT on a MODCOMP. This manual assumes that the reader has a general knowledge of a MODCOMP running under MAXIV. A Technical Appendix follows which details how to allocate resources and install KERMIT on your machine. MAXIV KERMIT is adapted from a version written by John Lee of RCA Labs for an HP-1000. It is implemented in Fortran IV except for one subroutine in assembler. (1) KERMIT Distribution Columbia University Center for Computing Activities Seventh Floor, Watson Laboratory 612 West 115th Street New York, N.Y. 10025 II.1 II. OVERVIEW MAXIV KERMIT is run by activating a job control procedure which makes the necessary logical assignments and then, executes the program. Each site will probably wish to create their own job control for this, taking into account the requirements addressed in the Technical Appendix. The original MAXIV KERMIT distribution contains a simple command file which may be used as a guide. The file's name is KERMIV. The syntax for activating this procedure is: $KERMIV co,oc where co - logical assignment for file transfer output (Default = CO) oc - logical assignment for file transfer input (Default = OC ) Operator input is always from OC and informational output is to CO. Therefore, if no parameters are specified, KERMIT will expect operator input and file transfer to occur at the same ports. MAXIV KERMIT may be run in either remote or local mode. In remote mode, the data transfer occurs at the same terminal port which is controlling the program. Presumably, the user is accessing the MODCOMP from some computer which has the ability to emulate a terminal as part of a communications package. Local mode implies that KERMIT is controlled by a terminal which is on an I/O port different from the port assigned to the data transfer. This is most likely to be used when neither machine has a communications software package. When MAXIV KERMIT is initially run, it senses the current logical assignments and chooses the appropriate mode automatically. In the initial release ( Version 1.0 ), it is not possible to alter the file transfer port or the local/remote mode once KERMIT is invoked. MAXIV KERMIT is designed with a command structure that reflects MAXIV's division of files into libraries. KERMIT is always logically assigned to a directorized source library. (by default, USL) If the user does not intervene, all files to be sent must be cataloged in USL. All received files will by default be cataloged to USL. The methods to modify these defaults are discussed later. KERMIT's choice of <CTL-A> (ASCII 01) as the start-of-packet character presents special problems under MAXIV since this is the standard break character for getting the TMP prompt. Short of requiring that the break character be redefined in the SYSGEN, there is no bulletproof way to always pass the <CTL-A> through to KERMIT without waking up TMP. II.2 The user must be aware that all input including the <CTL-A>s will be passed through into a 132 byte buffer. This is sufficient for at least one packet. However, if the other KERMIT sends a number of unexpected packets it could fill up the buffer. One possible scenario that could cause this is when the other KERMIT begins to send initialization packets before MAXIV KERMIT is told to receive. If this buffer is ever filled up an outstanding read request is terminated and the next <CTL-A> received will be interpreted as the break character. In this case, the user has no choice other than to exit KERMIT and start over. In local mode, the buffer is activated immediately upon execution but, no check for incoming packet data is made until MAXIV KERMIT is told to SEND or RECEIVE. In remote mode, it is activated as soon as the SEND or RECEIVE command is entered. Once the initial connection is made, the buffer is checked periodically for packet data and refreshed after each packet so that it should not overflow. It is important to remember that this checking only occurs in SEND and RECEIVE mode. At other times the user must exercise discretion regarding sending unexpected packets. The conclusion is that MAXIV KERMIT is more sensitive to the initial connection sequence than many other KERMITs. The following general principles may be helpful: Local mode Invoke MAXIV KERMIT first. In the case of MODCOMP to MODCOMP transfer start the receiving KERMIT first. Remote mode Issue the command to the remote machine first. III.1 III. MAXIV KERMIT COMMANDS After executing KERMIT, the prompt "MAXIV KERMIT>" will appear. The user may enter the following commands: HELP STATUS SET EXIT / QUIT SEND RECEIVE CONNECT These commands may or may not require additional parameters. In all cases, the parameters must be separated by spaces. The commands and parameters may be abbreviated so long as they may be uniquely identified. For example, HELP may be shortened to H, but SEND can only be shortened to SEN so that it may be distinguished from SET. The CONNECT command is recognized but the function is not supported in Version 1.0 . The other commands are discussed below. HELP The command HELP prints out a description of each available command to the terminal. STATUS The command STATUS prints out the current values for a number of user-definable parameters. SET The command SET allows the user to change various parameters according to your current needs. The syntax of the command is: SET option value III.2 The options and their applicable values are: SET DELAY x This command controls how long KERMIT waits before sending an initialization packet. The values 1 - 60 seconds are acceptable. The default is 10 seconds. SET EOL x This command sets the end-of-line character which this KERMIT is expecting to terminate each received packet. This value does not have to match the EOL expected by the other KERMIT. The values 1 - 31 are acceptable with the default being 13 (<CR> ). SET ESCAPE x This command sets the character which terminates CONNECT mode. Since CONNECT is not currently supported, this command has no operational effect. SET MYQUOTE x This command sets the value for the character which prefixes all ASCII translated control characters. The valid values are 33 - 126. The default is 35 (<#>). SET PACKET x This command sets the maximum packet length we want to receive. The valid values are 31 - 94 characters. The default is 90. SET SOH x This command sets the start-of-packet character. The acceptable values are 1 - 31. The default value is 1 (<CTL-A>). This is not a parameter which is adjusted by the initial exchange. Therefore, both KERMIT's must agree before the connection is made. III.3 SET USL usl This command changes the library which KERMIT is logically pointed at. This library must be a SED directorized partition or dataset. The default is USL. QUIT / EXIT Either command will end this KERMIT session. If any files were received, the user will then be prompted to catalog them away properly. SEND This command has two forms: SEND file_id SEND @usl The first command will send a single file with the specified name. The file must be cataloged in the current USL. (see the SET USL command) The second command will send every file in the specified library. This library is not required to be the same as the current source library. It may be a library in a scratch partition. This allows the operator to create a directorized library in scratch and catalog files from several libraries to be sent as a group. RECEIVE When the command RECEIVE is issued, MAXIV KERMIT will receive as many files as are sent until the sender KERMIT issues an end-of-transmission. The files are placed in a scratch partition to be cataloged at the end of the session. When MAXIV KERMIT is EXITed, the user is prompted to name and catalog the received files. The answers to these questions are used to create a Job Control procedure which places the files in the desired libraries. The default file name is the received file name truncated to 8 characters with any non-cancodeable characters replaced by "$". The user may elect to accept all the default names. In this case, you will be asked whether all the files should be CATaloged or RECATaloged to the current source library. If all the defaults are not accepted, you will be prompted to name each file, specify the library to use, and whether to CAT or RECAT. When the questions have all been answered, the command procedure is automatically invoked to perform the desired file operations. III.4 In the event that a file name conflict causes the cataloging operation to fail, all is not lost! The command procedure is in KE9 under the name "STORE" and can be edited to correct the problem. Then reinvoke the procedure to complete the operation. Care must be exercised to preserve the received text while the procedure is being modified. A.1 TECHNICAL APPENDIX ___________________________ A. Building KERMIT from Source The KERMIT source files are intended to reside in a single, directorized SED USL library. Procedures are provided to compile, assemble, and link all modules and to create KERMIT as a load module overlay. All subroutines should be compiled to a single, directorized object library. This library will then be referenced to link the main program. The procedure which builds KERMIT is called BLDKER and it requires 3 arguments. BLDKER could be invoked as follows: $ASSIGN JC=KER,UJC=KER $BLDKER KER,KUL,BM where - KER is the source library containing KERMIT source, KUL is a directorized object library to contain object versions of all KERMIT subroutines, BM is the load module library to contain the KERMIT overlay. The fourth argument to BLDKER is an optional switch which tells whether or not to generate listing output. For example, to generate hardcopy listings during the build invoke BLDKER as follows: $ASSIGN JC=KER,UJC=KER,LO=LP $BLDKER KER,KUL,BM,LO __________________________________ B. Logical file assignments and usage KERMIT requires several logical files which must be assigned to I/O channels and scratch disk partitions. They are as follows: KE1 - Terminal output KE2 - Terminal input KE3 - KERMIT data output KE4 - KERMIT data input KE5 - List of file names received during the current session KE8 - Received text files KE9 - List of file names to be sent to the remote KERMIT, and Job Control procedure to catalog received files away KEH - Directorized source library containing HELPFILE A.2 One or two full duplex or half duplex asynchronous I/O ports may be used for KERMIT. If KE2 and KE4 are assigned to the same device (port) then remote operation is assumed. If they are assigned to different ports then KERMIT is set up for local operation. As files are received, the text is written to the disk partition to which KE8 is assigned, and the name of the file is written to KE9. When the user EXITs, several questions are asked concerning the disposition of the files. The file name list in KE9 is then used as the basis for creating a Job Control procedure to catalog all the received files to directorized libraries. KE9 is also used to contain a list of file names to be transmitted to the remote KERMIT. This file will contain either a single name, specified by the "SEND filename" command or the names of all the files in a directory if the "SEND @usl" command is used. For most applications, the disk resources of a BATxxx task are adequate for KERMIT. The procedure KERMIV which is provided as a template uses SCA for keeping received files, SCB for the received file list, and SC for the sending file list and Job Control procedure. KERMIV also provides the capability of designating the logical device(s) to be used for KERMIT file transfer input and output. __________________________________________ C. Control-A collision between KERMIT and TMP Many systems use Control-A as the TMP attention character. It is also used by KERMIT as the start-of-packet character. This causes problems if the asynch port used for KERMIT transfers is on the MAX IV break list. This is only a problem when KERMIT is operating in local mode. When KERMIT is invoked in local mode, a non-standard binary read is immediately issued to intercept any unsolicited packets which could cause a BREAK. However if the number of unsolicited characters exceeds the size of the read (132 bytes) the read will complete and the next control-A will cause a BREAK. To avoid this anomaly it is necessary to initiate the SEND and RECEIVE operations at roughly the same time. The user may want to customize KERMIT by increasing the size of the incoming data buffers, but must take note that only the first packet in the buffer is interpreted. A.3 _______________________________ D. Warning about SEND @usl command This command causes the specified directory to be read and the names of all active file entries to be extracted. This logic will only work correctly for 128 word-per-sector disks. Systems with sector sizes different from 128 words should avoid this command. ________________________________________ E. BATxxx task resources required by KERMIT The number of concurrent I/O operations and the number of vacant logical file assignments for Batch tasks which will be running KERMIT may have to be increased. 3 I/O operations and 15 vacant logfiles are adequate for KERMIT's use. The partitions assigned for scratch use for KERMIT must be large enough to hold the data that KERMIT will temporarily store there. The critical file is KE8 which holds the received text files. Received files are written in compressed format so as to conserve disk resources, but the user must still make sure that KE8, or any other disk partitions are not overfilled. ________________________________ F. Communications port conditioning The configuration (baud rate, frame size, parity, and stop bits) of the I/O port used for KERMIT file transfers must be set up to match the parameters of the remote KERMIT before the MAX IV KERMIT is invoked. Modification of those parameters is not supported in this release of KERMIT. ___________________ G. Future Enhancements This version of KERMIT implements only some of the basic features of a KERMIT program. Time permitting several additions are planned. Those include: 1) SET LINE and CONNECT commands to allow going from local to remote operation after KERMIT is invoked and to support a dumb terminal emulation. 2) SERVER commands to simplify the transfer of files to KERMIT versions which support server commands. 3) TAKE command which allows command sequences to be stored in an external disk file and invoked from inside KERMIT. 4) Use of the SET command to modify the KERMIT I/O port parameters such as baud rate, parity, frame size, or stop bits. A.4 5) A STATISTICS feature which would summarize information about the current session and the current transaction, including bytes transferred, packets transferred, and effective transfer rate.