OS/2 Shareware BBS: 18 REXX/18-REXX.zip/RXSHIP24.ZIP/REXXSHIP.DOC

Text File | 1993-04-11 | 11KB | 230 lines

REXXShip  Version 2.4
by Timothy F. Sipples

Copyright 1992, 1993 by Timothy F. Sipples.  All rights reserved.
This utility may be freely distributed.  No guarantees or
warranties of any kind are made.

The author welcomes comments but cannot promise to respond to them.
Comments may be sent via electronic mail through the Internet
to [e-mail], or by regular post to Timothy F. Sipples,
Center for Population Economics, 1101 East 58th Street, Chicago,
IL, 60637, U.S.A.  Bug reports, especially, are appreciated.


FILE LISTING

REXXSHIP.DOC   The document you are reading.
REXXSHIP.EXE   REXXShip encoder utility.
XXDECODE.C     Generic C source code for XXDECODE.
XXDECODE.EXE   OS/2 1.x/2.x XXDECODE utility.


INTRODUCTION

Many mail systems and online services do not provide a means for the
transfer of binary files.  Only messages, in text form, are permitted.
In order to transfer binary files several schemes have been developed
to translate binary data into a stream of ASCII text.  Such schemes
include BOO, UUEncoding, XXEncoding, BTOA, and ABE.

All these schemes depend upon whether the recipient has the necessary
decoding software.  Beginners, especially, are not likely to have the
tools necessary to decode such files.

REXXShip is intended to address that problem.  REXXShip encodes binary
files in ASCII form, suitable for transmission over text only elec-
tronic mail systems and other online services.  However, the decoder,
a short REXX script, is built into every REXXShip encoded file.
Since REXX comes as a part of IBM OS/2 2.x and 1.3, anyone running
OS/2 (who has installed REXX support) can decode a REXXShip
encoded file.  Quercus's Personal REXX for DOS (and OS/2) should
also be able to decode REXXShip encoded files.


SYSTEM REQUIREMENTS

REXXShip requires a REXX interpreter to run.  It has been tested with
IBM OS/2 2.x's REXX interpreter, and the author's recommendation is to
use REXXShip in that environment.  The encoded files that REXXShip
produces should be decoded under a similar environment.  However,
REXXShip was written to be as generic as possible, so use in other
environments may be possible (at least with xxdecode; see below).

OS/2 2.x provides the option of not installing the REXX interpreter.
If the Procedures Language/2 (REXX) interpreter has not been installed
on an OS/2 2.x system it may be added using the Selective Install
facility.  Selective Install is located in OS/2 System -> System
Setup.

IBM has released patches to the OS/2 2.0 REXX interpreter.  These
patches may be obtained from many BBSes and online services, including
the IBM NSC BBS (tel. [phone]) in Atlanta, Georgia, U.S.A.  The
REXX patches are usually listed under the name REXX20.  These patches
may be required for proper operation of REXXShip and for proper
decoding of REXXShip encoded files.  The REXX patches are only
required for IBM OS/2 2.0 CSD Level 02000 or earlier.  (To display the
OS/2 CSD Level, type SYSLEVEL at any OS/2 command line prompt.)


USAGE

To invoke REXXShip for encoding, simply type:

REXXShip source_file encoded_file

at the command line (assuming REXXShip.Exe is located in the current
directory or in a directory specified by the PATH environment
variable).  Invoking REXXShip without any parameters will provide
instructions on usage.

To decode a REXXShip encoded file, first make sure the encoded
file contains no extraneous parts (at the beginning).  The first line,
starting at the first column, must contain a REXX comment such as:

/* REXXShip 2.4 encoded file. */

so that OS/2 understands that the encoded file is a REXX program.
Also make sure the file is named using the .CMD extension.  For
example, the encoded file can be saved with the name SAMPLE.CMD.
Then, to decode the file, simply type:

SAMPLE

at any OS/2 command line, assuming SAMPLE.CMD is located in the
current directory.  The decoded file will be placed in the current
directory.  SAMPLE.CMD (or any other encoded file) may also be decoded
by double clicking on the filename from an OS/2 2.x drive object.

Incidently, comments may be added at the top of any REXXShip encoded
file (using any text editor).  The only requirement is that at least
one comment (using /* ... */ syntax) appear at the top of a REXXShip
encoded file.  The author recommends that the comment lines produced
by REXXShip when encoding a file be left as they are, with additional
comments added below, BEFORE THE SAY"Decoding..." LINE, if desired.


APPLICATIONS

REXXShip is intended to be used in conjunction with an archiver/
compressor utility.  Such utilities include LHA, Zoo, and Zip.  These
utilities will store multiple files (including, if requested, full
pathnames) in a single file (archive).  The files are compressed as
they are stored, to take up less disk space (and, hence, to transmit
more quickly over a communications link).  OS/2 versions of LHA and
Info-ZIP's Zip even store extended attributes, and all three will
preserve long filenames.  The single archive file can then be
encoded with REXXShip for transmission over a text only communications
link.

The archiver/compressor utility itself can be REXXShip encoded and
sent (if the recipient does not have the necessary utility to extract
files from archives).  There is no official REXXShip archiver/
compressor, so it is up to the sender and recipient to coordinate
their efforts.  Note that some archiver/compressor utilties can create
self extracting archives themselves, so it is possible to create a
completely self decoding, self extracting file with REXXShip and such
a utility.

Why shouldn't REXXShip include compression and archiving features?
Since the encoded REXXShip format is self extracting (self decoding),
it is desirable to keep the REXX "wrapper" code as small as possible
(to keep the overall size of REXXShip encoded files as small as
possible).  Adding compression and archiving features would make
REXXShip encoded files, if precompressed, much larger, paradoxically.

REXXShip encoded files are compatible with the xxdecode utility which
is especially popular among systems belonging to the Usenet.  Compiled
versions of xxdecode are available for many platforms, including OS/2.
Thus, recipients have the flexibility of using a "standard" decoding
utility (xxdecode) or passing a REXXShip encoded file through any
REXX interpreter.  (The OS/2 1.x/2.x version of XXDECODE is included
in this REXXShip package along with generic C source code.  This
utility is the work of others.)


SECURITY

Since REXXShip encoded files are interpreted when decoded (rather than
executed as a binary like self extracting archive formats), it is
easy to examine the wrapper code to determine whether any tampering
has taken place.  Users concerned about tampering should make sure the
decode wrapper does not contain any harmful statements (such as
"DELETE").  And, of course, virus checking, relying on known
sources, and other standard steps should be taken to avoid problems.

The fact that REXXShip is a convenient self extracting format that
does not rely on complicated code -- the recipient can examine the
wrapper visually and quickly for tampering -- should prevent the
problems associated with binary self extracting formats.

Also, since REXXShip encoded files are xxdecode compatible, a known,
safe copy of the xxdecode utility can be used in lieu of the self-
decoding script.


PLANNED ENHANCEMENTS

If anyone thinks that a uudecode-compatible option would be
helpful, please let me know.


LIMITATIONS

REXXShip does not encode a file's standard attributes (e.g. the
archive bit), extended attributes, date stamp, or time stamp.

REXXShip is, to put it politely, slow when decoding.

REXXShip encoded files are slightly more than four thirds as large as
their binary sources.  Some size penalty is to be expected, since the
decoding wrapper requires some space and since only ASCII text can
be used to represent the binary file.  REXXShip uses an encoding
scheme identical to xxencode.  This scheme should survive most mail
gateways, such as EBCIDIC to ASCII translators, although the REXX
wrapper may be more sensitive to gateways.  If the REXX wrapper is
garbled, xxdecode may still be used to decode the file received.

A 16-bit checksum is used to detect file corruption.  While this is
more than xxencode provides, it is not ideal.  Still, it should catch
many errors.


VERSION HISTORY (Major Changes)

Version 1.0.  Initial release.
Version 2.0.  Encoded file format changed from a simple hex scheme to
              a XXEncode-like scheme.  Checksum moved to top of queue
              with PUSH statement (no longer escaped, no longer hex).
Version 2.1.  Encoded file format changed to xxdecode-compatible
              scheme.  Lines processed using SOURCELINE function.
              Encoding speed improved.  Checksum, not part of xx-
              format, retained, while preserving xx-compatibility.
Version 2.2.  Wrapper skips line that does not appear to be xx-
              conforming (instead of aborting) so that concatenated
              files with some interspersed garbage can still be
              decoded.  Wrapper checks for 'end' instead of '+' to
              find end of file.  Wrapper uses SIGL to locate start.
Version 2.3.  The REXXShip encoder is now compiled Pascal for speed.
              Opening and closing comment markers are now placed in the
              encoded file to provide compatibility with Quercus's
              Personal REXX (not tested).  EXIT added to end of error
              line in REXX wrapper.
Version 2.4.  Made many changes suggested by Richard Naff to improve
              performance by an estimated 20%.  Nonconforming lines
              are displayed during decoding.  Decoder lookup table
              now conforms to EBCDIC norms.  "CUT HERE" line added
              to top of encoded file.


OTHER UTILITIES by Timothy F. Sipples

AddIcon (presently Version 1.1) attaches icon files to any other
file(s).  Such files with custom icons are then more readily
identifiable when using OS/2 2.0's drive objects.

The OS/2 Frequently Asked Questions (FAQ) List, published monthly,
is available in both plain text and OS/2 INF formats.  The FAQ
List answers the most commonly asked questions about OS/2.