Contents of the TD.DOC file

TD - A Tree Directory Tool

Copyright 1984 by John Falconer

*** All Commercial Rights Reserved ***

The author dedicates this program to the public domain. It maybe freely distributed and used for non-commercial purposes. Ifyou find personal value in the program you are encouraged to helpdefray the cost of its developement by sending a small contribu-tion to the author. Please direct suggestions, bug reports, andany 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 languageadditions assembled with Microsoft's MASM macro assembler.

1. Overview:

TD is a directory listing program with features designed tosimplify 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:

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 withdBASE (or other general purpose file handlers) to create a usefulmaster catalog. An example of this master catalog applicationmay 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 belowthe root level for any diskettes placed in drive B. Additional-ly, the switch settings shown in the example will cause theprogram to prompt for a volume name for each diskette which doesnot already have a name, and to include any system or hiddenfiles in the directory listing. Because the "2" switch is used,the directory listings in the "catalog.txt" file will be in anSDF format suitable for direct pick up with a dBASE II filehaving 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. Thisallows 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 searchan entire disk for files with just one command. Here are a fewexamples:

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

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

SET TD=b:/th.

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

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

SET TD=+/wha.

This set of options (which I set in my AUTOEXEC.BAT file) willbe 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 avolume name if none exists. Because the environment options areappended to the command line options, some program behavior willonly 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 atboot time. If problems are experienced using the environmentoptions the environment is probably full. If the environment isfull, either some variables (or overly long PATH or PROMPTstrings) must be eliminated or the environment must be expanded.

7. Restrictions:

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

8. Contradictions:

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