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

The assembler processes the generated statements, with or without value

substitution, at assembly time.

Processing statements

Processing statements are processed during conditional assembly, when macros are

expanded, but they are not themselves generated for further processing at

assembly time. The processing statements are:

v AEJECT instructions

v AREAD instructions

v ASPACE instructions

v Conditional assembly instructions

v Inner macro calls

v MEXIT instructions

v MNOTE instructions

The AEJECT and ASPACE instructions let you control the listing of your macro

definition. Use the AEJECT instruction to stop printing the listing on the current

page and continue printing on the next. Use the ASPACE instruction to insert

blank lines in the listing. The AEJECT instruction is described in “AEJECT

instruction” on page 258. The ASPACE instruction is described in “ASPACE

instruction” on page 261.

The AREAD instruction assigns a character string value, of a statement that is

placed immediately after a macro instruction, to a SETC symbol. The AREAD

instruction is described in “AREAD instruction” on page 259.

Conditional assembly instructions, inner macro calls, and macro processing

instructions are described in detail in the following chapters.

The MNOTE instruction generates an error message with an error condition code

attached, or generates comments in which you can display the results of a

conditional assembly computation. The MNOTE instruction is described in

“MNOTE instruction” on page 200.

The MEND statement delimits the contents of a macro definition, and also

provides an exit from the definition. The MEND instruction is described in

“MEND statement” on page 246.

The MEXIT instruction tells the assembler to stop processing a macro definition,

and provides an exit from the macro definition at a point before the MEND

statement. The MEXIT instruction is described in “MEXIT instruction” on page 261.

Comment statements

One type of comment statement describes conditional assembly operations and is

not generated. The other type describes assembly-time operations and is, therefore,

generated. For a description of the two types of comment statements, see

“Comment statements” on page 262.

Macro instruction

A macro instruction is a source program statement that you code to tell the

assembler to process a particular macro definition. The assembler generates a

sequence of assembler language statements for each occurrence of the same macro

instruction. The generated statements are then processed as any other assembler

language statement.

Chapter 6. Introduction to macro language

241

The macro instruction provides the assembler with:

v The name of the macro definition to be processed.

v The information or values to be passed to the macro definition. The assembler

uses the information either in processing the macro definition or for substituting

values into a model statement in the definition.

The output from a macro definition, called by a macro instruction, can be:

v A sequence of statements generated from the model statements of the macro for

further processing at assembly time.

v Values assigned to global SET symbols. These values can be used in other macro

definitions and in open code.

You can call a macro definition by specifying a macro instruction anywhere in a

source module. You can also call a macro definition from within another macro

definition. This type of call is an inner macro call; it is said to be nested in the

macro definition.

Source and library macro definitions

You can include a macro definition in a source module. This type of definition is

called a source macro definition, or, sometimes, an in-line macro definition.

You can also insert a macro definition into a system or user library by using the

applicable utility program. This type of definition is called a library macro definition.

The IBM-supplied macro definitions are examples of library macro definitions.

You can call a source macro definition only from the source module in which it is

included. You can call a library macro definition from any source module if the

library containing the macro definition is available to the assembler.

Syntax errors in processing statements are handled differently for source macro

definitions and library macro definitions. In source macro definitions, error

messages are listed following the statements in error. In library macros, however,

error messages cannot be associated with the statement in error, because the

statements in library macro definitions are not included in the assembly listing.

Therefore, the error messages are listed directly following the first call of that

macro.

Because of the difficulty of finding syntax errors in library macros, run and

“debug” a macro definition as a source macro before placing it in a macro library.

Alternatively, use the LIBMAC assembler option to have the assembler

automatically include the source statements of the library macro in your source

module. For more information about the LIBMAC option, see the section

“LIBMAC” in the HLASM Programmer's Guide.

Macro library

The same macro definition can be made available to more than one source

program by placing the macro definition in the macro library. The macro library is

a collection of macro definitions that can be used by all the assembler language

programs in an installation. When a macro definition has been placed in the macro

library, it can be called by coding its corresponding macro instruction in a source

program. Macro definitions must be in a macro library with a member name that

is the same as the macro name. The procedure for placing macro definitions in the

macro library is described in the applicable utilities manual.

242

HLASM V1R6 Language Reference

The DOS/VSE assembler requires library macro definitions to be placed in the

macro library in a special edited format. High Level Assembler does not require

this. Library macro definitions must be placed in the macro library in source

statement format. If you wish to use edited macros in z/VSE you can provide a

LIBRARY exit to read the edited macros and convert them into source statement

format. A library exit is supplied with z/VSE and is described in z/VSE: Guide to

System Functions.

System macro instructions

The macro instructions that correspond to macro definitions prepared by IBM are

called system macro instructions. System macro instructions are described in the

applicable operating system manuals that describe macro instructions for

supervisor services and data management.

Conditional assembly language

The conditional assembly language is a programming language with most of the

features that characterize a programming language. For example, it provides:

v Variables

v Data attributes

v Expression computation

v Assignment instructions

v Labels for branching

v Branching instructions

v Substring operators that select characters from a string

Use the conditional assembly language in a macro definition to receive input from

a calling macro instruction. You can produce output from the conditional assembly

language by using the MNOTE instruction.

Use the functions of the conditional assembly language to select statements for

generation, to determine their order of generation, and to do computations that

affect the content of the generated statements.

The conditional assembly language is described in Chapter 9, “How to write

conditional assembly instructions,” on page 319.

Chapter 6. Introduction to macro language

243

Chapter 7. How to specify macro definitions

A macro definition is a set of statements that defines the name, the format, and the

conditions for generating a sequence of assembler language statements. The macro

definition can then be called by a macro instruction to process the statements. See

page “Macro instruction” on page 241 for a description of the macro instruction. To

define a macro you must:

v Give it a name

v Declare any parameters to be used

v Write the statements it contains

v Establish its boundaries with a macro definition header statement (MACRO) and

a macro definition trailer statement (MEND)

Except for conditional assembly instructions, this chapter describes all the

statements that can be used to specify macro definitions. Conditional assembly

instructions are described in Chapter 9, “How to write conditional assembly

instructions,” on page 319.

Where to define a macro in a source module

Macro definitions can appear anywhere in a source module. They remain in effect

for the rest of your source module, or until another macro definition defining a

macro with the same operation code is encountered, or until an OPSYN statement

deletes its definition. Thus, you can redefine a macro at any point in your

program. The new definition is used for all subsequent calls to the macro in the

program.

This type of macro definition is called a source macro definition, or, sometimes, an

in-line macro definition. A macro definition can also reside in a system library; this

type of macro is called a library macro definition. Either type can be called from the

source module by the applicable macro instruction.

Macro definitions can also appear inside other macro definitions. There is no limit

to the levels of macro definitions permitted.

The assembler does not process inner macro definitions until it finds the definition

during the processing of a macro instruction calling the outer macro. The following

example shows an inner macro definition:

Example:

MACRO

Macro header for outer macro

OUTER

&A,&C=

Macro prototype

AIF

(’&C’ EQ ’’).A

MACRO

Macro header for inner macro

INNER

Macro prototype

MEND

Macro trailer for inner macro

ANOP

MEND

Macro trailer for outer macro

The assembler does not process the macro definition for INNER until OUTER is called

with a value for &C other than a null string.

245

Open Code: Open code is that part of a source module that lies outside of any

source macro definition. At coding time, it is important to distinguish between

source statements that lie in open code, and those that lie inside macro definitions.

Format of a macro definition

The general format of a macro definition is shown in Figure 32. The four parts are

described in detail in the following sections.

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

│

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

│

MACRO

Header statement

│

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

│

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

│

ANYNAME

Prototype statement│

│

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

│

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

│

Body of macro

│

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

│

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

│

MEND

Trailer statement

│

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

│

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

Figure 32. Format of a macro definition

Macro definition header and trailer

You must establish the boundaries of a macro definition by coding:

v A macro definition header statement as the first statement of the macro

definition (a MACRO statement)

v A macro definition trailer statement as the last statement of the macro definition

(a MEND statement)

The instructions used to define the boundaries of a macro instruction are described

in the following sections.

MACRO statement

Use the MACRO statement to indicate the beginning of a macro definition. It must

be the first non-comment statement in every macro definition. Library macro

definitions can have ordinary or internal macro comments before the MACRO

statement.

►► MACRO

►◄

The MACRO statement must not have a name entry or an operand entry.

MEND statement

Use the MEND statement to indicate the end of a macro definition. It also provides

an exit when it is processed during macro expansion. It can appear only once

within a macro definition and must be the last statement in every macro definition.

246

HLASM V1R6 Language Reference

►►

MEND

►◄

sequence_symbol

Is a sequence symbol.

See “MEXIT instruction” on page 261 for details on exiting from a macro before the

MEND statement.

Macro instruction prototype

The macro instruction prototype statement (from here on called the “prototype

statement”) specifies the mnemonic operation code and the format of all macro

instructions that you use to call the macro definition.

The prototype statement must be the second non-comment statement in every

macro definition. Both ordinary comment statements and internal comment

statements are allowed between the macro definition header and the macro

prototype. Such comment statements are listed only with the macro definition.

►►

operation_field

►◄

name_entry

▼

symbolic_parameter

name_entry

Is a variable symbol.

You can write this parameter, like the symbolic parameter, as the name entry of

a macro prototype statement. You can then assign a value to this parameter

from the name entry in the calling macro instruction.

If this parameter also appears in the body of a macro, it is given the value

assigned to the parameter in the name field of the corresponding macro

instruction.

operation_field

Is an ordinary symbol.

The symbol in the operation field of the prototype statement establishes the

name by which a macro definition must be called. This name becomes the

operation code required in any macro instruction that calls the macro.

Any operation code can be specified in the prototype operation field. If the

entry is the same as an assembler or a machine operation code, the new

definition overrides the previous use of the symbol. The same is true if the

specified operation code has been defined earlier in the program as a macro, in

the operation code of a library macro, or defined in an OPSYN instruction as

equivalent to another operation code.

Macros that are defined inline can use any ordinary symbol, up to 63

characters in length, for the operation field. However, operating system rules

might prevent some of these macros from being stored as member names in a

library.

Chapter 7. How to specify macro definitions

247

The assembler requires that the library member name and macro name are the

same; otherwise error diagnostic message ASMA126S Library macro name

incorrect is issued.

symbolic_parameter

The symbolic parameters are used in the macro definition to represent the

operands of the corresponding macro instruction. A description of symbolic

parameters appears under “Symbolic parameters” on page 255.

The operand field in a prototype statement lets you specify positional or

keyword parameters. These parameters represent the values you can pass from

the calling macro instruction to the statements within the body of a macro

definition.

The operand field of the macro prototype statement must contain 0 to 32000

symbolic parameters separated by commas. They can be positional parameters

or keyword parameters, or both.

If no parameters are specified in the operand field and if the absence of the

operand entry is indicated by a comma preceded and followed by one or more

spaces, remarks are allowed.

Here is an example of a prototype statement:

&NAME

MOVE

&TO,&FROM

Alternative formats for the prototype statement

The prototype statement can be specified in one of the following three ways:

v The normal way, with all the symbolic parameters preceding any remarks

v An alternative way, allowing remarks for each parameter

v A combination of the first two ways

The continuation rules for macro instructions are different from those for machine

or assembler instruction statements. This difference is important for those who

write macros that override a machine/assembler mnemonic.

The following examples show the normal statement format (&NAME1), the alternative

statement format (&NAME2), and a combination of both statement formats (&NAME3):

Opera-

Name tion Operand

Comment

Cont.

&NAME1 OP1

&OPERAND1,&OPERAND2,&OPERAND3 This is the normal

statement format

&NAME2 OP2

&OPERAND1,

This is the alter-

&OPERAND2

native statement format

&NAME3 OP3

&OPERAND1,

This is a combination

&OPERAND2,&OPERAND3,

of both

&OPERAND4

Notes:

1. Any number of continuation lines is allowed. However, each continuation line

must be indicated by a non-space character in the column after the end column

on the preceding line.

2. For each continuation line, the operand field entries (symbolic parameters)

must begin in the continue column; otherwise, the whole line and any lines

that follow are considered to contain remarks.

248

HLASM V1R6 Language Reference

No error diagnostic message is issued to indicate that operands are treated as

remarks in this situation. However, the FLAG(CONT) assembler option can

be specified so that the assembler issues warning messages if it suspects an

error in a continuation line.

3. The standard value for the continue column is 16 and the standard value for

the end column is 71.

4. A comma is required after each parameter except the last. If you code excess

commas between parameters, they are considered null positional parameters.

No error diagnostic message is issued.

5. One or more spaces is required between the operand and the remarks.

6. If the DBCS assembler option is specified, the continuation features outlined in

“Continuation of double-byte data” on page 17 apply to continuation in the

macro language. Extended continuation is useful if a macro keyword parameter

contains double-byte data.

Body of a macro definition

The body of a macro definition contains the sequence of statements that constitutes

the working part of a macro. You can specify:

v Model statements to be generated

v Processing statements that, for example, can alter the content and sequence of

the statements generated or issue error messages

v Comment statements, some that are generated and others that are not

v Conditional assembly instructions to compute results to be displayed in the

message created by the MNOTE instruction, without causing any assembler

language statements to be generated

The statements in the body of a macro definition must appear between the macro

prototype statement and the MEND statement of the definition. The body of a

macro definition can be empty, that is, contain no statements.

Nesting Macros: You can include macro definitions in the body of a macro

definition.

Model statements

Model statements are statements from which assembler language statements are

generated during conditional assembly. They let you determine the form of the

statements to be generated. By specifying variable symbols as points of

substitution in a model statement, you can vary the contents of the statements

generated from that model statement. You can also substitute values into model

statements in open code.

A model statement consists of one or more fields, separated by one or more spaces,

in columns 1 to 71. The fields are called the name, operation, operand, and

remarks fields.

Each field or subfield can consist of:

v An ordinary character string composed of alphanumeric and special characters

v A variable symbol as a point of substitution, except in remarks fields and

comment statements

v Any combination of ordinary character strings and variable symbols to form a

concatenated string

Chapter 7. How to specify macro definitions

249

The statements generated from model statements during conditional assembly

must be valid machine or assembler instructions, but must not be conditional

assembly instructions. They must follow the coding rules described in “Rules for

model statement fields” on page 252 or they are flagged as errors at assembly time.

Examples:

LABEL

3,AREA

LABEL2

3,20(4,5)

&LABEL

3,&AREA

FIELD&A

3,AREA&C

Variable symbols as points of substitution

Values can be substituted for variable symbols that appear in the name, operation,

and operand fields of model statements; thus, variable symbols represent points of

substitution. The three main types of variable symbol are:

v Symbolic parameters (positional or keyword)

v System variable symbols (see “System variable symbols” on page 263)

v SET symbols (global-scope or local-scope SETA, SETB, or SETC symbols)

Examples:

&PARAM(3)

&SYSLIST(1,3)

&SYSLIST(2)

&SETA(10)

&SETC(15)

Symbols That Can Be Subscripted: Symbolic parameters, SET symbols, and the

system variable symbols &SYSLIST and &SYSMAC, can all be subscripted. All

remaining system variable symbols contain only one value.

Listing of generated fields

The different fields in a macro-generated statement or a statement generated in

open code appear in the listing in the same column as they are coded in the model

statement, with the following exceptions:

v If the substituted value in the name or operation field is too large for the space

available, the next field is moved to the right with one space separating the

fields.

v If the substituted value in the operand field causes the remarks field to be

displaced, the remarks field is written on the next line, starting in the column

where it is coded in the model statement.

v If the substituted value in the operation field of a macro-generated statement

contains leading spaces, the spaces are ignored.

v If the substituted value in the operation field of a model statement in open code

contains leading spaces, the spaces are used to move the field to the right.

v If the substituted value in the operand field contains leading spaces, the spaces

are used to move the field to the right.

v If the substituted value contains trailing spaces, the spaces are ignored.

Listing of generated fields containing double-byte data

If the DBCS assembler option is specified, then the following differences apply:

v Any continuation indicators present in the model statement are discarded.

v Double-byte data that must be split at a continuation point is always readable on

a device capable of presenting DBCS characters—SI and SO are inserted at the

break point, and the break-point always occurs between double-byte characters.

250

HLASM V1R6 Language Reference

v The continuation indicator is extended to the left, if necessary, to fill space that

cannot be filled with double-byte data because of alignment and delimiter

considerations. The maximum number of columns filled is 3.

v If continuation is required and the character to the left of the continuation

indicator is X, then + is used as the continuation indicator so as to clearly

distinguish the position of the end column. This applies to any generated field,

regardless of its contents, to prevent ambiguity.

v Redundant SI/SO pairs can be present in a field after substitution. If they occur

at a continuation point, the assembler does not distinguish them from SI and SO

inserted in the listing by the assembler to preserve readability. Refer to the

generated object code to resolve this ambiguity. For more information, see

Table 37.

Rules for concatenation

If a symbolic parameter in a model statement is immediately preceded or followed

by other characters or another symbolic parameter, the characters that correspond

to the symbolic parameter are combined in the generated statement with the other

characters, or with the characters that correspond to the other symbolic parameter.

This process is called concatenation.

When variable symbols are concatenated to ordinary character strings, the

following rules apply to the use of the concatenation character (a period). The

concatenation character is mandatory when:

▌1▐

An alphanumeric character follows a variable symbol.

▌2▐

A left parenthesis that does not enclose a subscript follows a variable

symbol.

▌3▐—▌4▐

A period (.) is to be generated. Two periods must be specified in the

concatenated string following a variable symbol.

The concatenation character is not required when:

▌5▐

An ordinary character string precedes a variable symbol.

▌6▐

A special character, except a left parenthesis or a period, is to follow a

variable symbol.

▌7▐

A variable symbol follows another variable symbol.

▌8▐

A variable symbol is used with a subscript. The concatenation character

must not be used between a variable symbol and its subscript; otherwise,

the characters are considered a concatenated string and not a subscripted

variable symbol.

Table 37 gives the rules for concatenating variable symbols to ordinary character

strings. The highlighted numbers correspond to the numbers in the mandatory and

not required lists.

Table 37. Rules for concatenation

Values to be Substituted

Variable

Concatenated String

Symbol

Value

Generated Result

&FIELD&FIELDA AREASUM

AREAASUM

&FIELD.A

▌1▐

&FIELDA

Chapter 7. How to specify macro definitions

251

Table 37. Rules for concatenation (continued)

Values to be Substituted

Variable

Concatenated String

Symbol

Value

Generated Result

&DISP&BASE

10010

100(10)

&DISP.(&BASE)¹

⌂

▌2▐

▌6▐

&INT&FRACT

9988

DC D’&INT..&FRACT’¹

DC D’99.88’

⌂

▌3▐

▌4▐

DC D’&INT&FRACT’

DC D’9988’

⌂

▌7▐

FIELDA

FIELD&A

▌5▐

&A&B

A+B*3-D

&A+&B*3-D

⌂

!──┴── ▌6▐

&SUBSCR

10ENTRY

ENTRY

&SYM(&SUBSCR)

⌂

&SYM(10)

▌8▐

Notes:

1. The concatenation character is not generated.

Concatenation of fields containing double-byte data

If the DBCS assembler option is specified, then the following additional rules

apply:

v Because ampersand is not recognized in double-byte data, variable symbols

must not be present in double-byte data.

v The concatenation character is mandatory when double-byte data is to follow a

variable symbol.

v The assembler checks for redundant SI and SO at concatenation points. If the

byte to the left of the join is SI and the byte to the right of the join is SO, then

the SI/SO pair is considered redundant and is removed.

Note: The rules for redundant SI and SO are different for variable substitution

and listing display, which are described at “Listing of generated fields

containing double-byte data” on page 250.

The following example shows these rules:

&SYMBOL SETC

’<DcDd>’

DBCS

C’<DaDb>&SYMBOL.<.&.S.Y.M.B.O.L>’

The SI/SO pairs between double-byte characters Db and Dc, and Dd and .&, are

removed. The variable symbol &SYMBOL is recognized between the double-byte

strings but not in the double-byte strings. The result after concatenation is:

DBCS

C’<DaDbDcDd.&.S.Y.M.B.O.L>’

Rules for model statement fields

The fields that can be specified in model statements are the same fields that can be

specified in an ordinary assembler language statement. They are the name,

operation, operand, and remarks fields. You can also specify a

252

HLASM V1R6 Language Reference

continuation-indicator field, an identification-sequence field, and, in source macro

definitions, a field before the begin column if the correct ICTL instruction has been

specified. Character strings in the last three fields (in the standard format only,

columns 72 through 80) are generated exactly as they appear in the model

statement, and no values are substituted for variable symbols.

Model statements must have an entry in the operation field, and, in most cases, an

entry in the operand field in order to generate valid assembler language

instructions.

Name field

The entries allowed in the name field of a model statement, before generation, are:

v Space

v An ordinary symbol

v A sequence symbol

v A variable symbol

v Any combination of variable symbols, or system variable symbols such as

&SYSNDX, and other character strings concatenated together

The generated result must be spaces (if valid) or a character string that represents a

valid assembler or machine instruction name field. Double-byte data is not valid in

an assembler or machine instruction name field and must not be generated.

Variable symbols must not be used to generate comment statement indicators (* or

.*).

Notes:

1. You cannot reference an ordinary symbol defined in the name field of a model

statement until the macro definition containing the model statement has been

called, and the model statement has been generated.

2. Restrictions on the name entry of assembler language instructions are further

specified where each individual assembler language instruction is described in

this manual.

Operation field

The entries allowed in the operation field of a model statement, before generation,

are given in the following list:

v An ordinary symbol that represents the operation code for:

- Any machine instruction

- A macro instruction

- MNOTE instruction

- A variable symbol

- A combination of variable strings concatenated together

- All assembler instructions, except ICTL and conditional assembly instructions

The following rules apply to the operation field of a model statement:

v Operation code ICTL is not allowed inside a macro definition.

v The MACRO and MEND statements are not allowed in model statements; they

are used only for delimiting macro definitions.

v If the REPRO operation code is specified in a model statement, no substitution is

done for the variable symbols in the record following the REPRO statement.

v Variable symbols can be used alone or as part of a concatenated string to

generate operation codes for:

- Any machine instruction

Chapter 7. How to specify macro definitions

253

- Any assembler instruction, except COPY, ICTL, ISEQ, REPRO, and MEXIT

The generated operation code must not be an operation code for these

instructions, either directly, or from copies created by use of OPSYN:

- A conditional assembly instruction, such as LCLx, GBLx, SETx, AIF, and AGO

- The following assembler instructions: COPY, ICTL, ISEQ, MACRO, MEND,

MEXIT, and REPRO

v Double-byte data is not valid in the operation field.

Operand field

The entries allowed in the operand field of a model statement, before generation,

are:

v Spaces (if valid)

v An ordinary symbol

v A character string, combining alphanumeric and special characters (but not

variable symbols)

v A variable symbol

v A combination of variable symbols and other character strings concatenated

together

v If the DBCS assembler option is specified, character strings that are enclosed in

apostrophes can contain double-byte data.

The allowable results of generation are spaces (if valid) and a character string that

represents a valid assembler, machine instruction, or macro instruction operand

field.

Variable symbols: Variable symbols must not be used in the operand field of an

ICTL or ISEQ instruction. A variable symbol must not be used in the operand field

of a COPY instruction that is inside a macro definition.

Remarks field

The remarks field of a model statement can contain any combination of characters.

No substitution is done for variable symbols appearing in the remarks field.

Using spaces

One or more spaces are used to separate the fields in a model statement from each

other. Spaces cannot be generated inside a field in order to delimit another field.

However, spaces in a combined operand-remarks field can be generated to

separate these two fields. Note that if the generated operand field is part of a

macro instruction, the entire string (including spaces) is passed as an operand.

MACRO

&PARMTAG PARMCMD

&PARMOPC SETC ’LA 1,=C’’PARAMETER HEADER>>>’’ PARAMETER HEADER’ .* GENERATE LA INSTRUCTION USING R1

&PARMTAG &PARMOPC MEND

Executing this macro would generate the following:

PARMLIST PARMCMD

+PARMLIST LA 1,=C’PARAMETER HEADER>>>’ PARAMETER HEADER

Also notice how this correct example contains a remark field encoded within the

operand as permitted by the rules governing the use of spaces.

Both examples also supply a number of spaces in the operand field in a character

literal string. This is valid since a literal string does not cross field boundaries.

254

HLASM V1R6 Language Reference

Symbolic parameters

Symbolic parameters let you receive values into the body of a macro definition

from the calling macro instruction. You declare these parameters in the macro

prototype statement. They can serve as points of substitution in the body of the

macro definition and are replaced by the values assigned to them by the calling

macro instruction.

By using symbolic parameters with meaningful names, you can indicate the

purpose for which the parameters (or substituted values) are used.

Symbolic parameters must be valid variable symbols. A symbolic parameter

consists of an ampersand followed by an alphabetic character and from 0 to 61

alphanumeric characters.

Here are valid symbolic parameters:

&READER

&LOOP2

&A23456

&X4F2

&$4

Here are invalid symbolic parameters:

CARDAREA first character is not an ampersand

&256B

first character after ampersand is not alphabetic

&BCD%34

contains a special character other than initial ampersand

&IN AREA

contains a special character [space] other than initial ampersand

Symbolic parameters have a local scope; that is, the name and value they are

assigned only applies to the macro definition in which they have been declared.

The value of the parameter remains constant throughout the processing of the

containing macro definition during each call of that definition.

Notes:

1. Symbolic parameters must not have multiple definitions or be identical to any

other variable symbols within the given local scope. This applies to the system

variable symbols described in “System variable symbols” on page 263, and to

local-scope and global-scope SET symbols described in “SET symbols” on page

320.

2. Do not begin symbolic parameters with &SYS, these characters are used for

system variable symbols provided with High Level Assembler.

The two kinds of symbolic parameters are:

v Positional parameters

v Keyword parameters

Each positional or keyword parameter used in the body of a macro definition must

be declared in the prototype statement.

Here is an example of a macro definition with symbolic parameters.

MACRO

Header

&NAME

MOVE

&TO,&FROM

Prototype

&NAME

2,SAVE

Model

2,&FROM

Model

2,&TO

Model

2,SAVE

Model

MEND

Trailer

Chapter 7. How to specify macro definitions

255

Here is a macro instruction that calls this macro. The characters HERE, FIELDA, and

FIELDB of the MOVE macro instruction correspond to the symbolic parameters &NAME,

&TO, and &FROM, of the MOVE prototype statement.

HERE

MOVE

FIELDA,FIELDB

If the macro instruction is used in a source program, these assembler language

statements are generated:

HERE

2,SAVE

2,FIELDB

2,FIELDA

2,SAVE

Positional parameters

Use a positional parameter in a macro definition if you want to change the value

of the parameter each time you call the macro definition. This is because it is easier

to supply the value for a positional parameter than for a keyword parameter. You

only have to write the value you want the corresponding argument to have in the

correct position in the operand of the calling macro instruction. However, if you

need a many parameters, use keyword parameters. The keywords make it easier to

keep track of the individual values you must specify at each call by reminding you

which parameters are being given values.

See “Positional operands” on page 300 for details of how to write macro

definitions with positional parameters.

Keyword parameters

Use a keyword parameter in a macro definition for a value that changes

infrequently, or if you have many parameters. The keyword, repeated in the

operand, reminds you which parameter is being given a value and for which

purpose the parameter is being used. By specifying a standard default value to be

assigned to the keyword parameter, you can omit the corresponding keyword

argument operand in the calling macro instruction. You can specify the

corresponding keyword operands in any order in the calling macro instruction.

See “Keyword operands” on page 301 for details of how to write macro definitions

with keyword parameters.

Combining positional and keyword parameters

By using positional and keyword parameters in a prototype statement, you

combine the benefits of both. You can use positional parameters in a macro

definition for passing values that change frequently, and keyword parameters for

passing values that do not change often.

Positional and keyword parameters can be mixed freely in the macro prototype

statement.

See “Combining positional and keyword operands” on page 303 for details of how

to write macro definitions using combined positional and keyword parameters.

Subscripted symbolic parameters

Subscripted symbolic parameters must be coded in the format:

&PARAM(subscript)

256

HLASM V1R6 Language Reference

where &PARAM is a variable symbol and subscript is an arithmetic expression. The

subscript can be any arithmetic expression allowed in the operand field of a SETA

instruction (arithmetic expressions are discussed in “SETA instruction” on page

355). The arithmetic expression can contain subscripted variable symbols.

Subscripts can be nested to any level if the total length of an individual operand

does not exceed 4064 characters.

The value of the subscript must be greater than or equal to one. The subscript

indicates the position of the entry in the sublist that is specified as the value of the

subscripted parameter (sublists as values in macro instruction operands are fully

described in “Sublists in operands” on page 304).

Processing statements

This section provides information about these processing statements:

“Conditional assembly instructions”

“Inner macro instructions”

“Other conditional assembly instructions” on page 258

“AEJECT instruction” on page 258

“AINSERT instruction” on page 258

“AREAD instruction” on page 259

“ASPACE instruction” on page 261

“COPY instruction” on page 261

“MEXIT instruction” on page 261

Conditional assembly instructions

Conditional assembly instructions let you determine at conditional assembly time

the content of the generated statements and the sequence in which they are

generated. Here are the instructions and their functions:

Conditional Assembly

Operation Done

GBLA, GBLB, GBLCLCLA, LCLB, Declaration of variable symbols (global-scope and

LCLC

local-scope SET symbols) and setting of default initial

values

SETA, SETB, SETC

Assignment of values to variable symbols (SET symbols)

SETAF, SETCF

External function assignment of values to variable

symbols (SET symbols)

ACTR

Setting loop counter

AGO

Unconditional branch

AIF

Conditional branch (based on logical test)

ANOP

Pass control to next sequential instruction (no operation)

Conditional assembly instructions can be used both inside macro definitions and in

open code. They are described in Chapter 9, “How to write conditional assembly

instructions,” on page 319.

Inner macro instructions

Macro instructions can be nested inside macro definitions, allowing you to call

other macros from within your own definition.

Chapter 7. How to specify macro definitions

257

Other conditional assembly instructions

Several additional instructions can help you write your macro definitions. Here are

the instructions and their functions:

Inner Macro Instruction

Operation Done

AEJECT

Skip to next page

AINSERT

Insert statement into input stream

AREAD

Assign an arbitrary character string to a variable

symbol (SETC symbol)

ASPACE

Insert one or more blank lines in listing

COPY

Copy the source statements from a source language

library member.

MEXIT

Exit from the macro definition

AEJECT instruction

Use the AEJECT instruction to stop the printing of the assembler listing of your

macro definition on the current page, and continue the printing on the next page.

►►

AEJECT

►◄

sequence_symbol

Is a sequence symbol.

The AEJECT instruction causes the next line of the assembly listing of your macro

definition to be printed at the top of a new page. If the line before the AEJECT

statement appears at the bottom of a page, the AEJECT statement has no effect. An

AEJECT instruction immediately following another AEJECT instruction causes a

blank page in the listing of the macro definition.

Notes:

1. The AEJECT instruction can only be used inside a macro definition.

2. The AEJECT instruction itself is not printed in the listing.

3. The AEJECT instruction does not affect the listing of statements generated

when the macro is called.

AINSERT instruction

The AINSERT instruction, inside macro definitions, harnesses the power of macros

to generate source statements, for instance, using variable substitution. Generated

statements are queued in a special buffer and read after the macro generator

finishes.

The specifications for the AINSERT instruction, which can also be used in open

code, are described in “AINSERT instruction” on page 111.

258

HLASM V1R6 Language Reference

AREAD instruction

The AREAD instruction assigns an arbitrary character string value to a SETC

symbol.

The AREAD instruction has two formats. The first format lets you assign to a

SETC symbol the character string value of a statement that is placed immediately

after a macro instruction.

The AREAD instruction can only be used inside macro definitions.

Assign character string value

►► SETC_symbol AREAD

►◄

NOPRINT

NOSTMT

The second format of the AREAD instruction assigns to a SETC symbol a character

string containing the local time.

Assign local time

►► SETC_symbol AREAD

CLOCKB

►◄

CLOCKD

SETC_symbol

Is a SETC symbol. See “SETC instruction” on page 375.

NOSTMT

Specifies that the statement to be read by the AREAD instruction is printed in

the assembly listing, but not given any statement number.

NOPRINT

specifies that the statement does not appear in the listing, and no statement

number is assigned to it.

CLOCKB

Assigns an 8-character string to SETC_symbol containing the local time in

hundredths of a second since midnight.

CLOCKD

Assigns an 8-character string to SETC_symbol containing the local time in the

format HHMMSSTH, where HH is a value 00 - 23, MM and SS each have a

value 00 - 59, and TH has a value 00 - 99.

Assign character string value

The first format of AREAD functions in much the same way as symbolic

parameters, but instead of providing your input to macro processing as part of the

macro instruction, you can supply full input records from either the AINSERT

buffer (if any are present), or from the records in the primary input stream that

follow immediately after the macro instruction. Any number of successive records

Chapter 7. How to specify macro definitions

259

can be read into the macro for processing. If no records remain, a null value is

assigned, but no diagnostic message is issued.

SETC_symbol can be subscripted. When the assembler encounters a Format-1

AREAD statement during the processing of a macro instruction, it reads the source

record following the macro instruction and assigns an 80-character string to the

SETC symbol in the name field. For nested macros, it reads the record following

the outermost macro instruction.

If no operand is specified, the record to be read by AREAD is printed in the listing

and assigned a statement number. The AREAD action is indicated in the listing by

a minus sign between the statement number and the first character of the record.

Repeated AREAD instruction statements read successive records. In the following

example, the input record starting with INRECORD1 is read by the first AREAD

statement, and assigned to the SETC symbol &VAL. The input record starting with

INRECORD2 is read by the second AREAD statement, and assigned to the SETC

symbol &VAL1.

Example:

MACRO

MAC1

&VAL

AREAD

&VAL1

AREAD

MEND

CSECT

MAC1

INRECORD1 THIS IS THE STATEMENT TO BE PROCESSED FIRST

INRECORD2 THIS IS THE NEXT STATEMENT

END

The records read by the AREAD instruction can be in code brought in with the

COPY instruction, if the macro instruction employing the AREAD appears in the

COPY member. Otherwise the COPY instruction may be read as an ordinary text

line.

If no more records exist in the code brought in by the COPY instruction,

subsequent records are read from the AINSERT buffer or the primary input stream.

Assign local time of day

The second format of AREAD functions in much the same way as a SETC

instruction, but instead of supplying the value you want assigned to the SETC

symbol as a character string in the operand of the AREAD instruction, the value is

provided by the operating system in the form of an 8-character string containing

the local time. A Format-2 AREAD instruction does not cause the assembler to read

the statement following the macro instruction.

Example:

MACRO

MAC2

&VAL

AREAD CLOCKB

C’&VAL’

260

HLASM V1R6 Language Reference

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