PART I.
RECOGNIZING DATA RELATIONSHIPS
by Wilson Ng

After writing programs for a while, you will notice that your data gets more
and more unwieldy.  Sometimes you lost track of your field names, and the
relationships with each other is lost to you.  If I edit ITEM CODE here, how
many other database files do I have to change too?  Many times, we forget to
change fields that are related. Alas!  Many of us do have the undesirable
habit of naming variables and field names as we go. There are three possible
confusions:

1.) Field names in different files that are supposed to represent the same
thing, but called by different field names.  For instance, there is the
error of using CUST_CODE in one database file, and of using CUSTCODE in the
other.

2.) Field names that are supposed to represent different things, but end up
with the same names.  For instance, we could get confuse when we see the
name CODE in two database files, where one is used to represent items, while
the other is used to represent the supplier.  Or the field name DATE seems
to crop up in almost half of our database files.  Some are delivery dates,
some expiry dates, but they are all called DATE, and it becomes really
exasperating when you start to encounter it while editing or debugging.

3.) Field names represent the same entities, and have the same name, but
have different lengths.  After finishing scores of customized inventory
programs, we now have suppcode that are five, six, seven, eight and nine
characters.  Sometimes it gets confusing, and on the same program, you could
have a field  with different length from the other.

If you have experienced the above problems, (and it becomes compounded when
you do workgroup programming),  the following program could help.  It does
so by helping you to recognize relationships.  It does the job by
automatically tagging field names with the same name, and if two database
files should have a common field name, it tags the two databases as possibly
related databases.

For instance, let us have an example of these three databases.


Structure for database: INVOICE.DBF
Field  Field Name      Type       Width    Dec    Index
    1  INVNO           Numeric        6             Asc
    2  COST            Numeric       10      2     
    3  DATE            Date           8             Asc
    4  TERMS           Character     10            
    5  TOTAL           Numeric       11      2     
    6  CUSTCODE        Character      4            
** Total **                          50

Structure for database: ITEMS.DBF
Field  Field Name   Type           Width    Dec    Index
    1  ITEMCODE     Character         4            Asc
    2  ITEMDESC     Character        25
    3  ONHAND       Numeric           3
    4  TOT_ORDER    Numeric           3
    5  LASTSOLD     Date              8
    6  COST         Numeric          10      2
** Total **                          54

Structure for database: CUSTOMER.DBF
Field  Field Name  Type         Width   Dec    Index
    1  CUSTCODE    Character      4            Asc
    2  CUSTNAME    Character     25            
    3  ADDRESS     Character     20            
    4  CITY        Character     15            
    5  GOOD_CUST   Logical        1            
    6  TERMS       Character      8            
    7  TOTAL       Numeric       11      2     
** Total **                      85


After creating these data files, and making sure that they are the only
database files on your directory, run the program (2techdoc.PRG).  You need 
to input one parameter, the name of the file that will contain the text
definitions of the database file.  For example, let us assume we run it by
inputting "do 2techdoc with 'test1.str'".  This program will run and create
the definitions.  When you open the test1.str file with your editor, what
you will see will be similar to below:
Ŀ                                                                                                                                                     
FILE#   1                                                                                                                                                     
...Ŀ                                        
 FILE@ CUSTOMER               ...                                                                          
...Ĵ                                        
INDEX@ CUSTCODE  CUSTCODE     ...                                                                          
...Ĵ                                        
RELA@  INVOICE                 ...                                                                          
...Ĵ                                        
 FIELD NAME TYPE WIDTH DEC  ... RELA  RMRKS       PROMPT                                               
...Ĵ                                        
~ CUSTCODE    C    4    0   ... 1-2        CUSTCODE                                                    
~ CUSTNAME    C   25    0   ...            CUSTNAME                                                    
~ ADDRESS     C   20    0   ...            ADDRESS                                                     
~ CITY        C   15    0   ...            CITY                                                        
~ COUNTRY     C   10    0   ...            COUNTRY                                                     
~ GOOD_CUST   L    1    0   ...            GOOD_CUST                                                   
~ TERMS       C    8    0   ...7-2         TERMS                                                       
~ TOTAL       N   11    2   ...8-2         TOTAL                                                       
...                                        


The program had automatically tagged for you that the possibly related file
of customer.dbf is invoice.dbf.  A closer look will reveal that they have
three fields in common, CUSTCODE, TERMS, and TOTAL.  This can be found by
studying the numbers under the RELA column. The RELA column of custcode says
1-2.  1 is an index number.  The 2 indicates that there are a total of two
fields among those analyzed files that have the same field name.  Since
Invoice is the only related file, the fastest way to seek that field name
would be to go to invoice file and seek out any field that would have also
1-2 under the RELA column.

Now, writing code will be easier with this automatic cross checking feature,
and we can now analyze possible errors.  A brief examination will quickly
give you the following possible incongruities:

1.) TERMS in Customer file have 8 chars, while TERMS in invoice have 10
chars.

2.) TOTAL in Customer file and TOTAL in invoice file is not supposed to be
related.  TOTAL in customer file would mean that field probably stores data
about the total purchase of that customer, while TOTAL field in invoice
would probably mean the total value of that invoice.  To counter this
mistake, maybe we can change TOTAL in invoice to INVTOTAL?

3.) Again, COST in items, and COST in invoice are not supposed to be
related?  Or are they?

Thus, running the program had helped us catch three possible errors, as well
as informing us, that since CUSTCODE (or any other field) is found in more
than one file, everytime you edit one, you be careful of its effect on the
others.  Of course, if fields you expected to be related ends up not being
so, this is also a possible lookout.

The other columns are extra, and is helpful also for the programmer,
especially when creating screen files for append or edit.  A sample of the
customer file that has been filled is demonstrated in (test2.str),and
explained as follows:

1.) PICTURE is the format to follow in screen display commands.
2.) E stand for Editable.  It means that the field is for display only (@say),
or for edit.  Note that CUSTCODE, being the pointer to other files cannot be
edited.  So is TOTAL, because it presumably is a computed field.
3.) U stands for Unique. CUSTCODE being Y means whenever there is append or
edit on this field, the program has to check that no other CUSTCODE fields
should have the same value.
4.) M stands for Mandatory.  It means that the user must input a value, or
the whole record might be void.
5.) Valid is the range of valid values that is allowed for the validity
routine ran for that field.
6.) Default is the default value of the field you are inputting.  For
instance, if most of your customers are good, then you can automatically
default GOOD_CUST field to Y in the program. 
7.) RELA, as has been discussed, tells you if there are similar fields to be
aware of when changing this value.
8.) Remarks is just for additioal remarks regarding that field.  Since there
is not much space, input most remarks as footnotes.
9.) Prompt is the prompt when you are inputting the field.  The default
assigned by the program is the field name, but you can change this.

While the table after being generated, may take sometime to fill up, it
should make programming a breeze.  It should also not only allow you to spot
data relationships, but hopefully should be a valuable tool that will also
help get your thoughts and design together before you even sit down to write
that program! Moreover, just input the values onto the table, and you could
present it already as part of the technical documentation to your client!  

Now, let us look at a slight change we can do to eliminate the technical
side and to enable the output also to become part of the user manual.

2userman.prg is the simpler version of 2techdoc.prg.  It accepts exactly the
same parameters, however, the STR file it generates is geared towards output
as a user's manual. It accepts the same parameters, the first which is the
name of the STR file you want to create; It also accepts a second
optional parameter which you specify the database filename you would like to
include in the STR.  If no database filename is specified,  the structures
of all databases in the current directory will be added to the STR file. Try
running the program using " do 2userman with 'test2.str' ". You will note
that the string file will give you the necessary foundation to make your
documentation much faster.

Therefore, to conclude, with the following utility, you can:

Construct your .dbf files then:
1.) Run 2techdoc. and have the data dictionary and the tables to fill up
    in writing your functional specifications or technical documentation.
    It also alerts you to possible relations and errors in your structure.

2.) Run 2userman. and fill in the blanks, and your user's guide's
    file structure will already have been solved!

The following utilities should be helpful in shortening the programming
cycle and in not having to duplicate the efforts between programming and
documentation. Happy Programming!

