6.2 Basics and Conventions .1 Origin and Format
6.2.7 The Macro Library
To standardize interface conventions, automate production of commonly used code sequences, and impose a structure to the runtime library, a series of macros are used.
This section describes the function, use, and expansion of these macros. Lower case letters are used to indicate variable fields. Square brackets [ ] indicate optional fields, braces { } indicate a choice of required fields.
AMAIN
Function:
Defines "name" as the primary entry point of a routine.
INTSIC=YES:
Defines the routine (and any entry points) as an intrinsic. If the INTSIC operand is omitted, the routine is defined as a procedure.
1 TITLE
2 WORKAREA macro definition used only if additional stack storage was needed 3 AMAIN
4 * Comment card describing the function of the primary entry point 5 INPUT
6 OUTPUT
7 Body of executable code including use of WORK, AERROR, AEXIT macros where needed and alternate entry points defined using the AENTRY macro, function comment card, and INPUT and OUTPUT macros in the same manner as the primary entry point.
8 DC constant area addressed via PC relative mode
9 ADATA, followed by a DC constant area addressed via base and displacement mode. Used only if constants need to be indexed.
10 ACLOSE
name AMAIN INTSIC = YES INTERNAL
ACALL = YES SECTOR = 0
INTSIC=INTERNAL:
Defines an intrinsic which is called only by other routines in the library. At present, this is only GTBYTE and STBYTE.
ACALL=YES:
(Valid only for procedure routines) Allows use of the ACALL macro within the routine (See ACALL description).
SECTOR=0:
Defines the routine (intrinsic or procedure) as a Sector 0 routine.
Expansion:
The macro first defines the primary entry "name" (the AMAIN label) as the CSECT name, unless SECTOR=0 was specified. In the latter case, the CSECT name is generated by prefixing "name" with #0, and the primary entry "name" is defined using the DS and ENTRY statements. The options selected via the AMAIN operands are saved in global SETB variables for testing by the other macros. If either INTSIC option was selected, the macro ends. Otherwise, a procedure is being defined, so the STACK DSECT is generated.
The STACK DSECT consists of a standard 18 halfword area, including symbols for the saved copies of the fixed point register parameters (ARG2, ARG4, ARG5, ARG6, ARG7), followed by the WORKAREA macro. The WORKAREA macro is the means by which additional storage beyond the standard stack of 18 halfwords may be defined. If such storage is needed a local WORKAREA macro must have been defined earlier in the source which contains the appropriate DS assembler statements. These statements are thus incorporated as the remainder of the STACK DSECT. If additional storage is not needed, the local WORKAREA macro is not defined. As a result, the system WORKAREA macro is invoked, which does not define any storage, leaving the STACK DSECT at its standard length. The system WORKAREA macro also sets a global SETB variable, which is tested later by the AMAIN macro to determine if the stack is standard or augmented. The STACK DSECT is then terminated by resuming the original CSECT. The STACK DSECT is defined in this sequence so that the assembler will output the SYM records in the order expected by the link editor's stack size algorithm. A USING statement is generated to give addressability to the stack area. Finally, the executable code of the entry prologue is generated. For PASS, this consists of an NIST instruction to zero the 10th halfword of the new stack frame, establishing a null ON ERROR environment. The Backup Operating System (BOS) does not require NIST, therefore, BFS does not use NIST. In addition, if both ACALL=YES is specified and a local WORKAREA provided, the default stack size of 18 set up by the SCAL microcode will be insufficient, so an IAL to set up the new stack size is generated.
AENTRY
name AENTRY Function:
Defines "name" as a secondary entry point.
Expansion:
"name" is externally defined using the DS and ENTRY statements. If the routine was defined as an intrinsic, the macro ends. Otherwise, the executable code of the entry prologue is generated in the same manner as the AMAIN macro.
AEXIT
Function:
Cause return of control from a procedure or intrinsic routine.
CC:
Used to pass a condition code back to the caller. It can be used only if OUTPUT CC was specified (See OUTPUT macro).
Valid for Intrinsics Only:
CC=KEEP:
Passes back the condition code as is.
CC=(rx):
Passes back the condition code generated by a LR rx, rx.
Valid for Procedures Only:
CC=EQ:
Passes back an equal (B’00’) condition code.
CC=NE:
Passes back a not equal (B‘11’) condition code.
Note: The CC= operand is used in the following 8 routines:
CPR, CPRA, CSTR, CSTRUCT, VV8DN, VV8D3, VV8SN, and VV8S3.
COND=code:
Used to do a conditional return, i.e. based on the current condition code. Valid for procedures only. "Code" is either a number used as the mask on a BC opcode, or a letter or letter pair representing the mask in the extended BC mnemonic op codes (E, Z, NE, NZ, H, O, L, M, HE, LE, NL, NM, NH, NO). This operand may be used to improve the efficiency of some routines. If used, be sure valid executable code follows it, so the fall through case is valid.
KEEP name AEXIT CC = (rx) EQ NE COND = code
Expansion:
The code generated by the AEXIT macro depends primarily on whether the routine is an intrinsic or procedure, and secondarily on what operands were supplied, and, in the case of intrinsics, what fixed point registers were used. The expansions for intrinsics and procedures are described separately.
Intrinsics:
If register(s) R1 and/or R3 have been defined (see INPUT, OUTPUT, and WORK macros), it is assumed they have been modified and must be restored from the stack, since they are the addressing registers for compiled code. This is done via the appropriate LH instruction(s), or IHL and SLL instructions if CC=KEEP was specified, since LH would destroy the existing condition code. If CC=(rx) was specified, a LR rx,rx is generated to set the condition code. Finally, a BCRE or BCR is generated to cause a return to the caller. A BCR is generated if SECTOR=0 or INTSIC=INTERNAL was specified on the AMAIN macro.
Procedures:
If CC=EQ or CC=NE was specified, the condition code bits in the return PSW in the stack are zeroed or set via the ZB or SB instruction. Then, an SRET instruction is generated with a mask of 7 if the COND operand was omitted or the appropriate mask if it was supplied.
I2DEDR
name I2DEDR dpscalar1, dpscalar2, dpscalar3, dpscalar4 Function:
I2DEDR was substituted for DEDR in DMOD in order to avoid incorrect results caused by some inputs. See CR11164 and DR106660.
IBMCEDR
name IBMCEDR dpscalar1, dpscalar2 Function:
IBMCEDR was substituted for CEDR in DMDVAL and DMOD in order to avoid incorrect results caused by an incorrectly set condition code. See CR11163 and DR106644.
INPUT
⎧register spec type comments⎫
INPUT ⎨NONE ⎬ ⎩ ⎭ Function:
Defines input interface of primary or alternate entry point and symbolic names for the register(s).
Register Spec:
One of R1, R2, R3, R4, R5, R6, R7, F0, F1, F2, F3, F4, F5, F6, or F7. If there is no input (RANDOM, RANDG only), code NONE. If there is more than one, use continuation lines for each subsequent one (see examples).
Type Comments:
type precision units SCALAR SINGLE/DOUBLE RADIANS MATRIX(3,3)
MATRIX(N,N) VECTOR(3) VECTOR(N) INTEGER(N) CHARACTER Examples:
col. 16 col. 72 ↓ ↓ (1) INPUT F0 SCALAR SINGLE RADIANS X (2) INPUT R2, VECTOR(N) DOUBLE X R3, VECTOR(N) DOUBLE X R5 INTEGER(N) SINGLE
Expansion:
For each register spec supplied, the macro checks for a valid register symbolic, or for the special case of NONE. If the symbolic register name has not been previously defined, an EQU statement is generated to define it. The macro also tests for the illegal use of R1 or R3 for a procedure parameter and R4 for an intrinsic. A global arrayed SETB variable is set, which in conjunction with the AMAIN, AENTRY, and ACLOSE macros, will guarantee that an INPUT macro has been supplied for each entry point (see ACLOSE macro).
OUTPUT
⎧register spec type comments⎫ OUTPUT ⎨NONE ⎬ ⎩CC ⎭ Function:
Defines output interface of primary or alternate entry point.
Operand form is identical to that of INPUT macro, with the addition of CC as a possibility. This indicates that the condition code is the output of the routine. If CC is specified, the CC= option of the AEXIT macro must be used.
Expansion:
Same as for INPUT macro, except for special processing for the CC operand. If CC is supplied, a global SETB variable is set which is tested by the AEXIT macro for consistency with its CC operand.
Note: R1 and R3 are illegal inputs for procedure routines and R4 is illegal for intrinsic routines.
WORK
WORK {register spec}
Function:
Defines work registers.
Expansion:
Similar to INPUT and OUTPUT, except that this macro is required only if additional register symbols need to be defined.