Format of a macro call
The macro format comprises two areas.
The upper area contains the optional name field and the macro name.
The lower area contains the possible operands.
[name] macro name |
<operand1> ,<operand2> |
An entry in the name field is permitted; the name specified is the symbolic address of the first statement in the macro expansion. The user may use this address, for example, as a branch address or as a halt point when using the Interactive Debugging Aid.
The call formats in the present manual generally omit the name field except in cases where a specification in a name field is of special significance. An example would be a macro of type S in L form (see "S-type macros"): The symbolic address specified in the name field is required for linking the data area with the instruction part of the macro (E form). Further examples are the ARDS, CUPAB, DCSTA and TMODE macros, where the default name of the generated dummy section may be replaced by the specification in the name field. Such macro formats also comprise the name field.
The macro name identifies the required macro. The dollar sign '$' is not used as the first character in user macros, because it is reserved for privileged macros.
The operand field may contain any number of operands, separated by commas, but it may also remain empty. The type and number of operands that may or must be specified is defined in the format description of each macro.
When calling a macro in an Assembler program, the name field, macro name and first operand must be separated by at least one space. Multiple operands must be separated by commas.
Format errors that are detected by the Assembler when the macros are being processed are included in the Assembler listing as MNOTE messages (see section “Macro language” in the “ASSEMBH” manual [2 (Related publications)]).
Operand forms
Positional operands
Positional operands must be written in a specific order as they are interpreted by the Assembler on the basis of their position in the operand field.
Example: MACRO A,B,C
If the second operand (B) is deleted, the user must supply the second comma (immediately after the first comma) so as to maintain the proper position for the third operand (C):MACRO A,,C
However, if the last positional operands are omitted, the delimiting commas need not be written. For example, if the operands B and C are omitted in the present example, the macro could be written as follows: MACRO A
Keyword operands
The keyword associated with a given keyword operand uniquely identifies that operand to the Assembler. Therefore, these operands can be written in any order. An operand value which originates from a defined set of allowed values is assigned to an operand by an equals sign.
Keyword operands have the following format: <keyword>=<desired value>
Example: MACRO AREA=X,LENGTH=100
Mixed operands
An operand field may contain a combination of positional and keyword operands; however, all positional operands must precede all keyword operands.
Example: MAKRO A,B,C,AREA=X,LENGTH=100
The rules for positional operand and keyword operand omissions also apply to mixed operand fields. Thus, if the operands B, C and AREA are omitted, the above example appears as: MAKRO A,LENGTH=100
Operand sublists
A sublist consists of one or more positional operands, each separated by commas.
The entire list must be enclosed in parentheses, and is considered to be one operand in that it occupies a single position in the operand field or is associated with a single keyword. The contents of the sublist are processed similarly to positional operands.
Example: (A,B,C) or (A)
In the second example, the sublist consists of only one operand. In this case, the enclosing parentheses must still be written, even though there is only one element in the sublist, as otherwise it will not be recognized as a sublist.
Metasyntax
In the macro format, specific characters (metacharacters) and conventions are used; an overview is given in the following description.
Appears as | Meaning | Example |
| Uppercase letters denote keywords or constants and must be entered by the user exactly as shown. |
the user must enter |
Keywords must begin with * if both keywords and names or constants and variables can be specified as alternatives. |
the user must enter | |
UPPERCASE | Uppercase letters printed in boldface denote allowed abbreviations of keywords. |
GLOBAL=YES oder GLOBAL=Y |
| Lowercase letters denote data types of values, which can be specified by the user, or variables which, on entry, must be replaced by current values. |
user must specify for example |
| Angle brackets denote variables whose allowed values are described by the data types. |
|
| Braces enclose alternatives, i.e. one entry must be selected from the specifications enclosed. Exception: default values. | {SINAME=name |} the user must enter |
| The slash denotes a choice between alternatives; in complicated structures, the alternative operand values can also be grouped with curly brackets. Curly brackets cannot be specified. |
the user must enter |
| | The vertical bar separates information that can be used alternatively within curly brackets. See also note below. |
the user must enter |
[ ] | Square brackets enclose options, i.e. the entries may be deleted. When a comma is enclosed between square brackets in optional entries, it need only be written if the option is used. When it is outside the brackets it must be specified even if the option is not used (round brackets must be entered). |
the user must enter
|
| Underlining denotes the default value of an operand, which is the value the system assumes if the user makes no entry (= system preset). If an operand has no default value, specification of an operand is mandatory. |
the user must enter, for instance (no specification implies |
| A list can be formed from the operand values following list-poss. n specifies the maximum number of list elements. If the list contains more than one element it must be enclosed in round brackets. | FLAG=list-poss(3): *SLI/*SKIP/*DC the user must enter FLAG=*SKIP |
| Ellipses denote repetition, i.e. the preceding syntactical unit may be specified one or more times in succession. |
the user must enter, for instance MF=(E,...) (see also Types of macro) |
The equal sign assigns an operand value to the operands. |
| |
| This character denotes a blank (X'40') |
(without inverted commas) |
Table 1: Macro syntax
The representation of alternatives using a slash ( ACCESS=READ / WRITE) or curly brackets with a vertical bar (ACCESS={ READ | WRITE }) is equivalent. The curly braces are used in more complex expressions to provide clarity or to avoid ambiguity.
Example 1:
...
,{ LIBNAM@=addr / (r) / label | LIBNAM= *DBLOPT / file / * | LIBLINK=name }
...
The curly brackets contain alternatives that are separated from each other with vertical bars: the operands LIBNAM@, LIBNAM or LIBLINK can be used alternatively. For the LIBNAM@ operand, the values adr, (r) or label can be used alternatively; For the LIBNAM operand, the values *DBLOPT, file or "*" can be used alternatively. The alternative values are separated here with a slash.
Example 2:
{ --------------------------------------------------- (1) { ------------------------------------------------- (2) SINAME=name | SINAMAD=addr / (r)[,SINAMLN=length] } ------------------------------------------------- (2') ,SCOPE=LOCAL / GROUP / USER_GROUP / GLOBAL |
SIID=addr / (r)
} --------------------------------------------------- (1')
The operands SINAME=name or SINAMAD=.. can be used within the brackets (2)/(2'). The alternative values adr or (r),SINAMLN=length can be specified within the SINAMAD operand, whereby the SINAMLN specification is optional. Optional operands/values are enclosed in square brackets.
Within the brackets (1)/(1') either the construct of the brackets (2)/(2') can be used with the specification SCOPE= or alternatively the specification SIID=.
Alternative operand values for SCOPE are LOCAL, GROUP, USER_GROUP or GLOBAL. Alternative operand values for SIID are adr or (r).
Example 3:
{ -------------------------------------------------- (3)
INTR='messid' / addr / (r)[,AREA={addr | (r)}] | (4)
FINISH='messid' / addr / (r),AREA={addr | (r)} (5)} -------------------------------------------------- (3')
Alternatively, the operands INTR or FINISH can be specified within the outermost curly brackets (3)+(3'). The two alternatives are separated by "|" separated at the end of (4).
The operand values of INTR can alternatively be 'messid', adr, (r), (r),AREA=adr or (r),AREA=(r). The square brackets around AREA... indicate that the specification is optional. The situation is similar for the FINISH operand, except that the specification of AREA is mandatory for the alternative (r),AREA=. The two alternatives adr and (r) for the AREA operand were enclosed in curly brackets to avoid ambiguity when assigning the alternatives to the operands.
Example 4:
FCT=
{ DESTROY,SPID=spid_addr | --- (6)
INFORM,IDENT=NAME / SPID
[,SPID=spid_addr]
[,NAME='name' / name_addr]
,SCOPE={LOCAL / GROUP / USER_GROUP / GLOBAL} | --- (6)
EXTEND,SPID=spid_addr
,SIZE={zahl / (r)} | --- (6)
CLEAR,SPID=spid_addr
,AREA=area_addr / (r)
,SIZE=zahl / (r) }
In the example above, the operand FCT allows four alternative functions: DESTROY, INFORM, EXTEND, CLEAR. The alternatives are indicated by "|" separated (6). The indentations make it clear which other operands belong to the respective functions. For example, the INFORM function includes the other operands IDENT, SPID, NAME and SCOPE. The EXTEND function only knows the SPID and SIZE operands.
Data types of the operand values
Data type | Character set | Remarks |
| EBCDIC characters | must be enclosed in inverted commas |
| [+-] 0..2147483647 | is a decimal number |
| precedes specification of a variable. |
|
| Register 0..15 |
|
Suffixes to data types
Suffix | Meaning |
| for the |
for the | |
| in the |
The operand values can be entered directly as a character string or integer (see data types c-string and integer) or indirectly via a variable (see data type var:). The following table contains the data types that are possible for variables.
Data types of variables
Data type | Description | Definition in |
| The variable is a character string of n characters. If no length is specified, it is assumed that |
|
| The variable is an integer that occupies n bytes. |
|
| The variable is the enumeration of |
|
| The variable is an address or an address value. |
|