Fresh Fish 4

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

/ Fresh Fish 4 / FreshFish_May-June1994.bin / bbs / amigalib / d995 / xprkermit.lha / XprKermit / ckxker.doc < prev next >

Wrap

Text File | 1994-04-05 | 26.5 KB | 544 lines

XPR Kermit Version 2.30 February 14, 1993 Frank da Cruz - Columbia University 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: Yes Transfer text files: Yes Transfer binary files: Yes International text: No Wildcard send: Yes, if supported by comm program File transfer interruption: Yes Filename collision actions: Yes Can time out: Yes 8th-bit prefixing: Yes Repeat count prefixing: Yes Alternate block checks: Yes Automatic parity detection: No Dynamic packet length: Yes CONNECT mode: * Terminal emulation: * Key mapping: * Communication settings: * Transmit BREAK: * Support for dialout modems: * TCP/IP support: * X.25 support: * IBM mainframe communication: * Transaction logging: No Session logging: No Debug logging: No Packet logging: No Act as server: No Talk to server: Yes Advanced server functions: No Security for server: No Local file management: N/A Command/Init files: N/A Long packets: Yes Sliding Windows: Yes File attributes packets: Yes, but limited by XPR protocol Command macros: * Script programming language: * Raw file transmit and capture: * 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 communication 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. 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. "C Kermit" by Christine Gianone and Frank da Cruz, is a wealth of good introductory information about any version of Kermit. In addition, the latter book is also the documentation for the standalone version of C Kermit which is available for the Amiga. The Kermit protocol, and XPR Kermit, are copyright by Columbia University. XPR Kermit is subject to the same restrictions as any other version of Kermit. In particular, XPR Kermit may be included as part of a commercial package, provided the cost of said package is not increased as a result. I cannot resist saying a few words in support of Kermit. Unlike many other file transfer protocols such as the X/Y/ZMODEM family, the design of the Kermit protocol started with the assumption that communication lines are unreliable and quirky. Kermit's slightly lower efficiency on good lines is more than compensated for by the fact that it can often successfully transfer files under conditions where other protocols fail. It can transfer binary files over a seven-bit-wide communication line, or one which "eats" most control characters; in fact, only two binary characters, the start-of-packet and end-of-packet markers, need be passed unchanged by the line. II. Installation ----------------- 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. Among the programs supporting the XPR specification are the commercial programs A-Talk III and JRComm and the free programs VLT, Term, and NComm. III. Setting Options -------------------- XPR Kermit supports the parts of the Kermit protocol outlined in the table above. There are currently nine 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 control-A--you may need to get a copy of the stand-alone Kermit program, C Kermit for the Amiga, distributed via many paths. The current version is 5A(189). 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 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 file names are converted from Amiga file names to a "least common denominator" form and back again. On files which XPR Kermit sends, this means that any leading directory path is stripped, and the file name can consist of only upper case letters, numerals, and at most one period. Lower case letters are translated to upper case, and non-alphanumeric characters, including extra periods, are translated to X. Received file names are converted to lower case. If "no," then none of these translations occur. NOTE: This means that files will often be sent with a complete leading Amiga path name, and so you should make sure that you send files with the comm program's current directory set to the directory containing the file you're sending. 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. Also, it is possible using attribute packets for the sending Kermit to request switching from text to binary and back again on a per-file basis. XPR Kermit fully supports this. It will switch if requested to by a sending Kermit. When sending, XPR Kermit uses the xpr_finfo() function on a per-file basis. The Amiga has no real way of determining whether a file is text or binary, however, so it is usually up to the user to choose the correct mode from a menu item or other setup in the comm program. Numerical or alphabetic settings are as follows. Here, the init string key letter should be followed by a numerical or alphabetic value, as indicated. Packet Length (P{length}): The Long Packets extension to Kermit is fully supported. The longest possible packet is 9024; 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. See the extended discussion of timeouts below. (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. Window Size (W{number}): The number of windows to use in the sliding window extension to the protocol. This is the number of packets which XPR Kermit will send without waiting for an acknowledgement from the other end. Default 1, meaning sliding windows are not used by default. File Name Collision action (N{X|A|D|R}): What action to take if a received file has the same name as an already existing file. Each letter is a possible action, as follows: X - Replace. Unconditionally replace the old file with the new one. A - Append. Append the incoming file to the end of the old file. D - Discard. Refuse to accept the incoming file. R - Rename. Rename the incoming file to a unique name by appending a tilde followed by a sequence number to its name. The default is Replace. Send Packet Size and Send Timeout (SPn and SOn): These values override the ones requested by the Kermit at the other end for the packet size and timeout, respectively, for XPR Kermit to use when sending files to the other Kermit. They should only be used if there is good reason to believe that the values requested by the other Kermit are not working well: for example, that you know more about the connection than the other end does. If these are zero, then the other end's requested packet size and timeout are used. The default is zero. 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. All of the above parameters, except the Send Overrides, correspond to the numbers set in a typical standalone Kermit program via the SET RECEIVE command. In the initial setup transaction for a Kermit file transfer, these values are sent to the Kermit at the other end as a request for it to use them when receiving packets from XPR Kermit. The values for block check, timeout, window size, and packet length which XPR Kermit actually uses depend, in turn, on the ones requested by the Kermit at the other end. The block check, packet size, and window size used in the transaction will be the smaller of the values requested by the other Kermit and the values set by you in the XPR Kermit initialization. Timeout settings are handled differently and are a bit confusing, I've found. The timeout set via XPR Kermit's requester 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 length of time XPR Kermit should wait for a packet from the remote end is requested by the remote end, and is generally set by a SET RECEIVE TIMEOUT command typed by the user to the remote Kermit. 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. The same symptom can occur even if the connection between the remote Kermit and XPR Kermit is fast but has long transmission delays; this is often the case when connected to a distant site via the Internet. If you have problems such as these, try using the Send Overrides to change the values which XPR Kermit uses when sending packets. Options 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, five windows, and a 10-second timeout, the init string could be "OP750,B2,KY,TN,W5,O10". 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. When a remote Kermit is a server, it accepts incoming requests of a special format about which file to send. On a command-line oriented version of Kermit, the command "GET filename" would be typed to the local Kermit, which would request the remote Kermit server to send that file. XPR Kermit uses the protocol behind the Kermit GET command as well. If the comm program sends XPR Kermit the name of a file or files to GET, for example from a script command, then that filename is used. In the case of VLT, for example, the script command 'XPR RECEIVE "file"' will result in the file named "file" being used in XPR Kermit's GET command, provided the "Host is Server" flag is set. If no file name is sent to XPR Kermit by the comm program in this manner, the file or files to GET is requested interactively by XPR Kermit through the comm program. This will almost always happen when you issue an interactive "Receive File" command to the comm program. 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. Most comm programs supply a nice status display, which XPR Kermit will update regularly to keep the user apprised of the transfer's progress. The name of the sent or received file will be shown. If file name conversion is on, the converted name will appear after the word "as;" for example, 'Sending S:Startup-Sequence as STARTUPXSEQUENCE.' The current packet count, packet length, packet type, timeout count, error count, number of file bytes transferred, elapsed time, and estimated total time are all updated after each attempt to transfer file data, whether the attempt is successful or not. After the transfer completes, the total number of files, number of file bytes, elapsed time, and character-per-second (cps) transfer rate will be shown. 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. Credits ------------ The following people had a hand in this code. In chronological order, they are: -- Frank DaCruz of Columbia University, who deserves most of the credit here. The system-independent code in the ckcfn?.c files is his, and XPR Kermit is really just an interface to these files, which are identical to the ones used in every other C language implementation of Kermit. -- 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! V. 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: swalton@solar.stanford.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.111: 1. Attribute packets, file name collision handling, and sliding windows are all new in this version. 2. The system-independent C Kermit code is now used. This means that, absent changes in the system-dependent routines required, XPR Kermit will automatically share in any improvements made to its big sister, C Kermit 5A(189). 3. The file transfer display code has been completely rewritten. This was only possible because C Kermit already contains a system-dependent screen() function specification, which describes how to update the file transfer status display. In fact, the screen() function in XPR Kermit is largely copied from the screenc() function in the Unix and Amiga versions of C Kermit. The following improvements were made between version 1.5, the first release of XPR Kermit, and the second release, version 1.111. 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 binary.] 7. xpr_chkmisc() and xpr_chkabort() are now called properly. VI. BUGS AND LIMITATIONS ------------------------- The file transfer cancellation button doesn't seem to work in Olaf Barthel's Term 3.2. I have sent him e-mail about it. The XPR protocol does not allow for the XPR to rename existing files. If it did, a "backup" option for file name collision detection would be possible. In this case, if an existing file has the same name as a received file, the existing file is renamed to a unique name and the received file is stored under its own name. This is my personal preferred option, and is the default action with C Kermit. The XPR protocol also does not allow one to find or set the modification date of a file. If it did, then several additional features would become possible. One would be an "Update" option for filename collision, which would replace the existing file but only if the incoming file was newer. XPR Kermit could also tell the receiving Kermit the modification date of a sent file, and set the modification date of a received file to agree with that on the sending system. XPR Kermit is the largest of the XPR libraries, by a factor of three. Because of this size, I have chosen not to implement one of the other major improvements of the most recent version of the Kermit protocol, namely support for international character sets. If you need this feature, for example if you regularly transfer text files between machines in different countries, I recommend setting XPR Kermit to binary mode and setting the sending Kermit to use "ISO Latin-1" as its transfer character set. Since the file character set of the Amiga is ISO Latin-1, this should result in a file transfer with all international characters intact, at the cost of a carriage return/line feed pair at the end of each text line, which can be trimmed after the file transfer. If the remote system is a Unix system, or another Amiga, a binary-to-binary transfer of text files should work also. XPR Kermit uses more memory than is strictly necessary, because both read-only and read-write data are copied for each comm program using XPR Kermit. However, all file and communication buffers are allocated when needed, so this is not as important as it might first seem. If international character sets were implemented, the large translation tables required would probably require an extensive rewrite of XPR Kermit to keep its memory usage reasonable.