Document revision date: 19 July 1999
|
|
|
|
OpenVMS Alpha System Analysis Tools Manual
SDA$FORMAT_HEADING
Formats a new page heading.
Format
void sda$format_heading (char *ctrstr, __optional_params);
Arguments
ctrstr
OpenVMS usage |
char_string |
type |
character-coded text string |
access |
read only |
mechanism |
by reference |
Address of control string (zero-terminated ASCII string).
prmlst
OpenVMS usage |
varying_arg |
type |
quadword (signed or unsigned) |
access |
read only |
mechanism |
by value |
FAO parameters that are optional. All arguments after the control
string are copied into a quadword parameter list as used by $FAOL_64.
Description
This routine prepares and saves the page heading to be used whenever
SDA$NEW_PAGE is called. Nothing is output until SDA$NEW_PAGE is next
called, or a page break is necessary because the current page is full.
Condition Values Returned
If the $FAOL_64 call issued by SDA$FORMAT_HEADING fails, an empty
string is used as the page heading.
Example
|
char hw_name[64];
...
sda$get_hw_name (hw_name, sizeof(hw_name));
sda$format_heading (
"SDA Extension Commands, system type !AZ",
&hw_name);
sda$new_page ();
|
This example produces the following heading:
|
SDA Extension Commands, system type DEC 3000 Model 400
------------------------------------------------------
|
SDA$GET_ADDRESS
Gets the address value of the current memory location.
Format
void sda$get_address (VOID_PQ *address);
Argument
address
OpenVMS usage |
quadword_unsigned |
type |
quadword (unsigned) |
access |
write only |
mechanism |
by reference |
Location to store the current 64-bit memory address.
Description
Returns the current address being referenced by SDA (location ".").
Condition Values Returned
Example
|
VOID_PQ current_address;
...
sda$get_address (¤t_address);
|
This call stores SDA's current memory location in the long pointer
CURRENT_ADDRESS.
SDA$GET_BLOCK_NAME
Returns the name of a structure, given its type and/or subtype.
Format
void sda$extend_get_block_name (uint32 block_type, uint32
block_subtype,
char *buffer_ptr, uint32 buffer_len);
Arguments
block_type
OpenVMS usage |
longword_unsigned |
type |
longword (unsigned) |
access |
read only |
mechanism |
by value |
Block type in range 0 - 255 (usually extracted from xxx$b_type field).
block_subtype
OpenVMS usage |
longword_unsigned |
type |
longword (unsigned) |
access |
read only |
mechanism |
by value |
Block subtype in range 0 - 255 (ignored if the given block type has no
subtypes).
buffer_ptr
OpenVMS usage |
char_string |
type |
character string |
access |
write only |
mechanism |
by reference |
Address of buffer to save block name, which is returned as a
zero-terminated string.
buffer_len
OpenVMS usage |
longword_unsigned |
type |
longword (unsigned) |
access |
read only |
mechanism |
by value |
Length of buffer to receive block name.
Description
Given the block type and/or subtype of a structure, this routine
returns the name of the structure. If the structure type is one that
has no subtypes, the given subtype is ignored. If the structure type is
one that has subtypes, and the subtype is given as zero, the name of
the block type itself is returned. If an invalid type or subtype (out
of range) is given, an empty string is returned.
Note
The buffer should be large enough to accomodate the largest possible
block name (25 bytes plus the termination byte). The block name is
truncated if it is too long for the supplied buffer.
|
Condition Values Returned
Example
|
char buffer[32];
...
sda$get_block_name (0x6F, 0x20,
buffer,
sizeof (buffer));
if (strlen (buffer) == 0)
sda$print ("Block type: no named type/subtype");
else
sda$print ("Block type: !AZ", buffer);
|
This example produces the following output:
SDA$GET_BUGCHECK_MSG
Gets the text associated with a bugcheck code.
Format
void sda$get_bugcheck_msg (uint32 bugcheck_code, char *buffer_ptr,
uint32 buffer_size);
Arguments
bugcheck_code
OpenVMS usage |
longword_unsigned |
type |
longword (unsigned) |
access |
read only |
mechanism |
by value |
The bugcheck code to look up.
buffer_ptr
OpenVMS usage |
char_string |
type |
character string |
access |
write only |
mechanism |
by reference |
Address of buffer to save bugcheck message.
buffer_len
OpenVMS usage |
longword_unsigned |
type |
longword (unsigned) |
access |
read only |
mechanism |
by value |
Length of buffer to receive message.
Description
Gets the string representing the bugcheck code passed as the argument.
The bugcheck message string is passed in the buffer (represented as a
pointer and length) as a zero-terminated ASCII string.
Note
The buffer should be large enough to accomodate the largest possible
bugcheck message (128 bytes including the termination byte). The text
is terminated if it is too long for the supplied buffer.
|
Condition Values Returned
Example
|
char buffer[128];
...
sda$get_bugcheck_msg (0x108, buffer, sizeof(buffer));
sda$print ("Bugcheck code 108 (hex) =");
sda$print ("!_\"!AZ\"", buffer);
|
This example produces the following output:
|
Bugcheck code 108 (hex) =
"DOUBLDALOC, Double deallocation of swap file space"
|
SDA$GET_CURRENT_CPU
Gets the CPU database address of the currently selected CPU.
Format
void sda$get_current_cpu (cpu **cpudb);
Arguments
cpudb
OpenVMS usage |
address |
type |
longword (unsigned) |
access |
write only |
mechanism |
by reference |
Location to which the address of the CPU database is to be returned.
Description
This routine causes SDA to return the address of the database for the
currently selected CPU.
Condition Values Returned
Example
|
#include <cpudef>
CPU *current_cpu;
sda$get_current_cpu ( ¤t_cpu );
|
In this example, the system address of the database for the current CPU
is returned in variable current_cpu.
SDA$GET_CURRENT_PCB
Gets the PCB address of the "SDA current process" currently selected.
Format
void sda$get_current_pcb (PCB **pcbadr);
Argument
pcbadr
OpenVMS usage |
quadword_unsigned |
type |
quadword (unsigned) |
access |
write only |
mechanism |
by reference |
Location in which to store the current PCB address.
Description
The PCB address of the process currently selected by SDA is returned in
the specified location.
Condition Values Returned
Example
|
PCB *current_pcb;
...
sda$get_current_pcb ( ¤t_pcb );
|
This call stores the dump address of the PCB of the process currently
being referenced by SDA in the pointer CURRENT_PCB.
SDA$GET_HEADER
Returns pointers to the dump file header and the error log buffer
together with the size of those data structures.
Format
void sda$get_header (DMP **dmp_header, uint32 *dmp_header_size,
void **errlog_buf, uint32 *errlog_buf_size);
Arguments
dmp_header
OpenVMS usage |
address |
type |
longword (unsigned) |
access |
write only |
mechanism |
by reference |
Location in which to store the address of the copy of the dump file
header held by SDA.
dmp_header_size
OpenVMS usage |
longword_unsigned |
type |
longword (unsigned) |
access |
write only |
mechanism |
by reference |
Location in which to store the size of the dump file header.
errlog_buf
OpenVMS usage |
address |
type |
longword (unsigned) |
access |
write only |
mechanism |
by reference |
Location in which to store the address of the copy of the error log
buffer held by SDA.
errlog_buf_size
OpenVMS usage |
longword_unsigned |
type |
longword (unsigned) |
access |
write only |
mechanism |
by reference |
Location in which to store the size of the error log buffer.
Description
This routine returns the addresses and sizes of the dump header and
error logs read by SDA when the dump file is opened. If this routine is
called when the running system is being analyzed with ANALYZE/SYSTEM,
then the following occurs:
- Returns the address and size of SDA's dump header buffer, but the
header contains zeroes.
- Returns zeroes for the address and size of SDA's error log buffer.
Condition Values Returned
Example
|
DMP *dmp_header;
uint32 dmp_header_size;
char *errlog_buffer;
uint32 errlog_buffer_size;
...
sda$get_header (&dmp_header,
&dmp_header_size,
(void **)&errlog_buffer,
&errlog_buffer_size);
|
This call stores the address and size of SDA's copy of the dump file
header in DMP_HEADER and DMP_HEADER_SIZE, and stores the address and
size of SDA's copy of the error log buffers in ERRLOG_BUFFER and
ERRLOG_BUFFER_SIZE, respectively.
SDA$GET_HW_NAME
Returns the full name of the hardware platform where the dump was
written.
Format
void sda$get_hw_name (char *buffer_ptr, uint32 buffer_len);
Arguments
buffer_ptr
OpenVMS usage |
char_string |
type |
character string |
access |
write only |
mechanism |
by reference |
Address of buffer to save HW name.
buffer_len
OpenVMS usage |
longword_unsigned |
type |
longword (unsigned) |
access |
read only |
mechanism |
by value |
Length of buffer to receive HW name.
Description
Gets the string representing the platform hardware name and puts it in
the buffer passed as the argument as a zero-terminated ASCII string.
Note
The buffer should be large enough to accomodate the largest possible
hardware platform name (120 bytes including the termination byte). The
name is truncated if it is too long for the supplied buffer.
|
Condition Values Returned
Example
|
char hw_name[64];
...
sda$get_hw_name (hw_name, sizeof(hw_name));
sda$print ("Platform name: \"!AZ\"", hw_name);
|
This example produces output of the form:
|
Platform name: "DEC 3000 Model 400"
|
SDA$GET_IMAGE_OFFSET
Maps a given virtual address onto an image or execlet.
Format
COMP_IMG_OFF sda$get_image_offset (VOID_PQ va, VOID_PQ img_info,
VOID_PQ subimg_info, VOID_PQ offset);
Arguments
va
OpenVMS usage |
address |
type |
quadword (unsigned) |
access |
read only |
mechanism |
by value |
Virtual address of interest.
img_info
OpenVMS usage |
address |
type |
quadword (unsigned) |
access |
write only |
mechanism |
by reference |
Pointer to return addr of LDRIMG or IMCB block.
subimg_info
OpenVMS usage |
address |
type |
quadword (unsigned) |
access |
write only |
mechanism |
by reference |
Pointer to return addr of ISD_OVERLAY or KFERES.
offset
OpenVMS usage |
quadword_unsigned |
type |
quadword (unsigned) |
access |
write only |
mechanism |
by reference |
Pointer to address to return offset from image.
Description
Given a virtual address, this routine finds in which image it falls and
returns the image information and offset. The loaded image list is
traversed first to find this information. If it is not found, then the
activated image list of the currently selected process is traversed. If
still unsuccessful, then the resident installed images are checked.
Condition Values Returned
SDA_CIO$V_VALID
|
Set if image offset is found.
|
SDA_CIO$V_PROCESS
|
Set if image is an activated image.
|
SDA_CIO$V_SLICED
|
Set if the image is sliced.
|
SDA_CIO$V_COMPRESSED
|
Set if activated image contains compressed data sections.
|
SDA_CIO$V_ISD_INDEX
|
Index into ISD_LABELS table (only for LDRIMG execlets).
|
The status returned indicates the type of image if a match was found.
SDA_CIO$V_xxx flags set: |
img_info type: |
subimg_info type: |
valid
|
LDRIMG
|
n/a
|
valid && sliced
|
LDRIMG
|
ISD_OVERLAY
|
valid && process
|
IMCB
|
n/a
|
valid && process && sliced
|
IMCB
|
KFERES_SECTION
|
Example
|
VOID_PQ va = (VOID_PQ)0xFFFFFFFF80102030;
COMP_IMG_OFF sda_cio;
int64 img_info;
int64 subimg_info;
int64 offset;
...
sda_cio = sda$get_image_offset (va,
&img_info,
&subimg_info,
&offset);
|
For an example of code that interprets the returned COMP_IMG_OFF
structure, see the supplied example program, SYS$EXAMPLES:MBX$SDA.C.