Document revision date: 19 July 1999

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

None

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

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$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

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 dump address of the PCB of the process currently being referenced by SDA in the pointer CURRENT_PCB.

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

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

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

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 (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.

	privacy and legal statement
6549PRO_023.HTML