High Level Assembler for z/OS & z/VM & z/VSE. Language Reference (Version 1 Release 6)

Source Module

┌────────────────────────────────────────────────┐

Macro

│

MACRO

│

Definition

├────────────────────────────────────────────────┤

│

POSPAR

&POS1,&POS2,&POS3

│

⌂

│

MEND

│

├──────────────────────────┼─────┼─────┼─────────┤

│

▌1▐

│

START

│

┌──┘ ┌───┘

│

Macro

│

POSPAR

ONE,TWO,THREE

▌2▐

│

Instruction

│

END

│

!────────────────────────────────────────────────┘

Figure 35. Positional operands

Notes:

1. An omitted operand has a null character value.

2. Each positional operand can be up to4064 characters long.

3. If the DBCS assembler option is specified, the positional operand can be a

string containing double-byte data. The string does not need to be quoted.

Here 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. 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.

Chapter 8. How to write macro instructions

301

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 4064 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:

v The keyword of the operand corresponds (see ▌1▐ in Figure 36 on page 303) to a

keyword parameter. The value in the operand overrides the default value of the

parameter.

v If the keyword operand is not specified (see ▌2▐ in Figure 36 on page 303), the

default value of the parameter is used.

v If the keyword of the operand does not correspond (see▌3▐ in Figure 36 on page

303) to any keyword parameter, the assembler issues an error message, but the

macro is generated using the default values of the other parameters.

v The default value specified for a keyword parameter can be the null character

string (see ▌4▐ in Figure 36 on page 303). 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.

302

HLASM V1R6 Language Reference

┌─ ▌4▐ Null character string

│

is default value

MACRO

⌂

MACCORR &KEY1=DEFAULT,&KEY2=,&KEY3=123

C’&KEY1&KEY2&KEY3’

MEND

────────────────────────────────────────────────────────

───────

OPEN

START 0

▌1▐

MACCOOR KEY1=OVERRIDE,KEY2=0,KEY3=456

│

┌────┘

┌──────────┘

│

⌂

│

C’OVERRIDE0456’

│

⌂

│

└────────────────┘

MACCOOR

▌2▐

┌──── KEY2 has null character

│

string as default

⌂

C’DEFAULT123’

▌3▐

MACCOOR KEY4=SYMBOL,KEY2=0

ASMA017W

** WARNING ** Undefined keyword parameter

C’DEFAULT0123’

MACCOOR KEY1=,KEY3=456

┌──────────────────── • KEY1 parameter has

null

│

character string value

⌂

• KEY2 has null character

C’456’

string as default

END

Figure 36. Relationship between keyword operands and keyword parameters and their

assigned values

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 37 on page 304). The same applies to the positional

and keyword operands of the macro instruction (see ▌2▐ in Figure 37 on page 304).

Note, however, that the order in which the positional parameters appear (see ▌3▐

in Figure 37 on page 304) determines the order in which the positional operands

Chapter 8. How to write macro instructions

303

must appear. Interspersed keyword parameters and operands (see ▌4▐ in Figure

37)

do not affect this order.

▌4▐

┌─────────┴─────────┐

MACRO

⌂

▌1▐

MIX &P1,&KEY1=A,&P2,&P3,&P4,&KEY2=,&P5

⁴

⁵

▌3▐

MEND

─────────────────────────────────────────────────────────────────

START 0

₁

₂

₃

₄

₅

▌3▐

▌2▐

MIX KEY1=B,ONE,TWO,THREE,KEY2=33,FOUR,FIVE

⌂

└─────────┬──────────┘

▌4▐

END

Figure 37. Combining positional and keyword parameters

&SYSLIST(n): The system variable symbol &SYSLIST(n) refers only to the

positional operands in a macro instruction.

Sublists in operands

You can use a sublist in a positional or keyword operand to specify several values.

A sublist is a character string that consists of one or more entries separated by

commas and enclosed in parentheses.

If the COMPAT(SYSLIST) assembler option is not specified, a variable symbol that

has been assigned a character string that consists of one or more entries separated

by commas and enclosed in parentheses is also treated as a sublist. However, if the

COMPAT(SYSLIST) assembler option is specified, a sublist assigned to a variable

symbol is treated as a character string, not as a sublist.

A variable symbol is not treated as a sublist if the parentheses are not present. The

following example shows two calls to macro MAC1. In the first call, the value of the

operand in variable &VAR1 is treated as a sublist. In the second call, the value of the

operand is treated as a character string, not a sublist, because the variable &VAR2

does not include parentheses.

&VAR1

SETC

’(1,2)’

MAC1

KEY=&VAR1

&VAR2

SETC

’1,2’

MAC1

KEY=(&VAR2)

To refer to an entry of a sublist code, use:

v The corresponding symbolic parameter with an applicable subscript.

v The system variable symbol &SYSLIST with applicable subscripts, the first of

which refers to the positional operand, and the second to the sublist entry in the

operand. &SYSLIST can refer only to sublists in positional operands.

Figure 38 on page 305 shows that the value specified in a positional or keyword

operand can be a sublist.

304

HLASM V1R6 Language Reference

A symbolic parameter can refer to the whole sublist (see▌1▐ in Figure 38), or to an

individual entry of the sublist. To refer to an individual entry, the symbolic

parameter (see ▌2▐ in Figure 38) must have a subscript whose value indicates the

position (see ▌3▐ in Figure 38) of the entry in the sublist. The subscript must have a

value greater than or equal to 1.

A sublist, including the enclosing parentheses, must not contain more than 4064

characters. It consists of one or more entries separated by commas and enclosed in

parentheses; for example, (A,B,C,D,E). () is a valid sublist with the null character

string as the only entry.

MACRO

SUBLISTS &P1,&P2,&KEY=(F0,F,0)

⌂

Refers to default value

┌───▌3▐──┘

in keyword operand

│

&KEY(1) DC

&KEY(2)’&KEY(3)’

┌────────────▌3▐

Refers to value in

&P1(1) DC

&P1(2)’&P1(3)’

│

positional operand

▌2▐

│

A&P2

│

!───────────────▌1▐

│

MEND

│

──────────────────────────────────┼──────┼───────────────────────────────

OPEN

START 0

│

⌂

│

┌─────┐

│

SUBLISTS (H20,H,200),(A,B,C)

│

⌂

│

!──────────────┘

+F0

F’0’

+H20

H’200’

A(A,B,C)

END

Figure 38. Sublists in operands

Table 48 on page 306 shows the relationship between subscripted parameters and

sublist entries if:

v A sublist entry is omitted (see ▌1▐ in Table 48 on page 306).

v The subscript refers past the end of the sublist (see▌2▐ in Table 48 on page 306).

v The value of the operand is not a sublist (see ▌3▐ in Table 48 on page 306).

v The parameter is not subscripted (see ▌4▐ in Table 48 on page 306).

&SYSLIST(n,m): The system variable symbol, &SYSLIST(n,m), can also refer to

sublist entries, but only if the sublist is specified in a positional operand.

Chapter 8. How to write macro instructions

305

Table 48. Relationship between subscripted parameters and sublist entries

Sublist specified in

corresponding operand

or as default value

Value generated or used in

Parameter

of a keyword parameter

computation

▌1▐ &PARM1(3)

(1,2,,4)

Null character string

▌2▐ &PARM1(5)

(1,2,3,4)

Null character string

&PARM1▌3▐

&PARM1(1)

&PARM1(2)

Null character string

▌4▐ &PARM1

(A)¹

(A)

&PARM1(1)▌2▐

(A)¹

&PARM1(2)

(A)¹

Null character string

&PARM1

()¹

()

&PARM1(1)

()¹

Null character string

&PARM1(2)

()¹

Null character string

&PARM1(2)

(A, ,C,D)²

Nothing³

&PARM1(1)

( )²

Nothing³

&PARM1

A,(1,2,3,4)⁴

&PARM2(3)

A,(1,2,3,4)⁴

&SYSLIST(2,3)

A,(1,2,3,4)⁴

Notes:

1. Considered a sublist.

2. The space indicates the end of the operand field.

3. Produces error diagnostic message ASMA088E Unbalanced parentheses in macro call

operand.

4. Positional operands.

Multilevel sublists

You can specify multilevel sublists (sublists within sublists) in macro operands. The

depth of this nesting is limited only by the constraint that the total operand length

must not exceed 4064 characters. Inner elements of the sublists are referenced using

additional subscripts on symbolic parameters or on &SYSLIST.

N'&SYSLIST(n) gives the number of operands in the indicated n-th level sublist.

The number attribute (N') and a parameter name with an n-element subscript array

gives the number of operands in the indicated (n+1)-th operand sublist. Table 49 on

page 307 shows the value of selected elements if &P is the first positional

parameter, and the value assigned to it in a macro instruction is (A,(B,(C)),D).

306

HLASM V1R6 Language Reference

Table 49. Multilevel sublists

Selected Elementsfrom

Selected Elementsfrom &P &SYSLIST

Value ofSelected Element

&SYSLIST(1)

(A,(B,(C)),D)

&P(1)

&SYSLIST(1,1)

&P(2)

&SYSLIST(1,2)

(B,(C))

&P(2,1)

&SYSLIST(1,2,1)

&P(2,2)

&SYSLIST(1,2,2)

(C)

&P(2,2,1)

&SYSLIST(1,2,2,1)

&P(2,2,2)

&SYSLIST(1,2,2,2)

null

N'&P(2,2)

N'&SYSLIST(1,2,2)

N'&P(2)

N'&SYSLIST(1,2)

N'&P(3)

N'&SYSLIST(1,3)

N'&P

N'&SYSLIST(1)

Passing sublists to inner macro instructions

You can pass a suboperand of an outer macro instruction sublist as a sublist to an

inner macro instruction. However, if you specify the COMPAT(SYSLIST) assembler

option, a sublist assigned to a variable symbol is treated as a character string, not

as a sublist.

Values in operands

You can use a macro instruction operand to pass a value into the called macro

definition. The two types of value you can pass are:

v Explicit values or the actual character strings you specify in the operand

v Implicit values, or the attributes inherent in the data represented by the explicit

values

The explicit value specified in a macro instruction operand is a character string

that can contain zero or more variable symbols.

The character string must not be greater than 4064 characters after substitution of

values for any variable symbols. This includes a character string that constitutes a

sublist.

The character string values in the operands, including sublist entries, are assigned

to the corresponding parameters declared in the prototype statement of the called

macro definition. A sublist entry is assigned to the corresponding subscripted

parameter.

Omitted operands

When a keyword operand is omitted, the default value specified for the

corresponding keyword parameter is the value assigned to the parameter. When a

positional operand or sublist entry is omitted, the null character string is assigned

to the parameter.

Notes:

1. Spaces appearing between commas (without surrounding apostrophes) do not

signify an omitted positional operand or an omitted sublist entry; they indicate

the end of the operand field.

Chapter 8. How to write macro instructions

307

2. Adjacent commas indicate omission of positional operands; no comma is

needed to indicate omission of the last or only positional operand.

The following example shows a macro instruction preceded by its corresponding

prototype statement. The macro instruction operands that correspond to the third

and sixth operands of the prototype statement are omitted in this example.

EXAMPLE

&A,&B,&C,&D,&E,&F

macro prototype

EXAMPLE

17,*+4,,AREA,FIELD(6)

macro instruction

Unquoted operands

The assembler normally retains the case of unquoted macro operands. However, to

maintain uppercase alphabetic character set compatibility with earlier assemblers,

High Level Assembler provides the COMPAT(MACROCASE) assembler option.

When you specify this option, the assembler internally converts lowercase

alphabetic characters (a through z) in unquoted macro instruction operands to

uppercase alphabetic characters (A though Z), before macro expansion begins.

Special characters

Any of the 256 characters of the EBCDIC character set can appear in the value of a

macro instruction operand (or sublist entry). However, the following characters

require special consideration:

Ampersands

A single ampersand indicates the presence of a variable symbol. The assembler

substitutes the value of the variable symbol into the character string specified in a

macro instruction operand. The resultant string is then the value passed into the

macro definition. If the variable symbol is undefined, an error message is issued.

Double ampersands must be specified if a single ampersand is to be passed to the

macro definition.

Examples:

&VAR

&A+&B+3+&C*10

’&MESSAGE’

&®ISTER

Apostrophes

An apostrophe is used:

v To indicate the beginning and end of a quoted string

v In a length, type, integer, opcode, or scale attribute reference notation that is not

within a quoted string

Examples:

’QUOTED STRING’

L’SYMBOL

T’SYMBOL

Shift-out (SO) and shift-in (SI)

If the DBCS assembler option is specified, then SO (X'0E') and SI (X'0F') are

recognized as shift codes. SO and SI delimit the start and end of double-byte data.

Quoted strings and character strings

A “quoted string” is any sequence of characters that begins and ends with an

apostrophe (compare with conditional assembly character expressions described in

“Character (SETC) expressions” on page 378).

308

HLASM V1R6 Language Reference

To include one or more apostrophes or substituted apostrophes within the string

(inside the delimiting apostrophes) two apostrophes must be specified for each

apostrophe.

A “character string” is a sequence of characters that is not delimited with

apostrophes.

Quoted strings can contain double-byte data, if the DBCS assembler option is

specified. The double-byte data must be bracketed by the SO and SI delimiters.

Only valid double-byte data is recognized between the SO and SI. The SI must be

in any odd-numbered byte position after the SO. If the end of the operand is

reached before SI is found, then error ASMA203E Unbalanced double-byte

delimiters is issued.

Macro instruction operands can have values that include one or more quoted

strings. Each quoted string can be separated from the following quoted string by

one or more characters, and each must contain an even number of apostrophes.

Examples:

’’

’L’’SYMBOL’

’QUOTE1’AND’QUOTE2’

A’B’C

Attribute reference notation

You can specify an attribute reference notation as a macro instruction operand

value. The attribute reference notation must be preceded by a space or any other

special character except the ampersand and the apostrophe. See “Data attributes”

on page 325 for details about data attributes, and the format of attribute references.

Examples:

MAC1

L’SYMBOL,10+L’AREA*L’FIELD

MAC1

I’PACKED-S’PACKED

Parentheses

In macro instruction operand values, there must be an equal number of left and

right parentheses. They must be paired, that is, each left parenthesis needs a

following right parenthesis at the same level of nesting. An unpaired (single) left

or right parenthesis can appear only in a quoted string.

Examples:

(PAIRED-PARENTHESES)

()

(A(B)C)D(E)

(IN’(’STRING)

Spaces

One or more spaces outside a quoted string indicates the end of the operands of a

macro instruction. If this is not your intention, place the spaces inside quoted

strings.

Example:

’SPACES ALLOWED’

Chapter 8. How to write macro instructions

309

Commas

A comma outside a quoted string indicates the end of an operand value or sublist

entry. Commas that do not delimit values can appear inside quoted strings or

paired parentheses that do not enclose sublists.

Examples:

A,B,C,D

(1,2)3’5,6’

Equal signs

An equal sign can appear in the value of a macro instruction operand or sublist

entry:

v As the first character

v Inside quoted strings

v Between paired parentheses

v In a keyword operand

v In a positional operand, provided the parameter does not resemble a keyword

operand

Examples:

=H’201’

A’=’B

C(A=B)

2X=B

KEY=A=B

The assembler issues a warning message for a positional operand containing an

equal sign, if the operand resembles a keyword operand. Thus, if we assume that

this is the prototype of a macro definition:

MAC1

then this macro instruction generates a warning message:

MAC1

K=L

(K appears to be a valid keyword)

while this macro instruction does not:

MAC1

2+2=4

(2+2 is not a valid keyword)

Periods

A period (.) can be used in the value of an operand or sublist entry. It is passed as

a period. However, if it is used immediately after a variable symbol, it becomes a

concatenation character. Two periods are required if one is to be passed as a

character.

Examples:

3.4

&A.1

&A..1

Nesting macro instruction definitions

A nested macro instruction definition is a macro instruction definition you can

specify as a set of model statements in the body of an enclosing macro definition.

This lets you create a macro definition by expanding the outer macro that contains

the nested definition.

310

HLASM V1R6 Language Reference

All nested inner macro definitions are effectively “black boxes”: there is no

visibility to the outermost macro definition of any variable symbol or sequence

symbol within any of the nested macro definitions. This means that you cannot use

an enclosing macro definition to tailor or parameterize the contents of a nested

inner macro definition.

High Level Assembler allows both inner macro instructions and inner macro

definitions. The inner macro definition is not edited until the outer macro is

generated as the result of a macro instruction calling it, and then only if the inner

macro definition is encountered during the generation of the outer macro. If the

outer macro is not called, or if the inner macro is not encountered in the

generation of the outer macro, the inner macro definition is never edited. Figure 39

shows the editing of inner macro definitions.

┌─────────────┐

│

MACRO

│

MAC1

├─────────────────────────────────────┐

│

•

│

└─────────────┘

│

┌─────────────┐

│

MACRO

│

MAC2

├──────────────────┐

│

•

│

└─────────────┘

│

┌─────────────┐

│

MACRO

│

MAC3

│

•

│ Edited when

│

Edited when

│

•

├── MAC2 is called ├── MAC1 is called ├── definition first

│

•

│ and generated

│

encountered

│

•

│

MEND

│

└─────────────┘

│

┌─────────────┐

│

•

├──────────────────┘

│

MEND

│

└─────────────┘

│

┌─────────────┐

│

•

├─────────────────────────────────────┘

│

MEND

│

└─────────────┘

Figure 39. Editing inner macro definitions

First MAC1 is edited, and MAC2 and MAC3 are not. When MAC1 is called, MAC2

is edited

(unless its definition is bypassed by an AIF or AGO branch); when MAC2 is called,

MAC3 is edited. No macro can be called until it has been edited.

There is no limit to the number of nestings allowed for inner macro definitions.

The lack of parameterization can be overcome in some cases by using the

AINSERT statement. This lets you generate a macro definition from within another

macro generation. A simple example is shown at “Where to define a macro in a

source module” on page 245. In Figure 40 on page 312, macro ainsert_test_macro

generates the macro mac1 using a combination of AINSERT and AREAD

instructions. The mac1 macro is then called with a list of seven parameters.

Chapter 8. How to write macro instructions

311

macro

2 &name

ainsert_test_macro

ainsert

’

Macro’,back

ainsert

’

mac1’,back

ainsert

’Blah blah blah’,front

6 &aread

aread

7 &aread

setc

’&aread’(1,10)

ainsert

’&&n

seta n’’&&syslist ’,back

ainsert

’

dc a(&&n)’,back

ainsert

’

dc c’’&aread’’ ’,back

ainsert

’

mend’,back

mend

13 *

14 testains csect 0

15 *

ainsert_test_macro

17+

ainsert

’

Macro’,back

18+

ainsert

’

mac1’,back

19+

ainsert

’Blah blah blah’,front

20-Blah blah blah

21+

ainsert

’&&n

seta n’’&&syslist ’,back

22+

ainsert

’

dc a(&&n)’,back

23+

ainsert

’

dc c’’Blah blah ’’ ’,back

24+

ainsert

’

mend’,back

25>

Macro

26>

mac1

27>&n

seta n’&syslist

28>

dc a(&n)

29>

dc c’Blah blah ’

30>

mend

31 *

mac1

a,b,c,d,e,f,g

33+

dc a(7)

34+

dc c’Blah blah ’

35 *

end

Figure 40. Expanding nested macro definitions

Inner and outer macro instructions

Any macro instruction you write in the open code of a source module is an outer

macro instruction or call. Any macro instruction that appears within a macro

definition is an inner macro instruction or call.

Levels of macro call nesting

The code generated by a macro definition called by an inner macro call is nested

inside the code generated by the macro definition that contains the inner macro

call. In the macro definition called by an inner macro call, you can include a macro

call to another macro definition. Thus, you can nest macro calls at different levels.

The &SYSNEST system variable indicates how many levels you called. It has the

value 1 in an outer macro, and is incremented by one at a macro call.

312

HLASM V1R6 Language Reference

Recursion

You can also call a macro definition recursively; that is, you can write macro

instructions inside macro definitions that are calls to the containing definition. This

is how you define macros to process recursive functions.

General rules and restrictions

Macro instruction statements can be written inside macro definitions. Values are

substituted in the same way as they are for the model statements of the containing

macro definition. The assembler processes the called macro definition, passing to it

the operand values (after substitution) from the inner macro instruction. In

addition to the operand values described in “Values in operands” on page 307,

nested macro calls can specify values that include:

v Any of the symbolic parameters (see ▌1▐ in Figure 41) specified in the prototype

statement of the containing macro definition

v Any SET symbols (see ▌2▐ in Figure 41) declared in the containing macro

definition

v Any of the system variable symbols, such as &SYSDATE or &SYSTIME, (see ▌3▐

in Figure 41).

┌──────────── Parameters

│

MACRO

┌────────┴────────┐

OUTERMAC

&P1,&P2,&KEY1=VALUE

Prototype

│

▌1▐

│

LCLC &C──────────────►▌2▐

│

SETC

’ABC’

│

⌂

INNERMAC

&P1,&KEY1,&C

Inner macro call

!─────┬────┘

!─────────────── Operands

MEND

─────────────────────────────────────────────────────────────────────

MACRO

OUT

Prototype

▌3▐

&SYSLIST(3),&SYSECT,A&SYSDNX Inner macro call

MEND

Figure 41. Values in nested macro calls

The number of nesting levels permitted depends on the complexity and size of the

macros at the different levels; that is, the number of operands specified, the

number of local-scope and global-scope SET symbols declared, and the number of

sequence symbols used.

When the assembler processes a macro exit instruction, either MEXIT or MEND, it

selects the next statement to process depending on the level of nesting. If the

macro exit instruction is from an inner macro, the assembler processes the next

statement after the statement that called the outer macro. The next statement in

Chapter 8. How to write macro instructions

313

open code might come from the AINSERT buffer. If the macro exit instruction is

from an outer macro, the assembler processes the next statement in open code,

after the statement that called the outer macro.

Passing values through nesting levels

The value contained in an outer macro instruction operand can be passed through

one or more levels of nesting (see Figure 42 on page 315). However, the value

specified (see ▌1▐ in Figure 42 on page 315) in the inner macro instruction operand

must be identical to the corresponding symbolic parameter (see ▌2▐ in Figure 42 on

page 315) declared in the prototype of the containing macro definition.

Thus, a sublist can be passed (see ▌3▐ in Figure 42 on page 315) and referred to

(see ▌4▐ in Figure 42 on page 315) as a sublist in the macro definition called by the

inner macro call. Also, any symbol (see ▌5▐ in Figure 42 on page 315) that is passed

carries its attribute values through the nesting levels.

If inner macro calls at each level are specified with symbolic parameters as

operand values, values can be passed from open code through several levels of

macro nesting.

COMPAT(SYSLIST) Assembler Option: If the COMPAT(SYSLIST) assembler option

is specified, and a symbolic parameter is only a part of the value specified in an

inner macro instruction operand, only the character string value given to the

parameter by an outer call is passed through the nesting level. Inner sublist entries

are, therefore, not available for reference in the inner macro.

314

HLASM V1R6 Language Reference

▌2▐

MACRO

┌────┴────┐

OUTER

&P1,&P2,&P3

INNER

&P1,&P2,&P3

!────┬────┘

▌1▐

MEND

MACRO

INNER

&Q,&R,&S

┐

3,&Q(1) │

3,&Q(2) ├ ▌4▐

3,&Q(3) │

┘

MVC

&R,&S

MEND

────────────────────────────────────────────────────────────────

START

▌5▐

┌──┴──┐

OUTER

(AREA,F200,SUM),TO,FROM¹

!──────┬──────┘

▌3▐

3,AREA

2,F200

3,SUM

MVC

TO,FROM

END

Note:

1. The following inner macro call statement is generated, but not listed unless the

PCONTROL(MCALL) option is specified, or the assembler instruction ACONTROL

MCALL is active:

INNER (AREA,F200,SUM),TO,FROM

Figure 42. Passing values through nesting levels

System variable symbols in nested macros

The fixed global-scope system variable symbols (see “System variable symbols” on

page 263) are not affected by the nesting of macros. The variable global-scope

system variable symbols have values which might change during the expansion of

a macro definition. The following system variable is influenced by nested macros:

&SYSM_SEV

Provides the highest MNOTE severity code from the nested macro most

recently called.

Chapter 8. How to write macro instructions

315

The local system variable symbols are given read-only values each time a macro

definition is called.

The following system variable symbols can be affected by the position of a macro

instruction in code or the operand value specified in the macro instruction:

&SYSCLOCK

The assembler assigns &SYSCLOCK the constant string value representing

the TOD clock value at the time at which a macro call is made. The time

portion of this value is precise to the microsecond. For any inner macro

call, the value assigned to &SYSCLOCK differs from that of its parent.

&SYSECT

The assembler gives &SYSECT the character string value of the name of

the control section in use at the point at which a macro call is made. For a

macro definition called by an inner macro call, the assembler assigns to

&SYSECT the name of the control section in effect in the macro definition

that contains the inner macro call, at the time the inner macro is called.

If no control section is generated within a macro definition, the value

assigned to &SYSECT does not change. It is the same for the next level of

macro definition called by an inner macro instruction.

&SYSLIB_DSN, &SYSLIB_MEMBER, &SYSLIB_VOLUME

The assembler assigns the character string value of the &SYSLIB system

variable symbols at the point at which a macro is called. For an inner

macro call whose definition is from a library member, these values might

differ, if this is the first time this macro is invoked.

&SYSLIST

If &SYSLIST is specified in a macro definition called by an inner macro

instruction, &SYSLIST refers to the positional operands of the inner macro

instruction.

&SYSLOC

The assembler gives &SYSLOC the character string value of the name of

the location counter in use at the point at which a macro is called. For a

macro definition called by an inner macro call, the assembler assigns to

&SYSLOC the name of the location counter in effect in the macro definition

that contains the inner macro call. If no LOCTR or control section is

generated within a macro definition, the value assigned to &SYSLOC does

not change. It is the same for the next level of macro definition called by

an inner macro instruction.

&SYSNDX

The assembler increments &SYSNDX by one each time it encounters a

macro call. It retains the incremented value throughout the expansion of

the macro definition called, that is, within the local scope of the nesting

level.

&SYSNEST

The assembler increments &SYSNEST by one each time it encounters a

nested macro instruction. It retains the incremented value within the local

scope of the macro definition called by the inner macro instruction.

Subsequent nested macro instructions cause &SYSNEST to be incremented

by 1. When the assembler exits from a nested macro it decreases the value

in &SYSNEST by 1.

&SYSSEQF

The assembler assigns &SYSSEQF the character string value of the

316

HLASM V1R6 Language Reference

identification-field of the outer-most macro instruction statement. The

value of &SYSSEQF remains constant throughout the expansion of the

called macro definition and all macro definitions called from within the

outer macro.

&SYSSTYP

The assembler gives &SYSSTYP the character string value of the type of

the control section in use at the point at which a macro is called. For a

macro definition called by an inner macro call, the assembler assigns to

&SYSSTYP the type of the control section in effect in the macro definition

that contains the inner macro call, at the time the inner macro is called.

If no control section is generated within a macro definition, the value

assigned to &SYSSTYP does not change. It is the same for the next level of

macro definition called by an inner macro instruction.

Chapter 8. How to write macro instructions

317

Chapter 9. How to write conditional assembly instructions

This chapter describes the conditional assembly language. With the conditional

assembly language, you can carry out general arithmetic and logical computations,

and many of the other functions you can carry out with any other programming

language. Also, by writing conditional assembly instructions in combination with

other assembler language statements, you can:

v Select sequences of these source statements, called model statements, from which

machine and assembler instructions are generated

v Vary the contents of these model statements during generation

The assembler processes the instructions and expressions of the conditional

assembly language during conditional assembly processing. Then, at assembly

time, it processes the generated instructions. Conditional assembly instructions,

however, are not processed after conditional assembly processing is completed.

The conditional assembly language is more versatile when you use it to interact

with symbolic parameters and the system variable symbols inside a macro

definition. However, you can also use the conditional assembly language in open

code; that is, code that is not within a macro definition.

Elements and functions

The elements of the conditional assembly language are:

v SET symbols that represent data. See “SET symbols” on page 320.

v Attributes that represent different characteristics of symbols. See “Data

attributes” on page 325.

v Sequence symbols that act as labels for branching to statements during

conditional assembly processing. See “Sequence symbols” on page 339.

The functions of the conditional assembly language are:

v Declaring SET symbols as variables for use locally and globally in macro

definitions and open code. See “Declaring SET symbols” on page 345.

v Assigning values to the declared SET symbols. See “Assigning values to SET

symbols” on page 348.

v Selecting characters from strings for substitution in, and concatenation to, other

strings; or for inspection in condition tests. See “Substring notation” on page

378.

v Branching and exiting from conditional assembly loops. See “Branching” on

page 396.

The conditional assembly language can also be used in open code with few

restrictions. See “Open code” on page 342.

The conditional assembly language provides instructions for evaluating conditional

assembly expressions used as values for substitution, as subscripts for variable

symbols, and as condition tests for branching. See “Conditional assembly

instructions” on page 343 for details about the syntax and usage rules of each

instruction.

319

SET symbols

SET symbols are variable symbols that provide you with arithmetic, binary, or

character data, and whose values you can vary during conditional assembly

processing.

Use SET symbols as:

v Terms in conditional assembly expressions

v Counters, switches, and character strings

v Subscripts for variable symbols

v Values for substitution

Thus, SET symbols let you control your conditional assembly logic, and to generate

many different statements from the same model statement.

Subscripted SET symbols

You can use a SET symbol to represent a one-dimensional array of many values.

You can then refer to any one of the values of this array by subscripting the SET

symbol. For more information, see “Subscripted SET symbol specification” on page

323.

Scope of SET symbols

The scope of a SET symbol is that part of a program for which the SET symbol has

been declared. Local SET symbols need not be declared by explicit declarations.

The assembler considers any undeclared variable symbol found in the name field

of a SETx instruction as a local SET symbol.

If you declare a SET symbol to have a local scope, you can use it only in the

statements that are part of either:

v The same macro definition, or

v Open code

If you declare a SET symbol to have a global scope, you can use it in the

statements that are part of any one of:

v The same macro definition

v A different macro definition

v Open code

You must, however, declare the SET symbol as global for each part of the program

(a macro definition or open code) in which you use it.

You can change the value assigned to a SET symbol without affecting the scope of

this symbol.

Scope of symbolic parameters

A symbolic parameter has a local scope. You can use it only in the statements that

are part of the macro definition for which the parameter is declared. You declare a

symbolic parameter in the prototype statement of a macro definition.

The scope of system variable symbols is described in Table 50 on page 321.

320

HLASM V1R6 Language Reference

High Level Assembler for z/OS & z/VM & z/VSE. Language Reference (Version 1 Release 6) - page 17