home *** CD-ROM | disk | FTP | other *** search
/ Columbia Kermit / kermit.zip / protocol / tagged5.txt < prev    next >
Text File  |  2020-01-01  |  10KB  |  225 lines
  1.  3-Oct-97 19:18:44-GMT,10369;000000000001
  2. Return-Path: <fdc>
  3. Received: (from fdc@localhost)
  4.     by watsun.cc.columbia.edu (8.8.5/8.8.5) id PAA20833;
  5.     Fri, 3 Oct 1997 15:18:27 -0400 (EDT)
  6. Date: Fri, 3 Oct 97 15:18:27 EDT
  7. From: Frank da Cruz <fdc@watsun.cc.columbia.edu>
  8. To: townsend@patownsend.com
  9. In-Reply-To: Your message of Fri, 03 Oct 1997 12:00:54 -0700
  10. Subject: Labeled file transfer spec
  11. Message-ID: <CMM.0.90.4.875906307.fdc@watsun.cc.columbia.edu>
  12.  
  13. This has been implemented for VMS and OS/2 (with its Extended Attributes):
  14.  
  15. KERMIT LABELED FILE TRANSFER
  16.  
  17. Kermit programs presently differentiate between text and binary files via
  18. the SET FILE TYPE command.  When the file type is TEXT, the Kermit program
  19. that is sending the file converts the file's record format and character set
  20. from its local form to a standard form, and the receiving Kermit program
  21. converts from the standard form into its own local record format and character
  22. set.  When the file type is BINARY, the file is sent as-is, byte for byte.
  23.  
  24. These two ways of handling files are sufficient in many cases, but fall short
  25. when one or both computers has a complex file system, such as the Macintosh or
  26. DEC operating systems like VAX/VMS.  The Kermit protocol includes a mechanism
  27. for transmitting a file's attributes in a generic way, but these attributes
  28. are of little use when the file is being received by a computer with a simple
  29. file system, such as UNIX or MS-DOS, that can't do anything with them.  And
  30. they are not sufficient to convey every conceivable bit of information about
  31. about every kind of file on every kind of computer.
  32.  
  33. To allow a complicated file to be transferred, a new file type is proposed:
  34.  
  35.   SET FILE TYPE LABELED
  36.  
  37. Notice the spelling of "LABELED" (only one L between the E's).  When this
  38. setting is in effect, the sending Kermit sends not only the file's data, but
  39. also system-dependent structural information about the file.  Since this
  40. information can be quite lengthy, it is sent as if it were file data, in data
  41. packets preceding the actual file data, rather than in attribute packets.  All
  42. of this information is sent in binary mode (no conversions).
  43.  
  44. The receiver of the file can elect whether to act upon the label information,
  45. or simply store it.  Kermit programs for simple file systems need no changes,
  46. and can still act as repositories for labeled files, to be sent back later to
  47. the system of origin.  On the other hand, labeled file transfers between like
  48. systems (e.g. two VAX/VMS computers) will result in the reception of a file
  49. with all the correct characteristics.
  50.  
  51. There are two possible modes of operation.  The first (and safer) mode
  52. requires human intervention on a per-file basis, but an automatic mode is also
  53. possible.
  54.  
  55. DEFINITIONS
  56.  
  57. A "bare" file is a file stored on disk that does NOT contain, as part of
  58. its contents, Kermit-constructed label information.
  59.  
  60. A "labeled" file is a file stored on disk whose contents include
  61. Kermit-constructed label information.
  62.  
  63. FORMAT OF A LABELED FILE
  64.  
  65. This description applies to a labeled file as stored on disk and to a bare
  66. file that has label information added to it by a sending Kermit.
  67.  
  68.   BANNER  The literal text string "KERMIT LABELED FILE:", just the twenty
  69.           characters within the quotes including the trailing colon, in 7-bit
  70.           ASCII.  ASCII is used even on non-ASCII systems (like IBM mainframes
  71.           with EBCDIC).
  72.  
  73.   IDLEN   A 2-byte ASCII decimal numeric length field, with leading zeros if
  74.           necessary, for example "02".
  75.  
  76.   SYSID   The system ID, one of the codes listed on pp.275-278 of the Kermit
  77.       book.  This is a string of 1 to 99 ASCII characters (but typically
  78.           1-3 characters), for example "D7" for (Open)VMS.  The length of the
  79.           SYSID field is given by the preceding field (IDLEN):
  80.  
  81.           D7 = VMS
  82.           D8 = RSX-11
  83.           D9 = IAS
  84.           DA = RSTS/E
  85.           DB = RT-11 or TSX+
  86.           DC = P/OS
  87.  
  88. NOTE: The Kermit book predates AS/400, and in any case lacks any listings at
  89. all for any IBM midrange systems.  So let's assign the letter "O" for this
  90. line, and OA would be System/34, OB System/36, OC System/38, and OD for the
  91. AS/400.
  92.  
  93.   LBLEN   A 2-byte ASCII numeric length field, with leading zeros if
  94.           necessary, for example "00", "02", "09", "99".
  95.  
  96.   LABEL   A label field, 1 to 99 ASCII characters.  The length is given by
  97.           the preceding length field (LBLEN).  The LABEL field contains the
  98.           name of the file descriptor data that follows.
  99.  
  100.   VALEN   An 8-byte ASCII numeric length field, with leading zeros if 
  101.           necessary, for example "00000512".  Zero ("00000000") is a
  102.           permissible length for a value.
  103.  
  104.   VALUE   The value associated with the label, 0 to 99999999 bytes of
  105.           information about the file in system-dependent format.  The labels
  106.           and the format and layout of the associated values for each system
  107.           type should be clearly defined and documented.
  108.  
  109.      The sequence (LBLEN, LABEL, VALEN, VALUE) may be repeated for as many
  110.      labeled values are needed (if VALEN is zero, then VALUE is omitted).
  111.  
  112.   CONTENT The file's contents, encoded in whatever form that, in combination
  113.           with the labeled values, allows for its eventual reconstruction in
  114.           its original form.
  115.  
  116. REQUIRED LABELS
  117.  
  118. The following labels (composed of ASCII uppercase letters) are reserved, and
  119. are required in every labeled file:
  120.  
  121.   VERS    The operating system version, e.g. "5.3-1"
  122.  
  123.   DATA    This is the final label.  It has a zero-length value, which is
  124.           followed immediately by the file's contents, as defined above.
  125.           See example below.
  126.  
  127. EFFECTS ON THE KERMIT PROTOCOL
  128.  
  129. When SET FILE TYPE LABELED is in effect, the sending Kermit should include
  130. the file type (") attribute, specifying a type of binary (B), if attribute
  131. packets have been negotiated.  Otherwise, there is no effect on the protocol
  132. at all.  In particular, a label-wise Kermit program can interoperate perfectly
  133. well with another Kermit program that is completely ignorant of labeling, in
  134. which case the latter program simply "archives" the file, labels and all.
  135.  
  136. This proposal does not rule out the system-independent type of file archiving,
  137. based on file attribute packets, that is described in the Kermit book.
  138. However, if the "system-dependent" attributes suggested by this proposal can
  139. be worked out in a sufficiently generic fashion, this may lead to a more
  140. effective type of transmission of complex files between unlike systems that
  141. share similar types of file characteristics (block size, record format,
  142. character set, carriage control, etc).
  143.  
  144. On the other hand, for the first pass at an implementation (for VMS), it might
  145. make more sense to simply have a single system-dependent label, like "FAB",
  146. whose value is simply the File Access Block, and perhaps another one like
  147. "ACL" for its Access Control List.  The two approaches do not rule each other
  148. out.
  149.  
  150. USER INTERFACE
  151.  
  152. When SENDING a file, the user should first determine whether it is a bare file
  153. or a labeled file.  This can be done by visual inspection (looking at the
  154. first 20 bytes), or from memory (e.g. because all labeled files have a
  155. particular filetype, or are kept together in a certain directory).  Then:
  156.  
  157.   (a) If it is a bare file, use SET FILE TYPE LABELED if you want to send 
  158.       label information too.
  159.  
  160.   (b) If it is a labeled file, use SET FILE TYPE BINARY.
  161.  
  162. When receiving a file, use SET FILE TYPE LABELED if you want labels in the
  163. incoming file to be interpreted and applied, and:
  164.  
  165.  (a) The other Kermit is sending a bare file from a like system using SET 
  166.      FILE TYPE LABELED, or:
  167.  
  168.  (b) The other Kermit is sending a labeled file, of the receiving system's
  169.      system type, from any kind of system, without SET FILE TYPE LABELED.
  170.  
  171. The receiving Kermit program that has been given a SET FILE TYPE LABELED
  172. command must inspect the incoming data.  The first 30-36 bytes of the first
  173. packet contain the BANNER, IDLEN, SYSID, and the first LBLEN, and LABEL (which
  174. should be "04VERS").  If these five items are in correct format, and the SYSID
  175. matches the program's own, then the program will accept the file in labeled
  176. mode.  Otherwise, it will treat it as a binary file and store all the data,
  177. including BANNER, SYSID, LABELs, VALUEs, and all length fields.
  178.  
  179. If a receiving Kermit program has accepted the file in labeled mode, but then
  180. encounters an unknown label or other inconsistency in the labeled file format,
  181. it must interrupt the file transfer (by putting an X in the data field of the
  182. first available ACK) and discard the file.  This is because it cannot be
  183. expected to back up and undo whatever label interpretation it has already done.
  184.  
  185. It is also conceivable that "similar" systems -- such as the DEC operating
  186. systems VMS and RSX-11 -- might be able to honor each other's labels.  This
  187. eventuality should be allowed for, possibly with SET commands.
  188.  
  189. At the discretion of the programmer, a command such as SET FILE
  190. LABEL-DETECTION { AUTOMATIC, MANUAL } could be installed.  If so, the default
  191. must be MANUAL, that is, processing of labeled files occurs only if the user
  192. asks for it explicitly.  For an arriving file, AUTOMATIC mode would detect the
  193. BANNER, SYSID, and first LABEL and go into action as if the user had SET FILE
  194. TYPE LABELED.  When sending a file, the program would avoid adding surrounding
  195. label information if the user had already SET FILE TYPE LABELED.  This sort of
  196. thing is obviously dangerous, and users should be cautioned about it.
  197.  
  198. EXAMPLE
  199.  
  200. A hypothetical example for VMS (ignore the indentation and line breaks);
  201. the length fields are marked with L's:
  202.  
  203.                       LL  LL    LLLLLLLL     LL   LLLLLLLL
  204.   KERMIT LABELED FILE:02D704VERS000000055.3-103FAB00000512<512 bytes here>
  205.   03ACL00000723<723 bytes here>02DATA00000000<file's contents here>
  206.   LL   LLLLLLLL                LL    LLLLLLLL
  207.  
  208. Note: FAB and ACL are not necessarily real labels.
  209.  
  210. POSTPROCESSING
  211.  
  212. Separate programs should be provided to translate a labeled file into a real
  213. file, to be used in case the user forgot to SET FILE TYPE LABELED, or the file
  214. was deposited by means other than Kermit.  Such a program might have two
  215. options (or come in two forms): interpret the labels, and simply strip the
  216. labels.
  217.  
  218. (End)
  219.  
  220. You can find the VMS implementation in the file ckvfio.c in the Kermit
  221. archives.
  222.  
  223. - Frank
  224.  
  225.