home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 June / SIMTEL_0692.cdr / msdos / arc_lbr / mdcd10.arc / MDCD.DOC < prev    next >
Text File  |  1988-10-26  |  43KB  |  901 lines

  1.  
  2. MDCD Version 1.0 - 10/24/88 - File Compression and DeCompression Program
  3.  
  4.   This documentation is organized in the following order, under the
  5.   following headings:
  6.  
  7.       WHAT IS IT ?
  8.       WHAT ISN'T IT ?
  9.       WHY WAS IT WRITTEN ?
  10.       HOW CAN I USE IT ?
  11.       WHAT ARE THE RESTRICTIONS ?
  12.       CONCERN # 1
  13.       CONCERN # 2
  14.       CONCERN # 3
  15.       CONCERN # 4
  16.       MDCD GENERAL INFORMATION & FEATURES
  17.       MDCD COMPRESS OPTION
  18.       MDCD DECOMPRESS OPTIONS
  19.       MDCD LIST OPTIONS
  20.       MDCD FUTURE RELEASES
  21.       SOFTWARE DESCRIPTION
  22.       WRITING YOUR OWN PROGRAMS
  23.       THE COMPRESSION ALGORITHM
  24.       MISCELLANEOUS INFO
  25.       LIABILITY
  26.       DISCLAIMERS
  27.       ACKNOWLEDGEMENTS
  28.       WHERE CAN I GET THE MOST RECENT COPY OF THE SOFTWARE ?
  29.       WHERE CAN I CONTACT THE AUTHOR ?
  30.  
  31.  
  32. WHAT IS IT ?
  33.  
  34.               MDCD 1.0 is the first release of a file compression and
  35.               decompression program that compresses data using a 13 bit LZW
  36.               algorithm.  It was written in Turbo Pascal and requires the
  37.               Turbo Pascal 5.0 compiler.  Portions are written in 808x
  38.               assembler and require Turbo Assembler 1.0 or MASM 3.0+.
  39.  
  40.               It is not as fast as PKWARE products but compresses almost as
  41.               well.  It is significantly faster and compresses better than
  42.               the only version of ARC that I could find to compare it
  43.               against (version 5.20).
  44.  
  45.               It demonstrates some interesting differences when compared to
  46.               current file compression/decompression programs.  I will talk
  47.               about the differences in a bit, but first I want to talk
  48.               about what it is not...
  49.  
  50.  
  51. WHAT ISN'T IT ?
  52.  
  53.               It is not a replacement for PKWARE/SEA products.  It is not a
  54.               solution to the ARC wars that currently have (to mention a
  55.               few) BBS Sysops, telecommunications networks and PC users in
  56.               general in total disarray.  It is not meant to show off my
  57.               computer knowledge as I am terrible when it comes to math,
  58.               and have only a simplistic understanding of the compression
  59.               algorithm involved.
  60.  
  61.               You are probably asking yourself, "Then why was it written" ?
  62.               I shall explain...
  63.  
  64.  
  65. WHY WAS IT WRITTEN ?
  66.  
  67.               I write commercial PC software for a living.  This includes a
  68.               specialized communications program, a telephone call
  69.               accounting system and several clients that require low level
  70.               systems programming.  The communications program uses
  71.               compression in the process of preparing files for
  72.               transmission.  The call accounting system is rather large and
  73.               I need to reduce disk storage and increase reliability when
  74.               shipping and installing.  I also like to have an orderly
  75.               method of keeping track of various releases and revision
  76.               levels of this software.
  77.  
  78.               I did not want to pay an exorbitant fee to license
  79.               compression technology from a third party.  Not only is this
  80.               cost prohibitive for someone trying to make a simple living,
  81.               but it is nearly impossible to get
  82.               something that can be tailored to ones own needs.  You are
  83.               stuck with a program that more than likely requires more disk
  84.               space, or gobbles up more quantities of memory than you care
  85.               to relinquish.
  86.  
  87.               So, I wrote my own.  It is written for my needs.  It uses
  88.               minimal memory.  It requires no disk work area.  It allows me
  89.               to remember the exact path that a file was compressed from.
  90.               It lets me store comments about the file.  It lets me keep
  91.               duplicate file names in a compressed file, retaining their
  92.               real-time chronological order.  It lets me remember the
  93.               original file's date, time and size.  It allows me to retain
  94.               a file's original attributes so that if it is a hidden,
  95.               system, read only file before compression, it will be
  96.               likewise after.  It allows me to simply group files together
  97.               in a single area and doesn't waste time trying to compress
  98.               already compressed .ARC or .ZOO files.  It serves my exact
  99.               needs and is written for me, a commercial software author, to
  100.               facilitate control and distribution of software.
  101.  
  102.               I wrote it for one other express purpose.  I continually grow
  103.               in my programming abilities.  I have been programming
  104.               computers for over 20 years and can't think of any period in
  105.               my career where I wasn't constantly increasing my knowledge
  106.               and awareness of current computer technology.  This has
  107.               happened at a fairly logical pace for most of my programming
  108.               life...  Until I discovered the crazy world of
  109.               telecommunications/public domain/shareware/BBS'ing/networks in
  110.               the sky/etc./etc.
  111.  
  112.               This crazy world has increased my knowledge, solved my
  113.               day-to-day technical problems, provided my with one heck of a
  114.               lot of fun and exposed me to computer technology at a rate I
  115.               would never have believed possible.  I have learned from the
  116.               generosity of others sharing their knowledge, experience and
  117.               brilliance and I want to attempt to repay that in kind.
  118.  
  119.               "So", you ask yourself, "how can I use this software?"
  120.  
  121.  
  122. HOW CAN I USE IT ?
  123.  
  124.               You can use it in any way that it serves your needs, providing
  125.               you adhere to a couple of restrictions I will talk about in a
  126.               minute.  I am including all of the source code.  If you are a
  127.               shareware, or commercial software author, you could probably
  128.               use it in many of the ways I mentioned above.  Some ideas that
  129.               come to mind:
  130.  
  131.               A communications program compression of files prior to
  132.               transmission.  Graphics compression while saving to disk.
  133.               Word processor document compression.  Distributing products
  134.               in compressed format and reliably determining a successful
  135.               installation.  Personal file compression program.
  136.               Maintaining version/release control of software products,
  137.               word processing documents, or just about anything.  To
  138.               mention a few!
  139.  
  140.               "Hmmmmm, sounds like I could use this, but what ARE those
  141.               restrictions ?"
  142.  
  143.  
  144. WHAT ARE THE RESTRICTIONS ?
  145.  
  146.               I toyed with the idea of copyrighting this software.  I
  147.               wanted to somehow have a means to control the few
  148.               restrictions & requests that I had decided on.  But that
  149.               seemed kind of silly, and basically unenforceable.  I was
  150.               modifying a brilliant algorithm (which I do not understand),
  151.               written by someone else (who had placed the code in the
  152.               public domain) and adding some simple stuff to move some
  153.               files around and keep track of basic information.  And on top
  154.               of that I was releasing the source to the general public,
  155.               virtually no strings attached!  I figured that I would get
  156.               thrown out by any court trying to decide if my copyright was
  157.               enforceable, especially if the proprietary source code was
  158.               made available to all.  So...  NO COPYRIGHT.
  159.  
  160.               I have three restrictions.  All are unenforceable legally, one
  161.               is enforceable morally, the other two are enforceable by virtue
  162.               of the media in which this is distributed.
  163.  
  164.               Restriction 1:  If you use this code as part of a product that
  165.               you gain monetarily from, I will be considered a "registered"
  166.               user of that product, with all related privileges.  In other
  167.               words, you send me current releases of your product.  If you
  168.               have a BBS that supports your product and charge a related
  169.               fee, I will be able to use it.  If you have a quarterly
  170.               newsletter, I will receive a copy.  I consider this enforceable
  171.               morally as I find it difficult to believe that any shareware
  172.               or commercial organization would prohibit unauthorized use of
  173.               their own software and yet violate this principle in using
  174.               other's software against stated restrictions.  (is he naive,
  175.               you ask?)
  176.  
  177.               Restriction 2:  You may not use this code to create a product
  178.               that competes with existing compression programs, shareware or
  179.               otherwise.  I do not want to be part of, or contribute to, the
  180.               mass confusion that currently exists over conflicts between
  181.               SEA and PKWARE.  I will not delve into this issue in this
  182.               document, but please KNOW that I see RED every time I think of
  183.               the grief and chaos that this issue is causing a whole world
  184.               full of users.  This is somewhat enforceable in two ways.
  185.               Number 1, if you are discovered by the public in general, your
  186.               product will not be supported, and number 2, if I find out
  187.               about it, I will make it common knowledge on every BBS and
  188.               major network in this country.  And believe me, tenacity and
  189.               relentless are my two middle names.  (yup...  he's naive!)
  190.  
  191.               Restriction 3:  If you distribute this software, don't charge
  192.               for it.  Charges for postage & handling (that are in line with
  193.               currently prevailing rates for shareware & public domain
  194.               software) or connection and access charges to commercial
  195.               networks or pay BBS's are excluded from the "don't charge for
  196.               it" portion of this restriction.  Make sure that it is
  197.               distributed in the same form that you received it in.  Do not
  198.               remove or modify any of the files.  This is enforceable in the
  199.               same manner as restriction 2 discussed above.
  200.  
  201.               "Okay, I want to use it, and I agree to the restrictions,
  202.               ... BUT I have some concerns".
  203.  
  204.  
  205.  
  206. CONCERN # 1
  207.  
  208.               "I am concerned about the legality of using this software."
  209.  
  210.               If you have second thoughts about using this software in your
  211.               commercial or shareware products, and are worried about not
  212.               REALLY having my permission, write me a letter stating that
  213.               you would like express permission to use this software, and
  214.               state that you will adhere to the restrictions outlined above.
  215.               I will send you my permission on (what do they call that
  216.               stuff??  oh yeh..) paper giving you the authority to use the
  217.               programs in any way you see fit.
  218.  
  219.  
  220. CONCERN # 2
  221.  
  222.               "I'm not sure I'm up to modifying this compression stuff."
  223.  
  224.               If you're not sure you want to get into the complexities of
  225.               writing or adapting compression technology to your software
  226.               products, I will make myself available to you (after all, this
  227.               IS how I feed my rug rats!) on a consulting basis.  While
  228.               generating direct revenue was not a consideration for creating
  229.               this product, I would rather enjoy the task of adapting this
  230.               software in unique areas.
  231.  
  232.  
  233. CONCERN # 3
  234.  
  235.               "Does this stuff really work?"
  236.  
  237.               I have tested it as extensively as I can.  That means that the
  238.               first person to try it will probably find everything I missed,
  239.               and then some.  I have also had 5 other people putting it
  240.               through its paces.  So far, no problems.  I have included
  241.               extensive disk error checking.  Throughout the entire
  242.               development process, I did not once wipe out any of my disk
  243.               files, or create any cross-linked clusters, and most of the
  244.               disk I/O is done in assembler.  I attribute this to 1)
  245.               starting with an working public domain program, 2) extensive
  246.               disk error checking, 3) Turbo Pascal's extensive error
  247.               checking, and 4) extreme caution and care on my part.
  248.  
  249.  
  250. CONCERN # 4
  251.  
  252.               "I've heard about them VIRII.  Am I taking a chance?"
  253.  
  254.               All of the source code is included.  Look at it, recompile it
  255.               yourself, and test it in your own carefully created
  256.               environment.
  257.  
  258.  
  259. MDCD GENERAL INFORMATION & FEATURES
  260.  
  261.               MDCD has three basic functions.  It allows you to compress a
  262.               file or files, decompress a previously compressed file or
  263.               list the directory of files contained within a compressed
  264.               file.
  265.  
  266.               Typing MDCD with no parameters or entering an invalid command
  267.               will display a help screen.
  268.  
  269.               MCDC is a program that provides a fairly functional
  270.               compress/decompress program.  It was written to test and
  271.               exercise the core routine that does that actual
  272.               compression/decompression (MDCD1213.ASM).  The source code
  273.               provides excellent examples for writing your own compression
  274.               program or routines.
  275.  
  276.               Some of the features, and lack thereof are:
  277.  
  278.               - Uses 13 bit LZW compression.
  279.  
  280.               - Original file date, time, and attributes are preserved.
  281.  
  282.               - Compress file extensions default to .MD if not specified.
  283.  
  284.               - Files added to an existing Compress file are appended to
  285.                 the end of the file.
  286.  
  287.               - Because duplicate files are allowed, and because files are
  288.                 added in physical order, an inherent ability to keep a
  289.                 chronological backups of files is available.
  290.  
  291.               - File headers are added in the order that files are added to
  292.                 the Compress file.  Therefore Compress file directory lists
  293.                 will not be in alphabetical order as you are probably used
  294.                 to.  They will be in the same order that you added files to
  295.                 the Compress file.
  296.  
  297.               - No external disk work space is required for any functions.
  298.  
  299.               - The program is fairly small.  39k for Code, 1k for Date, 3k
  300.                 for Stack and 45k for heap for a total of 88k.  Using 12
  301.                 bit compression would reduce the program size by 20k
  302.                 requiring 68k total memory.
  303.  
  304.               - The complete drive:path\name is kept for every compressed
  305.                 file.
  306.  
  307.               - 122 bytes of overhead is incurred for each file stored in a
  308.                 compress file.  Most of this is for the original
  309.                 drive:\path\name.  I chose to do this on the first release
  310.                 because having this information available is much more
  311.                 valuable than the related disk space required.
  312.  
  313.               - If a file does not compress smaller than the original, it
  314.                 is stored as is, retaining its original size.
  315.  
  316.               - .ZOO and .ARC files are automatically recognized, and no
  317.                 attempt at compression is performed.  The file is stored as
  318.                 is.
  319.  
  320.               - Conventional DOS wildcards may be used when specifying
  321.                 files to be compressed.
  322.  
  323.               - MDCD will not inadvertently try and compress the file that
  324.                 is currently being output to.
  325.  
  326.               - MDCD will, at this time, only decompress an entire Compress
  327.                 file.
  328.  
  329.  
  330.  
  331.  
  332. MDCD COMPRESS OPTION
  333.  
  334.               This option allows you to compress a single or multiple
  335.               files.  You can compress to a new file, or existing file.
  336.               Additions are always made to the end of the file.  The
  337.               compress file may contain exact duplicate
  338.               drive:\path\filenames.  If you attempt to compress to an
  339.               existing file, a validity check is made prior to any physical
  340.               writing to the file.  If it is determined not to be a
  341.               compress file, you will be informed and the program will
  342.               terminate.  Three (3) parameters are required:
  343.  
  344.               Parameter 1:  This parameter always contains the option.  In
  345.               the case of compression it must be 'C'.
  346.  
  347.               Parameter 2:  File to be compressed.  This may contain a
  348.               complete drive:\path\ name in front of the file name.  If no
  349.               drive:  or path\ is specified, the currently directory will
  350.               be searched.  Valid DOS wild cards are allowed.
  351.  
  352.               Parameter 3:  File to contain the compressed input file.  If
  353.               pre-existing, it must be a valid compress file.  If not
  354.               found, it will be created.  It may contain a complete
  355.               drive:\path\name in front of the file name.  The drive:\path\
  356.               is verified for existence.  If no drive: or path\ is
  357.               specified, the currently directory will be used.  If no file
  358.               extension is specified, the extension of .MD will be
  359.               appended.  If you wish no file extension for the file, end
  360.               your file name with a period.  e.g.  [COMPFILE.].
  361.  
  362.  
  363. MDCD DECOMPRESS OPTIONS
  364.  
  365.               There are two different decompress options allowing the
  366.               decompression of all files in an existing compress file.
  367.               They are identical except that the 'D' option will pause and
  368.               prompt you if it encounters an existing file of the same name
  369.               as one it is about to decompress.  The 'R' option will
  370.               automatically 'R'eplace any files it decompresses, informing
  371.               you with a message, but no pause.
  372.  
  373.               If you attempt to decompress a nonexisting file, you will be
  374.               informed.  if you attempt to decompress an existing file, a
  375.               validity check is made.  If it is determined not to be a
  376.               compress file, you will be informed and the program will
  377.               terminate.  Two (2) or three (3) parameters may be specified:
  378.  
  379.               Parameter 1:  This parameter always contains the option.  In
  380.               the case of decompression, it must be 'D' or 'R'.  Specifying
  381.               'D' will cause a pause and prompt to occur if the program
  382.               attempts to decompress a file that currently exists.  You may
  383.               respond with 'Y'es to replace the file or any other key to
  384.               ignore the file and go on.  Specifying 'R' will automatically
  385.               replace any pre-existing files encountered.
  386.  
  387.               Parameter 2:  File to be decompressed.  This may contain a
  388.               complete drive:\path\ name in front of the file name.  If no
  389.               drive: or path\ is specified, the currently directory will
  390.               be searched.  If no file extension is specified, the
  391.               extension of .MD will be appended.  If you wish no file
  392.               extension for the file, end your file name with a period.
  393.               e.g.  [COMPFILE.].
  394.  
  395.               Parameter 3:  Drive:\path to contain the decompressed output
  396.               files.  This parameter may be left blank, in which case files
  397.               are decompressed to the current directory.  if a drive:\path\
  398.               is entered, it is verified for existence.  one slight problem
  399.               exists when specifying the path.  If you specify an output
  400.               drive:\path to decompress to and it is specifying other than
  401.               that root directory, you must leave off the trailing '\'.  In
  402.               other words, if you want to decompress to the root directory
  403.               of your C:  drive, enter c:\ - if you want to decompress to a
  404.               subdirectory off your root directory on your c:  drive, enter
  405.               C:\SUBDIR - do NOT enter c:\subdir\.  I will fix this in the
  406.               next release.
  407.  
  408.  
  409. MDCD LIST OPTIONS
  410.  
  411.  
  412.               There are two different list options.  they both allow you to
  413.               display a directory of all of the files in an existing
  414.               compress file.  They are identical except that the 'l' option
  415.               displays original file date and time information and the 'F'
  416.               option displays the original file drive:\path\ in its place.
  417.  
  418.               If you attempt to list a nonexisting file, you will be
  419.               informed.  if you attempt to list an existing file, a
  420.               validity check is made.  if it is determined not to be a
  421.               compress file, you will be informed and the program will
  422.               terminate.  Two (2) parameters are required:
  423.  
  424.               Parameter 1:  This parameter always contains the option.  In
  425.               the case of list, it must be 'l' or 'f'.  both options will
  426.               display a directory of all compressed files contained in a
  427.               compress file.  Specifying option 'l' will cause the original
  428.               file's date and time to be displayed.  specifying option 'F'
  429.               will cause the original file's drive:\path to be displayed
  430.               instead of the date/time.
  431.  
  432.               Parameter 2:  File to be listed.  this may contain a complete
  433.               drive:\path\ name in front of the file name.  If no drive:
  434.               or path\ is specified, the currently directory will be
  435.               searched.  If no file extension is specified, the extension
  436.               of .MD will be appended.  if you wish no file extension for
  437.               the file, end your file name with a period.  e.g.
  438.               [COMPFILE.].  Wildcards can not be currently used to specify
  439.               multiple compress files to be listed.  This will be addressed
  440.               in the next release.
  441.  
  442.               Output may be redirected with the > and >> redirection
  443.               symbols.
  444.  
  445.  
  446. Example of entering:  MD L LZ
  447.  
  448. Compressed File: LZ.MD
  449.  
  450.                ORIG    CMP    HDR  cmp  cmp  prg
  451.    FILE NAME   SIZE    SIZE   LEN  pct  typ  ver  crc    date      TIME
  452. -------------------------------------------------------------------------
  453.       LZ.TXT   3615    1965   122  45% lzw13 10  ecae  07-01-86  13:23:56
  454.   LZCOMP.ASM   7261    3703   122  48% lzw13 10  fc76  07-01-86  14:02:44
  455.   LZCOMP.EXE   3607     678   122  80% lzw13 10  a6ce  07-01-86  14:04:24
  456.   LZDCMP.ASM   6094    3152   122  47% lzw13 10  4c26  07-01-86  14:02:12
  457.   LZDCMP.EXE   3620     670   122  80% lzw13 10  8d01  07-01-86  14:04:18
  458.   MACROS.MLB   6422    2345   122  62% lzw13 10  45ca  06-30-86  14:12:34
  459.              ------  ------ -----  --
  460.               30619   12513   732  59%
  461.  
  462.  
  463.  
  464. Example of entering:  MD F LZ
  465.  
  466. Compressed File: LZ.MD
  467.  
  468.                ORIG    CMP    HDR  cmp  cmp  prg
  469.    FILE NAME   SIZE    SIZE   LEN  pct  typ  ver  crc  original pATH
  470. -------------------------------------------------------------------------
  471.       LZ.TXT   3615    1965   122  45% lzw13 10  ecae  j:\lzw\original\
  472.   LZCOMP.ASM   7261    3703   122  48% lzw13 10  fc76  j:\lzw\original\
  473.   LZCOMP.EXE   3607     678   122  80% lzw13 10  a6ce  j:\lzw\original\
  474.   LZDCMP.ASM   6094    3152   122  47% lzw13 10  4c26  j:\lzw\original\
  475.   LZDCMP.EXE   3620     670   122  80% lzw13 10  8d01  j:\lzw\original\
  476.   MACROS.MLB   6422    2345   122  62% lzw13 10  45ca  j:\lzw\original\
  477.              ------  ------ -----  --
  478.               30619   12513   732  59%
  479.  
  480.  
  481. MDCD FUTURE RELEASES
  482.  
  483.               MDCD will be an evolving product.  Items that are on my to do
  484.               list to be addressed are:
  485.  
  486.               - Ability to sort several ways when doing a compress file
  487.                 directory list.
  488.  
  489.               - Various length header records to allow a smaller header
  490.                 record without the drive:\path\, one to allow a file
  491.                 comment to be attached to each file and one to allow a file
  492.                 description to be attached to each file (variable length).
  493.  
  494.               - Ability to override file compression and force file(s) to
  495.                 be stored directly.
  496.  
  497.               - Ability to disable the saving/restoring of original file
  498.                 attributes.
  499.  
  500.               - Ability to compress and decompress an entire disk(ette), or
  501.                 sub-directory and all lower level sub-directories,
  502.                 maintaining original disk(ette) structure.
  503.  
  504.               - Ability to force decompression to the original
  505.                 drive:\path\.
  506.  
  507.               - Program to allow the creation of self-extracting compress
  508.                 files.
  509.  
  510.               - Ability to decompress individual files and selected file(s)
  511.                 that have duplicate names.
  512.  
  513.               - Fix the irritation when using append or similar TSR's where
  514.                 a file appears to already exist, but doesn't.
  515.  
  516.               - Allow wildcards to be used for decompressing and
  517.                 listing multiple Compress files.
  518.  
  519.               - Implement heuristic logic and user specified requests
  520.                 allowing the use of both 12 bit and 13 bit compression.
  521.  
  522.               - Change MDCD1213.ASM to allow simpler interface with Turbo C
  523.                 and various models.
  524.  
  525.  
  526. SOFTWARE DESCRIPTION
  527.  
  528.               The compressed file you received should contain the following
  529.               files:
  530.  
  531.                   LZ       MD     13245  10-26-88  12:52a
  532.                   MDCD     DOC    43168  10-26-88  12:55a
  533.                   MDCD     EXE    51107  10-26-88  12:52a
  534.                   MDCD     PAS    65020  10-26-88  12:52a
  535.                   MDCD1213 ASM    60995  10-26-88  12:52a
  536.                   MDCD1213 OBJ     3232  10-26-88  12:52a
  537.                   TESTC    PAS     7546  10-26-88  12:52a
  538.                   TESTD    PAS     7390  10-26-88  12:52a
  539.                   TIMING   DOC     7555  10-26-88  12:52a
  540.  
  541.  
  542.               A simple description of each file:
  543.  
  544.               LZ.MD       - Original .asm/.exe for lzcomp & lzdcmP.
  545.                               Compressed with MDCD.
  546.  
  547.                             To see a list of files:
  548.  
  549.                                 MDcd l lz       (show original date/time)
  550.                                 MDcd f lz       (show original path)
  551.  
  552.                             To decompress to current subdirectory:
  553.  
  554.                                 MDcd d lz
  555.  
  556.               MDCD.DOC     - Documentation and other information.
  557.  
  558.               MDCD.PAS     - Source for MDCD 1.0.
  559.  
  560.               MDCD.EXE     - Executable MDCD 1.0.
  561.  
  562.               MDCD1213.ASM - Source for the assembler compress &
  563.                              decompress functions.
  564.  
  565.               MDCD1213.OBJ - Linkable module for compress & decompress
  566.                              functions.
  567.  
  568.               TESTC.PAS    - Simple single file compression illustrating
  569.                              the use of MDCD1213.obj assembler module.
  570.  
  571.               TESTD.PAS    - Simple single file decompression illustrating
  572.                              the use of MDCD1213.obj assembler module.
  573.  
  574.               TIMING.DOC   - Timing/compression size comparison between
  575.                              MDCD 1.0, PKPAK/PKUNPAK 3.61, and ARC 5.20.
  576.  
  577.  
  578.  
  579. WRITING YOUR OWN PROGRAMS
  580.  
  581.               MDCD1213.ASM is the compression/decompression algorithm
  582.               routine.  It can be compiled with TASM 1.0 or MASM 3.0 and
  583.               up.  It creates MDCD1213.obj.  it has two routines which may
  584.               be called.  These routines are compressfile & decompress
  585.               file.  Each is a FAR assembler proc.  make sure you identify
  586.               these calls as FAR in your high level language.  They are
  587.               both implemented as high level language functions in that
  588.               they pass back a WORD/INT/DW value indicating the success of
  589.               the request.  They also pass back a RECORD/STRUCT/STRUCT that
  590.               contains either the compressed file crc and size, or the
  591.               decompressed file crc and size.  It is up to the caller to
  592.               determine if the crc is correct.  This assumes that the user
  593.               of this routine has implemented his/her own internal file
  594.               structure.
  595.  
  596.               To call CompressFile, or DecompressFile, you need to pass
  597.               several parameters on the stack.  The parameters are the same
  598.               for both functions however their meaning is a bit different
  599.               depending on which routine you are calling.  For a more
  600.               detailed description of the parameters, see the listing for
  601.               MDCD1213.ASM or look at TESTC.PAS, or TESTD.pas.  These
  602.               parameters are described below and are pushed onto the stack
  603.               in the order described:
  604.  
  605.               Parameter 1:  This is a valid dos file handle for the input
  606.               file.  The file must be currently opened under this handle.
  607.               For CompressFile, this is the individual file to be
  608.               compressed.  For DeCompressfile, this is the file that is to
  609.               be decompressed.
  610.  
  611.  
  612.               Parameter 2:  This is a valid dos file handle for the output
  613.               file.  The file must be currently opened under this handle.
  614.               For CompressFile, this is the compressed output file.  For
  615.               DeCompressFile, this is the name that you want to call the
  616.               file after it is decompressed.
  617.  
  618.  
  619.               Parameter 3:  This is the LONGINT/LONG/DD value that
  620.               specifies the byte offset within the input file that you want
  621.               to start decompressing at.  This is provided so that you may
  622.               include multiple files in a compressed file.  See MDCD.PAS
  623.               for an example.  MDCD1213.ASM specifies this parameter as two
  624.               word values, but to the caller, it is strictly a double word
  625.               long value.  If you are only compressing and compressing
  626.               single files, this value will always be zero (0).
  627.  
  628.  
  629.               Parameter 4:  This is a @POINTER/&POINTER/SEGMENT:OFFSET that
  630.               points to a RECORD/STRUCT/STRUCT defined in the callers
  631.               program.  MDCD1213.ASM specifies this parameter as two word
  632.               values, but to the high level language caller this is
  633.               strictly a single far pointer.  To an assembler programmer,
  634.               the first parameter is the segment and the second parameter
  635.               is the offset.  This area will receive return data from
  636.               CompressFile or DeCompressfile.  This record needs to contain
  637.               5 bytes allocated as a WORD/INT/DW and a LONGINT/LONG/DD.
  638.               For CompressFile, the compressed file's crc and size in bytes
  639.               is returned.  For Decompressfile, the decompressed file's CRC
  640.               and size in bytes is returned.  These structures should look
  641.               something like this, depending on your language:
  642.  
  643.                  {--------}                    /*-----*/
  644.                  { PASCAL }                    /*  c  */
  645.                  {--------}                    /*-----*/
  646.  
  647.                  Type
  648.                    ReturnRec = Record          struct returnrec {
  649.                      FileCrc  : Word;            int  filecrc;
  650.                      FileSize : Longint;         long filesize;
  651.                    end;                        } returnr;
  652.                  Var
  653.                    ReturnR : Returnrec;
  654.  
  655.                  ;-----------;
  656.                  ; ASSEMBLER ;
  657.                  ;-----------;
  658.  
  659.  
  660.                   returnr        struc
  661.                   filecrc   dw   ?
  662.                   filesize  dd   ?
  663.                   returnr        ends
  664.  
  665.               Parameter 5:  This is a WORD/INT/DW containing the segment
  666.               address of a contiguous area of memory used for storing the
  667.               temporary hash table.  the size of this area varies depending
  668.               on whether you are using 12 or 13 bit compression, and
  669.               depending on the routine being called:
  670.  
  671.                      CompressFile    12bit  20480 bytes
  672.                      CompressFile    13bit  40960 bytes
  673.                      DeCompressFile  12bit  12288 bytes
  674.                      DeCompressFile  13bit  24576 bytes
  675.  
  676.  
  677.               Parameter 6:  This is a value indicating the type of
  678.               compression or decompression to be performed.  This value
  679.               MUST be 12 for 12 bit or 13 for 13 bit.  The values are not
  680.               checked, and an incorrect value will more than likely lunch
  681.               your machine.
  682.  
  683.  
  684.               In the event of a severe error in the MDCD1213.OBJ module,
  685.               control will be passed back to the caller (after cleaning up
  686.               the stack) and a function return code of $ffff/0xffff/0ffffh
  687.               will be returned.  The SS & SP, registers and the number of
  688.               parameters on the stack are stored upon entry so that
  689.               MDCD1213.OBJ can unwind itself no matter what routine the
  690.               error occurs in and perform a far jump back to the caller.
  691.  
  692.               For a simple example of using MDCD1213.OBJ see the included
  693.               files TESTC.PAS and TESTD.PAS.  TESTC.PAS allows you to
  694.               compress a file by entering:
  695.  
  696.                   TESTC  [uncompressed_file_name]  [compressed_file_name]
  697.  
  698.               TESTD allows you to decompress a file by entering:
  699.  
  700.                   TESTD  [compressed_file_name]  [uncompressed_file_name]
  701.  
  702.               NOTE: MDCD1213.ASM needs to be changed to interface with
  703.               Tubro C.  It currently is model sensitive and the parameters
  704.               would have to be passed backwards, or with pascal calling
  705.               conventions.  The segment names would have to also agree to
  706.               Turbo C conventions.
  707.  
  708.  
  709.  
  710. THE COMPRESSION ALGORITHM
  711.  
  712.               The compression algorithm is contained in MDCD1213.ASM.  It is
  713.               an extensively modified version of Tom Pfau's LZCOMP & LZDCMP
  714.               programs written in 808x assembler.  It provides for 12 bit
  715.               and 13 bit LZW compression.  Tom's original programs are
  716.               contained in this download.
  717.  
  718.               Tom's original source implemented the Lempel-Ziv-Welch 12 bit
  719.               compression with non-repeat packing.  The initial size of the
  720.               code started at 9 bits and proceeded to a maximum code size
  721.               of 12 bits.  Once the number of codes exceeded the current
  722.               code size, the number of bits was increased.  When the table
  723.               filled (4096 entries), a clear code was transmitted for the
  724.               decompression routine and the table re-initialized, starting
  725.               over at 9 bits.  The maximum of 12 bits allowed 4096 codes.
  726.               This algorithm is referred to as "Crunched" (note the UPPER
  727.               case 'C') in several compression programs.
  728.  
  729.               I modified the code to also allow for a maximum of 13 bits, or
  730.               8192 codes.  Other than that, it is identical to 12 bit
  731.               compression.  This algorithm is referred to as "Squashed" in
  732.               several compression programs.
  733.  
  734.               The original source of the algorithm is from the article "A
  735.               Technique for High Performance Data Compression" by Terry A.
  736.               Welch which appeared in IEEE Computer Volume 17, Number 6
  737.               (June 1984), pp 8-19.
  738.  
  739.  
  740. MISCELLANEOUS INFO
  741.  
  742.               MDCD1213.ASM uses the same 16 bit CRC used by communications
  743.               programs.
  744.  
  745.               If MDCD1213.ASM encounters a corrupted file during
  746.               decompression, or if invalid parameters are passed to it
  747.               (e.g. 12 bit when it was actually compressed using 13 bit),
  748.               your machine will probably go to lunch.  I will work on
  749.               trying to recognize these problems and finding a solution
  750.               that allows for a graceful exit.
  751.  
  752.               All of the included source code is HEAVILY commented... Maybe
  753.               even excessively.  This should help to make it more
  754.               understandable for anyone attempting to utilize it in their
  755.               own software tools.
  756.  
  757.               My tests of the 12 vs. 13 bit compression show that .EXE
  758.               files are an average of 1/2 of 1% smaller using 12 bit.
  759.               Most other files, especially text type files will be anywhere
  760.               from 4% - 7% larger.  This is why I chose to implement the 13
  761.               bit LZW compression option in MDCD.
  762.  
  763.  
  764.  
  765. LIABILITY
  766.  
  767.                                   LIMIT OF LIABILITY
  768.  
  769.               MDCD and its related source code is distributed as-is.  The
  770.               author disclaims all warranties, expressed or implied.  The
  771.               author will assume no liability for damages either from the
  772.               direct use of this product or as a consequence of the use of
  773.               this product.
  774.  
  775.  
  776.  
  777. DISCLAIMERS
  778.  
  779.               I have NOT looked at the source code for ARC, ZOO, DWC or any
  780.               other file compression programs other than the original
  781.               LZCOMP/LZDCMP assembler code, in the process of designing or
  782.               programming this software.  I have not used any existing ARC,
  783.               ZOO or DWC documentation to assist in the design of file
  784.               formats or file stowage methodologies.  I have purposefully
  785.               avoided any likeness to existing file compression programs
  786.               that I have knowledge of.  I have used the command line to
  787.               pass parameters to my program.  If THIS ever becomes a
  788.               "look-and-feel" issue, we are ALL in big trouble.
  789.  
  790.               I HAVE looked at hex dumps of both ARC and ZOO files to
  791.               determine how to identify them as such, so that I can avoid
  792.               the compression cycle and subsequently store the file.  This
  793.               is limited to finding a commonality that identifies these
  794.               files, and in both cases, is determined by the file
  795.               extension, along with the first character stored in the file.
  796.               This information was NOT garnered from ARC/ZOO file
  797.               documentation.
  798.  
  799.               This program will NOT extract files from ARC or ZOO files or
  800.               compress files into existing ARC or ZOO files.  It WILL store
  801.               an ARC or ZOO file into my .MD files as it will ALL files.
  802.  
  803.  
  804.  
  805. ACKNOWLEDGEMENTS
  806.  
  807.               We walk on the shoulders of others that came before us, or
  808.               however that old cliche goes..  I want to acknowledge several
  809.               people who have contributed directly or indirectly to this
  810.               program; most, if not all of whom have never heard of me.
  811.               Please forgive any omissions:
  812.  
  813.               Terry A. Welch, for the compression algorithm.
  814.  
  815.               Tom Pfau, for LZCOMP & LZDCMP.
  816.  
  817.               SEA & PKWARE (in a convoluted way), for creating the
  818.               atmosphere that "incited" me to write this thing.
  819.  
  820.               TurboPower Software, for the highest quality programming tools
  821.               and a refreshingly unique commitment to professionalism and
  822.               business practices.
  823.  
  824.               Jerry D.  Stuckle for the ASYNC.ASM tutorial, from which I
  825.               learned 808x assembly and the 8250.
  826.  
  827.               Phil "PIB" Burns for PIBTERM, from which I learned many
  828.               excellent Turbo Pascal techniques and overcame communications
  829.               hurdles.
  830.  
  831.               Ray Duncan for "Advanced MSDOS Programming", Microsoft Press,
  832.               without which, life would have been much more complex.
  833.  
  834.               Jim Kyle, Chip Rabinowitz, Ray Duncan & other contributors to
  835.               "The MS-DOS Encyclopedia", Microsoft Press, a formidable
  836.               reference to Ms. DOS and all her idiosyncracies.
  837.  
  838.               Neil Rubenking, for once helping me with a simple (to him),
  839.               yet insoluble (to me) problem, saving me untold hours.
  840.  
  841.               Philippe Kahn and Borland International (a deity??) for
  842.               consistently producing the highest quality software, and the
  843.               most reasonable prices, and providing support to boot!  (Thank
  844.               you CIS and BPROGA)
  845.  
  846.               And..  last, but not least (don't the wife and kids ALWAYS
  847.               come last ?, just ask'm!)
  848.  
  849.               Emilie, Matthew, Michelle and Melissa, for putting up with my
  850.               idiosyncracies, long hours, and my mistress:  the computer.
  851.  
  852.  
  853.  
  854. WHERE CAN I GET THE MOST RECENT COPY OF THE SOFTWARE ?
  855.  
  856.               The software will be evolving.  Current copies may be obtained
  857.               from:
  858.  
  859.               (preferred)
  860.  
  861.                  1. Amiga Techniques + PC Tech BBS - (GT POWER)
  862.                         (209) 298-8453 - 1200-9600 HST (24 hours)
  863.  
  864.                  2. Compuserve
  865.                      (BPROGA, IBMPRO, IBMAPP, PCMAGNET, CONSULT, PROGFORUM)
  866.  
  867.                  3. EXEC PC BBS
  868.  
  869.               (if you're desperate)
  870.  
  871.                  4. Send a self-addressed, postage paid mailer to me
  872.                     plus $1.00 for diskette.
  873.  
  874.                  5. Send $3.00 and I will provide the diskette and postage.
  875.                     Please don't request FED-EX or UPS.
  876.  
  877.  
  878.  
  879. WHERE CAN I CONTACT THE AUTHOR ?
  880.  
  881.               I may be contacted (in order of preference) at the locations
  882.               (electronic or otherwise) listed below:
  883.  
  884.                   Amiga Techniques + PC Tech BBS - (GT POWER)
  885.                       (209) 298-8453 - 1200-9600 HST (24 hours)
  886.                       Directly or through NET mail node 014/000.
  887.  
  888.                   CIS:   76676,1362
  889.                      (BPROGA, IBMPRO, IBMAPP, PCMAGNET, CONSULT, PROGFORUM)
  890.                      (BPROGB, IBMSYS, IBMCOM)
  891.  
  892.                   GENIE: MDAVENPORT
  893.  
  894.                   Mike Davenport
  895.                   Mike Davenport & Associates
  896.                   6751 N. Blackstone Ave. Suite 252
  897.                   Fresno CA  93710
  898.  
  899.                   Voice: (209) 298-8846
  900.  
  901.