ESS-CODE
E S S - C o d e 6 . 1
"""""""""""""""""""""""""
Copyright 1993, 1994, Michel Forget
Electric Storm Software
* * * I M P O R T A N T N O T I C E ! * * *
As a direct result of the growing investment of time and effort
placed into this application, ESS-Code is now a SHAREWARE product.
Users who register ESS-Code will receive a disk with the latest
version of ESS-Code (optimized), and a registered (optimized,
personalized) version of MasterBrowse (which also includes MasterPrint,
AutoDate, ACC-Pad, ShadowTerm II, and a coupon for a free catalog from
Suzy B's Software and a $3 credit toward the purchase of a disk from
the Suzy B's Software collection).
The continued development of ESS-Code depends _solely_ on user
contributions; if no such contributions are received, this
application will not be developed further.
For more information on registration, please read the "Registration"
section of this manual.
* * * * * * * * * * * * * * * * * * * * * * *
*-----------------------------------------------------------------*
| For information about the distribution of ESS-Code, please read |
| the section of this manual entitled "Distribution". |
*-----------------------------------------------------------------*
- CONTENTS -
I. INTRODUCTION
II. REGISTRATION
III. INSTALLING & USING ESS-CODE
IV. OPTIONS
A. Confirm Termination
B. Confirm Overwrites
C. Progress Displays
D. Unix Line Termination
E. TOS 1.4 File Selector
F. AutoSave Options
G. Use Fast SHIP Encoding
I. Include Paths
J. Specify Segments
K. Select Target
L. Segmentation
V. ACKNOWLEDGEMENTS
VI. DISCLAIMER
VII. DISTRIBUTION
VIII. CONTACTING THE AUTHOR
IX. THE ART OF BINARY <-> ASCII CONVERSION
X. CLOSING
I. INTRODUCTION
-=-=-=-=-=-=-=-
This program was designed to allow computer users to exchange binary
files over computer networks that do not support the transmission of
binary data. This can be done by converting the binary file to an ASCII
file, then converting the ASCII file back to its original binary state
after transmission.
There are four popular methods of conversion; UUEncoding/UUDecoding,
MIME-Encoding/MIME-Decoding, BTOA-Encoding/BTOA-Decoding, and SHIP-Encoding/
SHIP-Decoding. Since each of these conversion methods is an accepted
standard, there are a wide variety of encoding/decoding utilities for
every computer platform.
If output size is not an issue, the best conversion method to use is
UUEncoding/UUDecoding. This method is fast, reliable, and allows large
files to be segmented (and re-assembled) automatically.
If output size is an issue, however, the best conversion method to use
is MIME-Encoding/MIME-Decoding. This conversion method is not very fast,
but produces very compact output. It is rapidly replacing UUEncoding/
UUDecoding as the conversion method of choice, because it is has all of
the power of UUEncoding/UUDecoding and is nearly as widely supported.
Why should you use ESS-Code instead of one of the many other utilities
currently available?
Here are six good reasons:
1) SPEED - ESS-Code is much faster than other coding programs
that I have tested. In some cases, the difference is as much
as 469%! (Yes, that is correct.)
2) APPEARANCE - ESS-Code uses GEM! This means that you are given
a nicely formatted progress display (which shows the output file,
the input file, the currently active parameters, the source and
destination path, and a "percentage" meter in both numeric and
graphic form that indicates how much of the current file
has been processed. Since it is a GEM program, you can access
your desk accessories at any time, and set your options using
pull-down menus. ESS-Code uses NON-MODAL window dialogs and
alert boxes, so you can use your accessories or applications
(or even other ESS-Code dialog boxes) while inside a dialog box!
With MultiTOS, all dialog boxes (and alert boxes) can be
iconified.
3) FLEXABILITY - ESS-Code supports UUEncoding, UUDecoding,
BTOA-Encoding, BTOA-Decoding, SHIP-Encoding, SHIP-Decoding,
MIME-Encoding, MIME-Decoding, RAW-Splitting, and RAW-Concatening
of files. All of your file conversion needs are handled by one
program.
4) COMPATIBILITY - While conversion methods have remained roughly
the same, the Atari ST has not. ESS-Code has support for the
ARGV command line standard that Atari has adopted, as well as
support for the default command line standard used by older ST
systems.
5) OPTIONS - ESS-Code has more options than any other encoding or
decoding program available for the Atari.
6) HELP - Using the ST-Guide HyperText accessory, the entire
ESS-Code manual is available at any time from within
ESS-Code.
II. REGISTRATION
-=-=-=-=-=-=-=-=
OR: Why should I send this person money if I have the program already?
I would like to start this section of the manual by saying I am not
going to try to make you feel guilty; I would like to say it, but I will
not.
Like many authors of Shareware products, I have come to learn that
very few people register Shareware software. I do not know why; I can
only guess the reasons. The reasons do not really matter, though,
because the end result is always the same. On GEnie, MasterBrowse is
regularly downloaded by over 150 users. The numbers are much the same
for CompuServe and Delphi, and much higher on the Internet. Only 23
people have registered MasterBrowse, though.
I hope that more people elect to register ESS-Code. There are many
incentives to do so, but the largest incentive of all is this; there
will be no further development of this product unless some registrations
are received. I cannot say it any more clearly; I love to write software
for this system, but I cannot continue to do it without your support.
Users who register ESS-Code will receive an optimized version of
ESS-Code, a registered (and optimized) version of the popular text
file viewer MasterBrowse, a series of utilities (AutoDate, ACC-Pad,
MasterPrint, ShadowTerm II, and a coupon for a free catalog from
Suzy B's Software.
To register ESS-Code, send $15 (Canadian/US) to:
Michel Forget
12209 Dovercourt Avenue
Edmonton, Alberta
CANADA
T5L 4E1
If you do not live in North America (and you are writing to this
address instead of the address for users in the United Kingdom), please
send an international money order or the equivalent of $15 in your own
currency. Please do not send a personal cheque unless you live in North
America.
If you live in the United Kingdom, you can send 14 UKPounds (cheque
or money order) to Denesh Bhabuta:
ESS (c/o Denesh Bhabuta)
203 Parr Lane
Unsworth
Bury
Lancashire
BL9 8JW
III. INSTALLING & USING ESS-CODE
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
ESS-Code is a very versatile application, so there are several ways that
it can be invoked:
1) The simplest way to use ESS-Code is to execute ESSCODE.PRG and then
select the options you would like to use and initiate an encoding
or decoding operation.
2) If you have a hard disk, you may want to install ESSCODE.PRG an an
application. For best results, please ensure that the current
directory is set to "top window". Since TOS 1.2 does not handle
installed applications correctly, it may be neccessary to edit
the DESKTOP.INF file (add the full pathname of ESS-Code to the
line containing the filename ESSCODE.PRG).
3) ESS-Code can also be installed on the desktop as an icon; this
allows an entire group of files to be processed in a single
pass. Simply drag the desired files to the ESS-Code icon and
release the mouse button. ESS-Code will _automatically_ decide
which files should be encoded and which files should be decoded.
Depending on your preferences, ESS-Code will also decide which
conversion method to use or ask which conversion method should be
used.
4) ESS-Code can easily be invoked from a command line interpreter;
commands are not case-sensitive, but must be in the correct order
and contain the correct number of arguments. The following
commands are available:
-uue source destination_file
-uud source destination_file
-btoa source destination_file
-atob source destination_file
-ship source destination_file
-unship destination_file source [source ...]
-mime source destination_file
-unmime source destination_file
To set the segment size (which does not change very often) define
the environment variable "SEGSIZE". It should contain the maximum
number of kilobytes in a segment.
IV. OPTIONS
-=-=-=-=-=-
There are several options that can be set to control how ESS-Code
behaves:
A. Confirm Termination - This option determines whether or not
ESS-Code will ask for confirmation before terminating.
B. Confirm Overwrites - This option determines how ESS-Code will
behave if an existing file will be overwritten by an encoding
or decoding operation; if it is enabled, you will be given the
option of aborting the operation.
C. Progress Displays - This option determines whether or not ESS-Code
will show progress displays. Other than saving screen space, there
is no real advantage to turning progress displays off.
D. Unix Line Termination - This option will force ESS-Code to terminate
ASCII lines with a linefeed (Unix) instead of a linefeed/carriage
return (IBM/Atari).
E. TOS 1.4 File Selector - If this option is enabled, ESS-Code will
display prompts in the file selector.
F. AutoSave Options - If this option is activated, ESS-Code will save
your options when you exit the program.
G. Use Fast SHIP Encoding - If this option is enabled, ESS-Code will
use an alternate (faster but less efficient) conversion method
during SHIP-Encoding operations.
H. Include Paths - If this option is used, ESS-Code will include the
complete path of the source file in the encoded data. Thus, when
decoding, the file will be written to the same path. This option
should usually not be used, since it is unlikely that the system
that will receive the file will have the same directory structure
as your system.
I. Specify Segments - This option (when selected) causes ESS-Code to
prompt the user for the name and location (using the file selector)
of each piece of the file to be UUDecoded. This option will mainly
be of interest to users of Hermes UUCP or UPoint, who will no longer
have to copy messages out of their news directory, and then waste
time renaming the segments.
J. Select Target - This option allows you to choose the destination
path for any encoding/decoding operation. This option is mainly
for floppy users who want to decode to a ramdisk or a second floppy
disk and CLI users (who must specify a destination on the command
line).
For those who would like the file selector to always be opened to
the same path (which is especially useful for people who always
extract files to the same place) the environment variable
"ESS_DPATH" can be defined; it should contain a "\" terminated
pathname.
K. Default Conversion Method - This option determines which conversion
method ESS-Code will use when processing a group of files (such as
when the user selects "Process Batch" or when ESS-Code is passed
files on the command line).
L. Segmentation - An encoded file can be divided into pieces, which
will be automatically joined together when being decoded. This
makes it easier for network mailing software to process the
encoded file. You can choose one of the preset sizes, or set your
own. (Unless you are sure it will work, you should not use
segment sizes larger than 50K).
The segment size can also be set through the environment, which is
especially useful for CLI users. To do this, defined the environment
variable "SEGSIZE", and set it to the maximum number of kilobytes
of data a segment can contain.
V. ACKNOWLEDGEMENTS
-=-=-=-=-=-=-=-=-=-
There are many people who are deserving of recognition for their aid
in creating this application:
First, I would like to thank Steve Yelvington, the author of UUCODER
1.0 (the program on which ESS-Code was based).
Another person deserving of recognition is Christian Grunenberg, the
author of the excellent EnhancedGEM Library which is the core of ESS-Code.
I would also like to thank Ofir Gal, Traci J. Ingram, Gerhard Hoelscher,
Carsten Friehe, the users of the MausNet, the users of the Internet, Mark
Adler, Steve Wells, Michael Mies, John G. Myers, and RSA Data Security
Incorporated.
VI. DISCLAIMER
-=-=-=-=-=-=-=
ESS-Code does not come with any warranty, express or implied. If you
use ESS-Code, you do so at your own risk. Neither the author of ESS-Code
(Michel Forget) nor any other party will accept responsability for any
equipment damage, data loss, or other unforseen consequence of the use or
mis-use of ESS-Code.
VII. DISTRIBUTION
-=-=-=-=-=-=-=-=-
There are two limitations placed on the distribution of ESS-Code:
1) When distributed, ESS-Code must contain all files found in the
original archive.
2) ESS-Code may not be distributed on the cover disk of any magazine
without the express written permission of the author. This
limitation does not apply to electronic (or non-profit)
magazines.
VIII. CONTACTING THE AUTHOR
-=-=-=-=-=-=-=-=-=-=-=-=-=-
If you would like to contact me with bug reports, suggestions, or
comments, you can do so through the following addresses (in order of
personal preference):
Internet: mforget@elfhaven.ersys.edmonton.ab.ca
ess@tibalt.supernet.ab.ca
Mail: Michel Forget
12209 Dovercourt Avenue
Edmonton, Alberta
CANADA
T5L 4E1
IX. THE ART OF BINARY <-> ASCII CONVERSION
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
ESS-Code is an extremely flexible application; this section of the
manual discusses (in detail) each of the four conversion methods supported
by ESS-Code, and compares them.
UUEncode/UUDecode
-----------------
SYNOPSIS -- Speed: Very Fast
Expansion: Poor (25%-30%)
Segmentation: Yes
Reconstruction: Automatic
This method of conversion is one of the first to gain popularity,
and is thus one of the most widely accepted/used conversion methods to
date. It is supported on every computer platform, and provides reasonably
good error checking. It is very fast, but not very efficient. The main
advantages of using this conversion method are the speed, the ability to
break up the output generated into small segments, and the ability to
automatically reconstruct the segmented output. The main (perhaps only)
disadvantage of using this conversion method is that it generates output
that is 25% (or more) larger than the original binary information.
BTOA-Encode/BTOA-Decode
-----------------------
SYNOPSIS -- Speed: Slow
Expansion: Good (20%-25%)
Segmentation: No
Reconstruction: Manual
While this method of conversion is popular, it is not as widely
used/accepted as UUEncode/UUDecode. It is vastly slower than UUEncode/
UUDecode, but it generates more compact output. The main advantage of
using this conversion method is that it provides slightly better error
checking that UUEncode/UUDecode. There are numerous disadvantages, though,
such as the lack of automatic segmentation or reconstruction.
SHIP-Encode/SHIP-Decode
-----------------------
SYNOPSIS -- Speed: Average
Expansion: Good (20%-25%)
Segmentation: Yes
Reconstruction: Semi-Automatic
While this conversion method is not as widely accepted/used as any of
the other conversion methods, it is used extensively on HP-UNIX platforms.
It is faster than BTOA-Encode/BTOA-Decode, and offers a nearly identical
expansion rate, but has very light error checking. It can create segmented
output, and has semi-automaic reconstruction of segmented output. There
are two variations of this conversion method; the 'Fast' conversion
algorithm is somewhat faster than the default conversion algorithm, but
(oddly) has a nearly identical expansion rate.
MIME-Encode/MIME-Decode
-----------------------
SYNOPSIS -- Speed: Fast
Expansion: Average (20%-30%)
Segmentation: Yes
Reconstruction: Automatic
This conversion method is rapidly becoming more popular than any
other conversion method to date. It is fast, but has a low expansion
rate. This conversion method, like UUEncode/UUDecode, has very good
error checking. It can generate segmented output, and reconstruct
that output with no user intervention. One of the main advantages to
using this conversion method is that it is supported on nearly every
computer platform; UNIX, Macintosh, IBM, Amiga, Atari, and others.
The Exact Figures
-----------------
Conversion Utility: ESS-Code 6.0 (Shareware)
Electric Storm Software
Archive #1: COMA_210.ZIP
Orginal UUE BTOA SHIP MIME
--------------------------------------------------------
Size | 256,695 | 355,276 | 321,079 | 321,422 | 343,520 |
Time | MM.SS.XX | 00.28.57 | 02.00.24 | 01.28.50 | 00.52.38 |
--------------------------------------------------------
Archive #2: EGEMSOZX.LZH
Orginal UUE BTOA SHIP MIME
--------------------------------------------------------
Size | 166,715 | 233,505 | 211,131 | 211,235 | 225,937 |
Time | MM.SS.XX | 00.20.55 | 01.20.59 | 00.59.41 | 00.36.45 |
--------------------------------------------------------
Archive #3: LPR_UTL3.ZOO
Orginal UUE BTOA SHIP MIME
--------------------------------------------------------
Size | 117,911 | 165,181 | 149,080 | 149,412 | 159,961 |
Time | MM.SS.XX | 00.15.11 | 00.58.59 | 00.43.22 | 00.26.52 |
--------------------------------------------------------
Conclusions
-----------
Each of the four conversion methods is acceptable, but your specific
situation may indicate which of the four conversion methods is best for
you. The average user will probably prefer to use UUEncode/UUDecode, since
it is the fastest of the four conversion methods, and offers automatic
segmentation and automatic reconstruction of segmented output. People who
use UNIX often should probably consider using MIME-Encoding; it is very
common on UNIX systems, and is rapidly replacing all other conversion
methods. If you are paying for data transfer by the kilobyte, though,
SHIP-Encoding is probably the best solution for you. It creates extremely
compact output, and offers automatic segmentation and semi-automatic
reconstruction of segmented output. The error checking is light, but this
is usually not a problem.
X. CLOSING
-=-=-=-=-=
I hope that you are pleased with ESS-Code, and decide to continue using
it after you have experimented with it.
I have invested more than a year of my life in the creation of this
program, though, so I _also_ hope that you will seriously consider sending
in the requested donation.
If the Atari is going to remain a viable system in the future, it needs
more Shareware, Donation-Ware, Freeware, and Public Domain applications to
compensate for the lack of commercial products available. In order to make
programming for the Atari viable, though, the Atari community needs to show
support for the programmers of these applications.
-Michel Forget
Electric Storm Software
June 29, 1994
Back to Packer/Depacker