
IMG  Version 1.2e Copyright (c) 1994-1995 by Falk Huth
*** (Internet email: wshao@cluster.urz.uni-halle.de)
*** Documentation file.

Usage:     IMG <command> [-<sw> [-<sw>...]] <image_name> [<file_names>...]

<file_names>
   <file>[ <file>[ <file>[ ...]]]        includes specified files
   @<file>[ @<file> [...]]               includes lists in each @<file>

<Commands>
  e: Extract files from image            t: Test integrity of image
  l: List contents of image              v: Verbosely list contents of image
  p: Print files to standard output      x: eXtract files with full pathname

<Switches>
  d: Destination for all image volumes   p: match using Pathnames
  e: Erase after finishing               q: Query on each file
  n: Destination directory's Name        v: enable multiple Volumes
     eg. -nC:\INSTALL\BIG_PRG\DISK1      x: eXclude selected files
  o: Original disk  eg. -oA:             y: assume Yes on all queries



 Abstract
~~~~~~~~~~
Comment:  Some of the names used within this documentation are registered
          trademarks.

Various programs have the ability to save all information, a floppy disk con-
tains (including boot sector, file allocation tables etc.), to a file. This
file may be written to an alternative media (eg. streamer-tape, SyQuest, MO).
With those files it is possible to restore the original floppy disks.

It is quite useful to install programs from a temporary directory on harddisk.
The program IMG is able to write the files out of those disk images (or simply
"images") to hard disk without restoring the original floppy disks.



 Copyright or something like that
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The copyright of the program IMG has got Falk Huth. He is reachable via
Internet-email to the address wshao@cluster.urz.uni-halle.de.

The routines for decompressing disk images created by HD-Copy are written by
the author of HD-Copy, Oliver Fromme (Internet: fromme@rz.tu-clausthal.de).
He has got the copyright of these routines nevertheless they can be used with-
in this program.

It is allowed to use this program  F R E E L Y .

There is  N O   W A R R A N T Y  for the functionalism of this program.

The copying and distribution of this program is explicitly welcomed. With that
the documentation file has to be found in the same directory as the program
IMG itself.

There is no commercial distribution of this program permitted without the
explicit agreement of the author himself. If you had paid for this program,
please send a note per internet-email for this version is  F R E E W A R E  .

It would be welcomed if send your opinion about the program IMG as a note via
internet-email to wshao@cluster.urz.uni-halle.de   -   thanks.



 States of development - The History of IMG
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Version 0.99      This version had been developed in a very fast way. It had
                   got the only function to extract a disk images, created by
                   HD-Copy, completely. The data were written to a directory
                   named after the root of the image's name (without path or
                   extension). In that version there were no commands or swit-
                   ches to be found. That matches with the today's IMG call
                        IMG x <image_name>

Version 1.0       This version was in five months in 1994. This version sup-
                   ported only HD-Copy disk images, and raw disk images if the
                   switch -wd was set.
                    In this version you have to use the extension .IMG for
                   diskimages created by HD-Copy and the extension .DSK for
                   raw disk images using the switch -wd.

Version 1.1        This is the first version of IMG which has been distributed
                   on Internet. In this version, the routines for extracting
                   disk images (especially of HD-Copy images) had been opti-
                   mized. Additionally it can be said that there were no more
                   important bugs in this version.
                    New in this version was the ability to support raw disk
                   image in a reasonable way.

Version 1.2        In this version there are also raw disk images supported
                   which are shortened  or/and  which have a header.
                    The header can be up to 10000 bytes long.

Version 1.3       This version was developped for users of VGA-Copy. Because
                   of the external call of ARJ, the dynamic memory had to be
                   limited. In some cases, a large directory tree might fail
                   to load.
                    All persons which have no need of extracting compressed
                   VGA-Copy images should better use the version 1.2, because
                   it is surer.



 Thanks
~~~~~~~~

Oliver Fromme                             fromme@rz.tu-clausthal.de (Internet)
Klingestrae 2
D-38640 Goslar                                                         Germany

is the author of HD-Copy. He sent the routine for decompressing his disk image
files.


alphabetic order:

Bob Babcock                         Author of WSScopy, Harvard-University, USA
Peter Hubinsky                   Slovak Antivirus Center, Bratislava, Slovakia
Rainer Huth                                        Student TH-Leipzig, Germany
Thomas Mhner                                       Student FHO-Emden, Germany
Thomas Tischer                                     Student TU-Dresden, Germany
Franck Uberto                                        Author of DixCopy, France
Andreas Walther                            Student MLU, Halle (Saale), Germany

are to be thanked for their numberous hints which were important for the fur-
ther development of IMG.



 Supported disk image formats
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

raw disk image     means that the floppy disk has been copied sector-per-
                   sector to a file without any compression. Those disk
                   images can be created by various programs.

other forms of     Since version 1.2 IMG supports raw disk images which are
raw disk images    shortened  or/and  have a header, as well.
                    It is only allowed to shorten raw disk images in that way
                   that the last unused sectors of a floppy disk are left out
                   in the disk image.
                    IMG knows raw disk images with a header with a size up to
                   10000 Bytes. The size of the header IMG finds out automati-
                   cally. This ability allows IMG to know almost all disk
                   images which are not compressed.

HD-copy image      is no raw but compressed and sometimes sensefully shortened
                   disk image.

VGA-Copy image     tries to compress the created raw disk images using ARJ.
                    The images which are compressed with ARJ are only suppor-
                   ted by version 1.3 of IMG.

Becker Tools       is the most complicated format of all. There are stored
deluxe 2.0         multiple disk images to one file. The compression method is
Disk Archiver      unknown. Therefore only completely uncompressed images are
                   supported by this version of IMG.
                    It would be very nice of you to send more detailled infor-
                   mation about this format, if you can, because one of the
                   next version could support this staff.


The program IMG tests automatically which image format it is. It turns back an
error if it is no disk image or the format is unknown to IMG.



 Introduction
~~~~~~~~~~~~~~
This is the documentation file for the versions 1.2 and 1.3 of the program
IMG. These versions are the update for the version 1.1 of the program IMG.

This program was originally created to write files out of disk images created
by HD-Copy to hard disk, without writing back the disk image to floppy disk.

Oliver Fromme, the author of HD-Copy, made the development of this program
possible for he described his image file format and sent the required source
codes.

The further versions were developped to support more disk image formats which
are usually raw images.

If you mention any mistake while using IMG or if you have got new ideas about
this program, you are pleased to send a note per internet-email to the address
wshao@cluster.urz.uni-halle.de. If you do that, your ideas can be included in
one of the next versions.

Please read the credit section "Thanks", as well. These people should be
thanked for their help while development.



 Commands
~~~~~~~~~~

  e:     Extract files from image. The directory structure which was on the
         original floppy disk won't be created. All files are write in the
         same  o n e   d i r e c t o r y  which has been specified.

  l:     List contents of image. The list contains the filenames and the size
         of each specified file. The subdirectories are written in form of an
         extra line. At the end, the number of shown files and the sum of
         their sizes will be written out.

  p:     Print files to standard output. You should regard that the specified
         files are only text files, at least nearly.

  t:     Test integrity of image. The image will be handled in the same way as
         it would be done while running the extract command but there won't be
         any data written to disk.

  v:     Verbosely list contents of image. Additionally to the command 'l' the
         date, time and attributes of each specified file are shown. At the
         end the number of directories and the compression rate will be shown.

  x:     eXtract files with full pathnames. The directory structure which can
         be found on the original disk will be recreated.



 Switches
~~~~~~~~~~

  d:     Destination for all image volumes   eg.: -dC:\INSTALL\BIG_PRG
          The example will extract the disk image, or all images if the switch
         'v' is set, starting with the specified directory.
          This switch is necessary if a program needs all files of the origi-
         nal floppy disks to be in the same directory while installing from a
         temporary hard disk path.

  e:     Erase after finishing
          If this switch is set the disk image file will be deleted after wor-
         king on it. If the switch 'y' is not set there will be a query
         before erasing the file.

  n:     Destination directory's Name   eg.: -nC:\INSTALL\BIG_PRG\DISK1
          The example will extract the first out of multiple disk images to
         the specified directory. The destination path's name will be
         'increased by 1' for every following image (see also switch 'v').
          This switch is necessary if a program needs the files of the
         original floppy disks in directories like .\DISK1, .\DISK2 ... .

  o:     Original disk  eg: -oA:
          The example will create an original floppy disk in drive A:. You
         have to watch two important facts.
          First:  This switch only works together with a command (eg. 'l'-List
         contents of image).
          Second:  If the format of the inserted floppy disk differs from the
         format of the disk image, the inserted floppy disk will be formatted.
         In this version, only standard DOS formats are supported. Otherwise
         the program will return an error.
          There  w o n ' t   b e   a n y   w a r n i n g  if there are data on
         the inserted floppy disk. If a write- or verify-error occurs, the
         program will be terminated with an error code.
          Before the program writes any data to floppy disk, it will be
         delayed until the user hits the <ENTER> key.

  p:     Match using pathnames
          The verification of every file name includes the full pathname, i.e.
         file names (see section file names) are given in the form of
         \EN*\*.E*
          Then, only the files in the directory \EN* match. The file name
         should start in this case with '\', '?' or '*'.

  q:     Query on each file
          If this switch is set, you are asked for permission for everything.
         The switch 'y' unsets the switch 'q'.

  v:     enable multiple Volumes
          If this switch is set, the command works with all disk images of one
         series. These are images, which names differ the following way:
          The number in the root of a disk images's name (without extension)
         is increased by 1. If there is no number the letters are 'increased'.
          If the switch 'd' is not set, the destination paths will also be
         'increased'.
          Examples: - series TEST1.IMG, TEST2.IMG, ..., TEST9.IMG, TEST10.IMG
                    - series DSK1A.IMG, DSK2A.IMG, ..., DSK9A.IMG, DSK10A.IMG
                    - series PRG_A.IMG, PRG_B.IMG, ...

  x:     eXclude selected files
          Works with all files included in the current disk image but not with
         those which are specified.

  y:     assume Yes on all queries
          If this switch is set, there won't be any query. You should use this
         switch  v e r y   c a r e f u l l y  .



 Image name
~~~~~~~~~~~~

This is the name of the disk image file. It has to be specfied with extension
and in a way that the program can find this file, eg.: ..\..\TEST\STUPID.IMG



 File names
~~~~~~~~~~~~

The specification of file names is optional. If you leave out them, the pro-
gram handles automatically all files.

Otherwise, file names can be specified with wild cards like under DOS. If you
specify filenames, the program IMG handles only the matching files - or
doesn't if the switch 'x' is set.

If the switch 'p' (match including pathnames) is set, the filenames have to be
specified with pathnames of the original floppy disk, eg.: \TEST . The drive
specification of the original floppy disk (eg. A:) has to be left out. You can
avoid the path specification by typing '*\...'.

It is possible (like under DOS) to specify list files with '@<file_name>'. In
every line of the list file (text file) has to be another file name.



 Data streams
~~~~~~~~~~~~~~

The data streams under DOS ('<', '>', '|') work together with IMG, as well.



 Queries
~~~~~~~~~

The following table contains the list of all queries which may occur while
running IMG. The character 'X' specifies in which cases which queries occur.
If the switch 'y' is set the switch 'q' is automatically unset.

The table matches the English version:

   Query                            no switch     switch 'q'    switch 'y'

Directory . already exists.                                   
Use?  [Yes,No,Always] :                 X              X      

Directory . does not exists.                                  
Create?  [Yes,No,Always]                               X      

Extract .? [Yes,No,Always,Quit]                        X      

File . already exists.                                        
Overwrite? [Yes,No,Always,Quit]         X              X      

Erase file .? [Yes,No,Always]           X              X      


If you answer a query with 'A', all queries of the  s a m e   k i n d  won't
happen no longer. This is not the same as the setting of the switch 'y'.

Is the name of a directory which should be created the same as the name of an
already existing file, or if you answer that you don't like to use an existing
directory, the program IMG will ask after an alternative directory name. If
you answer this query with just pressing the <ENTER> key, the program will be
terminated.

If you answer that you don't want to overwrite an already existing file, you
will be asked after an alternative file name. If you just press the <ENTER>
key in this case, the file will be skipped.

Two queries in the table might be answered with 'Q' or 'Quit'. This would ter-
minate the program.



 Exit codes of the program IMG
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If no error happened, the exit code is zero. Otherwise it is mostly the same
as a DOS run time error (eg.:  3 = Path not found).

In addition to these there are some more exit codes:

 65500      -      program terminated  (by user)
 65534      -      invalid file allocation tables
 65535      -      invalid disk image format



 Examples
~~~~~~~~~~

img v test.img                         list the contents of the disk image file
                                       test.img verbosely, all files match

img t ..\programs\test.img             test integrity of the disk image file
                                       test.img in the directory ..\programs,
                                       all files match

img p test.img *.txt                   print all files matching *.txt of the
                                       disk image file test.img to standard
                                       output

img l -oA: test.img                    list contents of the disk image file
                                       test.img and restore the original floppy
                                       disk to the disk inserted in drive A:

img e -d. -p -q test.img \english\*.*  extract files from the image test.img to
                                       the directory . (current), only the
                                       files which were in the directory
                                       \english of the original floppy disk
                                       match, query on each of these files, no
                                       directory .\english will be created

img x -ndisk1 -v -x -y test1.img *.bak extract files from the disk images which
                                       don't have the extension .bak, the ori-
                                       ginal directory structure will be
                                       created, there won't be any query, the
                                       image file test1.img will be extracted
                                       to the directory .\disk1, the image file
                                       test2.img will be extracted to the
                                       directory .\disk2 etc.

img x -e -y test.img readme.txt        extract all files "readme.txt" of the
                                       image test.img. The original directory
                                       structure will be created. Afterwards,
                                       The disk image file "test.img" will be
                                       deleted. There will be no query.


End.
