Keyword operands

You can use a keyword operand to pass a value through a keyword parameter into a macro definition. The values you specify in keyword operands override the default values assigned to the keyword parameters. Set the default value to a value you use frequently. Thus, you avoid having to write this value every time you code the calling macro instruction.

When you need to change the default value, you must use the corresponding keyword operand in the macro instruction. The keyword can indicate the purpose for which the passed value is used.

Any keyword operand specified in a macro instruction must correspond to a keyword parameter in the macro definition called. However, keyword operands do not have to be specified in any particular order.

The general specifications for symbolic parameters also apply to keyword operands. The actual operand keyword must be a valid variable symbol. A null character string can be specified as the standard value of a keyword operand, and is generated if the corresponding keyword operand is omitted.

A keyword operand must be coded in this format:

KEYWORD=VALUE

where:

KEYWORD: Has up to 62 characters without an ampersand.
VALUE: Can be up to 1024 characters.

The corresponding keyword parameter in the called macro definition is specified as:

&KEYWORD=DEFAULT

If a keyword operand is specified, its value overrides the default value specified for the corresponding keyword parameter.

If the DBCS assembler option is specified, the keyword operand can be a string containing double-byte data. The string does not need to be quoted.

If the value of a keyword operand is a literal, two equal signs must be specified.

The following examples of macro instructions have keyword operands:

          MACKEY         KEYWORD=(A,B,C,D,E)
          MACKEY         KEY1=1,KEY2=2,KEY3=3
          MACKEY         KEY3=2000,KEY1=0,KEYWORD=HALLO
          MACKEY         KEYWORD='<.S.T.R.I.N.G>'
          MACKEY         KEYWORD==C'STRING'

To summarize the relationship of keyword operands to keyword parameters:

The keyword of the operand corresponds (see 1 in Figure 1) to a keyword parameter. The value in the operand overrides the default value of the parameter.
If the keyword operand is not specified (see 2 in Figure 1), the default value of the parameter is used.
If the keyword of the operand does not correspond (see 3 in Figure 1) to any keyword parameter, the assembler issues an error message, but the macro is generated using the default values of the other parameters.
The default value specified for a keyword parameter can be the null character string (see 4 in Figure 1). The null character string is a character string with a length of zero; it is not a space, because a space occupies one character position.

Figure 1. Relationship between keyword operands and keyword parameters and their assigned values

                                      ┌─  4  Null character string
                                      │      is default value
          MACRO                       V
          MACCORR &KEY1=DEFAULT,&KEY2=,&KEY3=123
          .
          .
          DC    C'&KEY1&KEY2&KEY3'
          .
          .
          MEND
────────────────────────────────────────────────────────
───────
 OPEN     START 0
          .
          .        1             1      1 
          MACCOOR KEY1=OVERRIDE,KEY2=0,KEY3=456
          .            │             │      │
          .       ┌────┘  ┌──────────┘      │
          .       V       V                 │
+         DC    C'OVERRIDE0456'             │
          .                ∧                │
          .                └────────────────┘
          .
          MACCOOR    2 
          .              ┌──── KEY2 has null character
          .              │     string as default
          .              V
+         DC    C'DEFAULT123'
          .
          .
          .          3 
          MACCOOR   KEY4=SYMBOL,KEY2=0
ASMA017W ** WARNING ** Undefined keyword parameter . . .
          .
          .
          .
+         DC    C'DEFAULT0123'
          .
          .
          .
          MACCOOR   KEY1=,KEY3=456
          .       ┌──────────────────── • KEY1 parameter has null
          .       │                       character string value
          .       V                     • KEY2 has null character
+         DC    C'456'                    string as default
          END