HP 3000 Manuals

Invoking the Generator [ VIRTUOSO CODE GENERATOR Reference Manual ] MPE/iX 5.0 Documentation

VIRTUOSO CODE GENERATOR Reference Manual

Invoking the Generator

There are two main types of information in the :RUN statement for the
Virtuoso Code Generator. The first type is information on input/output
file names. The second type is parameters passed to the generator. You
can override the default source, output, and listing files using a :FILE
equation to specify any desired file name. You then specify the
appropriate value for the PARM parameter in the :RUN command, as shown in
Table 5-2. This informs the generator which default files you will be
overriding. Table 5-1 shows the formal file designators recognized by
the generator:

Table 5-1. Formal File Designators

Table 5-2. PARM Values

---------------------------------------------------------------------------------------------
| | |
| PARM Value | Formal File Designator(s) in File Equation |
| | |
---------------------------------------------------------------------------------------------
| | |
| 0 | none |
| 1 | GENTEXT |
| 2 | GENLIST |
| 3 | GENTEXT, GENLIST |
| 4 | GENOUT |
| 5 | GENTEXT, GENOUT |
| 6 | GENOUT, GENLIST |
| 7 | GENTEXT, GENOUT, GENLIST |
| | |
---------------------------------------------------------------------------------------------

Table 5-2 shows the integer values of the PARM parameter and the
corresponding file(s) which the Virtuoso generator then expects to find
specified by a :FILE equation. If PARM is not specified, then it
defaults to 0 (none).

The following example shows :FILE commands which equate the source and
output files for the generator followed by the :RUN command used to
invoke the generator:

:FILE GENMACRO=MACX0000.TEST.ORDMGT
:FILE GENTEXT=ORDCUSTS.TEST.ORDMGT
:FILE GENOUT=ORDCUST.TEST.ORDMGT
:RUN VIRTUOSO.PUB.SYS;PARM=5

The preceding example shows file equates for the GENTEXT and GENOUT
files. Also note that the Processed Macro File (MACX0000) is file
equated to GENMACRO. This tells the generator which Processed Macro File
to access. The PARM value in the :RUN command indicates to the generator
that the source and output files have been specified in previous file
equations.

You can also specify up to 11 processed macro files to be used by the
Virtuoso Code Generator during code generation. One of these files is
specified in the GENTEXT file equate, and up to 10 more can be specified
in the GENMACRO parameter of the INFO= string or in the GENINFO file.
The names of the processed macro files can be specified using the INFO
string, the formal file designator GENMACRO, or the GENINFO file. The
macro file specified through the INFO string will be searched first,
followed by the file specified through the formal file designator
GENMACRO, followed by the files specified through the GENINFO file.

The names of the processed macro file can be specified using any or all
of the following methods:

* Through the INFO string using a keyword-value pair of the form
GENMACRO=filename or GENMACRO=(filename, ..., filename).

* Using the formal file designator GENMACRO.

* Through the GENINFO file using a keyword-value pair of the form
GENMACRO=filename or GENMACRO=(filename, ..., filename).

The preprocessed macro files are searched in the order listed above.
Hence, those files specified using the INFO string are searched before a
file specified using the GENMACRO formal file designator which in turn is
searched before those specified through the GENINFO file. If no
processed macro file is specified through one of the above methods, and a
macro is called from within a Virtuoso source file, an error will result.

EXAMPLE

Suppose a programmer was using the following processed macro files:

MAINPRGM.DEMO Macros for the MAINPRG in the DEMO application
DEMOMAC.PUB Macros for the DEMO application
MISMACRO.VIRTUOSO.MIS Macros for the entire MIS shop
HPMACRO.VIRTUOSO.SYS Macros supplied by HP

The programmer created a GENINFO file which contained the following
lines:

S=DA
P=DA
V=X0000
D=DEMO
GENMACRO="MISMACRO.VIRTUOSO.MIS"
GENMACRO="HPMACRO.VIRTUOSO.SYS"

Parameters not in the GENINFO string can be passed in the INFO string.
The following commands were then used to run the generator:

:FILE GENTEXT=MAINPROG.MODELS
:FILE GENMACRO=DEMOMAC.PUB
:RUN VIRTUOSO.PUB>SYS;PARM=7;INFO="V=X0001 GENMACRO='MAINPRGM.DEMO'"

Then the generator would open the dictionary with the following security:

S=DA P=DA V=X0001 D=DEMO

Note in this example, the version specified in the INFO string overrode
the version specified in the GENINFO file.

The processed macro files would be searched in the following order when a
macro is invoked:

MAINPRGM.DEMO
DEMOMAC.PUB
MISMACRO.VIRTUOSO.MIS
HPMACRO.VIRTUOSO.SYS

Thus, if the macro OPENDB was contained in all four processed files, the
version in MAINPRGM.DEMO would actually be used. The ordering of the
macro files allows program-specific versions of macros to override
shop-wide versions of macros.

Here is a similar example which shows different parameters being passed
through the INFO string. These parameters can include information
necessary to open the System Dictionary, specify formatting options,
specify processing information, and set up keyword-value pairs which are
loaded in the keyword table.

:RUN VIRTUOSO.PUB.SYS;PARM=5;INFO="S=DA P=PASS V=TEST D=ORDMGT"

In this example, the INFO string tells the generator that the System
Dictionary Scope is DA (Dictionary Administrator), the Password is PASS,
the System Dictionary Version is TEST, and the Domain is ORDMGT. The
generator sets up this information in its keyword table.

In summary, the :RUN command for the Virtuoso Code Generator specifies
file information through the PARM parameter and other information through
the INFO string. The PARM parameter indicates which input/output files
are default values and which files have been file equated to different
values with the :FILE command. The next section discusses the INFO
string in more detail.

INFO String

The INFO string is used to pass information to the generator. The syntax
for the INFO string is as follows:

Syntax

INFO="parameter=value parameter=value...."

Parameters

[Dict]ionary is the name of the System Dictionary to be
accessed. This parameter is optional. If
omitted, the name defaults to SYSDIC.

[D]ictionary-[T]ype tells whether you are using a dictionary or
not. If you are using a dictionary, you may
omit this keyword. If you are not using a
dictionary, specify DT=NODICT. You may also
explicitly specify DT=SYSDIC.

[S]cope is the scope for opening the System Dictionary.
This parameter is required if you are using the
System Dictionary.

[P]assword is the password for opening the System
Dictionary. This parameter is required if you
are using the System Dictionary.

[D]omain is the Domain in the System Dictionary from
which to retrieve information. This parameter
is optional. If omitted, the domain defaults
to the Common domain.

[V]ersion is the Version in the System Dictionary from
which to retrieve information. This parameter
is optional. If omitted, the version is
determined by the Status parameter specified.

[Stat]us is the Version Status in the System Dictionary
from which to retrieve information. This
parameter is optional. Note that both Version
and Status cannot be specified; specify either
Version or Status. If Status is not specified,
then the default status (Production) is used.

genmacro is the name of the file(s) that contains
processed macro files. The syntax is
GENMACRO='filename' or GENMACRO=(filename, ...,
filename).

textmode is the textmode to be used; COBOL, TEXT, or
OVERLAY. COBOL textmode invokes special
formatting for COBOL code. TEXT textmode is
used when generating other forms of text, and
OVERLAY textmode is intended for generating
columnar-type reports. The default is COBOL.
For more information, refer to Chapter 3 and
the #option construct. This parameter is
optional. It can be overridden by the #option
construct.

macroformat is ON or OFF. If ON, and a macro is called, the
text lines in the macro are indented by the
number of spaces between the "#" sign and the
macro name. If OFF, and a macro is called, the
text lines are not indented and are placed in
the same output columns as the Processed Macro
File. This parameter is optional. It can be
overridden by the #option construct.

subchar is the character to be used when designating
that parameter replacement is to be performed
during this run of the generator. The
character specified must appear in single
quotes (' '). The VG default character is the
exclamation (!) mark. This parameter is
optional. It can be overridden by the #option
construct.

trace is either ON or OFF (default is OFF) and is
valid only for textmode=COBOL. If ON the first
8 characters of the called macro name or
include file name is returned in columns 73-80
of the output file (GENOUT). This information
is helpful in debugging a generated module.
This parameter is optional. It can be
overridden by the #option construct.

macroproc[mp] is ON if the generator is to process a Source
Macro File. The default value for this
parameter is OFF. This parameter must be
specified if the generator is to be run in
macro processor mode.

keyword=value You can also specify any keyword-value pair
which is to be loaded in the keyword table.
For example, you could include the name of a
database or module. Any valid keyword-value
pair can be specified in the INFO string.
However, the INFO string cannot exceed 255
bytes. Setting up keyword-value pairs through
the INFO string is the same as using #let
constructs at the start of the Virtuoso source
code.

The following example illustrates specifying a keyword-value pair in the
INFO string.

:RUN VIRTUOSO.PUB.SYS;INFO="S=DA P=PASS D=ORDMGT IMAGE-DATABASE=ORDERS"

In the above example, the required parameters are indicated along with an
optional keyword-value pair (IMAGE-DATABASE=ORDERS). During this run of
the generator, wherever the keyword image-database is preceded by the
substitution character it will be replaced with the value ORDERS. This
feature is useful for specifying a starting point in the System
Dictionary for the Virtuoso source file.

The parameters in the INFO string can be in any order:

:RUN VIRTUOSO.PUB.SYS;INFO="S=DA P=PASS MODULE=ORDENT SUBCHAR='%'"

:RUN VIRTUOSO.PUB.SYS;INFO="SUBCHAR='%' P=PASS MODULE=ORDENT S=DA"

In the above example, both of the :RUN commands are interpreted the same
way by the generator. The order of the parameters makes no difference.
Note that during the above run of the generator the substitution
character has been set to the percent (%) sign instead of the usual
exclamation point (!).

If any of the required parameters are omitted in the INFO string, an
error message is displayed and the generation process terminates.

Note that if you are using a textmode other than COBOL, it is usually a
good idea to specify the textmode in the :RUN command rather than in an
#option construct in the file. For example, if you place the #option
command in column 1 of the first line of the file, it will be ignored.
This is because the default textmode is COBOL, and so the generator will
ignore the #option command since it doesn't begin in column 7. To avoid
such problems, it is usually best to place the textmode parameter in the
INFO string or the GENINFO file. Otherwise, be sure that the #option
command begins in the correct column.

MPE/iX 5.0 Documentation