home *** CD-ROM | disk | FTP | other *** search
/ The Fred Fish Collection 1.5 / ffcollection-1-5-1992-11.iso / ff_disks / 300-399 / ff330.lzh / XprKermit / kermitproto.doc < prev    next >
Text File  |  1990-03-02  |  9KB  |  226 lines
  1.         The Small Portable Kermit Module (kermitproto.w)
  2.                Stephen Walton
  3.                August 2, 1988
  4.  
  5. The attached set of routines, which I have christened "kermitproto.w",
  6. represent several weeks of work.  It is intended to be a single,
  7. self-contained set of Kermit protocol routines suitable for adding to
  8. a microcomputer terminal emulation program.  As such, it does not
  9. allow the microcomputer to act as a server.  It does provide long
  10. packets, client support, and the optional protocol for a clean
  11. interrupt.
  12.     The code began its life as the routines in the book _Kermit: A File
  13. Transfer Protocol_ by Frank da Cruz (Digital Press, 1986). I have kept
  14. the original style of the book's code, only fixing bugs and adding
  15. some Lint-related items.  I must say here that I don't care all that
  16. much for the code in the book.  The C language provides many more
  17. elegant constructs for doing what Kermit requires.  Far too many
  18. important flags and result returns are done via global variables. Not
  19. a single instance of pointers to functions, enums, structs, macros
  20. beyond very simple string replacement, or abstract data types is to be
  21. found herein.  These should not be used for their own sake, but it
  22. seems to me that they could make Kermit code much easier to read.  An
  23. ADT called "packet" is an obvious possibility.
  24.      The code communicates to the outside world through both some
  25. subroutines which the user must provide and a set of global variables
  26. which control some aspects of the protocol.  The variables can safely
  27. be ignored for the most part;  they start out with reasonable default
  28. values which are modified as the result of Kermit transactions.  Only
  29. 3 must be set by the user interface, and my module declares these as
  30. extern so your code won't link if you don't.
  31.  
  32.             File Handling Primitives
  33.  
  34. The module contains file handling primitives written in terms of the
  35. soon-to-be ANSI standard I/O library.  These ought to work on nearly
  36. all systems, though some (MS-DOS for one) may require some changes to
  37. distinguish between text and binary files.  The ones most likely to
  38. require local changes are zltor() and zrtol() for converting file
  39. names back and forth between the local format and the generic Kermit
  40. format.
  41.  
  42.             Serial Port Primitives
  43.  
  44.      The first set of user-provided routines are for handling the
  45. serial communications.
  46.  
  47.     int ttol(char *out_string, int n)
  48.  
  49. Writes the n characters beginning at outstring to the serial port
  50. using the current settings of flow control, parity, word length, etc. 
  51. Returns the number of characters read from the port or -1 on failure.
  52.  
  53.     int ttinl(char *in_string, int max, int timeout, int eol)
  54.  
  55. Reads characters from the serial port into in_string.  It stops when
  56. either max characters have been seen or the end-of-read marker eol has
  57. been seen.  If timeout is greater than 0, then the read must be
  58. completed in no more than timeout seconds.  The value returned is the
  59. number of characters actually read or -1 on error or timeout.
  60.  
  61.     void ttflui(void)
  62.  
  63. Removes all pending readable characters from the serial port.
  64.  
  65.         Other User-Provided Routines
  66.  
  67.     int gnfile(char *filename, int length)
  68.  
  69. Copies the next file for Kermit to SEND or GET into the character
  70. string pointed to by filename, of maximum length length.  Returns a
  71. positive flag if there is a next file, 0 or negative if not.
  72.  
  73.     void sleep(int seconds)
  74.  
  75. Pause the user's program for the given number of seconds.
  76.  
  77.             Status Routines
  78.  
  79.     These routines are used to report the status of the protocol to
  80. the user's program for possible display.
  81.  
  82.     void tchar(char c)
  83.  
  84. Place the character "c" on the user's terminal.  c is a . for a
  85. successful packet transfer and a % for a retry, but c can also be
  86. anything a remote server might send in response to client commands
  87. (REMOTE COMMAND, for example).
  88.  
  89.     void tmsg(char *message)
  90.  
  91. Write the null-terminated string without a carriage return; i.e., if I
  92. call tmsg("first ") and tmsg("word"), the user should see "first word"
  93. displayed.
  94.  
  95.     void tmsgl(char *message)
  96.  
  97. Write tne null-terminated string and start a new line after
  98. displaying.
  99.  
  100.     Future update plans call for adding code to count packets, file
  101. bytes, and naks and adding a special call for displaying this type of
  102. information, similar to the screen() routine in C Kermit 4E(070).
  103.  
  104.             Starting It Up
  105.  
  106. All Kermit protocol transfers are started by doing whatever startup
  107. the user's code requires, putting the appropriate start state into the
  108. extern int start, and calling the routine proto().  Here are the supported
  109. start states and how they work:
  110.  
  111. 'v':  Receive a file.  The protocol module assumes that the remote Kermit
  112. has been given a SEND command, and passively waits (with timeouts) for the
  113. file(s) to start arriving.  Your Kermit receive subroutine could be as
  114. simple as:
  115.  
  116. void kermit_receive(void)
  117. {
  118.     extern int start;
  119.  
  120.     start = 'v';
  121.     proto();
  122. }
  123.  
  124. 's':  Send a file.  The protocol module calls gnfile() (see above)
  125. repeatedly, and sends each file requested to the remote.  The remote must
  126. have been given a RECEIVE or a SERVER command first.
  127.  
  128. 'r':  Get file(s).  The protocol module calls gnfile() for a list of files
  129. to request from a remote Kermit server.  These can generally include
  130. wildcards in the remote's syntax, for example *.FOR for all Fortran files
  131. from an MS/DOS server or *.c for all C files from a Unix server.
  132.  
  133. 'g': Kermit generic commands.  The protocol module sends the string pointed
  134. to by the extern char *cmarg to the remote as a Kermit generic server
  135. command.  The command string is of the format:
  136.  
  137.     <cmd>[%<string1>...]\0
  138.  
  139. where <cmd> is a single upper-case letter representing the Kermit generic
  140. command, and it is followed by one or more optional string arguments.  Each
  141. string is preceded by tochar() of its length.  For example, the <cmd> for a
  142. Kermit BYE (logout) command is L, and it takes no arguments, so the
  143. simplest possible BYE subroutine would be:
  144.  
  145. void kermit_bye(void) {
  146.     static char bye_command[] = "L";
  147.     extern char *cmarg;
  148.  
  149.     cmarg = &bye_command[0];
  150.     state = 'g';
  151.     proto();
  152. }
  153.  
  154. See the Kermit book for a complete list of the generic commands and the
  155. arguments required.
  156.  
  157. 'c':  Kermit REMOTE HOST command.  cmarg points to a string in the remote's
  158. command syntax which is to be executed by the remote, with output (if any)
  159. from that command being returned by the remote server.  Here is a simple
  160. example:
  161.  
  162. #define tochar(c) ((c) + 32)
  163.  
  164. void kermit_remote_host(char *remote_command)
  165. {
  166.     extern char *cmarg;
  167.     char command[90];
  168.  
  169.     state = 'c';
  170.  
  171.     cmarg = command;
  172.     cmarg[0] = tochar(strlen(remote_command));
  173.     strcpy(&cmarg[1], remote_command);
  174.     proto();
  175.     free(cmarg);
  176. }
  177.  
  178. Notice that the string pointed to by cmarg must be small enough to fit in a
  179. single Kermit packet; i.e., 90 characters or less.
  180.  
  181.             External variables
  182.  
  183. There are several which are of interest to every user program. These
  184. are, first of all, the flags parity, convert, and text.  These are
  185. simply checked against zero;  a non-zero value means that parity is in
  186. use (that is, the data path is 7 bits wide), that file names are to be
  187. converted to a generic form, and that files are to be sent or received
  188. as text, respectively.  If they are zero, they indicate an 8-bit wide
  189. data path, no file name conversion, and binary file transfer.  These
  190. are defined in kermitproto.w but must be declared in the user code;
  191. that is, the declarations "int parity", "int convert", and "int text"
  192. must appear somewhere outside of any block.
  193.     The value urpsiz must be declared by the user as well.  This is a
  194. mnemonic for "user requested packet size," and represents the size of
  195. packets the user wants to request be used.  I have written
  196. kermitproto.w so that if urpsiz is such that long packets are
  197. required, the code will also request type 3 (CRC) block checks, but
  198. the equivalent of the SET BLOCK-CHECK 3 must be issued to the remote
  199. as well.
  200.     The flags cx and cz can be used to abort a file transfer.  If cx
  201. is set upon return from ttinl(), the file currently being transferred
  202. is skipped, and any partial result from the transfer is deleted.  If
  203. cz is set, then an entire batch transfer is aborted if one is in
  204. progress.  Most Kermit programs understand the protocol used for this
  205. cancellation.  Incidentally, the reason for these flags' names is that
  206. the book recommends that Control-X be the cancel-file interrupt and
  207. that Control-Z be the cancel-batch interrupt character.
  208.     Finally, there are all of the variables which control timeouts,
  209. number of retries, block check type, and so on.  These are described
  210. in the comments at the beginning of the module.
  211.  
  212.             Compiling This
  213.  
  214. kermitproto.w is a Wart file, and should be passed through the wart
  215. preprocessor via the command:
  216.     wart kermitproto.w kermitproto.c
  217. to generate a C file to hand to your local C compiler.  wart is
  218. available (as CKWART.C) from the Kermit archives in the usual way, and
  219. is sufficiently portable so as to compile on a wide variety of systems
  220. without modification.
  221.  
  222.             Final Thoughts
  223.  
  224. 32K is longer than I thought this module would end up when I started. 
  225. I hope it does save someone some work.
  226.