The macro operands are divided into two groups:
Format operands that define the form and the generation of the macro
Function operands that define the contents of the parameter range in an interfacespecific manner
Syntax of the format operands
The syntax of the format operands corresponds to the BS2000 rules (see the manual “Executive Macros” [8 (Related publications )]).
| MF | controls generation of the code (“macroform”) |
| PREFIX | controls generation of the names (first letter) |
| MACID | controls generation of the names (second through fourth letters) |
| PARAM | controls addressing of the parameter range |
| XPAND | controls expansion of the individual data structures; If XPAND is contained in the macro syntax, it must be assigned a value as it does not have any default (mandatory operand). |
Macro forms
The MF operand defines the form of the macro. It can accept the following values:
MF=C / D / L / E / M / S
MF=C | |
The layout of the data structure (generally the parameter range) is generated, whereby each field and each equation are named. This data structure becomes part of the current program section (CSECT/DSECT). | |
XPAND | |
If this is required for the interface, the expansion of individual data structure can be selected using control operands – for instance, if different output areas can be selected in an interface (e.g. XPAND=PARAM / out1). | |
PREFIX | |
The PREFIX operand is used to generate the names to be created. PREFIX, which is exactly one letter, is used as the first letter of all names. The default value is the code letter of the function unit to which the macro belongs. To avoid similarities in names, PREFIX must be used if the same data structure is used a number of times within a module. | |
MACID | |
The MACID operand is used to generate the names to be created and specifies the second through fourth characters of the name. Default value: two characters as a development group code and one character as a macro-specific code. The default value guarantees that no names are the same within the component group. | |
MF=D | |
Generates the layout of the data structure as in MF=C. A DSECT statement is also generated. The MACID operand is ignored, the default value is assumed. | |
MF=L | |
Generates an instance of the parameter range by evaluating the function operands. This macro form does not generate any field names. The label specification is used to name the generated constants. | |
MF=E | |
Generates the commands needed to call the function. The function operands are ignored. Addressing of the parameter range must be checked using the PARAM control operand: | |
PARAM | |
The PARAM operand controls addressing of the parameter range. | |
=<adr> | |
| Address of the parameter range as a name | |
=(<reg>) | |
Address of the parameter range is contained in the register with the name <reg> | |
MF=M | |
Modifies a parameter range previously initialized by copying an MF=L form taking into account an evaluation of the specified function operands. Operands that are not specified retain their original state. The consistency of the parameter range is the responsibility of the person calling the macro. MF=M requires that the MF=D form or MF=C form was called with the same values of the PREFIX and MACID operands and that a USING statement was issued before the DSECT (MF=D form) was addressed. | |
MF=S | |
Generates an instance of the parameter range taking into account an evaluation of the function operands, as with MF=L. This also generates commands that – if necessary – skip the parameter range instance and call the function. | |
Elements of the macro syntax
Identifier | 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 of constants or variables can be specified as alternatives. | ||
DELETE=*NO / *YES | ||
lowercase letters | ||
Lowercase letters denote data types of values or variables which can be specified by the user. | ||
COUNT=<integer 1..8> | ||
= | ||
The equals sign links the operand name to the operand values associated with it. | ||
FILE=<c-string> | ||
< > | ||
Angle brackets denote variables whose allowed values are described by the data types. | ||
REPEAT=<integer> | ||
Underscoring | ||
Underscoring denotes the default value of an operand. If an operand has no default value, specification of an operand is mandatory.! | ||
ACTION=*ADD / *MOD | ||
/ | ||
The slash separates alternative operand values. | ||
CHECK=*NO / *YES | ||
list-poss(n) | ||
A list can be formed from the operand values following list-poss. n specifies the maximum number of list elements (for the type Keylist). The list must be enclosed in round brackets if more than one element is specified. | ||
OUTPUT=list-poss(2): *SYSOUT / *SYSLST Specification: OUTPUT=*SYSOUT OUTPUT=(*SYSOUT, *SYSLST) | ||
Table 4: Macro syntax: Elements
An operand is assigned an operand value from a defined range of values by means of an equals sign.
This range of values is specified by a data type. The following table contains the data types of the operand values.
Data types of the operand values
Data type | Character range | Remarks |
c-string | EBCDIC character | Must be enclosed in single quotes |
integer | [+-] 0..2147483647 | Is a decimal number |
var: | Introduces a variable specification. The variable type follows a colon (see table 6) | <var:var-type> |
reg: | Register 0..15 | Specification: (<reg:var-type>) |
Table 5: Macro syntax: Data types of operand values
Suffixes for data types
Suffix | Meaning |
n..m | For the integer data type, n..m represents an interval; n: minimum value m: maximum value |
For the c-string data type, n..m represents a length in bytes; n: minimum length m: maximum length with n < m | |
n | For the c-string data type, n represents a length in bytes; n must be adhered to exactly. |
Table 6: Macro syntax: Suffixes for data types
The operand values can be entered directly as a character string or integer number (see c-string and integer data types) or identified indirectly by means of a variable (see var: data type). The following table contains the data types that are possible for variables.
Data types of the variables
Data type | Meaning | Definition in the program |
char:n | This variable is a character string of n characters. If no length is specified, n=1 is assumed. | CLn |
int:n | This variable is an integer number that occupies n bytes. If no length is specified, n=1 is assumed. Condition: n ≤ 4 | FLn |
enum-of E:n | The variable is the enumeration E that occupies n bytes. If no length is specified, n=1 is assumed. (n ≤ 4) | XLn |
pointer | The variable is an address or an address value. | A |
Table 7: Macro syntax: Data types of the variables
Standard headers
All macros use the standard header to identify their interface.
The standard header is a field 8 bytes in length at the start of the parameter range containing the (standardized) name of the interface and 4 bytes for recording a return code.
The standard header is generated and initialized by the relevant macro. It is assigned the relevant values for UNIT, FUNCTION, and VERSION.
Structure of the standard header
Byte | Field contents and meaning |
0 - 1 | Name of the function unit (UNIT) with the demanded function |
2 | Name of the function (FUNCTION) within the function unit |
3 | Name of the modification status (VERSION) of the function |
4 | Subvalue 2 of the return code (subcode2) |
5 | Subvalue 1 of the return code (subcode1) |
6 - 7 | Main value of the return code (maincode) |
The following return code values apply for all macros:
| (SC2) | SC1 | Maincode | Meaning |
| X‘00‘ | X‘00‘ | X‘0000‘ | Function was executed successfully. There is no additional information for the maincode. |
| X‘01‘ | X‘00‘ | X‘0000‘ | Function was executed successfully. No further actions are required. |
| X‘00‘ | X‘01‘ | X‘FFFF‘ | The required function is not supported (incorrect specification for UNIT or FUNCTION in the default header). Error that cannot be resolved. |
| X‘00‘ | X‘02‘ | X‘FFFF‘ | The required function is not available. Error that cannot be resolved. |
| X‘00‘ | X‘03‘ | X‘FFFF‘ | The specified version of the interface is not supported (incorrect version specification in the default header). Error that cannot be resolved. |
| X‘00‘ | X‘04‘ | X‘FFFF‘ | Parameter block not in line with the word limit. |
| X‘00‘ | X‘41‘ | X‘FFFF‘ | The subsystem is not available; it must be generated explicitly. |
| X‘00‘ | X‘42‘ | X‘FFFF‘ | The calling task is not connected with this interface; it must be connected explicitly. |
| X‘00‘ | X‘81‘ | X‘FFFF‘ | The subsystem is not currently available. |
| X‘00‘ | X‘82‘ | X‘FFFF‘ | The subsystem is in the status DELETE or HOLD. |
Maincode identifies the result of executing the function. Subcode1 is used to classify the main value. Subcode2 is used to further divide the errors in error classes or contains additional diagnostic information.