Powered by QM on a Rpi server
About OpenQM
Sales and Downloads
Help and Support

KnowledgeBase 00079: The GENERATE Tool

Last updated: 17 Feb 2017
Applies to: All versions
Top level index       Full Index Search Tips
Previous article     Next article

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.

* 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 

Related Articles


Please tell us if this article was helpful
Very     Slightly     Not at all
Email (optional)