Syntactical representation of macro calls

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

<operand₁>

,<operand₂>

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	Uppercase letters denote keywords or constants and must be entered by the user exactly as shown. Keywords must begin with * if both keywords and names or constants and variables can be specified as alternatives.	DIB FORCED=*YES
UPPERCASE LETTERS in boldface	Uppercase letters printed in boldface denote allowed abbreviations of keywords.	GLOBAL=YES The user must enter GLOBAL=YES oder GLOBAL=Y
lowercase letters	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.	DIB=<var: pointer> FILE filename
< >	Angle brackets denote variables whose allowed values are described by the data types.	<var: pointer>
{ }	Braces enclose alternatives, i.e. one entry must be selected from the specifications enclosed. Exception: default values.	TAPE={YES/NO} The user must enter TAPE=YES or TAPE=NO
/	The slash denotes a choice between alternatives; it has the same function as braces.	FORCED=*NO/*YES The user must enter FORCED=*NO or FORCED=*YES
underlining	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.	FORCED=*NO/*YES The user must enter FORCED=*NO or FORCED=*YES (no specification implies FORCED=*NO)
[ ]	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).	filename[,ERASE] The user must enter, for instance, FILE,ERASE or FILE      or XYZ,ERASE etc.

Table 1: Macro syntax

Appears as	Meaning	Example
l listposs(n)	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 FLAG=(*SLI,*DC)
...	Ellipses denote repetition, i.e. the preceding syntactical unit may be specified one or more times in succession.	(filename,...) The user must enter FILE       or (FILE,XYZ) or (FILE1,FILE2,FILE3) etc.
'BLANK'	This character denotes a blank (X'40')	STD'BLANK' The user must enter 'STD ' (without inverted commas)
=	The equals sign links the operand name to the operand values associated with it.	DATA=<var:pointer>

Table 1: Macro syntax

Data types of the operand values

Data type	Character set	Remarks
c-string	EBCDIC characters	must be enclosed in inverted commas
integer	[+-] 0..2147483647	is a decimal number
var:	precedes specification of a variable. The type of variable follows the colon (see table “Data types of variables”.)	<var: var-type>
reg:	Register 0..15	(<reg: var-type>)

Suffixes to data types

Suffix	Meaning
n..m	for the integer data type, n..m means an interval is specified; n: minimum value m: maximum value
	for the c-string data type, n..m means a length specified in bytes; n: minimum length m: maximum length with n < m
n	in the c-string data type, n means a length specified in bytes; n must be the exact number

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 program
char: n	The variable is a character string of n characters. If no length is specified, it is assumed that n = 1.	CLn
int: n	The variable is an integer that occupies n bytes. If no length is specified, it is assumed that n = 1. Condition: n <= 4	FLn
enum-of E: n	The variable is the enumeration of E, which occupies n bytes. If no length is specified, it assumed that n = 1 (n <= 4).	XLn
pointer	The variable is an address or an address value.	A