.foDSIdCAT - Olympia Page #
.UJ1
.cw10

DSI dCAT - DISK CATALOG PROGRAM in dBASE III


by

P. L. Olympia, Ph.D.
Sysop, DARWIN BBS, 301-251-9206


Users of dBASE II who for years have had to program around its
many limitations are smiling these days - dBASE III has arrived and
with it the computing power that everyone had been clamoring for. It
is a tribute to the versatility of dBASE III that it took very little
time, not too mention very little code, for us to convert many of our
application programs and utilities from traditional programming
languages to dBASE III. Two of our most heavily used programs that
we converted within a week of dBASE III's arrival were an appointment
calendar generator (originally written in "C") and a disk cataloging
system (originally written in assembler).

This article describes DSI dCAT, a subset of our disk cataloging
system that is hereby being released to the public domain. The article
is also partly a tutorial on the new features of dBASE III.


DSI dCAT IN A NUTSHELL

The system allows one to maintain a catalog of files contained on
either floppy or fixed disks. Files contained on the disk's
subdirectory (excluding the . and .. "files") will also be read and
cataloged. Since the system was originally conceived to track diskette
files, it is presently set to handle up to nine subdirectories on a
given disk but not subdirectories within subdirectories. The system
has a user-maintained data base of "exclude" filenames; these are
files which will be excluded from the catalog if they are found on a
disk's directory. Typical examples of such files are COMMAND.COM and
AUTOEXEC.BAT which are usually found on multiple diskettes and are of
no real interest to a catalog system. The number of files that may be
cataloged is one billion - a dBASE III limitation that we cannot
confirm.

The system consists of two command files: (1) DSIDCAT.PRG is the
main driver program that handles the user interface including the main
menu, help, data edits and reports; (2) DSIREAD.PRG is the heart of
the system that takes care of reading the disk directory and loading
the data bases with information obtained from the directory.
DSIREAD.PRG makes full use of dBASE III's power and is described in
detail below.

.cp7
DATA BASES USED

dBASE III allows multiple data bases to be open at one time and
the catalog program takes advantage of that. The four data bases that
the system uses are:


1. DSIFILE.DBF - data base of cataloged filenames and related data
INDEX: Indexed on FILE to DSIFILE
STRUCTURE:

Field Field name Type Width Dec Description
----- ---------- --------- ----- ----- --------------
1 FILE Character 12 File Name
2 FBYTES Numeric 6 Number of bytes
3 FDATE Date 8 Creation date
4 FTIME Character 6 Creation time
5 DISK Character 23 Disk label
6 FCATEG Character 30 Category
7 FDESC Character 50 File Description
** Total ** 136

NOTE: FCATEG and FDESC are added by the user via the EDIT function


2. DSIDISK.DBF - data base of cataloged disks
INDEX: Indexed on DISK to DSIDISK
STRUCTURE:

Field Field name Type Width Dec Description
----- ---------- --------- ----- ----- --------------
1 DISK Character 23 Disk label
2 NUMFILES Numeric 5 No. files
3 BYTESFREE Numeric 7 Bytes free
4 BYTESUSED Numeric 7 Bytes used
** Total ** 43


3. DSIXCLUD.DBF - data base of filenames to be excluded
INDEX: Indexed on FILE to DSIXCLUD
STRUCTURE:

Field Field name Type Width Dec Description
----- ---------- --------- ----- ----- --------------
1 FILE Character 12 File name
** Total ** 13

.cp10
4. DSISCRAT.DBF - scratch data base loaded from redirected
output of the DOS DIR command
INDEX: None
STRUCTURE:

Field Field name Type Width Dec Description
----- ---------- --------- ----- ----- --------------
1 FNAME Character 8
2 FILL1 Character 1
3 FTYPE Character 3
4 FILL2 Character 3
5 FBYTES Character 6
6 FILL3 Character 2
7 FDATE Character 8
8 FILL4 Character 2
9 FTIME Character 6
** Total ** 40


THE SYSTEM IN DETAIL

Figure 1 shows the source code for the main driver program,
DSIDCAT.PRG. The DO WHILE .F. - ENDDO block at the beginning of the
program shows a technique for including a cluster of comment lines in
a dBASE III program without using an asterisk on each line.

The SET SAFE OFF statement prevents dBASE III from asking the
user for permission to overwrite DSISCRAT.DBF each time a new disk to
be cataloged is read from the designated drive. Two of the memory
variables declared public are MDISK (drive where disk to be cataloged
is to be mounted) and MDIR (file to hold the redirected output of the
DOS DIR command). These variables are passed to DSIREAD.PRG; their
values may be changed by the user from a main menu option.

The program begins by asking the user for the drive containing
the system files and programs. This allows for more than one catalog
of files to be maintained on different drives or diskettes.

The system's main menu is shown in Figure 2. I created the
screen using WordStar and then used dBASE III's dFORMAT program to
convert it to an FMT file. I then used WordStar's read file command
(^KR) to include the FMT file in the main program, DSIDCAT.PRG. A
brief explanation of menu choices is provided if the user picks the
H(elp) option. The explanation is shown in the source listing and will
not be repeated here. However, the Z(ap) and V(iew) options introduce
new concepts and are worth discussing.

The ZAP command of dBASE III is an efficient (and dangerous) way
of removing data base records. Its equivalent in dBASE II is the
notoriously slow DELETE ALL and PACK commands.

The V(iew)/Change Report Destination option assigns either a
space to the memory variable MPRSC if the user elects the screen to be
the report destination, or the string 'TO PRINT NOEJECT' if she elects
instead to route the report to a printer. With this technique, we
save a lot of coding just to generate a report. Note that under the
F)ind A File option, we only had to use the statement:

REPO FORM DSIFILE FOR '&MFILEN'$FILE &MPRSC

instead of a more cumbersome alternative such as:

IF PRINTER
REPO FORM DSIFILE FOR '&MFILEN'$FILE TO PRINT NOEJECT
ELSE
REPO FORM DSIFILE FOR '&MFILEN'$FILE
ENDIF


Another technique that the program uses can be seen under the
D(elete) a Diskname option. In dBASE III, values of logical variables
require the surrounding periods as in .T. or .F. Thus, the old dBASE
II code that goes something like this:

STORE Y TO MORE
DO WHIL MORE
...
INPUT 'Delete another diskname? (Y/N)' TO MORE
ENDDO while more

is fraught with danger of generating a syntax error unless the user
always remembers to respond with .Y. instead of just Y (or .N. instead
of N). We avoid that problem by replacing the INPUT statement with
the following:

WAIT 'Delete another diskname? (Y/N)' TO ok
STORE ok$'yY' TO more

The last statement performs the same work as the following five
statements:

IF ok$'yY'
STORE .T. TO more
ELSE
STORE .F. TO more
ENDIF


The program also takes advantage of two new and desirable
features in dBASE III, namely EXIT (to exit from a DO WHILE construct)
and SEEK (a superior alternative to FIND). SEEK allows an expression
to be its argument, so that it is completely valid to have the name of
a memory variable (instead of its value) as the argument. We can say,
for example,

SEEK mvar

while we can only say something like:

FIND &mvar

Although Ashton-Tate warns dBASE III users not to use macros
inside loop constructs such as DO-ENDDO and IF-ENDIF (the claim is
that the speed of execution may be degraded up to 30 percent) we use
macros with impunity because we really do not have any choice - all
our programs are in one giant DO WHILE .T. loop. If there is any
speed degradation, we never observed it. To anyone who has used dBASE
II as long as we have, even a snail looks fast and, besides, dBASE III
is just light years ahead of dBASE II in speed.

Finally, the program contains four statements that use the new
SPACE function to assign a fixed number of blanks (spaces) to memory
variables. The function saves us the trouble of counting (or
miscounting) spaces to assign the variables.


HOW IT IS REALLY DONE

The A(dd) New Disk to Catalog option of the main menu invokes the
command file, DSIREAD.PRG where all the hard work is done. We get an
idea of some of dBASE III's power by examining the source listing in
Figure 3.

dBASE III has DOS-like commands such as TYPE. More importantly,
it allows us to invoke any DOS program from within it (provided that
we have enough memory for both dBASE and the external program). The
approach used by the program is to read a disk directory using the DOS
DIR command and redirect the output of the command to a scratch file
defined by the memory variable MDIR. The actual dBASE III command
that does this is:

RUN DIR &mdisk.*.* >&mdir

The period after '&mdisk' is important because the macro is at the
beginning of a "word" instead of at its end. Assuming that MDISK='B:'
and MDIR='D:DIRSCRAT.TXT', the macro expansion produces the command:

RUN DIR B:*.* >D:DIRSCRAT.TXT

The program then decomposes the standard output of the DIR
command into a form suitable for APPENDing to DSISCRAT.DBF. It also
determines if the disk has a volume ID; if there is no volume ID, the
second line will have the string 'no label'. In that case, the program
asks the user for a disk volume label and places it on the disk header
by way of an external program, CLIP.COM - a public domain program
written by W.C. Bodycomb. CLIP.COM (or a similar program such as
Norton's LABEL.COM) need not be on the current directory if the proper
path has been set to enable DOS to find it.

If the volume label has been encountered before, the user has the
choice of replacing the old entry with the current one or continuing
with a different disk.

The program recognizes that a "file" is a subdirectory when it
encounters the string '' in DIR's output line. It keeps track of
all subdirectories (up to 9 on a given disk) that it has encountered
and reads the files of those subdirectories by invoking the CD and DIR
commands as before.

While the DOS DIR command only gives the number of available
bytes on the disk, the program also computes the number of bytes that
have been used . Both values are stored in the second data base,
DSIDISK.DBF.

We have used this system to catalog more than 4000 files on
diskettes with multiple subdirectories. Clearly, the best performance
is obtained if the system files are on a hard or RAM disk. Copies of
the entire system along with CLIP.COM are available free from the SUGI
SIG/M RBBS (see below for the phone number). You will need a PC
communications program that support the XMODEM protocol. Those
without one can get a starter communications program, with
instructions, also from the RBBS.


FIGURE 2. DSIDCAT MAIN MENU


DSI dCAT MAIN MENU Today: 07/20/84
------------------------------------------------------------------------

SETUP
S) Set Environment Z) Zap/Erase all catalog entries
V) View/Change report destination

DATA ENTRY/EDIT
A) Add or Read a new disk to catalog E) Edit a filename record
D) Delete/List diskname record(s) I) Add a filename to the EXCLUDE file

REPORTS
F) Find a filename in the catalog
L) List all files on a given disk

OTHER
H) Help with these choices
X) Exit this program

Please choose a letter ... : :