Operand entry

Use the operand entry of a macro instruction to pass values into the called macro definition. These values can be passed through:

The two types of operands allowed in a macro instruction are positional and keyword operands. You can specify a sublist with multiple values in both types of operands. Special rules for the various values you can specify in operands are also given below.

Positional operands

You can use a positional operand to pass a value into a macro definition through the corresponding positional parameter declared for the definition. You should declare a positional parameter in a macro definition when you want to change the value passed at every call to that macro definition.

You can also use a positional operand to pass a value to the system variable symbol &SYSLIST. If &SYSLIST, with the applicable subscripts, is specified in a macro definition, you do not need to declare positional parameters in the prototype statement of the macro definition. You can thus use &SYSLIST to refer to any positional operand. This allows you to vary the number of operands you specify each time you call the same macro definition.

The positional operands of a macro instruction must be specified in the same order as the positional parameters declared in the called macro definition.

Each positional operand constitutes a character string. This character string is the value passed through a positional parameter into a macro definition.

The specification for each positional parameter in the prototype statement definition must be a valid variable symbol. Values are assigned (see  1  in Figure 29) to the positional operands by the corresponding positional arguments (see  2  in Figure 29) specified in the macro instruction that calls the macro definition.

Figure 29. Positional operands
                       Source Module
             *------------------------------------------------*
Macro        |         MACRO                                  |
Definition   *------------------------------------------------*
             |         POSPAR         &POS1,&POS2,&POS3       |
             |         .                ^     ^     ^         |
             |         .                |     |     |         |
             |         MEND             |     |     |         |
             *--------------------------+-----+-----+---------*
             |         .                |     |     |         |
             |         .                1     1     1         |
             |         START            |     |     |         |
             |         .                |  *--* *---*         |
             |         .                |  |    |             |
Macro        |         POSPAR         ONE,TWO,THREE      2    |
Instruction  |         .                                      |
             |         .                                      |
             |         END                                    |
             *------------------------------------------------*

Notes:
  1. An omitted operand has a null character value.
  2. Each positional operand can be up to 1024 characters long.
  3. If the DBCS assembler option is specified, the positional operand can be a string containing double-byte data. The string need not be quoted.

The following are examples of macro instructions with positional operands:

         MACCALL         VALUE,9,8
         MACCALL         &A,'QUOTED STRING'
         MACCALL         EXPR+2,,SYMBOL
         MACCALL         (A,B,C,D,E),(1,2,3,4)
         MACCALL         &A,'<.S.T.R.I.N.G>'

The following list shows what happens when the number of positional operands in the macro instruction is equal to or differs from the number of positional parameters declared in the prototype statement of the called macro definition:

Equal
Valid, if operands are correctly specified.
Greater than
Meaningless, unless &SYSLIST is specified in definition to refer to excess operands.
Less than
Omitted operands give null character values to corresponding parameters (or &SYSLIST specification).

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. The default value should be 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 need not 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:

Figure 30. 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

Combining positional and keyword operands

You can use positional and keyword operands in the same macro instruction. Use a positional operand for a value that you change often, and a keyword operand for a value that you change infrequently.

Positional and keyword parameters can be mixed freely in the macro prototype statement (see  1  in Figure 31). The same applies to the positional and keyword operands of the macro instruction (see  2  in Figure 31). Note, however, that the order in which the positional parameters appear (see  3  in Figure 31) determines the order in which the positional operands must appear. Interspersed keyword parameters and operands (see  4  in Figure 31) do not affect this order.

Figure 31. Combining positional and keyword parameters
                                    4 
                          *---------*---------*
              MACRO       V                   V
       1      MIX   &P1,&KEY1=A,&P2,&P3,&P4,&KEY2=,&P5
              .     1           2   3   4          5      3 
              .
              .
              MEND
-----------------------------------------------------------------
              START 0
              .
              .
              .            1   2   3             4    5      3 
       2      MIX   KEY1=B,ONE,TWO,THREE,KEY2=33,FOUR,FIVE
              .      ^                    ^
              .      *---------*----------*
              .                4 
              END

&SYSLIST(n): The system variable symbol &SYSLIST(n) refers only to the positional operands in a macro instruction.


[ Top of Page | Previous Page | Next Page | Contents | Index ]