NAME
The name of the routine. This argument is required for all
procedure kinds. There is no default. For example:
NAME=FOOZLE
ALIASES
List of alias names for the routine. This argument is optional
for all procedure types. There is no default. For example:
ALIASES=<FOO,BAR,FOOBAR,foo,bar,foobar,Foo,Bar,FooBar>
LOCAL
Boolean value indicating whether the routine is local (TRUE) or
externally visible (FALSE). This argument is optional for all
procedure kinds. The default is FALSE. For example:
LOCAL=TRUE
STANDARD_PROLOGUE
Specifies a Boolean value to indicate whether $ROUTINE should
generate a standard instruction prologue sequence at the
beginning of the routine's code section. This argument is
optional and valid only with REGISTER and STACK procedures. If
the procedure type is stack or register, the default is TRUE and
$ROUTINE generates a standard prologue sequence. The prologue
sequence generated by $ROUTINE saves the registers you specify
with the SAVED_REGS argument and performs stack-frame management
as necessary.
If you also specify BASE_REG_IS_FP=FALSE, the standard prologue
sequence generated by $ROUTINE makes a copy of the procedure
descriptor address that is in R27 upon entry into R29 (FP). While
you cannot change the value in R29 before the epilogue, you can
use R29 as a working, linkage-section register. If you specify
the STANDARD_PROLOGUE argument as FALSE, you must code your own
prologue sequence and mark the end of the prologue with the $END_
PROLOGUE macro. Whether or not you specify STANDARD_PROLOGUE as
TRUE or accept the default, you can generate a standard epilogue
sequence for stack and register procedures with the $RETURN
macro. For example:
STANDARD_PROLOGUE=FALSE
ENTRY
The name of the code-entry point. This argument is the code
entry-point label that $ROUTINE defines for you at the beginning
of the code section for the routine. If this argument is omitted,
$ROUTINE generates a label. For example:
ENTRY=FOOZLE_ENTRY
CODE_SECTION
The psect name and attributes of the code section. This argument
is optional for all procedure kinds. If omitted, the default
is the name and attributes defined by the $CODE$ lexical string
symbol. If you specify a name and attributes for the CODE_SECTION
argument, $ROUTINE redefines the $CODE$ lexical string symbol
such that the specified values become the new default. Initially,
$CODE$ is defined as follows:
$CODE$ = "$CODE$,OCTA,PIC,CON,REL,LCL,SHR,EXE,NORD,NOWRT"
Since you must delimit the psect name and attributes using
commas, be sure to enclose this argument within angle brackets
to avoid having the assembler interpret the name and attributes
as different arguments to $ROUTINE. For example:
CODE_SECTION=<MY_CODE,EXE,QUAD,NOWRT>
DATA_SECTION
The psect name and attributes of the data section. This argument
is optional for all procedure kinds. If omitted, the default
is the name and attributes defined by the $DATA$ lexical string
symbol. If you specify a name and attributes for the DATA_SECTION
argument, $ROUTINE redefines the $DATA$ lexical string symbol
such that the specified values become the new default. Initially,
$DATA$ is defined as follows:
$DATA$ = "$DATA$,OCTA,NOPIC,CON,REL,LCL,NOSHR,NOEXE,RD,WRT"
Since you must delimit the psect name and attributes using
commas, be sure to enclose this argument within angle brackets
to avoid having the assembler interpret the name and attributes
as different arguments to $ROUTINE. For example:
DATA_SECTION=<MY_DATA,NOEXE,QUAD,RD,WRT>
DATA_SECTION_POINTER
Boolean value indicating whether $ROUTINE should store a pointer
to the data section in the linkage section and define $DP as
the address of that pointer. This argument is optional for all
procedure kinds. The default is FALSE. For example:
DATA_SECTION_POINTER=TRUE
You can use the DATA_SECTION_POINTER argument as follows:
$ROUTINE TALLY_HO, DATA_SECTION_POINTER=TRUE
$DATA_SECTION
TALLY: .QUAD 0
$CODE_SECTION
.BASe R27, $LS ; Inform assembler that R27->$LS
LDQ R1, $DP ; R1->$DS
.BASE R1,$DS ;Inform assembler that R1-$DS
LDQ R0, TALLY ; R0<-TALLY
LDA R0, 1(R0) ; R0<-R0++
STQ R0, TALLY ; TALLY<-R0
RET (R26) ; Return
$END_ROUTINE TALLY_HO
In this example, the DATA_SECTION_POINTER argument is specified
in order to obtain linkage to the data section. The first LDQ
instruction loads R1 with the pointer to the data section
that $ROUTINE stores in the linkage section. The next three
instructions increment the value in the TALLY variable in the
data section. Finally, the routine returns the incremented value
to its caller in R0.
LINKAGE_SECTION
The psect name and attributes of the linkage section. This
argument is optional for all procedure kinds. If omitted, the
default is the name and attributes defined by the $LINK$ lexical
string symbol. If you specify a name and attributes for the
LINKAGE_SECTION argument, $ROUTINE redefines the $LINK$ lexical
string symbol such that the specified values become the new
default. Initially, $LINK$ is defined as follows:
$LINK$ = "$LINK$,OCTA,NOPIC,CON,REL,LCL,NOSHR,NOEXE,RD,NOWRT"
Since you must delimit the psect name and attributes using
commas, be sure to enclose this argument within angle brackets
to avoid having the assembler interpret the name and attributes
as different arguments to $ROUTINE. For example:
LINKAGE_SECTION=<MY_LINK,NOEXE,QUAD,RD,NOWRT>
KIND
Specifies the kind of routine being defined. This must be one
of the following: STACK, REGISTER, NULL, or BOUND. This is an
optional argument. The default is NULL. For example:
KIND=STACK
HANDLER_REINVOKABLE
Specifies a Boolean value to indicate whether the condition
handler can be re-invoked. This argument is optional and valid
only with STACK and REGISTER procedures. It defaults to FALSE
if no value is specified and the procedure kind is STACK or
REGISTER. Note that this argument is only valid if a value is
also specified for the HANDLER argument. For example:
HANDLER_REINVOKABLE=TRUE
BASE_REG_IS_FP
Specifies a Boolean value to indicate whether register R29
(FP) is used as the frame-pointer base register (TRUE) or not
(FALSE). If specified as FALSE, R29 must be used to hold the
address of the procedure descriptor (or the address of the
address of the procedure descriptor-see the OpenVMS Calling
Standard. You can use R29 to hold a working copy of the linkage-
section address passed in R27. In addition, your prologue and
epilogue instruction sequences can be shorter and more efficient.
However, you cannot make standard calls to other routines if
BASE_REG_IS_FP is specified as FALSE. This argument is optional
and valid only with stack and register procedure kinds. It
defaults to TRUE if the procedure type is stack or register.
For example:
BASE_REG_IS_FP=FALSE
REI_RETURN
Specifies a Boolean value to indicate whether this routine
returns using an REI instruction. This argument is optional and
valid only with STACK, REGISTER, and NULL procedure kinds. It
defaults to FALSE if the procedure kind is STACK, REGISTER, or
NULL. For example:
REI_RETURN=TRUE
STACK_RETURN_VALUE
This argument is obsolete. Do not specify this argument.
RSA_OFFSET
An integer value specifying the stack offset (in bytes) of the
register save area. This argument is optional and valid only
for STACK procedures. If you specify BASE_REG_IS_FP as TRUE,
the value you specify with RSA_OFFSET must be at least 8. RSA_
OFFSET defaults to 8 if BASE_REG_IS_FP is specified as TRUE, 0
otherwise. For example:
RSA_OFFSET=32
SAVE_FP
The register that contains a copy of the value of FP (R29) upon
entry to this routine. The prologue instruction sequence must
copy FP to the register specified by SAVE_FP and the epilogue
instruction sequence(s) must restore FP from the register
specified by SAVE_FP. This argument is required and only valid
for REGISTER procedures. There is no default. For example:
SAVE_FP=R1
SAVE_RA
The register that contains the return address. This argument
is optional and only valid for REGISTER procedures. If SAVE_RA
is not R26, the prologue instruction sequence must copy R26 to
the register specified by SAVE_RA and the epilogue instruction
sequence(s) must use the return address stored in the register
specified by SAVE_FP to affect its return to caller. SAVE_RA
defaults to R26 if the procedure kind is REGISTER. For example:
SAVE_RA=R22
SIZE
A numeric value that must be a multiple of 16 specifying the
size of the fixed-stack area in bytes. This parameter is valid
only for REGISTER and STACK procedure kinds. It defaults to the
minimum value possible given the other arguments you specify or
default. $ROUTINE computes the amount of stack storage needed for
the register save area (if any) and defines the $RSA_END symbol
to be the offset of the first byte beyond the register save area.
If you wish to allocate a fixed area of stack beyond the register
save area, you can specify an expression with the SIZE argument
that includes the term $RSA_END plus the amount of fixed-stack
storage you need for your application. For example:
SIZE=$RSA_END+32
SAVED_REGS
A list of registers saved on the stack by the prologue code of
this routine. It is valid only for STACK procedures and you must
specify at least FP (R29) with this argument. It defaults to FP
(R29) for STACK procedures. For example:
SAVED_REGS=<R5,FP,F2,F3,F4>
The OpenVMS Calling Standard specifies that registers R0, R1,
R28, R30 (SP), and R31 must never be saved and restored. If
you specify these registers with the SAVED_REGS argument, the
$ROUTINE macro issues a diagnostic warning message.
HANDLER
The address of an exception handler. It is optional and valid
only for STACK and REGISTER procedure kinds. By default, the
procedure is defined not to have an exception handler. For
example:
HANDLER=MY_HANDLER
HANDLER_DATA
The address of data for the specified handler, if any. This
argument is optional and valid only for stack and register
procedure kinds and has no default value. You cannot specify a
HANDLER_DATA argument if you do not specify the HANDLER argument.
For example:
HANDLER_DATA=MY_HANDLER_DATA
SYNCH_EXCEPTIONS
An argument to indicate whether exceptions must be synchronized
or not. This argument is optional with STACK and REGISTER
routines and is not allowed with other kinds of routines. This
argument defaults to TRUE if you specify an exception handler
with the HANDLER argument. Otherwise, it defaults to FALSE.
When this argument is TRUE and you specify or accept the default
STANDARD_PROLOGUE=TRUE, $ROUTINE generates a TRAPB instruction
as part of the standard prologue sequence. In addition, when this
argument is true, the $RETURN macro generates a TRAPB instruction
as part of the standard epilogue sequence. When this argument is
FALSE, neither $ROUTINE nor $RETURN generate TRAPB instructions.
PROC_VALUE
The procedure value of a bound procedure's parent. This argument
is required for BOUND procedures and is invalid for all other
procedure kinds. For example:
PROC_VALUE=PARENT_PROC
ENVIRONMENT
Specifies an environment value. This parameter is optional and
valid only for BOUND procedures. It has no default value. For
example:
ENVIRONMENT=0
FUNC_RETURN
Specifies the function return type. This argument is optional
and valid for all procedure kinds. If specified, it must be one
of the following: I64, D64, I32, U32, FF, FD, FG, FS, FT, FFC,
FDC, FGC, FSC, or FTC. These values correspond to those listed in
Table 3-7 of the OpenVMS Calling Standard that have an additional
"RASE$K_FR_" prefix. There is no default. For example:
FUNC_RETURN=U32
ARGLIST
Argument type list. This argument is optional and valid for
all procedure kinds. If the argument list contains one or more
elements, each of the first six elements must be one of the
following: Q, I32, U32, FF, FD, FG, FS, or FT. The seventh and
subsequent arguments (if any) must be either I32 or Q.
These values correspond to the PSIG$K_RA_* and MASE$K_MA_*
signature encodings in Table 3-6 of the OpenVMS Calling Standard.
There is no default. If you specify this argument, $ROUTINE
generates a procedure signature block. For example:
ARGLIST=<Q,I32,FF,FF,U32>.
USES_VAX_ARGLIST
Specifies a Boolean value indicating whether the routine uses a
VAX argument list. This argument is optional for all procedure
kinds and defaults to FALSE. If you specify this argument,
$ROUTINE generates a procedure signature block. For example:
USES_VAX_ARGLIST=TRUE
OVERRIDE_FLAGS
Specifies overriding flags for the PDSC$W_FLAGS field in the
procedure descriptor. This argument is optional and valid for
all procedure kinds. However, it is required for BOUND procedures
when the parameter specified with the PROC_VALUE argument is an
external or forward reference. There is no default. For example:
OVERRIDE_FLAGS=PARENT_FLAGS
DEFAULT_SIGNATURE
Specifies a Boolean value to indicate whether the standard
procedure signature is used. TRUE means to use the standard
signature. It is optional and valid for all procedure kinds.
The default is FALSE if you specify either the ARGLIST or USES_
VAX_ARGLIST arguments. Otherwise, the default is TRUE. Note that
this argument must be FALSE or blank if you specify either the
ARGLIST or USES_VAX_ARGLIST arguments. For example:
DEFAULT_SIGNATURE=TRUE
COMMON_BASE
An argument to specify one or more base registers that are used
in common with other routines. This argument is optional for
all routine kinds. By default, $ROUTINE invalidates any previous
.BASE directives that may be in effect when you invoke $ROUTINE.
In this way, you are prevented from inadvertently processing the
second or subsequent routines in a module with .BASE directives
in effect that apply only to a previous routine. However, you
may wish to share a common base register assignment between a
number of routines. To do so, you can reissue the appropriate
.BASE directive or directives after each invocation of $ROUTINE.
Alternatively, you can specify one or more common base registers
with the COMMON_BASE argument, and enter the appropriate .BASE
directive or directives only once at the beginning of the module.
Specify the value for the COMMON_BASE argument as a list of
integer registers. For example:
COMMON_BASE=<R5,R13>
In this example, $ROUTINE invalidates any previous .BASE
directives except those for registers R5 and R13. Previous .BASE
directives for registers R5 and R13 are unaffected.
TARGET_INVO
Specifies a Boolean value indicating whether or not the exception
handler for this procedure is invoked when this procedure is the
target of an invocation unwind. (TARGET_INVO=TRUE) causes the
exception handler to be invoked during an unwind. The default is
TARGET_INVO=FALSE.
EXCEPTION_MODE
An argument to specify one of the following exception modes with
STACK and REGISTER procedures:
o SIGNAL-raise all exceptions except underflow.
o SIGNAL_ALL-raise all exceptions.
o SILENT-raise no exceptions.
o FULL_IEEE-only raise exceptions as per IEEE control bits.
The default is EXCEPTION_MODE=SIGNAL.