 |
HP OpenVMS Utility Routines Manual
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.
For information about the TBK symbolize routine for Integrity server
systems, see the information for TBK$I64_SYMBOLIZE earlier in
TBK$I64_SYMBOLIZE.
Format
TBK$ALPHA_SYMBOLIZE parameter_block
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.
Argument
parmeter_block
| OpenVMS usage: |
TBK_API_PARAM |
| type: |
structure |
| access: |
modify |
| mechanism: |
by reference |
Table 21-2 shows the values for TBK_API_PARAM (defined in TBKDEF).
Table 21-2 Values for TBK_API_PARAM on Alpha
| 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 pointer
|
Optional output, 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 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_DESC
|
64-bit pointer
|
Optional output, 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 in with the module name.
|
|
TBK$PQ_ROUTINE_DESC
|
64-bit pointer
|
Optional output, 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 in with the routine
name.
|
TBK$PQ_
LISTING_LINENO
|
64-bit pointer
|
Optional output, pointer (if not 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 pointer
|
Optional output, pointer (if not requested, MBZ) to quadword to be
filled in with the relative PC. This may be an image or module relative
PC.
|
TBK$PQ_
IMAGE_BASE_ADDR
|
64-bit pointer
|
Optional output, pointer (if not requested, MBZ) to quadword to be
filled in with the image base address.
|
TBK$PQ_
MODULE_BASE_ADDR
|
64-bit pointer
|
Optional output pointer (if not requested, MBZ) to quadword to be
filled in with the module base address.
|
|
TBK$PQ_ MALLOC_RTN
|
64-bit pointer
|
Optional input, pointer (if not 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 pointer
|
Optional input, pointer (if not 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_
SYMBOLIZE_FLAGS
|
64-bit pointer
|
Optional input and output, 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_
EXCEPTION_IS_FAULT
|
0
|
Adjusts the PC value used for symbolization for target frames that
suffered a fault exception.
|
|
|
All remaining bits
|
Reserved. Must be initialized to zero.
|
Description
The TBK$ALPHA_SYMBOLIZE routine attempts to symbolize a PC. That is,
given a PC and a frame pointer, this routine returns as much of the
symbolic representation for that location that has been requested:
image name, file name, module name, routine name, listing line number,
file record number, and so on. This must be a PC in an active call
stack frame.
The degree of symbolization depends on the images symbolic information.
For best results, compile the image source modules with either
traceback (the default) or debug information (/DEBUG), and link the
image with either traceback (/TRACE) or debug (/DEBUG) information. If
no symbolic information records exists within the image for the PC,
then only partial symbolization is possible.
The TBK$ALPHA_SYMBOLIZE routine can be called by programs in user,
supervisor, or executive mode. Calls from kernel mode are not allowed;
calls when IPL is nonzero are not allowed.
Callers in supervisor or executive mode must supply routines that
perform the equivalent of malloc and free operations that are legal for
the given mode. (The C Run Time Library
malloc
and
free
routines are only supported in user mode.) Pointers to these
user-written replacement routines are specified in the
TBK$PQ_MALLOC_RTN and TBK$PQ_FREE_RTN fields.
Condition Values Returned
|
SS$_KERNELINV
|
This API does not support kernel mode calls.
|
|
SS$_BADPARAM
|
Incorrect TBK_API_PARAM length, type, or version.
|
|
SS$_INSFMEM
|
Unable to allocate needed memory.
|
|
SS$_NORMAL
|
Successful completion.
|
|
SS$_ACCVIO
|
Unable to read from the TBK_API_PARAM block.
|
|
