Network CD 2

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

/ Network CD 2 / Network CD - Volume 2.iso / term / docs / xprkermit.doc < prev

Wrap

Text File | 1993-07-05 | 17.8 KB | 381 lines

XPR Kermit Version 1.111 - RELEASE December 21, 1991 Marco Papa - Felsina Software Stephen R. Walton, Cal State Northridge This is an implentation of an External Protocol (XPR) library for the Kermit file transfer protocol. In keeping with the Kermit documents, here is a list of the items supported and not supported. XPR Kermit Capabilities At A Glance: Local operation: Yes Remote operation: No Login scripts: * Transfer text files: Yes Transfer binary files: Yes Wildcard send: Yes File transfer interruption: Yes Filename collision avoidance: No Can time out: Yes 8th-bit prefixing: Yes Repeat count prefixing: Yes Alternate block checks: Yes Terminal emulation: * Communication settings: Yes Transmit BREAK: * Support for dialout modems: * IBM mainframe communication: * Transaction logging: No Session logging (raw download): No Debug logging: No Packet logging: No Act as server: No Talk to server: Yes Advanced server functions: No Local file management: * Command/Init files: * UUCP and multiuser line locking: * Long packets: Yes Sliding Windows: No File attributes packets: No Command macros: * Raw file transmit: * The items marked with a '*' above are those which are to be provided by the calling terminal emulation program. Notice that, although XPR Kermit itself cannot be a "Kermit server," often the communcation program's scripting capability will allow XPR Kermit to be used for the unattended transfer of files between the Amiga and a remote machine. I. Introduction --------------- XPR Kermit implements the Kermit file transfer protocol in the form of an Amiga External Protocol (XPR) library. This allows the addition of an up-to-date version of the Kermit protocol to any communications program which supports the XPR specification. For further information on Kermit, read the book "Kermit: A File Transfer Protocol" by Frank da Cruz, 1986, Digital Press. To install XPR Kermit, simply copy the file "xprkermit.library" to your LIBS: directory, and request your comm program to use XPRKERMIT as its external file transfer protocol. XPR Kermit supports Version 2.0 of the XPR Protocol specification. For more details on this, I recommend that you find a copy of the XPR Zmodem library, version 2.0. Its documentation contains a good deal of the justification and philosophy of external protocol libraries, which I won't repeat here. Please note that this document assumes you already have some understanding of what the Kermit protocol is, and how to use it. I have tried to include a few hints about common problems, but there is no substitute for obtaining and using a copy of the documentation for the Kermit on the other system to which you will be talking. In addition, two commercial books are available. "Kermit: A File Transfer Protocol" by Frank da Cruz describes the protocol in some detail. While aimed at those writing a Kermit program, it contains a good deal of useful information about Kermit itself. "MS-DOS Kermit" by Christine Gianone is, despite its title, a wealth of good introductory information about any version of Kermit. II. Setting Options ------------------- XPR Kermit supports the parts of the Kermit protocol outlined in the table above. There are currently seven user-settable parameters in XPR Kermit, which cover the parameters which are most often necessary to customize. If your communications problem is especially severe--for example, your method of connection to another system swallows characters which are special to Kermit, such as '#' or '&'--you may need to get a copy of the stand-alone Kermit program, C Kermit for the Amiga, distributed via many paths. There are actually two sets of "setup" parameters in XPR Kermit. The first set are commands which XPR Kermit can send to a remote Kermit server. These are not actually setups, but are in fact commands to XPR Kermit which cause it to communicate with a remote Kermit server. The fourth command in this group is "Change Options," which causes no communication. Instead, you are requested for changes in the current values of the parameters which Kermit will use for communication. These items can be set in one of two ways. One method is with a simple character string which is sent to XPR Kermit by the comm program; this string will hereafter be referred to as the "init string." This is generally done if an environment variable named "xprkermit" exists and has a value, in which case XPR Kermit is sent the value when you first select XPR Kermit as your protocol. Some comm programs also allow an initialization string to be sent in other ways, such as from a script; VLT, for example, has an INITXPR script command. The format of this string is specified by the external protocol. The second, more elegant method, is with some type of requester or set of requesters. In this case, you will be presented by your comm program with a set of Intuition gadgets of some type which allow the choice of XPR Kermit commands and the setting of the options. However, the string method has the advantage of giving one the ability to change external protocol settings non-interactively, such as from a script. In the case of XPR Kermit, such a script can actually command XPR Kermit to perform communication. One obvious use of this is to transfer an entire directory tree from your Amiga to a remote machine: you can make the remote's Kermit a server and command it to perform the appropriate CD commands, then transfer files. The currently supported XPR Kermit server commands are listed below. The format of the init string is in parentheses, generally simply a single letter. Kermit Finish (F): Tells a Kermit server that you are done. The remote server will stop being a server. Kermit Bye (B): Tells a Kermit server that you are done; the server will exit and log you off the remote machine. Kermit CD (C{dir}): Change the default directory for files sent or received by the Kermit server. Examples of the init string would be 'C/bin' or 'Cuser:[username.amiga]'. For setting options via an init string, the first character of the init string must be the letter O (for Options). Following that letter can be one or more of the option setting formats listed bellow; these can be separated by whitespace and/or commas. There are three settings which are either "yes" or "no." Your comm program will give you some way of setting them interactively. Simple button gadgets will be labeled "yes" and "no;" otherwise, you may see a string gadget, into which you should type the word "yes" or "no" by hand. This string is case-insensitive. In the init-string, "yes" is represented by the single upper-case character Y. Convert FileName (C{Y|N}): If "yes," then incoming file names are converted to a form acceptable to the Amiga. Currently, this means simply translating them to lower case. Default "yes." Host Server (G{Y|N}): If "yes," then the host (remote) Kermit is assumed to be in server mode. You will be prompted for file names when you request an XPR Kermit receive, and this file name will be sent to the server in the form of a Kermit GET command. Default "no." Keep Incomplete (K{Y|N}) If "yes," then incomplete files will be kept. An incomplete file can result from either an actual error in the transfer, or a user-requested cancellation of a transfer in process. Default "no." Text File (T{Y|N}): Flags whether the incoming file is text or binary. If "yes," then carriage-return/line-feed pairs in the incoming packets are converted to a single line-feed before writing the packet to a file, and the opposite conversion is made when a file is sent to a remote system. Default "yes". If your communcations program supports its own text/binary flag (that is, if the xpr_finfo() function exists and can tell XPR Kermit whether a given file is text or binary), this option will not appear. Numerical settings are as follows. Here, the init string key letter should be followed by a numerical value. Packet Length (P{length}): The Long Packets extension to Kermit is fully supported. The current limit is 2048 for XPR Kermit; the default value is 94, the longest standard Kermit packet. Block Check (B{type}): This can have the value of 1, 2, or 3, and chooses successively more stringent types of error checking on the incoming data: 6-bit checksum, 12-bit checksum, and 16-bit CRC, respectively. Default is 1 (6-bit checksum). Timeout (O{seconds}): The length of time the remote Kermit should wait for a packet from XPR Kermit before assuming it isn't coming. The default is 10 seconds. (O is for Out, as in TimeOut; T is already taken by the Text flag.) Retry Limit (R{number}): The number of times XPR Kermit will attempt to send or receive the next packet of data before quitting. Notice that if the remote end simply stops sending, a length of time equal to the retry limit times the timeout will elapse before XPR Kermit actually exits. Default 5 retries. Setting a packet length larger than 94 (the default) enters long packet mode automatically. If you use long packets, it is *strongly* recommended that you use block check 2 or 3 if the host Kermit supports them. In addition, if binary files are to be transmitted, a higher block check than 1 should be used as well. Timeout settings are a bit confusing, I've found. The timeout set via XPR Kermit's requester is what standalone Kermit programs normally call the "receive timeout," and is the length of time which XPR Kermit will request the other end to wait before assuming that XPR Kermit is not sending any response to the most recently sent packet. The "send timeout" is the length of time XPR Kermit should wait for a packet from the remote end and is requested by the remote end. It is generally set at that end by a "set send timeout" command. With long packets at low baud rates (say, 2048 bytes at 1200 baud), both these times should be long enough to ensure an entire packet can be transferred in this time. The symptom if it is too short is that each packet will be sent exactly twice. These can be mixed and matched. For instance, to talk to a Kermit server with 750-byte packets, block check 2, keep incomplete files, binary files, and a 10-second timeout, the init string could be "OP750,B2,KY,TN,O10". Cryptic, but usable. III. Transferring Files ----------------------- Once XPR Kermit is set up, transferring files is as simple as with any of the protocols built in to your communication program. Typically, you will log into a remote computer, start up its Kermit program, and issue the "send filename" or "receive" command to the remote Kermit. A message will be printed, something like "Escape back to your local system and give a RECEIVE command" if you told the remote to send a file. Issue the Receive File command to your terminal program; frequently, this is Right-Amiga-R. Sit back and watch the file be transferred. The files received by XPR Kermit are placed in the comm program's idea of its current directory; that is, XPR Kermit asks the comm program to create a file of the same name as the file on the sending system, but leaves the directory in which the creation is to occur up to the comm program. For sending files, path information is stripped from the file name before it is sent to the remote. XPR Kermit supports multiple files on both send and receive. Multiple received files are handled by the sending Kermit. One almost always issues a wildcard send command, for example "send *.for" to send all Fortran files. For sending multiple files, XPR Kermit queries the calling communication program for the names of the files to send, one at a time. Check your program documentation for its method of supporting this. Two common possibilities are simply the ability to type a wildcard into a string requester specifying the files to send, and being able to check multiple files in a list on a file requester. If the "Host is Server" flag is set on the XPR Kermit options, it is assumed that you started the remote Kermit and issued the "Server" command to it. This modifies XPR Kermit's behavior on receiving files. Since you can no longer tell the remote host which files to send, XPR Kermit uses the Kermit GET command instead. The file to GET is requested by the comm program when you issue a "Receive File" command. A string requester is almost always used here to prompt for the files to receive. Note that this should be in the format of the *remote* system, not the Amiga. This is important for wildcards; SENDing a batch of Amiga files will generally use AmigaDOS wildcards (#?.for for all Fortran files), while a Unix, VAX/VMS, or MS/DOS system would use *.for for the same operation. XPR Kermit supports three levels of transfer abort, out of the 33 which can be part of an XPR-supporting comm program. The lowest level of an XPR abort is treated by XPR Kermit as a file abort, meaning that, if a batch transfer is in effect, the current file's transfer is interrupted but the protocol proceeds with the next file. This is most useful in a wildcard transfer, where the wildcard matches a long file which you don't actually want transferred. The next higher level is treated as a batch abort, meaning that all files are cancelled. Both of these aborts happen in a "graceful" way, which will not generally result in the remote Kermit exiting with an error status. The highest level XPR Kermit abort, which is all many programs provide, is treated as an immediate stop-dead. An error packet containing the string "User cancelled." is sent to the remote Kermit, the same message is echoed on the comm program status display, and XPR Kermit exits. In addition, if the "Keep Incomplete Files" flag is OFF, the most recently received file will be deleted, if the cancelled transfer was a receive. IV. Future Extensions ---------------------- This is probably the last release of XPR Kermit in its current form. At some future point, XPR Kermit will, I hope, become an interface to Columbia University's C Kermit code. This will allow XPR Kermit to always contain the latest version of the Kermit protocol, provided that I or someone writes the required machine-dependent functions. Among other things, such a rewrite would automatically include both the sliding windows and attribute packets extensions to the Kermit protocol into XPR Kermit, since they are in the current version of C Kermit. Incidentally, I (Stephen Walton) am the co-supporter of C Kermit for the Amiga. As of this writing, version 5A of this program is in alpha test. V. Other information ---------------------- The file "kermitproto.doc" describes the code contained in the file "kermitproto.w," which actually implements the Kermit protocol. It is somewhat out of data, and "kermitproto.w" is pretty XPR Kermit-specific at this point (it was originally intended as a small, stand-alone Kermit implementation in C). VI. Credits ----------- The following people had a hand in this code. In chronological order, they are: -- Frank DaCruz of Columbia University, who wrote the original code and published it in his book. -- Steve Walton of Cal State Northridge, who got Frank's code actually working in the form of the original "kermitproto.w" module. -- Marco Papa of Felsina Software, for the first beta XPR version -- Steve Walton, for second and subsequent XPR Kermit's. Other acknowledgements go to Willy Langeveld for developing the XPR spec, and to Rick Huebner, several of whose ideas in XPR Zmodem were taken over into XPR Kermit by Steve Walton. Thank you all! VI. Gripes ----------- The current author and babysitter of this code is: Stephen Walton Department of Physics and Astronomy Cal State Northridge 18111 Nordhoff St. Northridge, CA 91330 USA (818) 885-2775 E-mail can go to: srw@csun.edu (Internet) Thanks and congratulations gratefully accepted; bug fixes and enhancements even more so! VII. Changes ------------- The following changes and improvements have been made to XPR Kermit since the release of version 1.5: 1. The library is now re-entrant. This re-entrancy uses a bit of a "trick" which depends on the mechanism used by Manx Aztec C to set up small model programs. I have successfully run two simultaneous file transfers in XPR Kermit. 2. The timeout code has been improved; in fact, it appears that it may not have worked at all in version 1.5. 3. Block check type 2 did not work in version 1.5. 3. A buffer overflow which could trash the high byte of an address on an Amiga 3000 or other 68030-based machine was fixed. This would only be seen, normally, when sending a file with many repeated characters. 4. The "Keep incomplete file" feature is new. 5. The file status display has been cleaned up somewhat; in particular, the previous file's final display should no longer show up when a new transfer is started. Timeouts are now counted separately from other errors. 6. Local buffers (that is, within XPR Kermit) have been added for both file and communication line I/O. This substantially reduces the number of callbacks between XPR Kermit and the comm program, improving performance under heavy multitasking. [Note added 3 Dec 1991: an actual trial on the local buffer for serial I/O indicated *worse* performance, so the code is only compiled if the symbol MYREAD is #define'd in kermitproto.c. This is not the case in the distributed library.] 7. xpr_chkmisc() and xpr_chkabort() are now called properly.