HP OpenVMS Systems Documentation

Content starts here

HP OpenVMS System Analysis Tools Manual


Previous Contents Index


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

None  

Example


VOID_PQ current_address; 
... 
sda$get_address (&current_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$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

None  

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:


   Block type: VCC_CFCB 
      


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

None  

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

None  

Example


#include  <cpudef> 
CPU  *current_cpu; 
sda$get_current_cpu  (  &current_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

None  

Example


PCB *current_pcb; 
... 
sda$get_current_pcb ( &current_pcb ); 
      

This call stores the system address of the PCB of the process currently being referenced by SDA in the pointer CURRENT_PCB.


SDA$GET_DEVICE_NAME

Gets the device name, given the UCB address of the device.

Format

int sda$get_device_name (VOID_PQ ucb_addr, char *name_buf, int name_len);


Arguments

ucb_addr


OpenVMS usage address
type quadword (unsigned)
access read only
mechanism by value

System address of the Unit Control Block of the device.

name_buf


OpenVMS usage char_string
type character string
access write only
mechanism by reference

Address of buffer to receive device name.

name_len


OpenVMS usage longword_unsigned
type longword (unsigned)
access read only
mechanism by value

Length of buffer to receive device name.

Description

This routine creates and returns the name for the device described by the given UCB. The device name is returned as a zero-terminated ASCII string.

Note

The buffer should be large enough to accomodate the largest possible device name (32 bytes including the termination byte). The text is terminated if it is too long for the supplied buffer.

Condition Values Returned

SDA$_SUCCESS Successful completion
SDA$_NOTAUCB The address given is not the address of a UCB
SDA$_NOREAD The data is inaccessible for some reason
Others The data is inaccessible for some reason


Example


     VOID_PQ address; 
     char buffer[32]; 
     ... 
     sda$parse_command ("SHOW DEVICE DKB0:"); 
     sda$symbol_value ("UCB", (uint64 *)&address); 
     sda$get_device_name (address, buffer, 32); 
     sda$print ("UCB address: !XL = \"!AZ:\"", address, buffer); 
      

This example produces the following output:


     UCB address: 814A9A40 = "$31$DKB0:" 
      


SDA$GET_FLAGS

Obtain environment flags that indicate how SDA is being used.

Format

int sda$get_flags (SDA_FLAGS *flagaddr);


Argument

flagaddr


OpenVMS usage address
type SDA_FLAGS structure
access write only
mechanism by reference

The address of the location where the environment flags are to be returned.

Description

SDA provides a set of flag bits that indicate if it is being used to analyze the current system, a system dump, a process dump, and so on. The flag bits that can be returned are described in Table 10-1 and are defined in SDA_FLAGSDEF.H in SYS$LIBRARY:SYS$LIB_C.TLB.

Condition Values Returned

None  

Examples

#1

SDA_FLAGS flags; 
sda$get_flags (&flags); 
if (flags.sda_flags$v_current) 
    sda$print (Analyzing the current system); 
      

This example shows the use of SDA$GET_FLAGS.


SDA$GET_HEADER

Returns pointers to local copies of the dump file header and the error log buffer together with the sizes of those data structures; optionally returns pointers and sizes for the crash error log entry and trap data (if any).

Format

void sda$get_header (DMP **dmp_header, uint32 *dmp_header_size, void **errlog_buf, uint32 *errlog_buf_size,__optional_params);


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.

crasherl_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 crash error log entry held by SDA.

crasherl_buf_size


OpenVMS usage longword_unsigned
type longword (unsigned)
access write only
mechanism by reference

Location in which to store the size of the crash error log entry.

trapinfo_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 trap info, if any, held by SDA.

trapinfo_buf_size


OpenVMS usage longword_unsigned
type longword (unsigned)
access write only
mechanism by reference

Location in which to store the size of the trap data, if any.

Description

This routine returns the addresses and sizes of the dump header, error logs, and optionally the crash error log entry and trap data 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, the crash error log entry and trap data

Trap data only exists if an access violation occurs while the dump is being written. Usually, the returned trapinfo_buf and trapinfo_buf_size will be zero.


Condition Values Returned

None  

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

Returns a zero-terminated ASCII string representing the platform hardware name and puts it in the buffer passed as the argument.

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

None  

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 (on Alpha, 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

On Integrity servers, SDA_CIO$V_SLICED will always be set if SDA_CIO$V_VALID is set.

Table 10-2 and Table 10-3 describe the ISD_LABELS index on Alpha and Integrity server systems.

Table 10-2 Alpha ISD_LABELS Index
Index Name Meaning
0 SDA_CIO$K_NPRO Nonpaged read only
1 SDA_CIO$K_NPRW Nonpaged read/write
2 SDA_CIO$K_PRO Paged read only
3 SDA_CIO$K_PRW Paged read/write
4 SDA_CIO$K_FIX Fixup
5 SDA_CIO$K_INIT Initialization

Table 10-3 Integrity server ISD_Labels Index
Index Name Meaning
0 SDA_CIO$K_FIX Fixup
1 SDA_CIO$K_PROMO_CODE Promote (code)
2 SDA_CIO$K_PROMO_DATA Promote (data)
3 SDA_CIO$K_INIT_CODE Initialization (code)
4 SDA_CIO$K_INIT_DATA Initialization (data)
5 SDA_CIO$K_CODE Code
6 SDA_CIO$K_SHORT_RW Short data (read/write)
7 SDA_CIO$K_SHORT_RO Short data (read only)
8 SDA_CIO$K_RW Data (read/write)
9 SDA_CIO$K_RO Data (read only)
10 SDA_CIO$K_SHORT_DZ Short data (demand zero)
11 SDA_CIO$K_SHORT_TDZ Short data (trailing demand zero)
12 SDA_CIO$K_DZERO Demand zero
13 SDA_CIO$K_TR_DZERO Trailing demand zero


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.


SDA$GET_INPUT

Reads input commands.

Format

int sda$get_input (char *prompt, char *buffer, uint32 buflen);


Arguments

prompt


OpenVMS usage char_string
type character string
access read only
mechanism by reference

Address of prompt string (zero-terminated ASCII string).

buffer


OpenVMS usage char_string
type character string
access write only
mechanism by reference

Address of buffer to store command.

buflen


OpenVMS usage longword_unsigned
type longword (unsigned)
access read only
mechanism by value

Maximum length of buffer.

Description

The command entered is returned as a zero-terminated string. The string is not uppercased. If you do not enter input but simply press <return> or <ctrl/Z>, the routine returns a null string.

Condition Values Returned

SS$_NORMAL Successful completion.
RMS$_EOF User pressed <ctrl/Z>

Example


int status; 
char buffer[128]; 
... 
status = sda$get_input ( "MBX> ", buffer, sizeof (buffer) ); 
      

This call prompts you for input with "MBX> " and stores the response in the buffer.


SDA$GET_LINE_COUNT

Obtains the number of lines currently printed on the current page.

Format

void sda$get_line_count (uint32 *line_count);


Argument

line_count


OpenVMS usage longword_unsigned
type longword (unsigned)
access write only
mechanism by reference

The number of lines printed on current page.

Description

Returns the number of lines that have been printed so far on the current page.

Condition Values Returned

None  

Example


uint32 line_count; 
... 
sda$get_line_count (&line_count); 
      

This call copies the current line count on the current page of output to the location LINE_COUNT.


SDA$GETMEM

Reads dump or system memory and signals a warning if inaccessible.

Format

int sda$getmem (VOID_PQ start, void *dest, int length, __optional_params);


Arguments

start


OpenVMS usage address
type quadword (unsigned)
access read only
mechanism by value

Starting virtual address in dump or system.

dest


OpenVMS usage address
type varies
access write only
mechanism by reference

Return buffer address.

length


OpenVMS usage longword_unsigned
type longword (unsigned)
access read only
mechanism by value

Length of transfer.

physical


OpenVMS usage longword_unsigned
type longword (unsigned)
access read only
mechanism by value

0: <start> is a virtual address. This is the default.
1: <start> is a physical address.

Description

This routine transfers an area from the memory in the dump file or the running system to the caller's return buffer. It performs the necessary address translation to locate the data in the dump file. SDA$GETMEM signals a warning and returns an error status if the data is inaccessible.

Related Routines

SDA$REQMEM and SDA$TRYMEM


Condition Values Returned

SDA$_SUCCESS Successful completion
SDA$_NOREAD The data is inaccessible for some reason.
SDA$_NOTINPHYS The data is inaccessible for some reason.
Others The data is inaccessible for some reason.

If a failure status code is returned, it has already been signaled as a warning.


Example


int status; 
PCB *current_pcb; 
PHD *current_phd; 
 ... 
status = sda$getmem ((VOID_PQ)&current_pcb->pcb$l_phd, &current_phd, 4); 
      

This call returns the contents of the PCB$L_PHD field of the PCB, whose system address is in the pointer CURRENT_PCB, to the pointer CURRENT_PHD.


Previous Next Contents Index