FILL.DOC: documentation for 'Fill' v2.0
(c) Jean Lalonde, Montreal, Canada
January 4, 1988


This is a new version of 'Fill'. If you already know 'Fill', you
should first take a look at the history at the end of this file to see
what changed.


INTRODUCTION
============

Did you ever encountered this situation: you want to carry the files of
a directory from one hard-disk to another. You have to copy the files from
this directory to floppy disk. The directory contains several files, some
big, other smaller, and...

C>COPY *.* A:
FIRSTBIG.EXE
OTHERBIG.EXE
Insufficient disk space
1 File(s) copied

You realize that you will have to copy your directory on more than one
floppy. Then, you have two choices. First, copy each file seperately
checking the space remaining on 'A:' and the file's size. Second choice,
you can use a back-up program. The backup program is a good solution but
you will have to carry the restore program with you. With 'Fill', there is a
third solution...

C>FILL *.* A:

'Fill' will copy all your files, filling up each floppy disk. To do
this, 'Fill' will build a list of the files of the directory, sort this list
by size order and then copy the biggest file to the floppy. Second, it
will copy the biggest file that can be copied in the remaining space of the
floppy and so on. When the first floppy will be filled up, 'Fill' will prompt
you for another disk until the directory is completely copied to floppies.

This way, 'Fill' optimizes your floppy disk space, makes the job easy and
keeps your files in their original-executable format. To restore the files
on the destination hard-disk, all you will have to do is copying the files
of each floppy with the simple command...

A>COPY *.* C:\DIRECTORY

'Fill' will also allow you to list files (dir), delete or format the
destination floppy without leaving the program. You will never have to
stop because you do not have enough formatted floppies. You can also
change, make, remove directories or label the target floppy.

The only restriction is that the biggest file of your directory must
fit on one floppy (362,496 bytes or 1.2 meg according to your configuration).
If the biggest file does not fit on a floppy you will have to use the
backup/restore solution or use a "slicing" program to break your big files
into smaller parts. My program 'Cut' does it (CUT.ARC should be available
where you got this program).


USING 'FILL'
============

Command line syntax
-------------------

C>FILL drive(s)\directory\files target [options]


'drive(s)' to copy from (default is current drive), accepts multiple
drives (eg: 'CDE:').

'\directory\' is the directory to copy (default is current directory).

'files' to copy. Wild cards are allowed (default is '*.*'). Multiple
filenames are allowed with an exclusion list. The filename parameter
also accepts double wildcards to search for a pattern anywhere in the
filename. Double wildcards can be used on filename or extension, in
inclusion or exclusion list.

Some 'drive(s)\directory\files' examples:

'' all files ('*.*') in the current directory.

'\' for all files in root directory.

'C:' all files in the drive C:'s current directory.

'\DIR\*.COM' files ending by '.COM' in '\DIR'.

'*XYZ*.*' files with the pattern "XYZ" anywhere in
the left part of the name.

'*.BAT+*.SYS' files ending by '.BAT' or '.SYS'.

'\*.*/*.COM+*.EXE' for all files except files ending
by '.COM' or '.EXE'.

'*.BAT/AUTOEXEC.BAT' all batch files except the
autoexec batch file.

'CDE:\*.SYS' for files ending by '.SYS' on root
directory of drives C:, D: and E:.


'target' is the destination drive, accepts multiple drives (eg: 'AB:').

[options]:

'/?' for novice users, 'Fill' prompts you for all parameters. When the
work is done, 'Fill' will prompt you again for new parameters. To end
the program, enter at the first prompt.

'/A' to copy only files with Archive attribute ON. This attribute is
set ON when a file is modified and is reset OFF by backup programs.

'/B' to turn off the checking, allowing buffered keyboard
input and keyboard redirection.

'/D' for discrete scanning.

'/E' to allow confirmation for each directory.

'/F' to allow confirmation for each file.

'/H' to display a short help message.

'/K' to kill (delete) source file (see option '/V').

'/L' to log copied filenames and targets in a text file.

'/M' to copy files in the given directory mixed with files from
children directories.

'/O' to turn Archive attribute OFF on files successfully copied.

'/S' to repeat the task on sub-directories.

'/V' to verify integrity of copied files.


Starting 'Fill'
---------------

When you call 'Fill' with appropriate parameters, 'Fill' builds its list of
files to copy. The directory read by 'Fill' is shown at the beginning of the
scanning line. 'Fill' indicates the directory currently scanned before the
back-slask (".\" stands for current directory) and each dot represents a
file to copy. If you select the '/F' option, 'Fill' will ask for
confirmation before each file. When the list is builded, 'Fill' shows you
its main menu.

C>FILL *.* B:

Fill v2.0 (c) Jean Lalonde, Montreal, December 1987


Building list...

.\..................................................

Insert disk in 'B:' and press Copy files, Dir target, Erase target,
Format target, List files, Other target or to abort (C) ? _


Copying
-------

From there, check if your target disk is ready in B: and press
. The character between brackets before the question mark indicates
the default answer if you press . "C" stands for "Copy".

If the target directory is empty, 'Fill' will copy files beginning with
the largest file that can fit on the target disk. If the target is not
empty, 'Fill' asks you if you wish to delete all files from the current
target directory. If you answer yes, 'Fill' calls the DOS command "DEL *.*"
and this command will ask you to confirm.

This disk is not empty. Erase 'B:\', volume label: 'LABEL' (N) ? Y
Are you sure (Y/N)?y

Kilo-bytes on disk with label 'LABEL':
free - this file
354 - 100 .\ONEFILE.EXT to B:\ONEFILE.EXT

For each file copied, 'Fill' tells you how many kilo-bytes are available
on the target disk before this file and the size of the file to copy
(rounded to the next kilo-byte). Sometime, when the target is a sub-
directory, the available space may be followed by a tilde '~'. This
indicates that the available space may be underestimated by one cluster (on
standard floppies, one cluster equals one 1,024 bytes) because 'Fill' detected
that the "sub-directory file" could be extended by one cluster to include the
new file. After the file is copied, 'Fill' checks the free space to update
its free space counter.

If a file exists on the target disk, you have the choice to rename the
existing file, overwrite it or skip the source file (note about logging: if
you overwrite the destination file, your log file will include both first
and second copies of the destionation file).

ONEFILE.EXT exists on B:\
Rename, Skip, Overwrite (R) ? R
New destination name (only the name) ? NEWNAME.EXT

The root directories of disks have a limited capacity. For standard
floppies, the maximum number of files (or directories and label) that can
be written in the root directory is 112. When 'Fill' detects that only one
more file can be written in the root directory, 'Fill' asks you to change the
target floppy or to create a sub-directory and copy remaining files in this
sub-directory. There is no limit to sub-directory's capacity.

If the target disk is not ready, 'Fill' will wait for you to close the
disk door or escape the program. If the target disk is not formatted, 'Fill'
will automatically run FORMAT. You can always abort FORMAT by pressing
control-C (^C).


Menu options
------------

Instead of copying files, you could ask to see the target directory
"D", erase this directory "E", format the target floppy "F" (remember that
FORMAT is called automatically when an unformatted disk is detected, in
this case you don't have to press "F"), list files to copy "L" or call
a second menu. This menu gives you for other target options "O":

Current target directory is 'B:\', volume label: 'LABEL'.
Change dir, Make dir, Rem dir, Label, Next drive ? _

This menu first identifies the current target's drive, directory and
label. Every options of this menu are related to the target drive. You can
change the directory where files will be copied "C", make "M" or remove "R"
a directory, label the target disk "L" or skip to the next target drive
"N". This last option will appear only if you entered multiple disks as
target parameter (for example: 'AB:').

You can also abort the program by pressing . 'Fill' will ask
you to confirm your request. If you press , the program will be
aborted (note the default answer "(Y)"). If you press "N", 'Fill' will
return to the previous menu or task.

Do you really want to escape (Y) ? Y
Filling files of this directory: escaped.

You can request abortion from any menu or when 'Fill' is copying a file.
After each file, 'Fill' checks if has been pressed. If yes, it asks
you to confirm. Because this keyboard checking flushes the keyboard
buffer, you may wish to turn off the escape checking by selecting the
"buffered keyboard input" option from command line '/B'. This is
absolutely needed if you plan to use 'Fill' with redirected input
(eg: "FILL *.* B: /B
'Fill' always terminates with a result message. If 'Fill' terminates
successfully, the message is "fine!". If not, the message will give you
the condition that caused the termination. If you call 'Fill' with '/S'
option, 'Fill' will give you a result after each subdirectory.


Logging
-------

To keep track of files copied, 'Fill' can create or append a text file
called "log file" that contains names, source directories and destination
disks and directories for each file copied. In the log file, the destination
disk is designated by its volume label. When logging, 'Fill' checks if the
target disk has a label. If not, the program "LABEL" is automatically
called.

You can specify the log option at the command line or the "ask option"
('/?') prompt. The log option may be followed by the log filename and
sorting instruction. The log file will be sorted by 'Fill' if '/S' or '/D'
is added to the log filename. For example, with '/L:FILENAME/S' the file

will be sorted on source paths and filenames (drive:\dir\filename), with
'/L:FILENAME/D' the file will be sorted on destination filenames
(label:\dir\filename).

C>FILL *.* B: /L:C:\DATA\LOGGING.DAT/D

Here, the log file will be created or appended in the directory
"C:\DATA\" with the name "LOGGING.DAT" and will be sorted on the destination
names.

Log file is opened in the current directory or the specified
directory. If the log filename is not specified, the default name is
'FILL.LOG'. If the log filename's extension is not specified, the default
extension is '.LOG'. By default, there is no sorting. Note: if a source
name plus destination name are too long to fit on one line of the log file,
they are written on two lines. In this case, sorting is cancelled because
sorting options are available only if each copied file logging data fit on
one line.

If the log file exists, you will have the choice to append or
overwrite the existing file. If the log file is created in a source
directory to copy, it will NOT be copied by 'Fill' to the target disk.


Sub-directories
---------------

Normally, 'Fill' copies only files from the current directory (or the
specified directory). But it can also copy files from sub-directories.

The option '/S' allows you to repeat the process on every sub-
directories under the specified directory without repeating the command
line.

The option '/M' allows to copy all files matching 'files' in a given
directory and its children directories. This command:

C>FILL \*.ARC A: /M

will copy all .ARC files on the current drive to floppies. If a file has
the same name than another file already copied to the target floppy, 'Fill'
will prompt you if you want to ovewrite the file on the target floppy, if
you want to give another name to the second file copied or if you want to
skip the second file.

Caution: if two files with the same name are copied to different
floppies, 'Fill' will not prompt you. In this case, take care when you
copy the floppies to another hard-disk. If you use:

A>COPY *.* C:

the second file will overwrite the first one. There is no problem if those
files are duplicated but if different files have the same name, you may
lost the first one. To avoid this, use 'DDup' with option '/N' to identify
duplicated filenames before filling (DDUP.ARC should be available where you
got this program) or Xcopy (DOS 3.2 and later) instead of Copy. Xcopy will
prompt you before overwriting a file on the target disk.

With option '/E', 'Fill' will ask you if you want to scan the next
directory.
]

INSTALLATION
============

External programs
-----------------

'Fill' itself does not require any installation. But 'Fill' uses some
DOS commands related to files and directories. Some of these commands are
"resident" (like DIR and DEL) but other are "external" (like FORMAT or
LABEL). Three of those DOS programs are used by 'Fill' and must be
available to it: FORMAT, LABEL and SORT. To be found by 'Fill' those
programs must be in the current directory or in one of your path
directories. For example, if those programs are in the directory 'C:\DOS',
your PATH must include 'PATH=C:\DOS;'(if needed, take a look at "SET" and
"PATH" commands in your DOS documentation).

Compatibility
-------------

'Fill' uses mostly standard DOS calls so it should run on any MS-DOS
compatible systems. The only low-level feature is a call to BIOS to
get the target disk status. This explain why 'Fill' do not support target
drive re-assigments with ASSIGN.

'Fill' presents no compatibility problems with resident programs except
some caching program. 'Fill' does not (and can not) solve this kind of
problem. If you use such a program and experience some trouble, it is
recommended to include 'Fill' in a batch program that will disable caching
for the target floppies.


Environment
-----------

You can set permanent parameters using the environment and the DOS
command SET. When 'Fill' is loaded, it checks in the environment for the
variable "FILLSPEC". The content of this variable is read and added at
the beginning of the parameters you entered at the command line. For
example, you could type at the DOS prompt "C>SET FILLSPEC=/L:C:\MYLOG.TXT/S"
and 'Fill' will always run with logging option to the file C:\MYLOG.TXT with
sorting on source name. The SET command could be included in your
AUTOEXEC.BAT file.


PIF files
---------

'Fill' is provided with PIF file (Program Information Files) needed by
Windows (created with version 1.03). This file allows you to run 'Fill' with
multi-tasking and windows environment.

Under Windows, 'Fill' is called with the '/?' option. When you call the
program, 'Fill' asks you questions needed until you press at the first
prompt. Then, the window is closed.

The Windows PIF file (FILL.PIF) requires no modification if FILL.EXE
is saved in the current directory or one of the PATH directories. 'Fill' is
called with 192k of RAM. You can change this parameter as needed.

A second PIF file for DESQview should be provided with 'Fill' but I
experienced some problems running 'Fill' under DESQview (version 2.0). When
I will get the needed technical info from DV programmers, I'll add the
"FI-PIF.DVP" file to 'Fill's arc file.


HOW TO JOIN ME
==============

I hope 'Fill' will be usefull to you. You can send me comments, money
or reports to:

Jean Lalonde
6667 de Normanville
Montreal, Quebec
CANADA
H2S-2B8

You can join me online on Compuserve (ID: 76606,671) or on BIX Info
Exchange (Bix name: jlalonde).

'Fill' is written in LOGITECH MODULA-2 Compiler, DOS, Rel. 3.00, Aug 87,
Copyright (C) 1983, 1987 LOGITECH, using Logitech's library and my own
library JLModules v1.2.

'Fill' uses standard PC/MS-DOS (version 3.00 or more) and the BIOS
get disk status function.

You can use or redistribute this program freely as long as it is done
at no cost (except floppy's cost), if this documentation file and the
copyright remain intact. Fell free to send me some money if you like 'Fill'.
Modula-2 sources of this program and JLModules are available. To receive
those text files, please send me a $25 check.


Enjoy 'Fill'!

Jean Lalonde
January ??, 1988


HISTORY
=======

v1.0 (Feb 23, 87):
First release.

v1.1 (Mar 17, 87):
This version accept a non-empty target floppy to copy the
files in sub-directories. You can change, make or remove
directories on the target floppy.

v1.2 (Apr 13, 87):
This version allows to copy given files from various
sub-directories down from a given directory. 'Fill' prompt
you if a file already exists on the target floppy. You
can overwrite, rename or skip this file.

v1.3 (May 12, 87):
Correct a bug from v1.2. Now, 'Fill' will detect when the
target's root directory is almost full (maximum is 112 files).
When 'Fill' counts 111 files, it prompt you to change the target
directory or the target floppy. I also add in this version
a confirmation prompt before escape procedure. From this
version, multiple file names separated by '+' are allowed.

v1.4 (May 23, 87):
Maximum number of files in root is automatically initialized
from boot sector according to your disk drive type (maximum can
be 64, 112, 224, 512 or wathever future DOS compatible drives
manufacturers can define).
Remove prompt for a formatted diskette while loading program.
Option '/F' added to format immediately the first disk.
Correct a minor display bug in "O(ther / M(akeDir / Change to
this directory (y/N) ?" -> default in prompt was wrong.

v1.5 (August 14, 87)
Accepts to copy from multiple drives (eg: "FILL CDE:\*.*") and
multiple filenames with an exclusion list (eg: "FILL
*.*/*.COM+*.EXE"), gives a crude file logging option.

v2.0 (January 4, 88)
Target drives:
-Accepts multiple target drives (eg: with "FILL *.* ABF:", files
will be copied alternatively to A:, B:, F:, A:, B:, ...).
-Targets may be floppy disks (any kind), hard-disk or ram-disk
with any cluster size.
-Option '/F' is removed, 'Fill' automatically runs FORMAT program
whenever an unformatted disk is detected.

Source directories:
-Option '/M' can now mix files from multiple drives.
-'Fill' now show you each directory scanned during the files list
building. You can use '/D' (discrete) option to avoid this.

Attributes:
-Accepts Archive attribute filter with '/A'. This option
allows to copy only files with Archive attribute.
-You can reset the Archive attribute of files copied with
option '/O'.

Log option:
-Option '/L' accepts a log filename (eg: "/L:NAME.XYZ"). See
section called "Logging".

Other new options:
-Option '/B' added to allow buffered keyboard input and disable
escape checking.
-Option '/E' added to allow confirmation for each directory.
-Option '/F' added to allow confirmation for each file.
-Option '/V' added to verify integrity of copied files.
-Option '/K' added to kill (delete) source file.
-"List files" option from main menu will show you remaining
files to copy be size order.

-eof-