TD - A Tree Directory Tool




Copyright 1984 by John Falconer

*** All Commercial Rights Reserved ***


The author dedicates this program to the public domain. It may
be freely distributed and used for non-commercial purposes. If
you find personal value in the program you are encouraged to help
defray the cost of its developement by sending a small contribu-
tion to the author. Please direct suggestions, bug reports, and
any contributions to:

John D. Falconer
2012 Cambridge Drive
Alameda, CA 94501

(415) 521-7245
Compuserve 72435-1617


The source code for this program was compiled with Borland Inter-
national's Turbo (TM) Pascal compiler, with assembly language
additions assembled with Microsoft's MASM macro assembler.


1. Overview:

TD is a directory listing program with features designed to
simplify the use and cataloging of files stored on MS-DOS or PC-
DOS systems using tree-structured directories.

Features include:

- Access to all directories of a disk
- All features accessible from the command line
- Default configuration easily customized by user
- 3 different basic modes of output: full, tree, and wide
- Automatic logging to a directory holding a specified file
- Return of information to DOS's environment
- Alphabetic sorting of directories with a common parent
- Sorting of file entries by name, extension, size, or date
- Changing or adding volume names
- Optional display of hidden and system files
- Optional pause at full screens
- Output formats for dBASE II and dBASE III










1





TD - A Tree Directory Tool




2. Output Modes:

A. Full listing (default):

In its default mode, TD will search all subdirectories of a
disk for files meeting the ambiguous or unambiguous drive,
path, and file specification given on the command line. All
subdirectories containing files matching the command line
specification will be listed in alphabetical order, with all
matching files listed in alphabetical order within each direc-
tory. These listings will be in a fixed-field-length format
showing the path along which each listed entry was found. The
detailed output of this mode is sent to the standard output
file and may be redirectd.

B. Pictorial Tree:

An alternative output, directed only to the console, will,
when selected with the "T" switch on the command line, appear
as a graphic "tree", with the number of matching files found
in each directory indicated within square brackets. This
"tree" shows at a glance the structure of a volume and the
location of sought files. If a color graphics display is
used, directories which contain files matching the command
line specification will appear in green, while the others will
appear in yellow. The currently logged directory will be
marked with a pointer which will appear in red on a color
graphics display.

C. Wide (abreviated) listing:

Another alternative output is TD's "wide" listing. This is
selected with the "W" switch on the command line. In this
mode, TD's output will include only the file name and exten-
sion for every matching file. Directories will appear in
alphabetical order and the files within each directory will be
listed according to the currently selected sort mode. The
currently logged directory will be marked on the screen with a
pointer, but this pointer will not be included in the redirec-
table output. The detailed output of this mode is sent to the
standard output device and may be redirected.














2





TD - A Tree Directory Tool




3. Options (switch settings on the command line):

A - Add a volume name if none exists

When this option is switched on, TD will prompt for a volume
name if no volume name is currently assigned. This can be
useful when preparing a catalog of diskettes; most disks will
probably already be labeled and this option will prompt for
labels only for those which are not. This option defaults
off.


B - Batch: return NAM, ERR, SPC, SIZ

When this option is switched on, TD will return values to
variables maintained in the DOS environment. This feature is
meant to be especially useful to programmers who are custo-
mizing a system with batch files. For instance, if a backup
procedure has been designed using TD's environment variables,
it is easy to ensure that a user has the backup disk in the
right place at the right time, and that there is enough room
on it to receive the files being transferred. The variables
returned by TD are as follows:

NAM will return with the name of the volume.

SPC will return with a string containing the number of free
bytes on the disk.

SIZ will return with a string containing the number of bytes
used by files which meet the filespec given to TD.
ERR will contain a number corresponding to the following
conditions:

0 .. normal, if a file was sought, it was found
1 .. no find, couldn't find the specified file
2 .. unable to log to new directory
3 .. both of the two preceding
4 .. drive specified not available.

This option defaults off.













3





TD - A Tree Directory Tool




Here is an example which makes use of TD's ability to return
the volume ID's to keep a casual user from making a mistake
when backing up an important disk:

rem BATCH file VOLBACK.BAT
rem This file will verify that the user has placed the proper
rem volumes in the A: and B: drives for file copying.
rem
rem USE: volback sourcename destname
rem
rem Where sourcename and destname are volume ID's.
rem
echo off
cls
echo Please place %1 in A: and %2 in B:
pause
:GS
set VOL=A:
set MAT=%1
set FLT=GS
set RET=GD
goto SUB
:GD
set VOL=B:
set MAT=%2
set FLT=GD
set RET=OKS
goto SUB
:OKS
copy a:*.* b:
for %%1 in (VOL MAT FLT RET) do set %%1=
goto end
rem subroutine here uses TD
:SUB
td %VOL%:/bqx
if %NAM% == %MAT% goto %RET%
echo The disk in %VOL% is %NAM%, not %MAT%.
echo Please remove %NAM% and insert %MAT%.
pause
goto %FLT%
:END
cls













4





TD - A Tree Directory Tool




C - Continue until user quits

When this option is switched on, TD will perform its duties
on a disk in the default or specified drive, and then prompt
the user to insert another disk, repeating this process until
the user indicates a desire to quit. This is very useful when
sending listings to a textfile for cataloging purposes. Cata-
loging an entire library is reduced to the simple task of
removing and inserting disks when TD prompts (and beeps).
This option defaults off.

D, E, N, S - sort by Date, Extension, Name or Size

These options determine the order in which files are listed
within each directory. The date sort is performed so that the
time of file modification is considered in addition to the
date. The default sorting method is by name.

H - Hidden files

When this option is switched on, TD will list hidden and
system files in addition to other files. This option defaults
off.

L - Log to directory with match

When this option is switched on, TD will search for the
file(s) matching a filespec, and then log the searched disk to
the last directory in which a match was found. This can save
time and typing when working from the command line. For
instance, you may know that WS.COM is a file in the directory
you want to log to on your hard disk, but not remember the
complete path specification to it. Just type "td ws/ql" and
TD will log in to the directory where "ws" is found (the "q"
switch will suppress TD's output, as explained below). Used
in a batch file, this option can automatically log users into
subdirectories appropriate to their work; without the users
needing to know what subdirectories are. This option defaults
off.

O - Omit volume name

When this option is switched on, TD will omit the volume
name in the detail portion of listings. When switched off,
volume names will be appear at the beginning of path names,
allowing the unique identification of each file for cata-
loging. This option defaults on unless either of the dBASE
options has been switched on.







5





TD - A Tree Directory Tool




P - Pause at full screen

When this option is switched on, TD will pause at each full
screen and display a message asking the user to either
continue or quit. This option is effective only with TD's
default (full) and wide listings. This option defaults on
unless either of the dBASE options has been switched on.

Q - Quiet output

When this option is switched on, TD will suppress its output
to the screen. This option is included so that batch files
and other programs may call TD to change directories or get
results back through the environment variables, without dis-
trubing their own screen displays. This option defaults off.

T - Tree display

When this option is switched on, TD will display a pictorial
tree on the console. In this mode each level of a directory
structure will be listed on one line, with the directory's
name and the number of files in that directory which match the
filespec listed next to the directory name. Subdirectories
with common parents will be listed in aplhabetical order. A
pointer (in red on a color display) will indicate the cur-
rently logged-in directory, and (on a color display) the
directories with matches will appear in green while all others
will appear in yellow. This mode is limited to displaying 5
levels of a directory structure because of the 80 column limit
of the screen. However, as many levels as are necessary may
be displayed by starting the display at a lower level than the
root. This option defaults off.

U - Unsorted

When this option is switched on, TD will perform no sorting
of directories or files. TD's sorting is fast enough for most
purposes. However, when cataloging large disks, the directory
information may be taken in an unsorted form and the sorting
task deferred for the data manager. This will speed up the
capturing of entries somewhat, although the real limit to the
process is the slow speed of DOS's redirectable output. This
option defaults off.












6





TD - A Tree Directory Tool




V - Volume name change

When this option is switched on, TD will prompt for a new
volume name. If no name exists, one may be added. Pressing
the return key in response to the prompt will leave the old
name intact. Note that DOS's rules on volume names are not
enforced by TD. This makes things a bit more flexible, but
taking advantage of this flexibility (for instance, including
spaces in volume names) may cause trouble with other programs.
Names are restricted to 11 characters. This option defaults
off.

W - Wide listing

When this option is switched on, TD will restrict its list-
ing to blocks of filenames and extensions, where each block
represents a directory. The directory blocks are presented in
alphabetical order of directory name, and the files within the
blocks will appear according to the currently-selected sort
mode. From the command line, this is the most convenient mode
to use with TD. It allows more information on the screen and
operates faster than the full listing (default) mode. This
option defaults off.

X - eXclude other directories

When this option is switched on, TD will stop looking for
files after it has finished looking through the directory it
started looking in. This is included to keep TD from churning
through all the directories on a disk when it is known in
advance that the search should be restricted to one directory.
It is also useful in speeding up TD's operation in situations
where only the environment variables are of interest (as in
the batch file shown in the section on batch variables). This
option defaults off.

2, 3 - dBASE II or III SDF

If either of these options is switched on, TD will format
its output to be suitable for direct pick-up with the dBASE II
or dBASE III data base management programs from Ashton-Tate.
Please see the section on using TD as a tool for cataloging
files for a complete discussion. This option defaults off.

? - help

Selecting this option will cause TD to present a help screen
listing the switch options supported.







7





TD - A Tree Directory Tool




4. Using TD as a tool for cataloging files:

TD's default redirectable ASCII output may be picked up with
dBASE (or other general purpose file handlers) to create a useful
master catalog. An example of this master catalog application
may be had by starting TD with the following command line:

td b:\/cah2>>catalog.txt

This will cause the repeated listing of all files at or below
the root level for any diskettes placed in drive B. Additional-
ly, the switch settings shown in the example will cause the
program to prompt for a volume name for each diskette which does
not already have a name, and to include any system or hidden
files in the directory listing. Because the "2" switch is used,
the directory listings in the "catalog.txt" file will be in an
SDF format suitable for direct pick up with a dBASE II file
having the following fields:

VOL:PATH C 37
NAME C 8
EXT C 3
SIZE N 8
* DATE C 8
TIME C 8

( * make this a D field with dBASE III and use the /3 switch )

The loading of the data into dBASE is done with the command:

append from catalog.txt sdf

This will load the dBASE file with the directory entries. This
allows the full power of dBASE to be used in identifying dupli-
cate files and out-of-date copies of data or source code.




















8





TD - A Tree Directory Tool




5. Use of TD in place of DIR:

TD may be used in place of DIR, gaining the ability to search
an entire disk for files with just one command. Here are a few
examples:

COMMAND RESULTING LISTING
------- -----------------
td Files on current drive at or below the current
directory (no hidden or system files will be
shown, the output will be sorted within each
directory by file name, and the output will
pause at each full screen). Note, this may
be overridden by a option string stored in the
DOS environment as explained below.
td \ Files on current drive at or below the root
td \/w All files, but just the names and extensions
td \/t All directories, in tree format
td \/p All files, but with no pause at full screens
td \/q Environment variables only, no screen output
td /x Files in the current directory
td ??/x Files with one or two-character names in the current
directory
td td Files at or below the current directory which match

td.*
td b:\.com COM files on B:
td b:\util\/x Files in B:'s UTIL directory
td b:\util\.com COM files in or below B:'s UTIL directory
td \.doc/ql Logs the current drive into the last
directory which holds a *.DOC file

























9





TD - A Tree Directory Tool




6. TD's use of the DOS environment for options:

Typing TD's frequently used command line options can become
tedious. So, TD takes advantage of the DOS environment to store
a string of default command line options. These environment
options provide a convenient way to indefinitely modify TD's
behavior. Until they are cancelled, the options stored in the
environment will be used in place of, or in addition to, whatever
is typed on the command line when TD is started. To set the
environment options, use the DOS SET command. The format is SET
TD=[/options]. For example:

SET TD=b:/th.

This set of options will cause TD to give a pictorial tree of
the disk in the B: drive, listing system, hidden and normal files
whenever "td" is typed.

TD will append the environment options to options typed in on
the command line if the first character of the environment option
string is a "+". For example:

SET TD=+/wha.

This set of options (which I set in my AUTOEXEC.BAT file) will
be appended to whatever is typed in on the command line. So,
typing "td b:" will cause TD to give a wide listing of B:,
showing hidden, system and normal files, and prompting for a
volume name if none exists. Because the environment options are
appended to the command line options, some program behavior will
only be available after clearing the options in the environment.
To do this type "SET TD="

Remember that DOS sets aside only a small environment area at
boot time. If problems are experienced using the environment
options the environment is probably full. If the environment is
full, either some variables (or overly long PATH or PROMPT
strings) must be eliminated or the environment must be expanded.

7. Restrictions:

TD's output format is designed for 80 column displays. This
limits the total number of characters which may be properly
displayed from the combined volume and name path to 37. It also
limits the properly formatted display of "trees" to a depth of
five levels.

8. Contradictions:

If contradictory switch settings are specified on the command
line (for example, two sort methods) then the last-specified
setting will be used.



10