HP 3000 Manuals HP 3000 Manuals
Macro Syntax
This section discusses macro syntax in two parts: the macro header and
the macro body. The macro header consists of optional #comment
constructs and the #macro construct. The macro body contains the code to
be generated when the macro is called.
Macro Header
The macro header consists of a #macro statement and optional in-line
documentation (#comment lines). The macro header in this example begins
with several #comment lines at the beginning of the macro file which help
to identify and describe the macro.
#comment
#comment Macro: DataBaseOpen
#comment
#comment
#comment Description:
#comment Macro which opens a database in the specified mode.
#comment
#macro DataBaseOpen image-database=string &
# mode =(string,"5") &
# password =(string," ")
.
.
The #comment lines are optional. However, the #macro statement which
describes the valid usage of the macro is required by the . The #macro
construct gives the name of the macro (DataBaseOpen) and shows the
parameters used in the macro. The parameters appear as keyword-value
pairs, where the keyword is the name of the parameter. The keyword value
is information about the parameter: whether it is string or numeric, and
whether it is required or not. Parameters are required if their
keyword-info (keyword value) does not include a default value.
The DataBaseOpen macro has three parameters: image-database, mode, and
password. All three are defined as ASCII strings. The parameter
image-database is required, and the others are not. The default value
for mode is "5", and the default value for password is " ".
The following is the syntax for the #macro construct. It also appears in
Chapter 3 but is repeated here for more convenient reference. Refer to
Chapter 3 for a more detailed discussion of the #macro construct.
Syntax
#macro macroname [keyword1=Keyword-Info1 &
# keyword2=Keyword-Info2...]
.
.
#endmacro
Keywords
macroname is the name of the macro. This macro name must be
unique for the Processed Macro File and cannot be a
reserved word. The macro name can be up to 32
characters long.
keyword1 is the name by which a parameter will be known in the
macro body. The keyword must be unique for the macro.
There can be up to 30 keywords per macro.
keyword-info1 is a positional list of values that specify the type of
keyword and the default value, if the keyword is
optional. The syntax for keyword-info is:
(Keyword-Type, Default-Value) or
(Keyword-Type) or
Keyword-Type
Keyword-Type can be either STRING or NUMERIC. It
describes the data type of the value that will be
assigned to the keyword when the macro is invoked.
Default-Value is the default value of the keyword. If a
default value is not specified for the keyword, then the
keyword is required when the macro is invoked.
If a default value is specified, then the keyword is
optional when the macro is invoked. In this case, the
keyword is assigned the default value if another value
is not specified at macro invocation. Default values
are limited to 43 characters.
Note that if Keyword-Type is STRING, Default-Value must
be enclosed in quotes (" "). If Keyword-Type is
NUMERIC, Default-Value must not be enclosed in quotes.
It is invalid to use a construct name as a macro name. In addition, it
is recommended that macro names not begin with the prefix "HP". This
prefix is reserved for use in future constructs and macros. The
generator will issue an error if the macro has the same name as a
generator construct.
Macro names must be unique in the Processed Macro File. It is also
helpful to make the first 8 characters of the macro name unique. The
trace parameter can be used, either in the #option construct or the
generator INFO string, to print the first eight characters of the macro
name in the output file. Naming the macros uniquely will help identify
the macro when debugging. Refer to the #option construct in Chapter 3
for more information.
Macro Body
The macro body follows the last line of the macro header. It consists of
the Virtuoso statements and user text needed to accomplish the purpose of
the macro. The following example shows the macro body format for the
DataBaseOpen macro. This macro generates COBOL code to open a database.
#comment
#comment Macro: DataBaseOpen
#comment
#comment
#comment Description:
#comment Macro which opens a database in the specified mode.
#comment
#
#macro DataBaseOpen image-database=string &
# mode =(string,"5") &
# password =(string," ")
#
PERFORM
MOVE SPACES TO !image-database!-BASE-ID
MOVE "!image-database" TO !image-database!-BASE-NAME
#
#if password = " "
MOVE ";" TO DB-PASSWORD
#else
MOVE "!password" TO DB-PASSWORD
#endif
MOVE !mode TO DB-MODE
CALL "DBOPEN" USING !image-database!-DATA
DB-PASSWORD
DB-MODE
DB-STATUS
END-PERFORM
#endmacro
#comment ************************************************************
#comment
The macro body begins with the PERFORM line and ends with the #endmacro
construct. Notice that blank lines are used to make the macro more
readable. The statements included in the macro body appear exactly as
they would appear in the generated source file prior to parameter
replacement.
The macro is generic because it does not reference the name of a specific
database. The name of the database is substituted at generation-time
when the macro is invoked.
Macro Requirements
The following list summarizes the requirements of the when you create a
macro:
* The macro syntax must be followed for each new macro. For example,
each new macro must have a valid macro name.
* The macro body must consist of statements which define the text to be
generated for the macro.
* The macro body statements must appear in the exact way in which the
generated source file is to appear.
* The macro must be bracketed with #macro and #endmacro constructs.
* The Source Macro File must be processed into a run-time format before
it can be used.