1 TBK_Routines The Traceback facility for HP 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. 2 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 3 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. 3 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 3 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. 3 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