ESS-CODE

From AtariForumWiki
Jump to navigation Jump to search
                           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