|Powered by QM on a Rpi server|
KnowledgeBase 00079: The GENERATE Tool
This article was originally published as a Tip of the Week.
Historically, programmers on multivalue database products have tended to write applications that reference fields in data records by field number. This leads to statements such as
TREC<91> = CUS<4> * TTBL<8>which are very difficult for anyone who is not an expert on the application to understand, especially when combined with terse variable names as in this example. This can easily lead to programming errors and subsequent high maintenance costs.
A better approach is to use equated token names for each field in much the same way that a database dictionary defines names for use in the query processor. The resulting code is easier to read, understandable by less experienced developers, and less error prone. It also makes it trivial to find all references to a specific field simply by searching for its name.
Although lists of equated token names, preferably in an include record, can be constructed by hand, it is better if these can be created automatically from the corresponding dictionaries, guaranteeing that they cannot differ. The dictionary becomes the reference model of the data for documentation purposes.
The GENERATE Command
The GENERATE command generates a QMBasic include record from a dictionary. The precise action of the command is controlled by a dictionary record named $INCLUDE which is itself created from prompt responses when the GENERATE command is first used. Running the command after every dictionary update ensures that the dictionary and the QMBasic programs remain correctly in step.
The equate tokens created by GENERATE have a user defined prefix which should ideally be based on the filename to aid readability. The prefix is separated from the rest of the token name by a dot. A simple order processing system might use prefixes of C for the customers file, O for the orders file and S for the stock file. More realistic applications would probably need longer prefixes.
The GENERATE command can produce field number tokens for use with dynamic array references or it can equate names to the elements of a specific dimensioned array. Both modes can be used together. It can also produce tokens corresponding to the conversion codes applied to each field.
The small example below relates to a file storing copies of emails sent from within an application.
* BP EMAIL.LOG.H * Generated from DICT EMAIL.LOG at 11:54:47 on 04 Jan 2012 equate EL.DATE to 1 ;* Date equate EL.DATE.CNV to "D2DMYL[,A3]" equate EL.RECIPIENTS to 2 ;* Recipients equate EL.SENDER to 3 ;* Sender equate EL.SUBJECT to 4 ;* Subject equate EL.MESSAGE to 5 ;* Message