HP OpenVMS systems documentation

The following section describes the SDA extension callable routines.

Adds a symbol to SDA's local symbol table.

Format

void sda$add_symbol (char *symbol_name, uint64 symbol_value);

Arguments

symbol_name

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

Address of symbol name string (zero-terminated).

symbol_value

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

The symbol value.

Description

SDA maintains a list of symbols and the corresponding values. SDA$ADD_SYMBOL is used to insert additional symbols into this list, so that they can be used in expressions and during symbolization.

Condition Values Returned

None

Example

sda$add_symbol ("MBX", 0xFFFFFFFF80102030); 
      

This call defines the symbol MBX to the hexadecimal value FFFFFFFF80102030.

Allocates dynamic memory.

Format

void sda$allocate (uint32 size, void **ptr_block);

Arguments

size

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

Size of block to allocate (in bytes).

ptr_block

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

Address of longword to receive address of block.

Description

The requested memory is allocated and the address returned. Note that this is the only supported mechanism for allocation of dynamic memory.

Related Routine

SDA$DEALLOCATE

Condition Values Returned

None

If no memory is available, the error is signaled and the SDA session aborted.

Example

PCB *local_pcb; 
... 
sda$allocate (PCB$C_LENGTH, (void *)&local_pcb); 
      

This call allocates a block of heap storage for a copy of a PCB, and stores its address in the pointer LOCAL_PCB.

Displays a list of activated images together with their virtual address ranges for debugging purposes.

Format

void sda$dbg_image_info ();

Arguments

None.

Description

A list of the images currently activated, with their start and end addresses, is displayed. This is provided as a debugging aid for SDA extensions.

Condition Values Returned

None

Example

sda$dbg_image_info (); 
      

SDA outputs the list of images in the following format:

Current VMS Version:   "X6DX-FT1" 
 
     Process Activated Images: 
 
        Start VA  End VA    Image Name 
        00010000  000301FF  SDA 
        00032000  00177FFF  SDA$SHARE 
        7B508000  7B58BFFF  DECC$SHR 
        7B2D8000  7B399FFF  DPML$SHR 
        7B288000  7B2C9FFF  CMA$TIS_SHR 
        7B698000  7B6D9FFF  LBRSHR 
        0021A000  0025A3FF  SCRSHR 
        00178000  002187FF  SMGSHR 
        7B1E8000  7B239FFF  LIBRTL 
        7B248000  7B279FFF  LIBOTS 
        80C140D0  80C23120  SYS$BASE_IMAGE 
        80C036B8  80C05288  SYS$PUBLIC_VECTORS 
        002C6000  002D31FF  PRGDEVMSG 
        002D4000  002DA9FF  SHRIMGMSG 
        002DC000  002DFFFF  DECC$MSG 
        00380000  003E03FF  MBX$SDA 
      

Deallocates and frees dynamic memory.

Format

void sda$deallocate (void *ptr_block, uint32 size);

Arguments

ptr_block

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

Starting address of block to be freed.

size

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

Size of block to deallocate (in bytes).

Description

The specified memory is deallocated. Note that this is the only supported mechanism for deallocation of dynamic memory.

Related Routine

SDA$ALLOCATE

Condition Values Returned

None

If an error occurs, it is signaled and the SDA session aborted.

Example

PCB *local_pcb; 
... 
sda$deallocate ((void *)local_pcb, PCB$C_LENGTH; 
      

This call deallocates the block of length PCB$C_LENGTH whose address is stored in the pointer LOCAL_PCB.

Displays online help.

Format

void sda$display_help (char *library_desc, char *topic_desc);

Arguments

library

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

Address of library filespec. Specify as zero-terminated ASCII string.

topic

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

Address of topic name. Specify as zero-terminated ASCII string.

Description

Help from the specified library is displayed on the given topic.

Condition Values Returned

None

Example

sda$display_help ("SYS$HELP:SDA", "HELP"); 
      

This call produces the following output at the terminal:

HELP 
 
 
     The System Dump Analyzer (SDA) allows you to inspect the contents 
     of memory as saved in the dump taken at crash time or as exists 
     in a running system. You can use SDA interactively or in batch 
     mode. You can send the output from SDA to a listing file. You can 
     use SDA to perform the following operations: 
 
                      Assign a value to a symbol 
                      Examine memory of any process 
                      Format instructions and blocks of data 
                      Display device data structures 
                      Display memory management data structures 
                      Display a summary of all processes on the system 
                      Display the SDA symbol table 
                      Copy the system dump file 
                      Send output to a file or device 
                      Read global symbols from any object module 
                      Send output to a file or device 
                      Read global symbols from any object module 
                      Search memory for a given value 
 
     For help on performing these functions, use the HELP command and 
     specify a topic. 
 
     Format 
 
       HELP  [topic-name] 
 
 
 
 
  Additional information available: 
 
  Parameter 
 
HELP Subtopic? 
      

Ensures sufficient space on the current output page.

Format

void sda$ensure (uint32 lines);

Argument

lines

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

Number of lines to fit on a page.

Description

This routine checks and makes sure that the number of lines specified fit on the current page; otherwise, it issues a page break.

Condition Values Returned

None

Example

sda$ensure (5); 
      

This call ensures that there are five lines left on the current page, and it outputs a page break if there are not.

Formats data into a buffer.

Format

char * sda$fao (char * ctrstr, char * buffer, int buflen, __optional_params);

Arguments

ctrstr

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

Addess of a zero-terminated FAO control string.

buffer

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

Address of a string buffer into which to store the formatted string.

buflen

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

Maximum size of the string buffer.

prmlst

OpenVMS usage	varying_arg
type	quadword (signed or unsigned)
access	read only
mechanism	by value

Optional FAO parameters. All arguments after buflen are copied into a quadword parameter list, as used by $FAOL_64.

Description

Formats data into a buffer as a zero-terminated string.

Condition Values Returned

Address of terminating zero

SDA$FAO returns the address of the terminating zero in the output buffer. This allows successive calls to SDA$FAO to append strings.

Example

char faobuf [16]; 
char *faoptr; 
faoptr = sda$fao ( "!XL", 
                faobuf, sizeof (faobuf), 
                0xffffffff); 
sda$fao ( ".!XL", 
                faoptr, sizeof (faobuf) - strlen (faobuf), 
                0x80102030); 
      

This example shows the use of SDA$FAO to append a formatted string to another formatted string.

Displays the formatted contents of a data structure.

Format

void sda$format (VOID_PQ struct_addr, __optional_params);

Arguments

struct_addr

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

The address in the system dump of the data structure to be formatted.

options

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

The following provides more information on options:

Option	Meaning
None	Uses structure type from the xxx$B_TYPE and/or xxx$B_SUBTYPE field of the structure. This is the default.
SDA_OPT$M_FORMAT_TYPE	Uses the structure type given in struct_prefix.
SDA_OPT$M_FORMAT_PHYSICAL	Indicates that struct_addr is a physical address instead of a virtual address.

struct_prefix

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

Address of structure name string (zero-terminated).

Description

This routine displays the formatted content of a data structure that begins at the address specified. If no symbol prefix is passed, then SDA tries to find the symbols associated with the block type specified in the block-type byte of the data structure.

Condition Values Returned

None

Example

PCB *local_pcb; 
PHD *local_phd; 
... 
sda$format (local_pcb); 
sda$format (local_phd, SDA_OPT$M_FORMAT_TYPE, "PHD"); 
      

The first call formats the structure whose system address is held in the variable LOCAL_PCB, determining the type from the type and/or subtype byte of the structure. The second call formats the structure whose system address is held in the variable LOCAL_PHD, using PHD symbols.

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 either 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, the control 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.