IMAGEX ver 1.00
IMAGE EXTRACTOR - The Disk Image testing and extraction tool
****************************************************************************
** **
** DISCLAIMER **
** **
** Although I believe what I write in this documentation, you should be **
** forewarned that my experience with the manipulation of File Allocation **
** Tables is very limited and I could be making assumptions based on what **
** I think I know. As a result this utility is provided without warrantee **
** of any kind. I do not promise that it will do anything. If by chance **
** it does do something, then by using this utility, you accept whatever **
** consequences arise from its use. **
** At the time of release this utility seemed to operate as I expect **
** and as outlined below, however there is no guarantee that it will do **
** so for you. **
** This utility has been tested on disk images of the following sizes. **
** 360k - 720k - 1200k - 1440k - 1680k(DMF) - 1840k(XDF) **
** It may or may not work on disk images of other sizes. **
** **
****************************************************************************
IMAGEX is a tool to test and expand the files contained in disk image
files created by a number of utilities. This version is limited to 'true' disk
images of proper FAT formatted diskettes. It may or may not work with variants
and it may or may not lockup when testing diskette images other than those for
which it was intended.
My definition of a 'true' disk image is a file which is created who's
structure matches perfectly the byte for byte structure of a diskette. That
diskette must be a properly formatted DOS-type FAT diskette. It will not work
on disk images which have been created using any kind of compression. In other
words, it 'probably' won't work for many of the disk images you receive, but
it can save a considerable amount of time if you wish to test those that it
does work with.
The image itself need not start at the beginning of the image file but may
be imbedded in the file by as much as 1024 bytes. This allows expansion and
testing of a number of image creation programs which put a 'header' before the
actual image. This utility will not recognize any image who's header exceeds
1024 bytes and of course I cannot guarantee that it will recognize 'all'
images which meet my requirements as stated here.
I went to a lot of effort to make the checking strict and that strictness
may stop the program from recognizing some legitimate FAT based disk images.
THIS TOOL DOES NOT CREATE DISK IMAGES.
THIS TOOL DOES NOT RESTORE IMAGES TO DISK.
What it does do is to recreate the file and subdirectory structure of a
diskette image in the current directory (or another directory of your choosing)
with all dates and (optionally) file attributes intact. It also does not
create or manipulate the volume label if one is contained in the image file.
It can also be used to perform a preliminary 'check' of the FAT of such an
image to ensure it can be extracted correctly. This 'check' is only to ensure
that no 'loops' occur in the FAT which might cause extraction to loop
indefinitely. It does not check for lost clusters etc.
Since this tool does in fact NOT re-create the bootsector of the diskette
image, any virus scan of the files created from a disk image with this utility
will not be able to detect if the disk image has a bootsector virus. In this
respect, you should be aware that any disk image could contain a bootsector
virus and if the image is ever expanded to a disk by a utility which recreates
that bootsector, that disk should be virus scanned regardless of whether or
not you have scanned the files after they have been expanded using this
utility.
Intended use.
-------------
This utility was designed to be used by THD ProScan for the testing of
image files. However, it may be used manually as outlined below to test or
expand those image files with which it works. Manual use is restricted to
registered users of THD ProScan. It is my hope that someone who knows
considerably more than myself about these files will endeavour to release a
utility similar to this one which can handle many more types of disk images
reliably.
Real World Use.
---------------
Aside from testing the images, I've only found a single real world use
for this tool. Users of OS/2 can significantly speed up the application of
fixpaks by extracting directly from the disk images to the hard drive and
running the FSERVICE utility with the "/S" parameter (See the CSD
documentation for details). I was able to apply fixpak 32 to WARP 3 completely
in under 15 minutes (it takes longer than that to simply extract the files to
disk to apply from floppy, not to mention the extra access time to either
re-read the files from floppy to hard drive or to apply directly from the
floppies). Aside from this I've seen no real world usage for this utility.
Command syntax.
---------------
IMAGEX.EXE -{switches} {d:\path\filename.ext} {d:\path}
{switches}
The switches are optional. Failure to provide switches causes the program
to run as if the '-t' switch were used. The 'test' action is performed
regardless of what other actions are done. Switches may be preceded by either
a '-' or a '/' and may be strung together (ie. '/a' or '-ab'). The switches
are NOT case sensitive. Note that some switches (logically) don't work with
some other switches (-p when not extracting for instance makes no sense).
-a = recreate the file's original Attributes
The default action is to NOT restore the original attributes of the files
(thus allowing you to see all files which were extracted). Using this switch
will cause all of the original file attributes to be restored to the files
which are extracted. This switch has no effect if the files are not extracted
(using the '-e' or '-x' switch).
-b = show the Bootsector information
This switch causes the program to display a short screen with some useless
information about the disk's bootsector. By default this information is not
shown.
-e or -x = Extract the files and subdirectories
This switch causes the program to extract the files from the disk image.
Extraction maintains the directory structure as contained on the disk. Using
either of these switches also causes the '-v' switch to automatically become
active.
-f = ignore Fat errors.
This program checks the fat for 'possible' cycling entries (permanent
loops) and cross linked files. In some instances these 'errors' may not affect
the actual extraction of the files from the image. You can use this switch to
ignore those FAT errors, but if you do, be aware that it's entirely possible
that your computer may end up in a permanent loop as a result.
- o = Overwrite files without prompting if they exist. Default is to abort if
any file already exists. The '-p' switch overrides the '-o' switch. Prompt
will work if the '-o' switch is used (ie. -op operates the same as -p). Not
overwriting existing files will cause an immediate exit.
-p = Prompt for permission to overwrite files if they exist. Default is to
abort if any file already exists. The '-p' switch overrides the '-o' switch.
Prompt will work if the '-o' switch is used (ie. -po operates the same as -p).
Not overwriting existing files will cause an immediate exit.
-t = Test only [default]
This switch essentially does nothing. It causes the program to 'test' the
disk image and exit. This is the default action. The 'e' or 'x' switch
automatically overrides this switch.
-v = View full paths instead of only filenames
This switch causes the 'full' path to be displayed instead of just the
filename. The 'normal' output of test mode supplies only the filename without
any path information. Using the 'e' or 'x' switches causes this switch to
become active automatically.
{d:\path\filename.ext}
This is the full path and filename of the disk image to be processed. It
is the only command line parameter which 'must' be supplied. Needless to say,
the file must exist.
{d:\path}
An optional target directory into which to extract the directory structure
of the disk image. Failure to supply a directory will result in the current
directory being used to extract the disk image's directory structure.
Running without any parameters will show the syntax screen.
Running with invalid parameters will cause an exit although it is
important to note that when determining the worth of 'switches', the program
defines an invalid switch as a switch which contains no usable options. a
switch combination which contains one usable option is considered valid and all
invalid portions of that switch are ignored (ie. -abcdefgh is valid because it
contains the letters 'a', 'b' 'e' and 'f'. It would therefore be the same as
-abef. Using -qyl would cause an invalid switch error since it contains no
usable switch characters).
Special command line switch
---------------------------
There is one 'special' command line switch. It is a switch to 'force' the
creation of a directory to extract the files into. The switch ...
-MD:{d:\path}
will cause the program to attempt to create the directory which immediately
follows the '-MD:' switch. Use of this switch can create nested directories.
That is it will attempt to create all directories necessary along the way to
create the final directory. It is important to note that there can be NO space
between the '-MD:' and the path.
For instance if you supplied "-MD:C:\I\NEED\ALL\THESE\DIRS" on the command
line and the directory "C:\I" did not exist, this program would ATTEMPT to
create the following directories...
C:\I
C:\I\NEED
C:\I\NEED\ALL
C:\I\NEED\ALL\THESE
C:\I\NEED\ALL\THESE\DIRS
This switch works with or without a valid command line (so it could be
used 'just' to create deep directory structures). Since the creation takes
place while the command line is being parsed for parameters, it works even
when just testing (without expansion).
An error will occur if the target directory cannot be created ONLY if it
does not already exist. if the directory already exists, no action will be
taken and the program will not register a fatal error.
SCREEN OUTPUT
-------------
The 'output' of this program is intentionally redirected to the bios to
allow redirection. This is considered necessary as the length of some of the
output screens exceeds the 25 line limit on most systems. The use of
redirection will allow you to pipe the output through MORE or other paging
utilities.
Screen output has two separate options, the first is controlled by the
'-b' switch. This causes a short report of bootsector information to be
displayed. This information is 'generally' useless and is not shown by
default. It is output prior to the actual testing. Output for a typical 720k
disk would look something like this.
MSDOS5.0 OEM Name
512 Bytes Per Sector
2 Sectors Per Cluster
1 Reserved Sectors
2 Number of Fats
112 Maximum Root entries
1440 Number of sectors on media
249 Media descriptor
3 Sectors per FAT
9 Sectors per TRACK
2 Number of heads
0 Number of hidden sectors
The other output option is to use full pathnames instead of just filenames
when in 'test' mode (in extraction mode full pathnames are always shown).
"Filenames only" looks like this
Filename.ext Size Attr Date Time Clusters Extracted
------------ ------- ------ ---------- -------- -------- ---------
BYTEMOVE.PAS 703 ---A-- 07-06-1994 15:50:24 2 No
PASS 0 -----D 10-15-1996 19:23:40 1 No
APPNOTE.TXT 12491 ---A-- 04-04-1993 10:11:06 25 No
------------ ------- ------ ---------- -------- -------- ---------
"Full pathnames" (-v or -e or -x) looks like this
Filename.ext Size Attr Date Time Clusters Extracted
------------ ------- ------ ---------- -------- -------- ---------
C:\TEMPDIR\BYTEMOVE.PAS
703 ---A-- 07-06-1994 15:50:24 2 Yes
C:\TEMPDIR\PASS
0 -----D 10-15-1996 19:23:40 1 Yes
C:\TEMPDIR\PASS\APPNOTE.TXT
12491 ---A-- 04-04-1993 10:11:06 25 Yes
------------ ------- ------ ---------- -------- -------- ---------
Filename.ext -
The filename of the file or the full path and filename of the file when
extracting or using the '-v' switch .
Size -
The size of the file in bytes.
Attr -
A series of letters representing the possible file attributes of the file
whose name is shown. They are...
R - Read-Only
H - Hidden
S - System
A - Archive
V - Volume Label
D - Directory
Date -
The date of the file in the format Month-Day-Year
Time -
The time of the files last modification in the format Hour:Minute:Second
Clusters -
The number of clusters the file occupied on the original disk from which
the image was made.
Extracted -
Yes or No depending on whether or not the file or directory was expanded.
Volume labels are never expanded by this utility.
Memory Usage
------------
This utility allocates memory dynamically. When memory is needed, it is
allotted from the heap. In some instances recursion may cause the heap to run
low on memory. Depending on the disk type and size being tested along with the
directory structure the memory requirement can vary greatly. When a memory
shortage occurs, the program 'attempts' to tell you how much more memory is
required to get past the step that it ran short on. It is entirely possible
that you may need more than is reported as some recursive procedures will
attempt to allocate memory after the success of the previously failed
attempt.
Testing of a 1440k disk image with no subdirectories requires
approximately 150k of conventional memory although your milage may vary. On
average I have found (in my tests) to require between 140k and 170k, but
complex structured disk images could require significantly more.
Error Levels.
-------------
IMAGEX.EXE will return an errorlevel to the operating system each time
it is run. Aside from possible run time errors the following circumstances
will cause the noted error levels to be returned.
File is not recognized as a disk image - 255
No Filename supplied / Unrecognized Switch - 254
Filename supplied does not exist - 253
Unable to create extraction directory (-MD:) - 252
Memory Shortage - 251
FAT appears to contain a fatal loop - 2
File appears to be valid but cannot be expanded - 1
File appears to be valid with no apparent errors - 0 (test mode)
Files were extracted without error - 0 (expansion mode)
Other error levels returned will be as a result of run time errors or
other hardware or software errors. In the event that I have been able to trap
them, IMAGEX.EXE will exit with the same errorlevel which it encountered to
cause the exit.
REGISTRATION
------------
Note that registration is NOT required IF the program is ONLY used by
THD ProScan. If however you use it to expand or test files manually or via a
process other then THD ProScan, then you are required to register THD ProScan.
Also, persons who have previously sent donations to the author of THD ProScan
(see REGISTER.LST in the THD_13_0.RAR or THD213_0.RAR archive) are
automatically registered for this program and are not required to send any
further fee.
Given the low cost, please take a moment to register the program.
This program (Executable file and documentation) are Copyright 1997,
Painsoft. The program is part of the THD ProScan distribution package and may
be used ONLY with that package unless THD ProScan is registered.
Registration of that program entitles you to use this program
manually.
Rights for use are given ONLY to the original Registered person and are
not transferrable.
See THDCFG.EXE and/or THDCFG.DOC for details in regard to registering
THD ProScan.