Issues a call to another routine.
Format
$CALL NAME=routine-being-called -
[Rls=linkage-section-register] -
[LS=linkage-section-address] -
[LOCAL=boolean] -
[ARGS=argument-list] -
[SET_ARG_INFO=boolean-value] -
[STACK_RETURN_VALUE=boolean-value] -
[SCRATCH_REGS=scratch_reg-list] -
[TIE=boolean-value] -
[FUNC_RETURN=
{I64,D64,I32,U32,FF,FD,FG,FS,FT,FDC,FGC,FSC,FTC}]
-
[USES_VAX_ARGLIST=boolean-value] -
[SIGNATURE_BLOCK=signature_address] -
[NONSTANDARD=boolean-value] -
1 – Parameters
NAME
The name of the routine to call. This argument is required.
Rls
Linkage section register to use when generating the LDQ, LDQ, JSR
instruction sequence. This argument is optional.
If Rls is omitted, $CALL assumes that you entered a .BASE
directive before invoking $CALL that establishes the value of a
base register pointing into the linkage section. If you omit the
Rls argument and you do not enter such a .BASE directive before
invoking $CALL, the assembler issues the following error message
during the $CALL macro expansion:
"Argument 2 invalid" The assembler failed to find a
base register specified with a previous .BASE directive
to form a register expression of the form offset(Rn)"
LS
LS is the address of the linkage section. If you use $CALL within
a routine defined by the $ROUTINE macro, the LS argument defaults
to the $LS symbol defined by $ROUTINE. If you use $CALL outside
of a routine defined by the $ROUTINE macro, there are two ways
that you can indicate the location of the linkage section to
$CALL. First, you can specify the LS argument to $CALL as a
relocatable address expression that indicates the base of the
linkage section. In this case you must also specify the Rls
argument. Second, you can specify both the linkage-section base
register and the linkage-section address in a .BASE directive
before invoking $CALL. In this case, you must omit both the Rls
and LS arguments to $CALL.
Digital recommends that you omit this argument if you use $CALL
within a routine defined by the $ROUTINE macro.
LOCAL
A Boolean value (TRUE or FALSE) that specifies whether the
routine to be called is local to the module or globally visible.
By default, $CALL generates a call to a globally visible routine.
To generate a call to a routine that is not globally visible, you
must specify LOCAL=TRUE.
ARGS
An optional list of arguments to pass to the called routine.
Enclose the argument list within angle brackets (<>) and
separate the arguments with commas (,). You can use the
following qualifiers with each argument you specify with the
ARGS argument. These qualifiers are described in the following
table.
Each argument is an address expression (which may include a
register) followed by a qualifier. The table also contains
the argument type, the instruction used to load the argument
into a register, the instruction used to store the argument on
the stack, and the encodings used in the Argument Information
Register (R25) in the call signature block when you specify
TIE=TRUE. See the OpenVMS Calling Standard for more information
on these encodings. Note that arguments are only stored on
the stack if there are more than six arguments provided to the
routine.
ARGS Arguments
_________________________________________________________________________
Argument
Argument LOAD STORE AI Reg Arg Mem Arg
Qualifier Type Instruction Instruction Encoding Signature Signature
_________________________________________________________________________
1.1 /A Address LDA STQ I64 I32 I32
1.2 /D D-floating LDG STG FD FD Q
1.3 /F F-floating LDF STF FF FF I32
1.4 /G G-floating LDG STG FG FG Q
1.5 /L Longword LDL STQ I64 I32 I32
1.6 /Q Quadword LDQ STQ I64 Q Q
1.7 /S S-floating LDS STS FS FS I32
1.8 /T T-floating LDT STT FT FT Q
1.9 /UL(1) Unsigned LDL STQ I64 U32 I32
Longword /ZAP
#^xF0
_______________________________________________________________________
(1)--Unsigned 32-bit integers are normally passed using the /L argument
qualifier. Therefore, Digital does not recommend that you use the /UL
argument qualifier.
_______________________________________________________________________
SET_ARG_INFO
An optional argument to indicate whether $CALL should
set the Argument Information (AI) register (R25) with
the appropriate argument information or not. By default,
or if you specify SET_ARG_INFO=TRUE, $CALL stores the
appropriate argument information in R25. If you specify
SET_ARG_INFO=FALSE, $CALL does not affect R25.
If you want to conform to the OpenVMS Calling Standard, you
must store the appropriate information in R25 yourself before
invoking $CALL. If you do not need to conform to the OpenVMS
Calling Standard, and if the called routine does not need
argument information in R25, you can specify SET_ARG_INFO=FALSE
and make no change in R25. By making no change in R25, you
avoid the overhead involved when either you or $CALL load
argument information into R25 at the expense of calling standard
conformance.
STACK_RETURN_VALUE
An optional argument to indicate that the called routine returns
a value on the stack. By default, $CALL assumes that the called
routine does not return a value on the stack. In this case, $CALL
removes any arguments passed to the called routine from the stack
when the called routine returns.
If the called routine returns a value on the stack, the returned
value is placed at a lower address than the arguments on the
stack. In this case, you must specify STACK_RETURN_VALUE=TRUE
to prevent $CALL from removing the arguments to the called
routine from the stack and erasing the value returned by the
called routine. You must retrieve the return value and remove it
from the stack. Then you can remove the arguments to the called
routine using the $STACK_ARG_SIZE symbol defined by $CALL.
SCRATCH_REGS
An optional list of scratch registers for $CALL to use when
processing arguments passed to the called routine with the ARGS
argument. If you pass more than six arguments to the called
routine, $CALL may need to use scratch registers to process the
call.
By default, $CALL uses R0, R1, F0, and F1. You can cause $CALL to
use different scratch registers with the SCRATCH_REGS argument.
If you are passing integer arguments, you should specify at
least one integer register. If you are passing floating-point
arguments, you should specify at least one floating-point
register.
$CALL can process arguments to the called routine more
efficiently if you specify two or more scratch registers of the
type or types appropriate to the arguments you are passsing.
TIE
A Boolean value (TRUE or FALSE) that specifies whether $CALL
should generate a call sequence that is compatible with both
native routines and the Translated Image Environment (TIE). By
default, $CALL generates a faster call sequence that is only
compatible with native routines. If you specify TIE=TRUE, $CALL
generates a call sequence that works with both native routines
and translated routines. If you are calling a VAX routine in a
shareable image that has been translated with the DECmigrate
image translator, specify TIE=TRUE. If you are calling a native
routine, Digital recommends you default the TIE argument or
specify TIE=FALSE. While $CALL generates a call sequence that
is compatible with native routines when you specify TIE=TRUE,
that call sequence is slower than when you specify or default
TIE=FALSE.
FUNC_RETURN
An optional argument used to indicate the type of function return
when you also specify TIE=TRUE. This argument is ignored unless
you also specify TIE=TRUE. Specify one of I64, D64, I32, U32,
FF, FD, FG, FS, FT, FFC, FDC, FGC, FSC, or FTC. These values
correspond to the RASE$K_FR_* signature encodings described
in Table 3-7 in the OpenVMS Calling Standard. If you specify
TIE=TRUE and do not specify a function return type with FUNC_
RETURN, the default function return type is I64.
NOTE
Specification of the FUNC_RETURN argument does not in itself
cause $ROUTINE to generate a procedure signature block.
However, if you specify either or both the ARGLIST or USES_
VAX_ARGLIST arguments, any value you specify with the FUNC_
RETURN argument is recorded in both the procedure descriptor
and the procedure signature block.
USES_VAX_ARGLIST
An optional argument to indicate whether the called routine uses
a VAX argument list. This argument is ignored unless you also
specify TIE=TRUE. By default, $CALL assumes the called routine
does not use a VAX argument list. Specify USES_VAX_ARGLIST=TRUE
to indicate that the called routine uses a VAX argument list.
SIGNATURE_BLOCK
An optional argument that you can use to supply the address of
the call signature block. This argument is ignored unless you
also specify TIE=TRUE. Note that you cannot specify a SIGNATURE_
BLOCK argument in combination with either of the FUNC_RETURN
or USES_VAX_ARGLIST arguments. By default, $CALL generates a
call signature block for you when you specify TIE=TRUE, and you
can in part control the contents of that signature block with
the FUNC_RETURN and USES_VAX_ARGLIST arguments. If you wish to
define your own call signature block, do not specify either of
the FUNC_RETURN or USES_VAX_ARGLIST arguments and supply the
address of your call signature block with the SIGNATURE_BLOCK
argument.
NONSTANDARD
A Boolean value (TRUE or FALSE) that specifies whether $CALL
should suppress warning and informational messages concerning
nonstandard usage. By default, $CALL issues warning and
informational messages to indicate you are using $CALL in a
way that violates the OpenVMS Calling Standard or in a way
that requires special programming considerations. Specify
NONSTANDARD=TRUE if you wish to suppress these messages.
2 – Description
$CALL issues a call to another routine and performs the following
actions:
1. Searches a list of linkage pairs referenced in previous
invocations of the $CALL and $LINKAGE_PAIR macros. If a
linkage pair is already in the list, $CALL uses the linkage
pair from the previous invocation. Otherwise, $CALL stores
the linkage pair of the called routine in the caller's linkage
section and adds the linkage pair to the caller's list. If you
use $CALL within a routine defined with the $ROUTINE macro,
$CALL and $LINKAGE_PAIR reset the list of linkage pairs for
each routine.
2. Allocates stack space for arguments if necessary.
3. Generates instructions to load the arguments to the called
routine.
4. Sets the value in the argument information register, R25.
5. Generates the following instruction sequence to perform
the actual call based on the location of the linkage pair
generated from step 1 and the address specified or defaulted
with the LS argument. The register specified with the Rls
argument is assumed to point to the base of the linkage
section as shown in the following example:
LDQ R26, code_address_offset(Rls) ; load code address
LDQ R27, procedure_descriptor_address_offset(Rls) ; load
; procedure
; descriptor
; address
JSR R26, R26
6. Frees argument stack space, if any, and if the called routine
does not return a value on the stack.
3 – Examples
Example 1
$CALL SUB1, Rls=R13, LS=MY_LINKAGE_SECTION
.BASE R13, MY_LINKAGE_SECTION
$CALL SUB2
$ROUTINE SUB3, KIND=STACK, SAVED_REGS=<R2,FP>
$LINKAGE_SECTION
.QUAD 1
XX:
$CODE_SECTION
MOV R27, R2
$CALL SUB4, R2
.BASE R2, $LS
$CALL SUB5
$CALL SUB6, -
ARGS=<XX/A, R0/Q>, -
SCRATCH_REGS=<R22,R23>
$CALL SUB7, -
ARGS=<1/A,2/A,3/A>
$RETURN
$END_ROUTINE SUB3
Example 2
$CALL FOO, ARGS=<A,B,C,D,E,F,G,H>, STACK_RETURN_VALUE=TRUE
; Fetch octaword return value from stack
LDQ R4, 0(SP) ; low quadword
LDQ R5, 8(SP) ; high quadword
LDA SP, $STACK_ARG_SIZE+16(SP) ; RESET STACK