Calls a routine that was linked with your program.
Format
CALL routine-name [(argument[, . . . ])]
1 – Parameters
routine-name
Specifies the name or the memory address of the routine to be
called.
argument
Specifies an argument required by the routine. Arguments can be
passed by address, by descriptor, by reference, and by value, as
follows:
%ADDR (Default, except for C and C++.) Passes the argument by
address. The format is as follows:
CALL routine-name (%ADDR address-expression)
The debugger evaluates the address expression and
passes that address to the routine specified. For
simple variables (such as X), the address of X is
passed into the routine. This passing mechanism is how
Fortran implements ROUTINE(X). In other words, for named
variables, using %ADDR corresponds to a call by reference
in Fortran. For other expressions, however, you must use
the %REF function to call by reference. For complex or
composite variables (such as arrays, records, and access
types), the address is passed when you specify %ADDR,
but the called routine might not handle the passed data
properly. Do not specify a literal value (a number or an
expression composed of numbers) with %ADDR.
%DESCR Passes the argument by descriptor. The format is as
follows:
CALL routine-name (%DESCR language-expression)
The debugger evaluates the language expression and
builds a standard descriptor to describe the value. The
descriptor is then passed to the routine you named. You
would use this technique to pass strings to a Fortran
routine.
%REF Passes the argument by reference. The format is as
follows:
CALL routine-name (%REF language-expression)
The debugger evaluates the language expression and passes
a pointer to the value, into the called routine. This
passing mechanism corresponds to the way Fortran passes
the result of an expression.
%VAL (Default for C and C++.) Passes the argument by value.
The format is as follows:
CALL routine-name (%VAL language-expression)
The debugger evaluates the language expression and passes
the value directly to the called routine.
2 – Qualifiers
2.1 /AST
/AST (default)
/NOAST
Controls whether the delivery of asynchronous system traps
(ASTs) is enabled or disabled during the execution of the called
routine. The /AST qualifier enables the delivery of ASTs in the
called routine. The /NOAST qualifier disables the delivery of
ASTs in the called routine. If you do not specify /AST or /NOAST
with the CALL command, the delivery of ASTs is enabled unless you
have previously entered the DISABLE AST command.
2.2 /SAVE_VECTOR_STATE
/SAVE_VECTOR_STATE
/NOSAVE_VECTOR_STATE (default)
Applies to VAX vectorized programs. Controls whether the current
state of the vector processor is saved and then restored when a
routine is called with the CALL command.
The state of the vector processor comprises the following:
o The values of the vector registers (V0 to V15) and the vector
control registers (VCR, VLR, and VMR)
o Any vector exception (an exception caused by the execution of
a vector instruction) that might be pending delivery
When you use the CALL command to execute a routine, execution
of the routine might change the state of the vector processor as
follows:
o By changing the values of vector registers or vector control
registers
o By causing a vector exception
o By causing the delivery of a vector exception that was pending
when the CALL command was issued
The /SAVE_VECTOR_STATE qualifier specifies that after the called
routine has completed execution, the debugger restores the state
of the vector processor that exists before the CALL command is
issued. This ensures that, after the called routine has completed
execution:
o Any vector exception that was pending delivery before the CALL
command was issued is still pending delivery
o No vector exception that was triggered during the routine call
is still pending delivery
o The values of the vector registers are identical to their
values before the CALL command was issued
The /NOSAVE_VECTOR_STATE qualifier (which is the default)
specifies that the state of the vector processor that exists
before the CALL command is issued is not restored by the debugger
after the called routine has completed execution. In this case,
the state of the vector processor after the routine call depends
on the effect (if any) of the called routine.
The /[NO]SAVE_VECTOR_STATE qualifiers have no effect on the
general registers. The values of these registers are always saved
and restored when you execute a routine with the CALL command.
3 – Description
The CALL command is one of the four debugger commands that
can be used to execute your program (the others are GO, STEP,
and EXIT). The CALL command enables you to execute a routine
independently of the normal execution of your program. The CALL
command executes a routine whether or not your program actually
includes a call to that routine, as long as the routine was
linked with your program.
When you enter a CALL command, the debugger takes the following
actions. For more information, see the qualifier descriptions.
1. Saves the current values of the general registers.
2. Constructs an argument list.
3. Executes a call to the routine specified in the command and
passes any arguments.
4. Executes the routine.
5. Displays the value returned by the routine in the return
status register. By convention, after a called routine has
executed, register R0 contains the function return value
(if the routine is a function) or the procedure completion
status (if the routine is a procedure that returns a status
value). If a called procedure does not return a status value
or function value, the value in R0 might be meaningless, and
the "value returned" message can be ignored.
6. Restores the values of the general registers to the values
they had just before the CALL command was executed.
7. Issues the prompt.
The debugger assumes that the called routine conforms to the
procedure calling standard (see the OpenVMS Calling Standard).
However, the debugger does not know about all the argument-
passing mechanisms for all supported languages. Therefore,
you might need to specify how to pass parameters, for example,
use CALL SUB1(%VAL X) rather than CALL SUB1(X). For complete
information about how arguments are passed to routines, see your
language documentation.
When the current language is C or C++, the CALL command by
default now passes arguments by value rather than by reference.
In addition, you can now pass the following arguments without
using a passing mechanism lexical (such as %REF or %VAL):
o Routine references
o Quoted strings (treated as %REF strings)
o Structures, records, and objects
o Floating-point parameters by value in F_, D_, G_, S_, and T_
floating format by dereferencing a variable of that type.
If the routine contains parameters that are not read-only, the
values assigned to parameters may not be visible, and access
to values is unreliable. This is because the debugger adjusts
parameter values in an internal argument list, not the program
argument list. To examine changing values, consider using static
variables instead of parameters.
The CALL command converts all floating-point literals to F_
floating format for VAX and Alpha systems and T_floating format
for Integrity servers.
On Alpha, passing a floating-point literal in a format other than
F_floating is not supported, as shown in the example below.
A common debugging technique at an exception breakpoint
(resulting from a SET BREAK/EXCEPTION or STEP/EXCEPTION command)
is to call a dump routine with the CALL command. When you enter
the CALL command at an exception breakpoint, any breakpoints,
tracepoints, or watchpoints that were previously set within the
called routine are temporarily disabled so that the debugger does
not lose the exception context. However, such eventpoints are
active if you enter the CALL command at a location other than an
exception breakpoint.
4 – Description, Continued...
When an exception breakpoint is triggered, execution is suspended
before any application-declared condition handler is invoked.
At an exception breakpoint, entering a GO or STEP command after
executing a routine with the CALL command causes the debugger to
resignal the exception (see the GO and STEP commands).
On Alpha processors, you cannot debug routines that are activated
before the routine activated by a CALL command. For example, your
program is stopped in routine MAIN, and you set a breakpoint in
routine SORT. You issue the debugger command CALL SORT. While
debugging routine SORT, you cannot debug routine MAIN. You must
first return from the call to routine SO RT.
If you are debugging a multiprocess program, the CALL command is
executed in the context of the current process set. In addition,
when debugging a multiprocess program, the way in which execution
continues in your process depends on whether you entered a SET
MODE [NO]INTERRUPT command or a SET MODE [NO]WAIT command. By
default (SET MODE NOINTERRUPT), when one process stops, the
debugger takes no action with regard to the other processes.
Also by default (SET MODE WAIT), the debugger waits until
all processes in the current process set have stopped before
prompting for a new command.
Related commands:
GO
EXIT
SET PROCESS
SET MODE [NO]INTERRUPT
STEP
5 – Examples
1.DBG> CALL SUB1(X)
value returned is 19
DBG>
This command calls routine SUB1, with parameter X (by default,
the address of X is passed). In this case, the routine returns
the value 19.
2.DBG> CALL SUB(%REF 1)
value returned is 1
DBG>
This command passes a pointer to a memory location containing
the numeric literal 1, into the routine SUB.
3.DBG> SET MODULE SHARE$LIBRTL
DBG> CALL LIB$SHOW_VM
1785 calls to LIB$GET_VM, 284 calls to LIB$FREE_VM, 122216 bytes
still allocated, value returned is 00000001
DBG>
This example calls Run-Time Library routine LIB$SHOW_VM
(in shareable image LIBRTL) to display memory statistics.
The SET MODULE command makes the universal symbols (routine
names) in LIBRTL visible in the main image. See also the SHOW
MODULE/SHARE command.
4.DBG> CALL testsub (%val 11.11, %val 22.22, %val 33.33)
This example passes floating-point parameters by value, to a
C subroutine with the function prototype void testsub (float,
float, float). The floating-point parameters are passed in F_
floating format.