HP 3000 Manuals HP 3000 Manuals
How to Create a Model
In order to create a reusable model from a non-reusable Virtuoso source
file, you must first classify the code into reusable logic, specific
code, and specific data names. The code is then divided as follows:
* Reusable logic is left in the source file and becomes the core of the
model.
* Specific code is placed in include files and accessed via
#section/#entry constructs (or via the UserAction macro) in the
model. (This is discussed in more detail later in the chapter.)
* Specific data names are removed from the model and replaced with
generic keywords. The data names are placed in the System
Dictionary. Macros or constructs are used in the model to retrieve
the data names as keywords during generation. These keywords are
then inserted in the logic via keyword parameter replacement.
* The specific module name is specified through the INFO string at run
time to give the generator a starting point in the dictionary to
retrieve the other data names.
Techniques for Creating Reusable Code
As stated above, there are two main tasks when creating reusable code
from a non-reusable Virtuoso source file. One is to remove specific data
names, and the other is to remove specific code.
Removing Specific Data Names. To remove specific data names, the data
names must be defined in the System Dictionary. The specific data names
are then replaced with generic keywords in the model. For example, if
the module READCUST processes the CUSTOMER data set in the ORDERS
database, then this specific information must be replaced by keywords
such as image-database and image-dataset within the Virtuoso source code.
The specific information for the module is then placed in the System
Dictionary:
MODULE processes IMAGE-DATABASE
READCUST processes ORDERS
MODULE processes IMAGE-DATASET
READCUST processes CUSTOMER
Once this information is present in the dictionary, the generator can be
instructed to retrieve it with constructs such as #getrel, #getent and
#for/#endfor. These constructs are added to the Virtuoso source to
retrieve the data names before the corresponding keywords are used for
parameter replacement.
Inserting Specific Code. One method for inserting specific code into a
model is to use the Section/Entry feature to reposition specific code in
a desired location. This method works as follows:
1. The location at which the specific code should be placed is
identified using the #section construct.
2. The specific code is placed within the #entry/#endentry
constructs. The section for the entry should match the name
specified in the previous step.
3. The entries are grouped together into one file. This file is
included into the model via the #include construct.
Example
The file containing the specific code for the model is included using the
#include construct. In this example, the file contains the specific code
to perform data movement. The location at which to insert the specific
code is identified using the #section construct as follows:
.
#include file="USERACT"
.
.
.
#section name="data-movement"
.
The file USERACT contains the following entry containing the specific
code to perform the data movement:
#entry name="order-data" section="data-movement"
MOVE PART-NO OF SCREEN-BUF-DATA
TO PART-NUMBER OF DATASET-BUF-DATA
MOVE QUANTITY OF SCREEN-BUF-DATA
TO QUANTITY OF DATASET-BUF-DATA
#endentry
This file may also have additional entries which correspond to other
sections within the model where specific code should be inserted.
If the specific code within the include file contains references to any
keywords, make sure that these keywords have been retrieved before the
#include statement for the file or before the parameter is accessed
within the include file. Otherwise the keywords will not be defined
before they are used, and this is an error.
A second method for inserting specific code into a model is to use the
UserAction macro in the Virtuoso COBOL Sample Library. UserAction
requires additional System Dictionary entries to define the various
action types. Refer to the Virtuoso COBOL Sample Library Reference
Manual (30426-90001) for more information on using this macro.
Example: Creating a Model
The following pages show a comprehensive example of creating a model.
The example includes a description of the problem, the conversion
process, the resulting model, and the related System Dictionary
definitions.
Problem
The following Virtuoso source file generates the module READCUST which
performs the simple operation of opening the ORDERS database, serially
reading the CUSTOMER master dataset, displaying each record read from the
dataset, and closing the database. The structure of the ORDERS database
is already defined in the System Dictionary. Also, the relationship
"READCUST processes ORDERS" (of type "MODULE processes IMAGE-DATABASE")
has been defined to relate the module to the database. Refer to the
Virtuoso COBOL Sample Library Reference Manual (30426-90001) for examples
of defining specific relationships in the System Dictionary.
Note that there are several macro calls in the source file, including
DefineImageData, Module, Startup, Terminate and End. The Module macro
generates the division statements (COBOL template) of the program, and
the End macro generates the #section statements used to reposition #entry
paragraphs. The Startup macro calls paragraphs to open formsfiles, files
and databases for the module, while the Terminate macro generates the
code to close all open formsfiles, files and databases. The macro
DefineImageData defines all of the data required by the TurboIMAGE
intrinsics. These macros are all contained in the Virtuoso COBOL Sample
Library. Remember that you are not restricted to the macros.
User-defined macros can be used in Virtuoso source code and models.
#module module="READCUST"
#
#DefineImageData
#entry name="CUSTOMER-DATA" section="working-storage"
COPY CUSTOMER.
#endentry
#
#Startup
PERFORM UNTIL NOT DB-OK
# DBGetNext image-database="ORDERS" &
# image-dataset="CUSTOMER" &
# record="CUSTOMER" &
# dblist="@" &
# mode="MODE2"
IF DB-OK
DISPLAY "ACCOUNT: " ACCOUNT
DISPLAY "LAST NAME: " LAST-NAME
DISPLAY "FIRST NAME: " FIRST-NAME
END-IF
END-PERFORM
#Terminate
GOBACK.
#End
Using the techniques outlined in this section, the Virtuoso source file
will be converted into a model. The model will open any database,
serially read any master dataset, display each record read from the
dataset, and close the database.
Conversion Process
The steps to convert the source file into a model are as follows:
* Given the definition of the functionality of the model, all of the
logic in the source file is reusable except for the logic to display
the data record, since this logic must know about specific data
names.
* The specific logic to display the data record is placed between
#entry/#endentry in an include file called "DISPDATA". A #section
statement and #include statement in the model are used to place the
code properly.
* The specific data names ORDERS and CUSTOMER are replaced with generic
keywords. The data names are placed in the dictionary as part of the
structure of the Orders database and are retrieved by using the
#getrel construct.
* The specific module name is replaced with a generic keyword. The
module name is defined at generation-time through the INFO string
using the keyword-value pair "MODULE=READCUST".
Model
The resulting model looks as follows:
#module module="!module"
#
#getrel module="!module" image-database=? &
# relclass="processes"
#getrel module="!module" image-dataset=? &
# relclass="processes" alias="image-alias"
#getrel image-dataset="!image-dataset" record=? &
# relclass="contains"
#
#let dataset-record="!record"
#
#DefineImageData
#entry name="CUSTOMER-DATA" section="working-storage"
COPY !dataset-record.
#endentry
#
#include file="DISPDATA"
#
#Startup
PERFORM UNTIL NOT DB-OK
# DBGetNext image-database="!image-database" &
# image-dataset="!image-dataset" &
# record="!dataset-record" &
# dblist="@" &
# mode="MODE2"
IF DB-OK
#section name="display-data"
END-IF
END-PERFORM
#Terminate
GOBACK.
#End
Include File
The include file DISPDATA would contain the following specific code to
display the data record:
#entry name="customer-data" section="display-data"
DISPLAY "ACCOUNT: " ACCOUNT
DISPLAY "LAST NAME: " LAST-NAME
DISPLAY "FIRST NAME: " FIRST-NAME
#endentry
Dictionary Definitions
The utility SDDBD must be used to load the database definitions into the
System Dictionary if they are not already present. The System Dictionary
must also be customized to add the relationship types corresponding to
the information which needs to be stored in the dictionary. The
information that needs to be stored in the System Dictionary is
determined by the logic in the Virtuoso source or model. In the above
example, the relationship type MODULE processes IMAGE-DATASET must be
added to the dictionary. Finally, the necessary relationship occurrences
are added to the System Dictionary:
* Relate the module to the database:
MODULE processes IMAGE-DATABASE
READCUST processes ORDERS
* Relate the module to the dataset:
MODULE processes IMAGE-DATASET
READCUST processes CUSTOMER
These definitions must be present in the System Dictionary when this
model is processed by VG or generator errors will occur. Note that the
relationship DATASET contains RECORD need not be added, since this
relationship was created when the utility SDDBD was used to load the
database definitions into the System Dictionary. Note also that you can
customize the dictionary to include your own information.
The same model may be used for another database and dataset containing
entirely different data simply by referencing another set of definitions
in the System Dictionary and replacing the include file DISPDATA with
another include file containing the specific code to display the data
record.
Refer to the Virtuoso COBOL Sample Library Reference Manual (30426-90001)
for additional examples of using the Virtuoso Code Generator to generate
COBOL programs.