home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / rexx / rxship24 / rexxship.doc next >
Encoding:
Text File  |  1993-04-11  |  10.3 KB  |  230 lines
  1. REXXShip  Version 2.4
  2. by Timothy F. Sipples
  3.  
  4. Copyright 1992, 1993 by Timothy F. Sipples.  All rights reserved.
  5. This utility may be freely distributed.  No guarantees or
  6. warranties of any kind are made.
  7.  
  8. The author welcomes comments but cannot promise to respond to them.
  9. Comments may be sent via electronic mail through the Internet
  10. to sip1@ellis.uchicago.edu, or by regular post to Timothy F. Sipples,
  11. Center for Population Economics, 1101 East 58th Street, Chicago,
  12. IL, 60637, U.S.A.  Bug reports, especially, are appreciated.
  13.  
  14.  
  15. FILE LISTING
  16.  
  17. REXXSHIP.DOC   The document you are reading.
  18. REXXSHIP.EXE   REXXShip encoder utility.
  19. XXDECODE.C     Generic C source code for XXDECODE.
  20. XXDECODE.EXE   OS/2 1.x/2.x XXDECODE utility.
  21.  
  22.  
  23. INTRODUCTION
  24.  
  25. Many mail systems and online services do not provide a means for the
  26. transfer of binary files.  Only messages, in text form, are permitted.
  27. In order to transfer binary files several schemes have been developed
  28. to translate binary data into a stream of ASCII text.  Such schemes
  29. include BOO, UUEncoding, XXEncoding, BTOA, and ABE.
  30.  
  31. All these schemes depend upon whether the recipient has the necessary
  32. decoding software.  Beginners, especially, are not likely to have the
  33. tools necessary to decode such files.
  34.  
  35. REXXShip is intended to address that problem.  REXXShip encodes binary
  36. files in ASCII form, suitable for transmission over text only elec-
  37. tronic mail systems and other online services.  However, the decoder,
  38. a short REXX script, is built into every REXXShip encoded file.
  39. Since REXX comes as a part of IBM OS/2 2.x and 1.3, anyone running
  40. OS/2 (who has installed REXX support) can decode a REXXShip
  41. encoded file.  Quercus's Personal REXX for DOS (and OS/2) should
  42. also be able to decode REXXShip encoded files.
  43.  
  44.  
  45. SYSTEM REQUIREMENTS
  46.  
  47. REXXShip requires a REXX interpreter to run.  It has been tested with
  48. IBM OS/2 2.x's REXX interpreter, and the author's recommendation is to
  49. use REXXShip in that environment.  The encoded files that REXXShip
  50. produces should be decoded under a similar environment.  However,
  51. REXXShip was written to be as generic as possible, so use in other
  52. environments may be possible (at least with xxdecode; see below).
  53.  
  54. OS/2 2.x provides the option of not installing the REXX interpreter.
  55. If the Procedures Language/2 (REXX) interpreter has not been installed
  56. on an OS/2 2.x system it may be added using the Selective Install
  57. facility.  Selective Install is located in OS/2 System -> System
  58. Setup.
  59.  
  60. IBM has released patches to the OS/2 2.0 REXX interpreter.  These
  61. patches may be obtained from many BBSes and online services, including
  62. the IBM NSC BBS (tel. +1 404 835-6600) in Atlanta, Georgia, U.S.A.  The
  63. REXX patches are usually listed under the name REXX20.  These patches
  64. may be required for proper operation of REXXShip and for proper
  65. decoding of REXXShip encoded files.  The REXX patches are only
  66. required for IBM OS/2 2.0 CSD Level 02000 or earlier.  (To display the
  67. OS/2 CSD Level, type SYSLEVEL at any OS/2 command line prompt.)
  68.  
  69.  
  70. USAGE
  71.  
  72. To invoke REXXShip for encoding, simply type:
  73.  
  74. REXXShip source_file encoded_file
  75.  
  76. at the command line (assuming REXXShip.Exe is located in the current
  77. directory or in a directory specified by the PATH environment
  78. variable).  Invoking REXXShip without any parameters will provide
  79. instructions on usage.
  80.  
  81. To decode a REXXShip encoded file, first make sure the encoded
  82. file contains no extraneous parts (at the beginning).  The first line,
  83. starting at the first column, must contain a REXX comment such as:
  84.  
  85. /* REXXShip 2.4 encoded file. */
  86.  
  87. so that OS/2 understands that the encoded file is a REXX program.
  88. Also make sure the file is named using the .CMD extension.  For
  89. example, the encoded file can be saved with the name SAMPLE.CMD.
  90. Then, to decode the file, simply type:
  91.  
  92. SAMPLE
  93.  
  94. at any OS/2 command line, assuming SAMPLE.CMD is located in the
  95. current directory.  The decoded file will be placed in the current
  96. directory.  SAMPLE.CMD (or any other encoded file) may also be decoded
  97. by double clicking on the filename from an OS/2 2.x drive object.
  98.  
  99. Incidently, comments may be added at the top of any REXXShip encoded
  100. file (using any text editor).  The only requirement is that at least
  101. one comment (using /* ... */ syntax) appear at the top of a REXXShip
  102. encoded file.  The author recommends that the comment lines produced
  103. by REXXShip when encoding a file be left as they are, with additional
  104. comments added below, BEFORE THE SAY"Decoding..." LINE, if desired.
  105.  
  106.  
  107. APPLICATIONS
  108.  
  109. REXXShip is intended to be used in conjunction with an archiver/
  110. compressor utility.  Such utilities include LHA, Zoo, and Zip.  These
  111. utilities will store multiple files (including, if requested, full
  112. pathnames) in a single file (archive).  The files are compressed as
  113. they are stored, to take up less disk space (and, hence, to transmit
  114. more quickly over a communications link).  OS/2 versions of LHA and
  115. Info-ZIP's Zip even store extended attributes, and all three will
  116. preserve long filenames.  The single archive file can then be
  117. encoded with REXXShip for transmission over a text only communications
  118. link.
  119.  
  120. The archiver/compressor utility itself can be REXXShip encoded and
  121. sent (if the recipient does not have the necessary utility to extract
  122. files from archives).  There is no official REXXShip archiver/
  123. compressor, so it is up to the sender and recipient to coordinate
  124. their efforts.  Note that some archiver/compressor utilties can create
  125. self extracting archives themselves, so it is possible to create a
  126. completely self decoding, self extracting file with REXXShip and such
  127. a utility.
  128.  
  129. Why shouldn't REXXShip include compression and archiving features?
  130. Since the encoded REXXShip format is self extracting (self decoding),
  131. it is desirable to keep the REXX "wrapper" code as small as possible
  132. (to keep the overall size of REXXShip encoded files as small as
  133. possible).  Adding compression and archiving features would make
  134. REXXShip encoded files, if precompressed, much larger, paradoxically.
  135.  
  136. REXXShip encoded files are compatible with the xxdecode utility which
  137. is especially popular among systems belonging to the Usenet.  Compiled
  138. versions of xxdecode are available for many platforms, including OS/2.
  139. Thus, recipients have the flexibility of using a "standard" decoding
  140. utility (xxdecode) or passing a REXXShip encoded file through any
  141. REXX interpreter.  (The OS/2 1.x/2.x version of XXDECODE is included
  142. in this REXXShip package along with generic C source code.  This
  143. utility is the work of others.)
  144.  
  145.  
  146. SECURITY
  147.  
  148. Since REXXShip encoded files are interpreted when decoded (rather than
  149. executed as a binary like self extracting archive formats), it is
  150. easy to examine the wrapper code to determine whether any tampering
  151. has taken place.  Users concerned about tampering should make sure the
  152. decode wrapper does not contain any harmful statements (such as
  153. "DELETE").  And, of course, virus checking, relying on known
  154. sources, and other standard steps should be taken to avoid problems.
  155.  
  156. The fact that REXXShip is a convenient self extracting format that
  157. does not rely on complicated code -- the recipient can examine the
  158. wrapper visually and quickly for tampering -- should prevent the
  159. problems associated with binary self extracting formats.
  160.  
  161. Also, since REXXShip encoded files are xxdecode compatible, a known,
  162. safe copy of the xxdecode utility can be used in lieu of the self-
  163. decoding script.
  164.  
  165.  
  166. PLANNED ENHANCEMENTS
  167.  
  168. If anyone thinks that a uudecode-compatible option would be
  169. helpful, please let me know.
  170.  
  171.  
  172. LIMITATIONS
  173.  
  174. REXXShip does not encode a file's standard attributes (e.g. the
  175. archive bit), extended attributes, date stamp, or time stamp.
  176.  
  177. REXXShip is, to put it politely, slow when decoding.
  178.  
  179. REXXShip encoded files are slightly more than four thirds as large as
  180. their binary sources.  Some size penalty is to be expected, since the
  181. decoding wrapper requires some space and since only ASCII text can
  182. be used to represent the binary file.  REXXShip uses an encoding
  183. scheme identical to xxencode.  This scheme should survive most mail
  184. gateways, such as EBCIDIC to ASCII translators, although the REXX
  185. wrapper may be more sensitive to gateways.  If the REXX wrapper is
  186. garbled, xxdecode may still be used to decode the file received.
  187.  
  188. A 16-bit checksum is used to detect file corruption.  While this is
  189. more than xxencode provides, it is not ideal.  Still, it should catch
  190. many errors.
  191.  
  192.  
  193. VERSION HISTORY (Major Changes)
  194.  
  195. Version 1.0.  Initial release.
  196. Version 2.0.  Encoded file format changed from a simple hex scheme to
  197.               a XXEncode-like scheme.  Checksum moved to top of queue
  198.               with PUSH statement (no longer escaped, no longer hex).
  199. Version 2.1.  Encoded file format changed to xxdecode-compatible
  200.               scheme.  Lines processed using SOURCELINE function.
  201.               Encoding speed improved.  Checksum, not part of xx-
  202.               format, retained, while preserving xx-compatibility.
  203. Version 2.2.  Wrapper skips line that does not appear to be xx-
  204.               conforming (instead of aborting) so that concatenated
  205.               files with some interspersed garbage can still be
  206.               decoded.  Wrapper checks for 'end' instead of '+' to
  207.               find end of file.  Wrapper uses SIGL to locate start.
  208. Version 2.3.  The REXXShip encoder is now compiled Pascal for speed.
  209.               Opening and closing comment markers are now placed in the
  210.               encoded file to provide compatibility with Quercus's
  211.               Personal REXX (not tested).  EXIT added to end of error
  212.               line in REXX wrapper.
  213. Version 2.4.  Made many changes suggested by Richard Naff to improve
  214.               performance by an estimated 20%.  Nonconforming lines
  215.               are displayed during decoding.  Decoder lookup table
  216.               now conforms to EBCDIC norms.  "CUT HERE" line added
  217.               to top of encoded file.
  218.  
  219.  
  220. OTHER UTILITIES by Timothy F. Sipples
  221.  
  222. AddIcon (presently Version 1.1) attaches icon files to any other
  223. file(s).  Such files with custom icons are then more readily
  224. identifiable when using OS/2 2.0's drive objects.
  225.  
  226. The OS/2 Frequently Asked Questions (FAQ) List, published monthly,
  227. is available in both plain text and OS/2 INF formats.  The FAQ
  228. List answers the most commonly asked questions about OS/2.
  229.  
  230.