This chapter introduces the basic macro concept: what you can use the macro facility for, how you can prepare your own macro definitions, and how you call these macro definitions for processing by the assembler.
Macro language is an extension of assembler language. It provides a convenient way to generate a desired sequence of assembler language statements many times in one or more
programs. A macro definition is written only once; thereafter, a single statement, a macro instruction statement, is written each time you want to generate the desired sequence of
statements. This simplifies the coding of programs, reduces the chance of programming errors, and ensures that standard
sequences of statements are used to accomplish desired functions.
In addition, conditional assembly allows you to code statements that mayor may not be assembled, depending upon conditions evaluated at assembly time. These conditions are usually tests of values which may be defined, set, changed, and tested during assembly. Conditional assembly can be used without using macro
instruction statements.
The main use of macros is to insert assembler language statements into a source program.
You call a named sequence of statements (the macro definition) by using a macro instruction, or macro call. The assembler replaces the macro call by the statements from the macro
definition and inserts them into the source module at the point of call. The process of inserting the text of the macro
definition is called macro ge.neration or macro expansion. The assembler expands a macro at preassembly time.
The expanded stream of code then becomes the input for processing at assembly time; that is, the time at which the assembler translates the machine instructions into object code.
A macro definition is a named sequence of statements you can call with a macro instruction. When it is called, the assembler processes and usually generates assembler language statements from the definition into the source module. The statements generated can be:
• Copied directly from the definition
• Modified by parameter values before generation
• Manipulated by internal macro processing to change the sequence in which they are generated
You can define your own macro definitions in which any combination of these three processes can occur. Some macro definitions, like some of those used for system generation, do not generate assembler language statements, but perform only
internal processing.
A macro definition provides the assembler with (1) the name of the macro, (2) the parameters used in the macro, and (3) the sequence of statements the assembler generates when the macro instruction appears in the source program.
146 Assembler H Version 2 Application Programming: Language Reference
0 , ,', .. ' I, "
o
o
Model statements
o
Every macro definition consists of a macro definition header statement (MACRO); a macro instruction prototype statement; one or more assembler language statements; and a macro definitio~
trailer statement (MEND), as shown in Figure 37.
MACRO
Prototype
MACID &PARAMl,&PARAM2
_.._""-.... ----""'..,----JI
• •
•
Body of Macro- - - -.... MEND
•
Macro Instruction
MACID OPERANDl,OPERAND2
Figure 37. Parts of a Macro Definition
•
The macro definition header and trailer statements (MACRO and MEND) indicate to the assembler the beginning and end of a macro definition (see (1) in Figure 37).• The macro instruction prototype statement is used to name the macro (see (2) in Figure 37), and to declare its
parameters (see (3) in Figure 37). In the operand field of the macro instruction, you can assign values (see (4) in Figure 37) to the parameters declared for the called macro definition.
• The body of a macro definition (see (5) in Figure 37)
contains the statements that will be generated when you call the macro. These statements are called model statements;
they are usually interspersed with conditional assembly statements or other processing statements.
You can also write assembler language statements as model statements. When it expands the macro, the assembler copies them exactly as they are written. You can also use variable symbols as points of substitution in a model statement. The assembler will enter values in place of these points of substitution each time the macro is called.
The three types of variable symbols in the assembler language are:
• Symbolic parameters, declared in the prototype statement
•
•
System variable symbols
SET symbolsl which are part of the conditional assembly language
Chapter 6. Introduction to Macro Language 147
The assembler processes the generated statements, with or without value substitution, at assembly time.
Processing statements
comments statements
Processing statements perform functions at preassembly time when macros are expanded, but they are not themselves generated for further processing at assembly time. The processing statements are!
• Conditional assembly instructions
• Inner macro calls
• MNOTE instructions
• MEXIT instructions
• AREAD instructions
The MNOTE instruction allows you to generate an error message with an error condition code attached, or to generate comments
in which you can display the results of preassembly computation.
The MEXIT instruction tells the assembler to stop processing a macro definition. The MEXIT instruction, therefore, provides an exit from the middle of a macro definition.
The MEND instruction not only delimits the contents of a macro definition, but also provides an exit from the definition.
Th~ AREAD instruction allows you to assign to a SETC symbol the character string value of a statement that is placed immediately after a macro instruction.
One type of comments statement describes preassembly operations and is not generated. The other type describes assembly-time operations and is, therefore, generated.
MACRO INSTRUCTION STATEMENT
A macro instruction statement (hereafter called 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.
The macro instruction provides the assembler with:
• The name of the macro definition to be processed.
• 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:
• A sequence of statements generated from the model statements of the macro for further processing at assembly time.
• 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 148 Assembler H Version 2 Application Programming: Language Reference
o
o
0· ··'·'
~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
MACRO LIBRARY
You can include a macro definition in a source module. This type of definition is called a soyrce macro definition.
You can also insert a macro definition into a system or user library (located, for example, on disk) by using the appropriate utility program. This type of definition is called a library macro definjtion. 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.
Source and library macros are expanded in the same way, but syntax errors are handled differently. In source macros, error messages are attached to the statements in error. In library macros, however, error messages cannot be associated with the statement in error, because these macros are located and edited after the entire source module has been read. Therefore, the error messages are associated with the END statement.
Because of the difficulty of finding syntax errors in library macros, a macro definition should be run and "debugged" as a source macro before it is placed in a macro library.
The same macro definition may 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. Once a macro definition has been placed in the macro library, it may be used by writing its corresponding macro instruction in a source program. Macro definitions must be in the system macro library under the same name as the prototype.
The prncedure for placing macro definitions in the macro library is described in the appropriate utilities manual.
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 appropriate supervisor services and macro instructions and data management macro instructions manuals.
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:
•
Variables•
Data attributes•
Expression computation•
Assignment instructions•
Labels for branchingChapter 6. Introduction to Macro Language 149
• Branching instructions
•
Substring operators that select characters from a string You can 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.
You can use the functions of the conditional assembly language to select statements for generation, to determine their order of generation, and to perform computations that affect the content of the generated statements.
The conditional assembly language is described in "Chapter 9.
How to Write Conditional Assembly Instructions."
150 Assembler
H
Version 2 Application Programming: language Referenceo
G
o
o
o
o
CHAPTER 7. HOW TO PREPARE MACRO DEFINITIONS
Defining a macro means preparing the statements that constitute a macro definition. To define a macro you must:
• Give it a name.
• Declare any parameters to be used.
• Write the statements it contains.
• Establish its boundaries with a MACRO and a MEND instruction.
Except for conditional assembly instructions, this chapter describes all the statements that can be used to prepare macro definitions. Conditional assembly instructions are described in
"Chapter 9. How to Write Conditional Assembly Instructions" on page 195.