The Traceback facility for VSI OpenVMS Integrity servers and
Alpha systems is a debugging tool that provides information
(symbolizations) about call stack PCs. In normal operation, when
a process suffers a fatal unhandled exception, the operating
system launches Traceback which sends to SYS$OUTPUT the complete
call stack at the time of the exception. Applications can also
directly use the Traceback facility to sequentially generate
information for an individual call stack PC. In this case,
the Traceback simply returns information to the caller, not to
SYS$OUTPUT. The links below describe the routines for using this
direct Traceback interface. On Integrity server systems, the
routine is called TBK$I64_SYMBOLIZE and on Alpha systems, it is
called TBK$ALPHA_SYMBOLIZE. Choose the appropriate TBK routine
for your platform.
1 – TBK$I64_SYMBOLIZE
The TBK$I64_SYMBOLIZE routine attempts to symbolize a PC,
returning as much symbolic representation for that location as
was requested.
Format
TBK$I64_SYMBOLIZE parameter_block
1.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value. Condition values that this routine can return
are listed under Condition Values Returned.
1.2 – Argument
parmeter_block
OpenVMS usage:TBK_API_PARAM
type: structure
access: modify
mechanism: by reference
The values for TBK_API_PARAM (defined in TBKDEF) are defined as:
Field Size Description
TBK$W_LENGTH Word Input by value, structure length,
must be TBK$K_LENGTH
TBK$B_TYPE Byte Input, MBZ
TBK$B_VERSION Byte Input by value, must be TBK$K_
VERSION
TBK$L_RESERVEDA Longword Reserved for future use, MBZ
TBK$Q_FAULTING_PC Quadword Input by value, call stack frame PC
TBK$PQ_FILENAME_ 64-bit Optional output by reference
DESC pointer (Integrity servers only), pointer
(if not requested, MBZ) to a fixed-
length string text descriptor.
The descriptor must be set up
with preallocated adequate buffer
space. The descriptor is filled
with the image file name. This can
be a dynamic descriptor (rather
than fixed-length), but only if the
caller is in user mode.
TBK$PQ_ 64-bit Optional output, pointer (if
LIBRARY_MODULE_ pointer not requested, MBZ) to a fixed-
DESC length string text descriptor. The
descriptor must be set up with pre-
allocated adequate buffer space.
The descriptor is filled in with
library module name if the image
filename (see previous field) is
a text library file. This can be
a dynamic descriptor (rather than
fixed length) but only if the caller
is in user mode.
TBK$PQ_ 64-bit Optional output, pointer (if not
RECORD_NUMBER pointer requested, MBZ) to a longword to be
filled with the relevant image file
record number.
TBK$PQ_IMAGE_DESC 64-bit Optional output, pointer (if
pointer not requested, MBZ) to a fixed-
length string text descriptor.
The descriptor must be set up with
preallocated adequate buffer space.
The descriptor is filled in with the
image name. This can be a dynamic
descriptor (rather than fixed
length), but only if the caller
is in user mode.
TBK$PQ_MODULE_ 64-bit Optional output, pointer (if
DESC pointer not requested, MBZ) to a fixed-
length string text descriptor.
The descriptor must be set up with
preallocated adequate buffer space.
The descriptor is filled in with the
module name.
TBK$PQ_ROUTINE_ 64-bit Optional output, pointer (if
DESC pointer not requested, MBZ) to a fixed-
length string text descriptor.
The descriptor must be set up with
preallocated adequate buffer space.
The descriptor is filled in with the
routine name.
TBK$PQ_ 64-bit Optional output, pointer (if not
LISTING_LINENO pointer requested, MBZ) to longword to be
filled in with the line number (as
show in the modules LIS file).
TBK$PQ_REL_PC 64-bit Optional output, pointer (if not
pointer requested, MBZ) to quadword to be
filled in with the relative PC. This
can be an image or module relative
PC.
TBK$PQ_ MALLOC_ 64-bit Optional input, pointer (if not
RTN pointer supplied, MBZ) address to a user-
supplied malloc routine. Must be
supplied when called from supervisor
or executive mode (kernel mode is
not supported).
TBK$PQ_ FREE_RTN 64-bit Optional input, pointer (if not
pointer supplied, MBZ) address to a user-
supplied free routine. Must be
supplied when called from supervisor
or executive mode (kernel mode not
supported).
TBK$PQ_ 64-bit Optional input and output,
SYMBOLIZE_FLAGS pointer pointer (if not supplied, MBZ)
to TBK_SYMBOLIZE_FLAGS (quadword,
see below). Used to control
symbolization options and to return
additional status.
TBK$Q_RESERVED0 Quadword Reserved for future use, MBZ.
TBK$Q_RESERVED1 Quadword Reserved for future use, MBZ.
TBK$Q_RESERVED2 Quadword Reserved for future use, MBZ.
TBK$V_ 0 Adjusts the PC value used for
EXCEPTION_IS_ symbolization for target frames
FAULT that suffered a fault exception.
All re- Reserved, Must be initialized to
maining zero.
bits
2 – TBK$ALPHA_SYMBOLIZE
The TBK$ALPHA_SYMBOLIZE routine attempts to symbolize a call
stack PC, returning as much symbolic representation for that
location as was requested.
Format
TBK$ALPHA_SYMBOLIZE parameter_block
2.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value. Condition values that this routine can return
are listed under Condition Values Returned.
2.2 – Argument
parmeter_block
OpenVMS usage:TBK_API_PARAM
type: structure
access: modify
mechanism: by reference
The values for TBK_API_PARAM (defined in TBKDEF) are defined as:
Field Size Description
TBK$W_LENGTH Word Input by value, structure length,
must be TBK$K_LENGTH
TBK$B_TYPE Byte Input, MBZ
TBK$B_VERSION Byte Input by value, must be TBK$K_
VERSION
TBK$L_RESERVEDA Longword Reserved for future use, MBZ
TBK$Q_FAULTING_PC Quadword Input by value, call stack frame PC
TBK$Q_FAULTING_FP Quadword Input by value, call stack Frame
Pointer
TBK$PQ_IMAGE_DESC 64-bit Optional output, pointer (if
pointer not requested, MBZ) to a fixed-
length string text descriptor.
The descriptor must be set up
with preallocated adequate buffer
space. The descriptor is filled in
with the image name. This can be
a dynamic descriptor (rather than
fixed length) but only if the caller
is in user mode.
TBK$PQ_MODULE_ 64-bit Optional output, pointer (if
DESC pointer not requested, MBZ) to a fixed-
length string text descriptor.
The descriptor must be set up with
preallocated adequate buffer space.
The descriptor is filled in with the
module name.
TBK$PQ_ROUTINE_ 64-bit Optional output, pointer (if
DESC pointer not requested, MBZ) to a fixed-
length string text descriptor.
The descriptor must be set up with
preallocated adequate buffer space.
The descriptor is filled in with the
routine name.
TBK$PQ_ 64-bit Optional output, pointer (if not
LISTING_LINENO pointer requested, MBZ) to longword to be
filled in with the line number (as
show in the modules LIS file).
TBK$PQ_REL_PC 64-bit Optional output, pointer (if not
pointer requested, MBZ) to quadword to be
filled in with the relative PC. This
may be an image or module relative
PC.
TBK$PQ_ 64-bit Optional output, pointer (if not
IMAGE_BASE_ADDR pointer requested, MBZ) to quadword to
be filled in with the image base
address.
TBK$PQ_ 64-bit Optional output pointer (if not
MODULE_BASE_ADDR pointer requested, MBZ) to quadword to
be filled in with the module base
address.
TBK$PQ_ MALLOC_ 64-bit Optional input, pointer (if not
RTN pointer supplied, MBZ) address to a user-
supplied malloc routine. Must be
supplied when called from supervisor
or executive mode (kernel mode is
not supported).
TBK$PQ_FREE_RTN 64-bit Optional input, pointer (if not
pointer supplied, MBZ) address to a user-
supplied free routine. Must be
supplied when called from supervisor
or executive mode (kernel mode not
supported).
TBK$PQ_ 64-bit Optional input and output,
SYMBOLIZE_FLAGS pointer pointer (if not supplied, MBZ)
to TBK_SYMBOLIZE_FLAGS (quadword,
see below). Used to control
symbolization options and to return
additional status.
TBK$Q_RESERVED0 Quadword Reserved for future use, MBZ.
TBK$Q_RESERVED1 Quadword Reserved for future use, MBZ.
TBK$Q_RESERVED2 Quadword Reserved for future use, MBZ.
TBK$V_ 0 Adjusts the PC value used for
EXCEPTION_IS_ symbolization for target frames
FAULT that suffered a fault exception.
All re- Reserved. Must be initialized to
maining zero.
bits