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

DirList - Create a list of Directories
--------------------------------------
DirList is the companion program to MakeDirs.

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.

DirList creates a list of directories present below the specified root,
writing the output to a plain text file. The file contains, first, the
root directory, then the directories that were found below it. Note that
DirList always sorts the directories into ascending alphabetical order.

The function of each of the items in DirList's 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.

Root
----
Specify the root directory from which to start. This can be just a device, such
as WIN1_, or a full directory, but note that it is a feature of this program
that only a true Level 2 Device Driver directory is accepted - extended
filenames will not do.

Target
------
Specify the file that you wish to hold the list of directories.

To Scrap
--------
Selecting "To Scrap" sends the output to the Scrap instead, from where it
can be pasted into another application (QD, for instance).

List
----
This is only enabled if you have specified a valid root directory. DOing or
HITting it will create the list. Progress messages are shown in the output
window.

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
------------
DirList will accept a command line in the following format:

  RootDirectory TargetFile

Both parameters are optional, but you cannot skip one. If you supply
a Target File you must also specify the Root Directory. However, you
can supply a single backslash as the Root Directory, in which case
the current Data Default is 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 DirList to do its job and then immediately exit.
        If the TargetFile is specified (in the command line) as CON,
        and the /X switch is used, the program will just list the
        directories to the output window and pause before exiting.

  /B    Used in conjunction with /X this causes DirList to execute
        entirely in the background without displaying any window.
        No dialogue boxes will be displayed, and any confirmation
        requests will default to YES.

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

  /S    Selects the "To Scrap" option.

  /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 'DirList';'/x'

  With the program as supplied, this will create a file called
  DirNames on RAM1_, containing a list of all directories on WIN1_.

  EX 'DirList';DATAD$ & ' /s /x'

  Put a list of all directories below the current data default into
  the scrap.

Optionally, you can pass a single channel to DirList using the EX or QX
commands. This channel is where the output will be sent instead of
going to a target file. When this option is used, the 'To Scrap' item
cannot be selected, and the Target cannot be edited - it will hold the
Long Word channel ID of the output.

This example sends the output to a Named Pipe (SMSQ or NPipe_Rext is
needed).

  EX 'DirList_obj','PIPE_DirNames_1024'

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'

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.

Configuration
-------------
DirList can be configured using the Level 1 or Level 2 Config program. The
default root directory may be specified (default WIN1_), as can the name to
which the directory list is sent (RAM1_DirNames as supplied).

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

DirList uses the TREE command from the WD_bin file as supplied with the
QUBIDE interface (I think this was written by Phil Borman). This extension
is bound into the file, as is the QJump Pointer Toolkit.

Note: DirListRT_obj also includes bound QLiberator runtimes.

Revision History
----------------

DirList
-------
0.15    01/02/1998      First Release
0.20    07/02/1998      Allowed HITs on fields to directly edit their
                        contents
                        Better error trapping (i.e. There is some!)
0.21    11/02/1998      Fixed bug with [DEL] key when editing
                        a field
0.30    17/02/1998      Added support for passing an existing channel.
0.35    23/02/1998      Added support for /B switch.
                        (Version uploaded to Bulletin Boards displayed
                        incorrect version number on Info button, but the
                        right one using Config!)
0.40    01/03/1998      Copes with multiple channels passed
                        (i.e. stdin, stdout, and stderr)

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
