HP 3000 Manuals HP 3000 Manuals
Dictionary Macro Facility
The System Dictionary SDMAIN program provides a Macro Facility which
gives a shorthand method for entering SDMAIN commands. The use of macros
eliminates the need to remember detailed syntax and parameters and
replaces these with abbreviated macro calls that perform the same
detailed tasks.
What is a Macro?
A macro is a user-defined set of SDMAIN commands that you can save in a
file and call using macro names. When you call the macro, each defined
command is executed in the same way that it would have been had you
entered each command individually through the System Dictionary Command
Language. In addition, parameters can be passed to the macros when they
are called. In this way, user-supplied values are given to the macros.
System Dictionary macros are similar to the MPE User Defined Commands
(UDCs). They are created using any text editor (such as EDIT/V) and use
the following format:
macro-header
definition-body
*
macro-header
definition-body
**
macro-header
definition-body
*
Note that you can place any number of macro definitions in one file, as
long as you separate each definition from the next by a line with an
asterisk in the first column.
The Macro File
Once macros are defined, they are saved in a file. For the System
Dictionary SDMAIN program, the formal file designator for a macro file is
SDMACRO (see the earlier discussion about file equates).
The macro file must be an unnumbered file with a record length of 80
bytes or less (if over 80 bytes, only the first 80 are read and the
remainder are ignored). Only one macro file can be active at any one
time. When SDMAIN is first brought up, and SDMACRO exists, the macro
facility is turned on automatically. After SDMAIN is up and running, you
can redefine the macro file through the OPTIONS command, discussed in
Chapter 4 of this manual.
The Macro Header
The macro header defines a macro name and its argument list. The macro
header has the following format:
macro-name [ argument-name1 [=[default-value1]]
[,argument-name2 [=[default-value2]]]
.
.
.
[,argument-nameN [=[default-valueN]]]]
[;macro-option1]
[;macro-option2]
.
.
.
[;macro-optionN]
.
Macro-name is the name of the macro. The name of the macro can be up to
32 characters long. Valid characters are the same as for other System
Dictionary user-defined names. Macro names must be unique and must not
conflict with System Dictionary command names. You can enter macro names
in either upper or lower case, but they are upshifted when they are
processed.
Argument-name(N) is the name of an argument to be referenced in the
definition body. This name can be up to 32 characters long and must only
contain legal System Dictionary characters. If you use more than one
argument-name, the names must be separated by commas. Argument names
must be unique in a macro definition.
Default-value(N) is the default value of the corresponding argument. If
you do not supply a value for an argument when the macro is called, the
default value is substituted into the macro. If no default value is
supplied, no value is substituted into the macro unless you supply one.
Any value that can be specified when calling a macro can also be provided
as a default value for a macro argument.
Macro-option(N) is one of the macro options to specify for this macro.
These options control the processing and operation of the macro when you
execute that macro. The following sets of options are available. You
can specify only one option from each set.
HELP/NOHELP HELP allows you to use the HELP command to obtain a
listing of the macro definition (both the header and
body). If you specify NOHELP, the system returns a
warning message stating that help is not available for
the macro and the listing cannot be obtained. The
default is HELP.
LIST/NOLIST If you specify LIST, the system lists the expanded macro
commands as they are being executed. This is useful
when debugging a new macro since it allows you to see
which commands are causing errors to be generated. If
you specify NOLIST, the listing of commands is
suppressed, and only the output of the commands is
printed. The default is NOLIST.
PROMPT/ If you specify the PROMPT option, the system prompts you
NOPROMPT for any argument value not specified in the macro call.
If you specify NOPROMPT, the system uses the argument
values provided and uses the default values for all
arguments not provided with a value.
The prompt consists of the argument-name exactly as it
was defined and any default value in parentheses. Since
required arguments have no default value, the prompt is
the argument name for them. You can enter values for
each of the arguments prompted for by entering a
[[RETURN]], which means for the system to accept the
default value indicated. For required arguments, a
[[RETURN]] produces a warning and the system reprompts
for a value since a value is required for a required
argument. Any errors encountered produce an error
message and the system reprompts you for another value.
The value you enter must be a name, real or integer
number, or a string of text inside double quotes. Any
other value produces an error. This is the same
restriction that is placed on default values and
argument values.
You can use a [[CONTROL]] Y at any time to cancel the
macro. The default is NOPROMPT.
A period is required at the end of the macro header.
The Definition Body
The definition body is the set of System Dictionary commands and
parameters that you want to include in the macro definition. Also
included are the place holders for macro arguments. When executing in a
macro, the REDO command is not allowed.
An argument place holder is defined as an exclamation point (!) followed
by the argument-name that you defined in the macro header. You can also
define an argument place holder as an exclamation point (!) followed by
the argument-name placed inside double quotes. This allows you to embed
the argument place holder within a character string. Argument
place holders must be unique in a macro definition and it is your
responsibility to ensure uniqueness when an exclamation point (!) is
used as a wild card character in reporting commands.
The macro definition body can contain as many lines as you want.
However, each macro definition must be separated by a line which begins
with an asterisk (*). The line may contain other characters or even
several asterisks. Since an asterisk in the first column terminates a
macro definition, you should not have an asterisk in column one as part
of a macro definition.
The same syntax rules apply to macros that apply in SDMAIN. In other
words, the punctuation required in a System Dictionary command is also
required in the macro definition.
Like a UDC, a macro definition can contain calls to other macro
definitions. However, unlike UDC's, which search only downward from the
location in the file where the call is made to find any definitions for
UDC's that are called, macros always start at the top of the file when
searching for a called macro.
Calling Macros
When you call a macro with arguments, the argument values supplied by the
user (or the default values) are substituted for the argument place
holders (those arguments in the definition body preceded by exclamation
points). If more than one argument value is given, they must be
separated by commas. An argument value can be skipped by substituting a
comma for the value in the macro call. Trailing argument values can be
dropped without substituting commas. For example, if you define a macro
with four arguments and you only want to supply the first two values, you
can enter them as:
MACRO-CALL argument-value1, argument-value2.
However, if you want to supply values for argument numbers 1 and 4, you
must enter a comma as a place holder like this:
MACRO-CALL argument-value1,,, argument-value4.
The values you pass in are substituted into the macro definition body in
place of the placeholders. If no value is provided on the call, the
default value provided is used. If no value is provided on the call and
no default value was provided in the definition header, an error is
issued since a value is required.
If you enter more argument values than required, the macro processor
treats it as an error and the macro call is not executed. If the
argument value is not a legal System Dictionary name, you must enter the
argument value inside double quotes, for example, "default value" .
Double quotes are not part of the substitution text. If you want the
double quotes to appear when the macro is expanded, you must explicitly
define them as part of the macro definition (See Example 1 that follows)
or you must enter them explicitly when the macro is called (See Example 2
that follows).
Note that an empty string is treated as if no value was specified. In
Example 1, if no value is provided for the description, the description
attribute is not created with a value for the new occurrence as there is
only an empty string (no value). If any character is placed in a string
(including a blank,) the string is not empty, and the attribute is
created with a value for the occurrence.
NOTE A period is always required at the end of each macro call.
Help with Macros
There are two commands that provide help with macros after they have been
loaded. The first is SHOWMACRO, which provides a list of all the macros
that are currently active (all macros in the current macro file that had
valid headers). The second is HELP, which lists the macro header and
definition body for a specific macro if you did not specify the NOHELP
option. Both of these commands are described in detail in Chapter 4.
Example 1
Suppose a macro is defined as follows:
CREATE-ELEMENT entname, elemtype=X, bytelen=1, desc=.
create entity !entname;
entity-type=element;
attribute-list=(element-type=!elemtype,
byte-length=!bytelen,
description = "!desc").
***
Now if you call the macro:
CREATE-ELEMENT part-no,X,10,"First four characters denote product
code and the last six characters denote item code".
this call is expanded to:
create entity part-no;
entity-type=element;
attribute-list=(element-type=X,
byte-length=10;
description = "First four characters denote product
code and the last six characters denote item code").
If you call the macro as:
CREATE-ELEMENT part-no,X.
it is expanded to:
create entity part-no;
entity-type=element;
attribute-list=(element-type=X,
byte-length=1,
description = "").
Note that no description is created for the element part-no. Since no
value was supplied, the value for description is an empty string and no
value is created for an empty string.
Example 2
In this example, a macro is defined with two SDMAIN operations:
CREATE-RECORD-DEFINITION recname,entname,elemtype,stdalias,bytelen.
create entity !entname;
entity-type=element;
attribute-list=(element-type=!elemtype,
standard-alias=!stdalias,
byte-length=!bytelen).
create relationship (!recname,!entname;
relationship-type=record,element;
relationship-class=contains).
***
Now, suppose you call the above macro as follows:
CREATE-RECORD-DEFINITION employee-record,social-security-no,X,
"""social security number""",9.
The call is expanded to:
create entity social-security-no;
entity-type=element;
attribute-list=(element-type=X,
standard-alias="social security number",
byte-length=9).
create relationship (employee-record,social-security-no;
relationship-type=record,element;
relationship-class=contains).
Note the use of triple quotes surrounding the string in the
call--"""string""". This translates to a quote surrounding the string,
and the two quotes reduced to a single quote around the string at each
end.
Example 3
The following example shows the use of macro options. This macro has two
required arguments, two optional arguments with specified default values,
and one optional argument with no default value. It also has two
options, LIST and PROMPT. These options mean that the commands in the
macro will be echoed to you while the macro is executing and the system
will prompt you for any argument values you omitted on the call.
CREATE-RECORD-DEFINITION recname, entname, elemtype=I,
bytelen=4,stdalias=; list; prompt.
create entity !entname;
entity-type=element;
attribute-list=(element-type=!elemtype,
standard-alias=!stdalias,
byte-length=!bytelen).
create relationship (!recname,!entname;
relationship-type=record,element;
relationship-class=contains).
******
Now suppose you call the above macro as follows:
CREATE-RECORD-DEFINITION employee-record.
The system will prompt for values for each of the remaining arguments
entname>>emp-id
elemtype (I)>>
bytelen (4)>>8
stdalias ()>>employee_identification
Given the above specified values, the call is expanded to:
create entity emp-id;
entity-type=element;
attribute-list=(element-type=I,
standard-alias=employee_identification,
byte-length=8).
create relationship (employee-record,emp-id;
relationship-type=record,element;
relationship-class=contains).
The expanded macro will now execute, echoing the commands to