(Note: this file is called DISLITE.DOC in the distribution .ZIP and .tar.gz files)

                                    DISLITE

                       Executable file expander version 1.15



CONTENTS

         WARRANTY                           MESSAGES
         COPYING                            BUGS
         WHAT                               PRICE
         WHY                                THANKS
         HOW                                NEW
         LIMITS                             NOTE
         TECHS                              WHO



WARRANTY

   NONE! THIS PROGRAM COMES 'AS IS'. I CANNOT BE HELD RESPONSIBLE FOR
   ANY DAMAGE CAUSED BY THE USE OR MISUSE THIS PROGRAM. I CANNOT
   GUARANTEE THE FITNESS OF THIS PROGRAM FOR ANY PARTICULAR PURPOSE.
   IF THIS PROGRAM TURNS OUT TO BEHAVE UNEXPECTEDLY OR ERRONEOUSLY,
   THE USER IS RESPONSIBLE, AND I CANNOT BE FORCED TO SUPPLY THE USER
   WITH A FIX.
   
   So, now that I have the lawyers off my back (I hope), you can forget
   all that capsed crap above, and read the rest of the manual, in
   which I promise not to shout anymore.



COPYING

   You are free to distribute this program, provided that neither the
   program nor this document are changed, and the program and this
   document are kept together. Only a marginal fee may be asked for
   shipment and handling when distributing. You are not allowed to
   sell this program.

   Now that the black-market pirates are away too, we can get to business.



WHAT

   DISLITE expands all programs compressed by PKLITE to their
   original image. Expanding your files has many benefits over leaving
   them in their compressed state.

   Most important, the uncompressed image can be examined by other
   tools, such as virus scanners. A regular virus scanner can never
   detect a virus embedded in a compressed file (unless by executing
   and checking for suspicious actions), but on the uncompressed image
   a much faster pattern matching algorithm can be used.
   
   Then, PKLITE compressed programs can hardly be compressed any further
   using "regular" file compressors like UC2, ARJ. The uncompressed files
   however, usually compress quite well using these products, and normally
   the result of compressing the original file is better than that
   achieved when first compressing with PKLITE, and then with another
   compression utility. (Though not always)
   
   The same argument usually holds if you are using products like Stacker
   or SpeedStor to enlarge your disk, which could be considered as
   compression utilities on-the-fly. It would be silly to have a second,
   almost useless, compression slowing down your system.

   In a similar context can be mentioned that some people prefer other
   executable processors, such as DIET, to recompress the files.
   
   Then there is an increase in execution speed of uncompressed files,
   because the uncompression is no longer needed before execution. This
   may, on the other hand, not be true on fast machines with slow drives.
   In these circumstances the compressed file might actually execute
   quicker because there is less disk access.
   
   Finally, for the compression-hunters, there are a few extra's in this
   program that lets you strip unnecessary information off of the
   executables, making it a tad smaller.



WHY

   You could ask why this separate program is necessary, as PKLITE
   has the -x option to "extract" (I'd rather call it uncompress)
   a compressed files.
   
   The answer is simple. There is also an option in the commercial
   version of PKLITE to generate "unextractable" files (-e). Needless
   to say there are numerous programs available nowadays in this
   "unextractable" format.
   
   Also, with almost minimal effort it is quite easy to modify a
   PKLITE compressed file in such a way that "PKLITE -x" cannot
   handle it anymore. There are even tools around that do exactly
   this.
   
   DISLITE has the capability of expanding both "unextractable" files
   and slightly modified files to their original image. Notice that
   CHK4LITE that comes with PKLITE is also not able to recognise
   modified PKLITE compressed files. Use "DISLITE -l" to determine
   if a file is compressed by PKLITE or not. See the HOW section for
   info on the -l option.
   
   
   You should NOT use DISLITE to undo an erroneous "PKLITE -e" done
   on your recently compiled fantastic program, to do a binary
   compare with the latest version of your fantastic program. To
   make a binary compare all parts of the executable have to be
   restored exactly as they were, and the "PKLITE -e" process
   throws some information away that is subsequently lost.
   
   Needless to say the information lost during extra compression is not
   important to run your program.
   


HOW

   Usage of DISLITE is very simple. Just type:
   
> DISLITE file

   to decompress the executable file.EXE or file.COM in the
   current directory. You can also specify two filenames in which
   case the first file is left intact and the decompressed program
   is written to the second filename.
   
   If you type DISLITE without any parameters, the following help screen
   appears to remind you of the possible options:

        Usage: DISLITE [options] [d:][\path]Infile [[d:][\path]Outfile]
        Options are:
          -b = make backup .BAK file of original
          -cN = N is max number of segments
          -e = extract unextractable file (*)
          -f = un-do the fixup optimizations done by HDROPT & `extra`
          -h = remove irrelevant header data
          -k = omit kludge code added on some files
          -l = only list version info
          -o = overwrite output file if it exists
          -p = align text data on a page
          -r = remove overlay data
          -s = silent, do not generate any warnings
          -u = update file time/date to current time/date
          -v = verbose

   In fact the options can appear anywhere on the command line, not just
   directly after the program name. Options can always be combined,
   so "-b -v -h" can be abbreviated as "-bvh". You can also use the switch
   character (usually '/', but it could be set to anything) as the option
   indicator. In case you use '/', the program tries to be smart and figures
   out whether you mean a filename or indeed an option (since you can use
   the '/' character as a directory separator too). In case of difficulty,
   use '-' and '\'. (More specific: DISLITE will only recognise an option
   initiated with '/' as option if every following character is a valid
   option.)
   
   A short description of all possible options follows:
   
   -b  This option makes a backup of the compressed file image, which
       has the same name and path as the Infile, but the extension .BAK.
       Any existing file with that name will automatically be overwritten.
    
   -c  This option sets the maximum number of segments in a compressed
       program that DISLITE can handle. Notice that running out of segments
       only produces a warning or two. If memory is short, reducing the
       number of segments increases the amount of fixups DISLITE can handle.
       (It is essential that there is enough memory for fixups).
       If you are combining options, the c option should always be the last
       letter in a sequence. You can put the number either directly after
       the 'c' or separate them with a space.
   
   -e  This option is completly ignored by the program. Use it to your
       hearts contents to spell interesting words using the option
       letters. You might find "DISLITE -less" easier to remember than
       "DISLITE -ls" to which it is otherwise functionally the same.
       Notice that most option letters have no effect when you specify
       them more than once.

   -f  This option undoes the effect of "HDROPT", and also the optimization
       done by "PKLITE -e" extra compression, which is the same. The fixups
       are rearranged such that they become relative to the observed segments
       in the executable. This is automatically done for extra compressed
       files.
       
   -h  Most linkers include in the exe file header some information that
       is not needed for program execution in any way, information that
       might be used by a debugger later. Use this option to remove that
       information from the executable. (For the technically gifted:
       the information between the end of the documented DOS header, and
       the start of the relocation table. PKLITE ignores all information
       after the relocation table in the header, so that is lost forever
       after using any PKLITE compression method.)
       Note that this option has no effect on .COM files as they have no
       exe header, and neither on extra-compressed files, as the extra
       header data is then removed by PKLITE on compression.
       
   -k  Files compressed using PKLITE version 1.15 extra compression or
       higher, set a word in memory during decompression, so the
       compressed program can check if it was running compressed.
       If DISLITE detects this, it automatically inserts code to mimic
       the behaviour of the PKLITE decompression, adding 4 to 11 bytes
       of code to the program, depending on some program properties.
       If you don't want this kludge code to be automatically added,
       specify this option.
       IMPORTANT! If you decompress PKZIP 2.04g using the -k switch,
       then the resulting PKZIP executable will CAUSE DAMAGE TO YOUR FILES
       if you run it! Be aware!
       
   -l  Only list the version of PKLITE that compressed the file, don't
       decompress anything. This is especially useful with the '-s' option
       because DISLITE outputs one single line for a file in that case.
       None of the other options have any effect with the -l option.

   -o  Use this option to overwrite an output file that already exists.
       Note that files with extensions .BAK and .$$$ with the name of
       the Infile are always overwritten (provided these files are
       generated by the program. You normally never see .$$$ but this
       is used as an interim file in case you only specify an Infile).
   
   -p  Align text data on a page. This option can be used for any .EXE
       file, to make the exe header a multiple of 512 bytes. Some say
       that the executable loads faster if this is the case. Most linkers
       generate executables this way.
   
   -r  Remove any overlay data present. Overlay data is data after the
       executable file image until the physical end of file. DISLITE
       never complains when overlays are present, it normally just copies
       the overlays.
       
   -s  Be silent. No warnings are given, and the header is suppressed
       too. Usefull for background or batch execution.
   
   -u  Update time. Use this option to set the file date/time stamp to
       the current time. Normally, DISLITE leaves the file date/time
       of the file the same (even when you specify an Outfile).
   
   -v  Be verbose. When you use this option, you will get a more 
       detailed progress indicator, and lots and lots of information
       about the file being uncompressed. Recommended to the nosey.



LIMITS

   DISLITE uses quite a lot of memory. I haven't exactly calculated it,
   but I expect you need approximately 150K + the amount the expanded
   program takes to execute. In case you have not enough memory available,
   DISLITE will first try to shrink its buffers a little (upto a certain
   point), but this can lead to errors like "Too many fixups, sorry".

   DISLITE can only handle executables with upto 16384 fixups. If you find
   a file with more fixups, asking me nicely to provide a new version of
   DISLITE might help. 

   The program uses the built-in extractor of the executable, and
   therefore a very smart virus can get hold of your system if you
   expand a compressed file which had a virus infecting it after
   compression. But since DISLITE disallows DOS and BIOS access for the
   expanding program, the chances that you actually catch a virus
   that infected a compressed file are much larger. See the TECHS
   section for more info.
   
   The "effective compression" ratio as described under MESSAGES can
   give odd or incorrect results if you specify one of the -hpr
   options.
   


TECHS

   As said in the previous section, DISLITE uses the extractor built
   into the compressed file to decompress it. There is a little
   debugger inside DISLITE that allows it to only execute the built-in
   decompressor and extract information from it at the same time.
   But because DISLITE is still based on particular details about the
   built-in decompressor, there can always be ways around it. Therefore
   I do not guarantee that DISLITE will work for future version of
   PKLITE.
   
   Nevertheless, DISLITE has been thoroughly tested on files generated by
   PKLITE versions 1.03 - 1.15, and also works for the 1.20 compressed
   files that are available.
   
   When debugging the program that is decompressed, DOS and BIOS
   interrupts are disabled. But in case such an interrupt is called
   anyway, DISLITE displays the offending interrupt number and follows
   with a dump of all internal registers. This might indicate several
   things: If you had previous warnings about an unrecognised PKLITE
   version, that is likely to be cause of the troubles. If you
   haven't, someone might have modified the compressed program.
   This modification could have been done by the original programmer
   on purpose, or, as a final case, by a virus.

   .COM files are always extracted to their original image, and so are
   normal compressed .EXE files. (Well, at least restored just as
   PKLITE -x would restore them. If there was any information stored
   after the relocation table, that is lost.)

   Extra compressed .EXE files can not be restored to their original
   image exactly. As said before, the information stored in the header
   just after the DOS documented .EXE header and before the relocation
   table cannot be recovered. This information is not needed anyway.
   Further, there are 3 entries in the .EXE header that can not be
   recovered completely. Two of these, the headersize and the position
   of the relocation table follow from the fact that the additional
   header data is lost.
   
   The third entry that can not be completely recovered is the minimum
   memory to allocate to the program. This value might be a little bigger
   in the newly extracted image as compared to the original one. In case
   you have such a critical memory setup that the program cannot execute
   with this larger minimum memory requirement, it wouldn't have done so
   *with* the PKLITE decompression code either. Resuming, this is again not
   a great loss.
   
   However, DISLITE is very well able to *completely* restore the relocation
   or fixup table. In fact DISLITE goes through some trouble finding the
   right segment for each fixup, as PKLITE -e kindly throws that information
   away. However, if there isn't enough memory to store the segments used
   in the compressed program, then the fixups aren't restored completely.
   This doesn't have any impact on the execution of the program.



MESSAGES

   Many! DISLITE is stuffed to under its chin with all kinds of information
   messages, most of which are self-explanatory. I will, however, name
   some.
   
   There are four types of messages DISLITE can produce: informational,
   harmless warnings, warnings, and errors.
   
   Informational messages are enabled with the -v option. They include:
   progress indicators, and various file information. There are two
   compression ratio's mentioned for .EXE files: the real compression and
   the effective compression. The real compression is the compression of
   text (executable) data, as achieved by the PKLITE algorithms, and the
   effective compression is the file-to-file overall compression factor,
   the one that PKLITE displays. This latter value might not be correct
   in all circumstances. See the LIMITS section.
   
   Harmless warnings are indications that something isn't going as it
   should, but the decompression process isn't seriously hindered by
   it. The only harmless warning that you might react upon is:

Harmless warning: Fixup segments don't match observed segments.
You might use '-f' to correct this.
   
   This might be the result of a program that is first processed with
   HDROPT and then compressed using normal compression. If you specify
   the -f switch, as indicated, then both the compression *and* the
   optimizations done by HDROPT are undone.
   
   The harmless warning "Cannot fix fixups" indicates that there wasn't
   enough memory to store all segments found in the program, and as a
   result the fixups cannot be restored completely.


   A warning is given if DISLITE has serious doubts about the program
   you want to uncompress. For example if you specified a file without
   an executable extension.

   You are asked to confirm before proceeding. Setting -s inhibits all
   warning messages.


   There are innumerable errors, mostly DOS errors of the format
   "short explanation:DOS error description". These are all of the type
   "get your dirty hands off that disk drive door and retry". DISLITE
   can't do much about it.

   There are some DISLITE specific errors, like "Cannot find end of
   decode loop."; or "Unexpected interrupt xxh from processed program.",
   followed by a dump of all CPU registers; or "Not enough memory." or
   "Too many fixups, sorry."

   This all means that DISLITE can no longer keep track of what's happening,
   and gives up. Increasing the memory available to DISLITE might help.
   If it doesn't, blame PKWARE for bringing out an incompatible version of
   PKLITE. (And start looking for an updated DISLITE :-)
   
   The only likely error is that of an unexpected exit from the compressed
   program, which normally means you pressed Ctrl-Break.

   You cannot turn off the errors or stop them from aborting the program.



BUGS

   Well I've eliminated the One remaining bug in DISLITE v 1.01 :), but
   there is a slight change that the enhancements might have incorporated
   new bugs. If you find something that shouldn't occur according to you,
   you're free to send me a mail (see WHO section below).



PRICE

   Zero! Give this away to all your friends, especially if their initials
   are PK ;-) But of course donations are greatly appreciated. See the
   WHO section below to know where to send your money.
   
   

THANKS

   Special thanks to CV-Tassle for upgrading DISLITE to be able to handle
   1.14+ compressed files and for various other functions and bugfixes.
   Also thanks to Nico for getting the bugs out of the manual (old credit
   that still had to be paid).
   And last but not least, thanks to Sabine for being so patient with me.



NEW

   New in version 1.15 is the ability to deal with 1.14 and 1.15 compressed
   files, and with the PKLITE 1.20 extra compressed programs that were
   available.
   
   All undocumented options of v. 1.01 have changed. I don't think that
   anybody will regret the loss of -l for the new functionality :)
   -c changed because what it orginally served was no longer useful;
   "crippled" files are now automatically handled properly. The -d
   option disappeared as it was unsafe to use.
   
   Fixed a bug reporting out of memory while processing fixups.
   
   Added a progress indicator that provides for some entertainment while
   you await the decompression process.
   
   Greatly enhanced detection of PKLITEd executables! Even if the
   "PKLITE" indentification string is removed, DISLITE is still able
   to tell if an executable is compressed by PKLITE.
   
   Output files are no longer silently overwritten.



NOTE

   A note to people who are concerned about DISLITE removing the PKLITE -e
   "protection" from a program:

   As a software developer, if you want to make your programs tamper-proof,
   you should not rely on any single method, and certainly not on anything
   so easy to circumvent (and so widespread) as PKLITE -e. Any good cracker
   can undo the PKLITE compression with a debugger in a few minutes. The
   best protection is to be creative. Checksumming the executable in a
   complicated way and using the result to initialise some variables could
   be a nice suggestion. Make sure your program does lots of other things
   preferably with a lot of procedure calls before the actual check
   appears.  There's nothing so easy as skipping the first procedure call.

   Three notes from the developers of DISLITE to all evil people out there:

   Note to would-be crackers of PKZIP 2.04:
   In addition to the PKLITE compression (which DISLITE 1.15 will expand),
   there is internal encryption of portions of the code within the 
   executables. DISLITE 1.15 does not concern itself with this. If you 
   want to crack the PKZIP internals, you are on your own.
   Forget it--Get a life!

   Note to any crackers of any software:
   If you really need DISLITE to get around the PKLITE compression, then
   you're obviously no-good! Why are you wasting your time on this anyway,
   don't you have something better to do? If you are such a genuis on the
   keyboard as you keep saying to yourself, why don't you write a useful
   program?

   Note to would-be defeaters of DISLITE:
   Forget it. We can always figure out how to expand it. If the
   processor can expand it at run time, then some program can expand
   it too. Your last attempt was valiant, and only worked as long as it
   did because we had other demands on our time. However, you have our
   admiration for such a fine program as PKLITE.



WHO

   I can be reached:
   
      Jan-Pieter Cornet
      Email: <johnpc@xs4all.nl>

DISLITE (pd)   Executable File Expander   Version 1.17a   Jun 3, 1993
Copyleft 1991-1993 JohnPC & CV-Tassle.  Say NO! to software patents.