The QL Toolbox '98 Collection
-----------------------------

MakeDirs - Reconstruct a Directory Tree
---------------------------------------
MakeDirs is the companion program to DirList.

DirList and MakeDirs are two utilities to assist with backups, restores, and
reorganisation of Hard Disks and other devices which support Level 2
directories. Like the other utilities in the Ql Toolbox '98 collection these
programs can run as full-blown Pointer Environment applications, or will
happily run in command-line mode from a shell program, or S*BASIC's EX/EW
commands.

Both utilities were compiled with QLiberator, although they started out life
running uncompiled under SMSQ. They have been subjected to some (limited)
testing under both JM QDOS and Minerva.

This utility operates in the reverse direction to DirList, reading the
contents of a plain text file (as created by DirList) and re-creating the
directories on the Target. By default, the Target will be the same as that
specified in the file (the first line). However, if you select a different
Target in the program, the directories will be created there, instead.

The function of each of the items in MakeDirs' window is described in this
section. The "standard" items such as Move, Quit, and Sleep are not
covered here as their operation is standard for almost every Pointer
Environment program.

Info
----
Info can be called up by [F1], and just shows information about the program.
This currently just shows the version number and construction date.

Source
------
Specify the name of the directory list file (as created by DirList) that
MakeDirs is to process.

Target
------
Specify the device and/or directory where the directory tree is to be
re-created. This must be a valid device, or Level 2 Device Driver directory,
extended filenames are not acceptable.

Test
----
The Test option, if selected, enables you to try out a file without
actually creating any directories. The output window will show you what
directories would have been created. This option tests the directory
tree on the target device and counts the number of directories that are
not present, but which would be created by running the program (with
Update selected).

Case
----
You can optionally choose to have the case of the directory names shifted
into Upper, Lower or Mixed case. (My personal preference is to use upper
case for all directory names).

Fr Scrap
--------
Selecting "From Scrap" causes MakeDirs to read the directory list from the
scrap instead of from a List File. The information in the Scrap must be in
the same format as a list file. DirList can send the list straight to the
Scrap, which opens up the possibility to automate directory tree cloning
using both programs.

To Scrap
--------
In this program, the To Scrap option may be selected to send a list of the
directories that were created to the Scrap, instead of to the output
window.

Update
------
The Update item, if selected, creates just the directories on the target
that do not exist. This is useful for synchronising two devices.

The User Interface for these programs is, I hope, fairly standard, and set the
standard which the other QL Toolbox '98 utilities follow. Here are some basic
principles for working with the programs ...

A DO on the title to the left of a field will call up either a File or
Directory Selection dialog, as appropriate.

A DO on the field itself, will have the same effect.

A HIT on a field enables you to directly edit the field contents.

Whilst editing a field, most of the standard QDOS editing keys work
as expected. But there are some additional keys which are worth knowing
about. (All QL Toolbox '98 utilities use the same field editor):-

[SHIFT]+[SPACE] (Normally the [INSERT] key on a PC keyboard) toggles between
insert and overwrite modes.

[CTRL]+[S] will insert the contents of the scrap at the current cursor
position. Be careful with this, the Scrap can hold a LOT of data!

[CTRL]+[SHIFT]+[S] puts the current contents of the edit buffer into the
Scrap, overwriting anything already there.

[CTRL]+[SHIFT]+[H] puts the current contents of the edit buffer into the
HotKey System II Stuffer Buffer.

[CTRL]+[SHIFT]+[F] calls up the Menu Extension's Character Select dialog,
allowing you to select any character to insert at the current cursor
position.

Command Line
------------
MakeDirs will accept a command line in the following format:

  ListFile TargetDirectory

Both parameters are optional, but you cannot skip one. If you supply
a Target Directory you must also specify the List File. You can
supply a single backslash character for the Target, in which case the
current Data Default will be used.

Additionally, switches may be included at any position in the command
line:-

  /X    If enough information has been supplied in the command line
        this causes MakeDirs to do its job and then immediately exit.

  /B    Execute the program entirely in background mode. The /X switch
        must also be supplied to use this option, which will result in
        the program running without displaying any window. No dialog
        boxes will be displayed, and any confirmation requests will
        default to YES.

  /W    Used in conjunction with /X, this causes the program to pause
        on completion and display a message box.

  /F    Selects the "From Scrap" option.

  /S    Selects the "To Scrap" option.

  /T    Selects the "Test" option.

  /U    Selects Upper Case.

  /L    Selects Lower Case.

  /M    Selects Mixed Case.

  /A    Chooses Update mode (only add new subdirectories).

  /0    Ignore any channels that have been passed (see note below).
        This facility is only useful in cases where the program has
        been launched by a shell that automatically sets up the three
        channels stdin, stdout and stderr.

Examples:

  EX 'MakeDirs';'/x'

  With the program as supplied, this will (try to) create the
  directory tree on WIN1_ that is listed in the file RAM1_DirNames.

  EX 'MakeDirs';'FLP1_DirNames WIN1_ /u /x'

  Re-create the directory structure from another hard disk, but
  change all the directory names to upper case. (Obviously, DirList
  must have been used to create the file FLP1_DirNames originally).

  EX 'MakeDirs';'/t /x'

  See what will happen when you try and re-create the directory
  structure listed in RAM1_DirNames.

Like DirList, you can pass a channel to MakeDirs using the EX or QX
commands, in which case it will be used as the input from which the
directory list is read. when this is done, the Source cannot be edited
and From Scrap will be disabled. The Source field will show the Long
Word Channel ID of the source ...

  OPEN_IN #3,'FLP1_MyList'
  EX 'MakeDirs_obj',#3

By using the EX .. TO .. facility in the Toolkit II EXecute command it
is possible to pipe the output from DirList directly into MakeDirs -
thus making it possible to clone directory trees in a single step. This
example clones the directory tree from WIN1_ to WIN2_ ...

  EX 'DirList_obj';'/x /b' TO 'MakeDirs_obj';'nul WIN2_ /x /b'

... Note the use of nul as the source filename for MakeDirs. In fact, in
this example, you can put any string you want here, as it will be
ignored (but you must put something there). This is because EX opens a
PIPE to take the output from DirList, and passes the channel ID of the pipe
on to MakeDirs.

If three channels are passed, these are taken to be stdin, stdout and
stderr, and the program assumes that it has been launched from a UNIX-like
shell and should act as if it were a simple command-line utility. In
these circumstances, the /X and /B switches are automatically forced on.

Revision History
----------------
0.50    01/02/1998      First release
0.51    05/02/1998      Fixed bug that refused to accept a list file
                        whose root line was longer than just a device
                        name
0.60    07/02/1998      Allowed HITs on fields to directly edit their
                        contents
                        Now displays the root as stored in the selected
                        list file
                        Better error trapping (i.e. There is some!)
0.61    11/02/1998      Fixed bug with [DEL] key when editing
                        a field
0.70    17/02/1998      Added Mixed Case option (thanks to Phil Borman for
                        this suggestion).
                        Added Update facility.
                        Test options now checks existing directory tree.
                        Program can now accept an existing channel (another
                        suggestion from Phil).
0.75    23/02/1998      Added support for /B switch.
0.80    01/03/1998      Copes with multiple channels passed
                        (i.e. stdin, stdout, and stderr)
Configuration
-------------
MakeDirs can be configured using the Level 1 or Level 2 Config program. The
name of the directory list file can be set (it is RAM1_DirNames as supplied).

Acknowledgements
----------------
The program is compiled using QLiberator v3.33 with the 3.36mod runtimes.

Note: MakeDirsRT_obj also includes bound QLiberator runtimes.

License Terms
-------------

You are granted a license to use and distribute this software. The
terms of this license are stated below.

Provided that credit is given to the author, and that such credit is
included in any accompanying documentation, whether it be on written
or electronic media ...

1) This program may be freely distributed.

2) This program and its documentation may be incorporated as part of
another package, so long as it does not form the major or substantial
part of such package, and so long as, when taken in combination with
other programs supplied by the author under the same terms, the programs
together do not form the major or substantial part of that package.

3) The executable(s) may be modified, or patched, as necessary, to suit
different target environments. However, where such alterations are made,
and the executables are distributed, details of these changes must also
be included in electronic or written form.

No charge may be made for this program, other than reasonable costs of
electronic media and data transmission to facilitate its distribution.

The author gives no warranty as to the suitability of the program, or
the accuracy of the documentation. The programs are supplied 'as-is'.
It is the responsibility of the user to establish whether the program
is suitable and safe to use in his/her environment.

The author accepts no responsibility for any data that is lost or
corrupted as a result of using this program.

The author will make his best endeavours to fix any problems that are
reported to him, but does not accept an obligation to do so. The author
may be contacted via the E-Mail address quoted at the foot of this
document.


Adrian Ives
ADIves@aol.com
01/03/1998
