HP OpenVMS Systems Documentation

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.

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 
      

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" 
      

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.

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.

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:" 
      

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

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.

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.

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" 
      

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.

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.

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.

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.

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.

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.