3.
Code a move character instruction that moves the parameter list from its non-executable position in your program into the virtual storage area that you obtained.
4.
For macros that have a modify form, you can code the modify form of the macro to change the parameter list. Use the address parameter of the modify form to reference the parameter list in the virtual storage area that you obtained. Thus, the parameter list that you change is the one in the virtual storage area obtained by the GETMAIN or STORAGE macro.
5.
Invoke the macro by issuing the execute form of the macro. Use the address parameter of the execute form to reference the parameter list in the virtual storage area that you obtained.
With this technique, the parameter list is safe even if the first task is interrupted and a second task intervenes. When the program runs under the second task, it cannot access the parameter list in the virtual storage of the first task.
Alternative list form macros
Certain macros, called alternative list form macros, require a somewhat different technique for using the list form. With these macros, you do not move the area defined by the list form into virtual storage that you have obtained; instead, you place the area defined by the list form into a DSECT. Also, it is the list form, not the execute form, that you use to specify the address parameter that identifies the address of the storage for the parameter list. Note that no modify form is available for these macros.
You can use the macro forms for the alternative list form macros as follows:
1.
Use the list form of the macro to define an area of storage that the execute form can use to store the parameters. As with other macros, do not code the list form in the instruction stream of your program.
2.
In the instruction stream, code a GETMAIN or a STORAGE macro to obtain virtual storage for the list form expansion.
3.
Place the area defined by the list form into a DSECT that maps a portion of the virtual storage you obtained.
4.
Invoke the macro by issuing the execute form of the macro. The address parameter specified on the list form references the parameter list in the virtual storage area that you obtained.
Coding the macros
In this information, each macro description includes a syntax diagram near the beginning of the macro description. The diagram shows how to code the macro.
The syntax diagram does not explain the meanings of the parameters; the meanings are explained in the parameter descriptions that follow the syntax diagram. For most macros, the syntax diagrams are in a tabular format; however, some newer macros might have syntax diagrams in the railroad track format.
The syntax tables assume that the standard begin, end, and continue columns are used. Thus, column 1 is assumed as the begin column. To change the begin, end, and continue columns, use the ICTL instruction to establish the coding format you want to use. If you do not use ICTL, the assembler recognizes the standard columns. To code the ICTL instruction, see HLASM Language Reference.
Figure 2 on page 14 shows a sample macro called TEST and summarizes all the
coding information that is available for it. The table is divided into three zones, A,
Chapter 1. Using the services
13
A
B
B, and C.
C
A1
A2
B1
B2
name
b
TEST b
name:
symbol. Begin
name
in column 1.
One or more blanks must precede TEST.
One or more blanks must follow TEST.
MATH
HIST
GEOG
,DATA=
data addr data addr:
RX-type address, or register (2) - (12)
,LNG=
data length
data length: symbol or decimal digit, with a maximum value of 256.
,FMT=HEX
,FMT=DEC
,FMT=BIN
,PASS=
,grade value
Default: FMT=HEX
value:
symbol, decimal digit, or register (1) or (2) - (12).
Default: PASS=65
grade: symbol, decimal digit, or register (1) or (2) - (12).
Figure 2. Sample tabular syntax diagram for the TEST macro
v Column one of the table contains zones A and B. Zone A begins at the left margin; zone B is indented from the left margin by one or more blank spaces.
Column two of the table contains zone C.
v Zone A and zone B contain those parameters that are allowed for the macro.
Zone A contains those parameters that are required; zone B contains those parameters that are optional.
v If a parameter appears on a single line in the diagram (that is, a line whose preceding line and following line are both blank), as shown in A1 and B1, then that is the only available choice for the particular parameter.
v If two or more parameters appear on adjacent lines (that is, with no intervening blank lines), as shown in A2 and B2, the parameters on those lines are mutually exclusive, that is, you can code any one of those parameters.
v A further distinction is made between mandatory and optional parameters. The parameter descriptions that follow the syntax table clearly identify those parameters which are optional.
v Zone C (which is the second column in the syntax table), provides additional information about coding the macro.
When substitution of a variable is indicated in zone C, the following classifications are used:
Variable
Classification
14
z/OS MVS Authorized Assembler Services Reference ALE-DYN
symbol
Any symbol valid in the assembler language. The symbol can be as long as the supported maximum length of a name entry in the assembler you are using.
Decimal digit
Any decimal digit up to and including the value indicated in the parameter description. If both symbol and decimal digit are indicated, an absolute expression is also allowed.
Register (2) - (12)
One of general purpose registers 2 through 12, specified within parentheses, previously loaded with the right-adjusted value or address indicated in the parameter description. You must set the unused high-order bits to zero. You can designate the register symbolically or with an absolute expression.
Register (0)
General purpose register 0, previously loaded with the right-adjusted value or address indicated in the parameter description. You must set the unused high-order bits to zero. Designate the register as (0) only.
Register (1)
General purpose register 1, previously loaded with the right-adjusted value or address indicated in the parameter description. You must set the unused high-order bits to zero. Designate the register as (1) only.
Register (15)
General purpose register 15, previously loaded with the right-adjusted value or address indicated in the parameter description. You must set the unused high-order bits to zero. Designate the register as (15) only.
RX-type address
Any address that is valid in an RX-type instruction (for example, LA).
RS-type address
Any address that is valid in an RS-type instruction (for example, STM).
RS-type name
Any name that is valid in an RS-type instruction (for example, STM).
A-type address
Any address that can be written in an A-type address constant.
Default
A value that is used in default of a specified value; that is, the value the system assumes if the parameter is not coded.
Rules for parameters:
Use the parameters to specify the services and options to be performed, and write them according to the following rules: v If the selected parameter is written in all capital letters (for example, MATH,
HIST, or FMT=HEX), code the parameter exactly as shown.
v If the selected parameter is written in italics (for example, grade), substitute the indicated value, address, or name.
v If the selected parameter is a combination of capital letters and italics separated by an equal sign (for example, DATA=data addr), code the capital letters and equal sign as shown, and then make the indicated substitution for the italicized portion.
v Read the table from top to bottom.
v Code commas and parentheses exactly as shown.
Chapter 1. Using the services
15
v Positional parameters (parameters without equal signs) appear first; you must code them in the order shown. You may code keyword parameters (parameters with equal signs) in any order.
v If you select a parameter, read the second column (zone C) before proceeding to the next parameter. The second column often contains coding restrictions for the parameter.
Continuation lines
You can continue the parameter field of a macro on one or more additional lines according to the following rules: v Enter a continuation character (not blank, and not part of the parameter coding) in column 72 of the line.
v Continue the parameter field on the next line, starting in column 16. All columns to the left of column 16 must be blank.
You can code the parameter field being continued in one of two ways. Code the parameter field through column 71, with no blanks, and continue in column 16 of the next line; or truncate the parameter field by a comma, where a comma normally falls, with at least one blank before column 71, and then continue in
column 16 of the next line. Figure 3 shows an example of each method.
1
10 16
44 72
NAME 1
NAME 2
OP1 OPERAND1,OPERAND2,OPERAND3,OPERAND4,OPERAND5,OPERAND6,OPX
ERAND7
THIS IS ONE WAY
OP2 OPERAND1,OPERAND2
OPERAND3,OPERAND4,
THIS IS ANOTHER WAY
X
X
OPERAND5,OPERAND6,OPERAND7
Figure 3. Continuation Coding
Coding the callable services
A callable service is a programming interface that uses the CALL macro to access system services. To code a callable service, code the CALL macro followed by the name of the callable service, and a parameter list; for example:
CALL service,(parameter list)
Syntax
The syntax diagram for the sample callable service SCORE:
Description
CALL SCORE
,(test_type
,level
,data
,format_option
,return_code)
Considerations for coding callable services are:
16
z/OS MVS Authorized Assembler Services Reference ALE-DYN
