Whiteline: Alpha

home *** CD-ROM | disk | FTP | other *** search

/ Whiteline: Alpha / Whiteline Alpha.iso / tools / packer / esscode / esscode.txt < prev next >

Wrap

Text File | 1994-09-22 | 21.9 KB | 507 lines

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