                               === Diskcopy ===

Version.
--------

This is the documentation for FreeDOS diskcopy beta 0.51. This version is
a candidate for a stable version and contains all the planned features for
diskcopy. These include:

- disk copies for 160 Kb, 180 Kb, 320 Kb, 360 Kb, 720 Kb and 1.44 Mb 
  diskettes.
- use of XMS, EMS, swap files and main memory for disk copies.
- image file support.
- mouse button support.
- rawrite compatibility.
- disk error recovery mode.
- ini file support for easier configuration.
- ini cache file support for fastest speed.
- diskcopy can be compiled using only freely available software. 


New in this version.
--------------------

a) The textual output has been improved.
b) The .ini parser has been improved to allow more liberal input.
c) Optional generation of a compiled ini file to serve as a cache.
d) Lots of bug fixes.

Authors.
--------

Mathew Stanford (original version).

Imre Leber (ilebr@vub.ac.be, valid until 22 september 2000).

License.
--------
Diskcopy is distributed under the terms of the GNU General Public License
(see COPYING for details).

The XMS and EMS public domain routines by Cliff Rhodes have been translated 
to nasm by Imre Leber and the assembly versions have been put under the 
GNU General Public License by Imre Leber.

The file drvtypes.asm is a nasm translation of a pascal source file. Since
this file has been given to me by Ralph Quint this file remains under the 
public domain.

The original version of free diskcopy has been written by Matthew Stanford,
who personally asked me to work on it further.

Purpose.
--------
Diskcopy is a free implementation of the dos utility with the same name. It
currently supports disk copies for 160 Kb, 180 Kb, 320 Kb, 360 Kb, 720 Kb, 
1.2 MB and 1.44 MB disks, using XMS, EMS, buffers or swap file. On top of 
that diskcopy supports the use of image files.

Syntax and usage.
-----------------
The syntax for diskcopy is as follows:

Diskcopy <source><destination>[/a][/v][/m][/i][/o][/1][/x][/d][/r][/?]

The parameters are to be interpreted as:

source:      drive or image file to copy from.
destination: drive or image file to copy to.

/a : give an audible warning for user action.

     This option gives a beep each time user action is required.

/v : verify writes.

     Meant for verifying writes, actually has only influence on the DOS
     verify flag.

/m : only use memory for disk copy.

     With this option only memory is used for the diskcopy, meaning either
     XMS, EMS or buffers.

/i : show memory usage (informative).

     Tells you which kind of memory is used.

/o : overwrite destination, if it already exists (in case of an image file).

     When you want to make an image file of a floppy disk and a file with
     that name already exists the program refuses to overwrite the file.
     With this option you can change this behaviour and force an overwrite
     of existing files.

/x : always automatically exit.

     This switch makes sure the program always exit. You will most likely
     notice this at the end of the program. If you use this switch the 
     program will no longer ask you wether you want another copy of the disk
     or wether you want another copy of the disk.

/d : assume disk already in drive.

     This switch is used to speed up disk copying. The program will not
     ask you to insert the source or destination diskette if possible.

/r : go into error recovery mode.

     Sometimes part of a disk is unreadable, but everything else is still
     valid. In those cases you might want to copy the disk to a new disk,
     while recovering as much data as possible. Using this switch you can 
     force diskcopy to scan more effectively for media errors on the disk 
     and recover more of the disk than is possible without the switch.
     
     This option is not available, if you compile diskcopy to always be
     in error recovery mode (see also further).

/1 : this option doesn't do anything but has been included for MS-DOS
     compatibility.

/? : displays the help screen.

The character for the options (the '/') actually depends on the DOS switch
character. If you have changed it to an other character than '/', you can 
use that character instead (but this is not required).

Because there is now support for a configuration file, options set in the
configuration file can be cleared by using a minus sign (-) after the option.

compile time options.
---------------------

There are two compile time options that can be chosen to select different
ways in which diskcopy works. The options can be set in the makefile for
the source by changing the comments of the following four lines:

#hlpoptions =             
hlpoptions = -DDEF_HELP

recoptions = 
#recoptions = -DALL_RECOVERY_MODE

These two lines contain defines that can be turned on or off, the meaning
is as follows:

hlpotions = [-DDEF_HELP]

        This define changes the behaviour of diskcopy when there are no 
        parameters. The default is to show the help on the screen. By
        changing the define you can get the more MS-DOS like message

                Invalid drive specification or non removable media.

        which was used in earlier versions of diskcopy.

recoptions = [-DALL_RECOVERY_MODE]

        This define changes the way recovery mode is selected. Normally 
        recovery mode is only selected when the user uses the /r switch.
        When using this define diskcopy is always in recovery mode and
        the /r switch is no longer valid and results in a warning.

Image files.
------------

Image files are files that contain the contents of a floppy disk in raw 
format.

The main advatage of image files is that one can save the contents of a
floppy on a different medium, like a CD-ROM or a hard disk and recreate 
the disk only when you need it.

Image files allso make it possible to distribute image files through the
internet.

To make an image file you can do the following:

     diskcopy a: example.img

To rewrite the contents to a different floppy disk you can do the following:

     diskcopy example.img a:

For reasons of closure it is allso possible to copy image files with 
diskcopy, as follows:

     diskcopy example1.img example2.img

but this is (allmost) the same as copy example1.img example2.img.

Hint:  To get a better compression ratio on image files, use a wipe utility
       (like PC TOOLS wipe) to clear the unused space on a floppy disk.

Rawrite compatibility.
----------------------
The image files supported by diskcopy are now also compatible with rawrite
image files (commonly used with linux distributions and the FreeDOS 
distribution). 

Diskcopy can thus be used to create the images for use with rawrite. There
is only one thing to notice here. Because diskcopy uses DOS to find out the
disk sizes for the diskettes it can only work with FAT. Reading from non DOS
disks is impossible. 

On the other hand writing to a disk formatted to use FAT is possible no
matter what the image file itself contains. If there is an other file system
on the diskette format a: /q can be use before writing an image file to
the diskette.

Windows compatibility.
----------------------
Because diskcopy only uses DOS to copy disks it can be used to write in a
DOS box under windows without having to lock the drives first. Any boot 
sector will be written correctly so that the disk will be bootable.

Long filename support will be added when FreeDOS gets it's long filename
API wich might or might not be compatible with windows long filenames.

Diskcopy.ini file.
------------------
In order to facilitate using diskcopy you can optionally create a 
diskcopy.ini file to store the options you use often.

The structure of a diskcopy.ini is pretty standard:

There are three headers for the selection of options:

        [- OPTION -]

and

        [- MEMORY-]

and 

        [- GENERATE -]

which form blocks containing option statements. 

(The "-" in "[-" and "-]" is optional)

Option statements are of the form:

        LVALUE = RVALUE

where the "=" and the RVALUE are optional (if the RVALUE is not entered
nothing happens). 

The option statements that can be used in a [- OPTION -] block are:

audible = YES 
audible = NO
        
        turns the audible warning before user action on or off.

verify = YES
verify = NO

        turns verification on or off.

askdisk = YES
askdisk = NO

        determines wether a disk is asked to be inserted.

informative = YES
informative = NO

        determines wether the memory type is shown.

overwrite = ALWAYS
overwrite = NEVER     

        determines wether to overwrite the destination, if the destination
        is an image file.

autoexit = YES
autoexit = NO

        determines wether the program should automatically exit.

mode = RECOVERY
mode = NORMAL

        determines wether the program should allways be in recovery mode
        or not.

The option statements that can be used in a [- MEMORY -] block are:

XMS = YES
XMS = NO

        determines wether XMS memory can be used.

EMS = YES
EMS = NO

        determines wether EMS memory can be used.

DISK = YES
DISK = NO

        determines wether a swap file can be used.

The option statement that can be used in a [- GENERATE -] block is:

USEDATFILE = YES
USEDATFILE = NO

        determines wether a compiled ini file should be generated 
        (see further).

The diskcopy.ini file is looked up in the following places and in the 
following order:

1) the environment variable "dkcpini" can point to a directory where 
   the diskcopy.ini file is located. If no diskcopy.ini file is found 
   or the directory does not exist the search is continued.
2) the executable's directory.
3) the current directory.

Notes: 1) DOS shoudn't be case sensitive so diskcopy isn't either.
       2) command line options overwrite the options in the diskcopy.ini 
          file.

Compiled ini file.
------------------

In a previous version of diskcopy the .ini file had to be interpreted each
time the program is used. 

An .ini file is by definition a file that is written once for many uses. 
Therefore the speed of reading an .ini file can  be increased by generating 
a seperate file containing that contains only the essential information 
contained in an .ini file and using that file as long as the .ini file has 
not changed.

By using a simple entry in the .ini file such a file is generated with the
name diskcopy.dat. The entry is:

USEDATFILE = YES 
USEDATFILE = NO

When the option is set to YES a diskcopy.dat file is generated whenever 
the .ini file is changed. 

That the .ini file is newer is checked using the normal way by looking at 
the file time. (This is thus the same method used by the make utility).

A few checks are build in to ensure that any file with the name diskcopy.dat
is realy a diskcopy generated file. If the file is not valid it will not be
used. The file, however, can be overwritten when generating a new 
diskcopy.dat file.

Examples.
---------

Diskcopy a: a: /a /i

    Copy a floppy disk from a: to a:, give a beep before user action and show
    memory usage.

Diskcopy a: example.img

    Copy the contents of the floppy disk in drive a: to the image file
    example.img.

Diskcopy example.img a:

    Copy the contents of the file example.img to the floppy disk in drive a:

Diskcopy example1.img example2.img

    Copy the file example1.img to the file example2.img. 

Diskcopy a: a: /a-

    Copy the contents of the disk in drive a: to another disk in drive a:,
    making sure there is no beep for user action.

                                    *
                                   * *

The following example shows the defaults for a diskcopy.ini file (using 
these values is the same as not using a diskcopy.ini file at all).

        [- MEMORY -]
        DISK  = YES
        XMS   = YES
        EMS   = YES

        [- OPTIONS -]
        AUDIBLE      = NO
        VERIFY       = NO
        INFORMATIVE  = NO
        OVERWRITE    = NEVER
        AUTOEXIT     = NO
        MODE         = NORMAL
        ASKDISK      = YES

Another example illustrating the more liberal syntaxis is:
        
        [- MEMORY ]
        EMS   = YES

        [ OPTIONS -]
        AUDIBLE       NO
        VeRiFy       = NO
        INFORMATIVE
        OVERWRITE    = NeVeR
        AUTOEXIT     #= NO
        MODE         =# NORMAL
        #ASKDISK      = YES
        
        [ MEMORY ]
        DISK  = YES
        XMS   = YES


Planned improvements.
---------------------

Make it one day possible to make diskcopy run under DOS-C.
