XREF



dBASE Program Cross Referencer


Copyright (c)
Bob Yorke
1986,87


32 Patteson Road
Norwich
NR3 3EW
England

Tel: (0603) 667581

ALL RIGHTS RESERVED







dBASE is a trademark of Ashton-Tate
Clipper is a trademark of Nantucket Corp.
1. LICENCE.

The program is released on a 'shareware' basis, which
implies the following:

1.1. Permission is granted to duplicate, distribute and
share the program with anybody who wants a copy,
providing that no charge is made (except user groups
who may cover costs).

1.2. The files must be copied in their entirety, and must
not be modified in any way with the exception of the
.DAT files.

1.3. While I have made every effort to ensure that the
program does what it should, I accept NO RESPONSIBILITY
WHATSOEVER for the ability or inability of anybody to
use the program or its results. What you do with the
program or its output is up to you entirely...

1.4. The shareware concept is intended to fulfill two major
needs: the need of users to try out software for a
decent period before purchase; and the need of authors
to gain a little for their efforts. It is to be hoped
that both parties will benefit equally.

(Now for the bit where I simper and beg for money ...)

I don't want to make huge profits from XREF (it isn't
worth that much). However, it would be nice if I could
recoup enough from my efforts to update my own
development software a little (I have to buy my own -
and not at shareware prices!). This should incidentally
enable me to write better shareware in the future.

If you gain something from the use of XREF - better
productivity; better systems; a simpler life; green
hair - a contribution of whatever you can EASILY afford
would be appreciated. As a nice alternative, and if you
object to sending me money, send a donation to your
favourite charity (but mention my name, I may need them
someday!)

Last point: if you have any (clean) suggestions or
constructive criticisms, I would be glad to hear them.
In addition, if you get stuck, I will be happy to try
to help out - but please remember that I am not a
commercial enterprise, and that I have a wife, two
children (whoopee, make that three!), and two crazy
cats to go home to ...
2. DESCRIPTION.

2.1. XREF takes as its input a 'dBASE-type' program file,
and produces a sorted cross-referenced listing of all
'programmer-defined names' - variable names and
filenames (databases, indexes, reports, etc).

2.2. The program uses a simple binary tree structure to do
its work, which has the advantage that the listing is
already in sorted order when the program produces its
output.

2.3. Memory is allocated dynamically using DOS calls, which
means that the program is able to use all the free
memory which DOS will give it.

2.4. The program has only been tested on IBM XT, AT and
Amstrad PC1512, PC1640 machines. However, it uses no
'dirty' code, and should in theory work on any DOS
machine.

2.5. The following files are included:

XREFUSER DOC --> this documentation
XREF EXE --> executable file
XREF DAT --> 'reserved words' data file
DB224 DAT --> dBASE II 2.4 data file
DB311 DAT --> dBASE III Plus data file
CLIP86 DAT --> Clipper Autumn 86 data file
DEMO BAT --> simple demo batch file
ALLPRGS BAT --> xref all .prgs in directory
TEST PRG --> Program file used for demo
3. OPERATION.

3.1. The program is invoked from the DOS prompt, with a
command tail supplying the name of the file to cross
reference, e.g.,

C>xref filename.prg

3.2. The input file is read, line by line, and everything in
sight is capitalised. XREF then attempts to match each
'word' with a list of dBASE commands previously read
into memory from the file XREF.DAT.

3.3. If the program finds a match in the list of commands,
it increments a count of the number of times that
reserved word has been used.

3.4. If the word is not in the reserved word list, the
program assumes that it has found a 'programmer
defined' word, and stores it away for future reference.

3.5. When a new programmer defined word is encountered, the
program initialises a list of line numbers where that
word has been found.

3.6. If the word has been seen before however, the program
adds the current line number to the list for that word,
thus keeping track of each word and where it is to be
found in the source file.

3.7. Having exhausted the input file, the program produces a
cross referenced listing of programmer defined words,
along with a table showing which dBASE commands were
encountered, and how often they were used. (This makes
it easy to see whether, for instance, a program uses
the REPLACE verb or not).

3.8. Output is by default to the screen, but may easily be
routed to the printer or a disk file by using DOS
redirection (see the DOS manual for full details).
4. RESERVED WORD LIST.

4.1. It is a fact of life that every version of dBASE, and
all of its 'lookalikes', utilize a more or less varied
super/sub-set of commands.

In addition, users of Clipper may implement their own
functions, and wish them to be included in the list of
'reserved words'.

This being the case, it would be a hopeless task to
write a program capable of recognising all of the
commands from every implementation of dBASE, past,
present and yet to come ...

4.2. To circumvent this problem, the list of commands is
stored in a file (XREF.DAT) and may be amended so that
it is possible for the user to customize the program
for the 'version' of the language being used.

There are also 'basic' data files for dBASE II v2.4 and
dBASE III Plus v1.1 which may be utilised. Rename
XREF.DAT to (say) XREF.STD, and rename one of the other
data files to XREF.DAT. Please note though that I do
not use these packages so I have not tested their
completeness or accuracy.

4.3. The mechanics of customization are simple; all you need
is an editor capable of producing a flat ASCII file,
and a definitive list of commands for your
implementation.

The structure of the file is also simple: each word
must appear in ascending ASCII order (see the DOS
'SORT' command if this is a problem); each word must
start in the first column of a new line; there must be
no blank lines; there must be nothing else in the file
apart from the above; there is a limit of 500 words in
the current implementation (this should be plenty).

4.4. Please note the trailing left bracket after function
names - e.g., ABS( - and the trailing period after
logicals - e.g., NOT. - which must be present if your
version of the language uses them. It is a good idea to
print out the supplied XREF.DAT, and/or perhaps copy
this file to one called (say) XREF.STD before editing
it.

4.5. In addition, please note carefully that function names
which are the same as command names must be included
separately, along with a trailing left bracket - for
instance the command IF is a different beast from the
function IF().

4.6. One 'problem' is defining your list of commands.

The easy way around this is to start with a blank file.
Type in as many dBASE words as you can think of, run a
good selection of dBASE programs through XREF, and look
for dBASE words in the cross reference listing. When
you encounter a word or words you have forgotton,
simply edit XREF.DAT to include the missing word(s).

Thus, missing commands out of XREF.DAT will not
predjudice the operation of the program - you will
simply find them in the cross reference listing, where
they may be recognised and added to XREF.DAT to correct
the situation for next time.

4.7. A potentially more serious problem will occur if you
are in the habit of using dBASE commands for your
variable and/or file names. The program will think your
variable or filename is a dBASE word, and will not
cross reference it.

The only solution to this one is to think up your own
variable names, instead of pinching them from dBASE!
5. SHORTCOMINGS.

'Of these, there are a few, but then again ...'

There are (as always) one or two shortcomings of which I am
aware, but have not yet had the time to remedy. There are
undoubtedly more that I have not thought of (let me know).

5.1. The program only accepts single filenames on the
command line - no wildcards. This is intentional, as it
is intended for use from within batch files. See the
example batch file included.

5.2. The program is not 'context sensitive' - it does not
attempt to determine whether a 'word' is a variable
name (STORE something TO memvar), a filename (USE
filename), or anything else, from its context.

This is the reason you will get spurious results if (as
mentioned above) you choose to use dBASE words to name
your variables or files with.

5.3. No temporary disk files are created, all operations
being carried out in memory.

This has the advantage of simplicity, but means that
the size of input file which can be handled is finite.

For machines with limited memory this may be a problem,
the only answer being to split the input file into
smaller units. But then again, perhaps an extremely
large file should be split into smaller chunks ...

5.4. The output produced takes no account of the device to
which it is directed - again intentional. The program
was intended for use with DOS redirection, output going
to disk files for later printing.

If you choose to route output direct to the printer,
the program will blithely print over the perforations.

The sole concession to formatting is that the program
outputs a form feed at the end of each listing; this
means that each new listing will begin on a new page if
sent to the printer.

5.5. The program is NOT a syntax or structure checker; what
checks it does perform are simply a by-product of its
own work, and should not be relied upon to (say) check
that strings are delimited correctly.

5.6. The program 'ignores' single character commands, such
as ? @ ! etc. Their use is not reported in the 'command
usage' list.
6. KNOWN 'BUGS'.

Or 'things I did not think of ...'

I have only tested XREF on Clipper Autumn '86 files, and in
addition, only on my own code (which tends to be
predictable, consistent and therefore not much good for test
purposes).

As an example, I never use the 'NOTE' commenting feature, as
I never felt like typing NOTE rather than using an asterisk.
However, if it proves to be widely used, I will include it
in a future release of XREF.

There are undoubtedly going to be other problems thrown up.
Let me know as and when you find them, and I will try to
sort them out.

6.1. As mentioned, the program does not handle the NOTE
command - at least I don't remember including it ...

6.2. The program does not detect unmatched quotes on
continuation lines - or rather, it does, and bombs out
with (surprise, surprise!) an 'unmatched quote' error.
The solution is to have opening and closing quotes,
even on continuation lines.

6.3. A related problem is that it treats an apostrophe on an
ENDIF line as an unmatched quote. Solution is to use
comment lines instead.

(Thanks to Ariela Pomerance for spotting the latter two)

7. MESSAGES.

Fatal Errors:

xref: usage >xref

Cause: the command line you typed was incorrect in some way.
Check it and retype.

xref: can't open

Cause: the program cannot locate the input file specified on
the command line. Have you included the complete path?

xref: can't open xref.dat

Cause: the program cannot locate the data file XREF.DAT in
the default directory.

xref: symbol space exhausted
xref: snode space exhausted
xref: lnode space exhausted

Cause: not enough memory to process the input file - DOS
won't give any more memory to the program.

Warnings:

Line: nnn duplicate TEXT statement

Cause: the program has already detected a TEXT statement,
and has now found another without an intervening ENDTEXT.

Line: nnn duplicate ENDTEXT statement

Cause: the program has already seen an ENDTEXT statement,
and has subsequently found another with no intervening TEXT
statement.

Line: nnn unmatched '
Line: nnn unmatched "
Line: nnn unmatched [
Line: nnn unmatched ]

Cause: the program has found a beginning quote character,
but has not detected an end quote before reaching the end of
the current line.

EOF: mismatched TEXT ... ENDTEXT

Cause: the program has found a TEXT statement, but has
reached the end of the file without encountering a matching
ENDTEXT statement.