HP OpenVMS System Analysis Tools Manual

Contents

Index

SDA$REQMEM

Reads dump or system memory and signals an error if inaccessible.

Format

int sda$reqmem (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$REQMEM signals an error and aborts the current command if the data is inaccessible.
Related Routines

SDA$GETMEM and SDA$TRYMEM

Condition Values Returned

SDA$_SUCCESS Successful completion.

Any failure is signaled as an error and the current command aborts.

Example


VOID_PQ address; uint32 instruction; ... sda$symbol_value ("EXE_STD$ALLOCATE_C", (uint64 *)&address); sda$reqmem (address, &instruction, 4);

This example reads the first instruction of the routine EXE_STD$ALLOCATE into the location INSTRUCTION.

SDA$SET_ADDRESS

Stores a new address value as the current memory address (".").

Format

void sda$set_address (VOID_PQ address);

Argument

address

OpenVMS usage quadword_unsigned

type quadword (unsigned)

access read only

mechanism by value

Address value to store in current memory location.

Description

The specified address becomes SDA's current memory address (the predefined SDA symbol ".").

Condition Values Returned

None

Example


sda$set_address ((VOID_PQ)0xFFFFFFFF80102030);

This call sets SDA's current address to FFFFFFFF.80102030.

SDA$SET_CPU

Sets a new SDA CPU context.

Format

int sda$set_cpu (int cpu_id);

Arguments

cpu_id

OpenVMS usage longword_unsigned

type longword (unsigned)

access read only

mechanism by value

The desired CPU ID.

Description

This routine causes SDA to set the specified CPU as the currently selected CPU.

Condition Values Returned

SDA$_SUCCESS Successful completion.

Any failure is signaled as an error and the current command aborts.

Example


int cpu_id = 2; status = sda$set_cpu ( cpu_id );

In this example, SDA's current CPU context is set to the CPU whose number is held in the variable CPU_ID.

SDA$SET_HEADING_ROUTINE

Sets the current heading routine to be called after each page break.

Format

void sda$set_heading_routine (void (*heading_rtn) ());

Argument

heading_rtn

OpenVMS usage procedure

type rocedure value

access read only

mechanism by value

Address of routine to be called after each new page.

Description

When SDA begins a new page of output (either because SDA$NEW_PAGE was called, or because the current page is full), it outputs two types of headings. The first is the page title, and is set by calling the routine SDA$FORMAT_HEADING. This is the title that is included in the index page of a listing file when you issue a SET OUTPUT command. The second heading is typically for column headings, and as this can vary from display to display, you must write a routine for each separate heading. When you call SDA$SET_HEADING_ROUTINE to specify a user-written routine, the routine is called each time SDA begins a new page.
To stop the routine from being invoked each time SDA begins a new page, call either SDA$FORMAT_HEADING to set a new page title, or SDA$SET_HEADING_ROUTINE and specify the routine address as NULL.
If the column headings need to be output during a display (that is, in the middle of a page), and then be re-output each time SDA begins a new page, call the user-written routine directly the first time, then call SDA$SET_HEADING_ROUTINE to have it be called automatically thereafter.

Condition Values Returned

None

Example


void mbx$title (void) { sda$print ("Mailbox UCB ..."); sda$print (" Unit Address ..."); sda$print ("------------------------"); return; } ... sda$set_heading_routine (mbx$title); ... sda$set_heading_routine (NULL);

void mbx$title (void) 
  { 
  sda$print ("Mailbox     UCB      ..."); 
  sda$print ("  Unit    Address    ..."); 
  sda$print ("------------------------"); 
  return; 
  } 
... 
sda$set_heading_routine (mbx$title); 
... 
sda$set_heading_routine (NULL);

This example sets the heading routine to the routine MBX$TITLE, and later clears it. The routine is called if any page breaks are generated by the intervening code.

SDA$SET_LINE_COUNT

Sets the number of lines printed so far on the current page.

Format

void sda$set_line_count (uint32 line_count);

Argument

line_count

OpenVMS usage longword_unsigned

type longword (unsigned)

access read only

mechanism by value

The number of lines printed on current page.

Description

The number of lines that have been printed so far on the current page is set to the given value.

Condition Values Returned

None

Example


sda$set_line_count (5);

This call sets SDA's current line count on the current page of output to 5.

SDA$SET_PROCESS

Sets a new SDA process context.

Format

int sda$set_process (const char *proc_name, int proc_index, int proc_addr);

Arguments

proc_name

OpenVMS usage character_string

type character string

access read only

mechanism by reference

Address of the process name string (zero-terminated).
proc_index

OpenVMS usage longword_unsigned

type longword (unsigned)

access read only

mechanism by value

The index of the desired process.
proc_addr

OpenVMS usage address

type longword (unsigned)

access read only

mechanism by value

The address of the PCB for the desired process.

Description

This routine causes SDA to set the specified process as the currently selected process.

Note
The proc_name, proc_index, and proc_addr are mutually exclusive.

Condition Values Returned

SDA$_SUCCESS Successful completion.

Any failure is signaled as an error and the current command aborts.

Example


status = sda$set_process ( "JOB_CONTROL", 0, 0);

In this example, SDA's current process context is set to the JOB_CONTROL process.

SDA$SKIP_LINES

This routine outputs a specified number of blank lines.

Format

void sda$skip_lines (uint32 lines);

Argument

lines

OpenVMS usage longword_unsigned

type longword (unsigned)

access read only

mechanism by value

Number of lines to skip.

Description

The specified number of blank lines are output.

Condition Values Returned

None

Example


sda$skip_lines (2);

This call causes two blank lines to be output.

SDA$SYMBOL_VALUE

Obtains the 64-bit value of a specified symbol.

Format

int sda$symbol_value (char *symb_name, uint64 *symb_value);

Arguments

symb_name

OpenVMS usage char_string

type character string

access read only

mechanism by reference

Zero-terminated string containing symbol name.
symb_value

OpenVMS usage quadword_unsigned

type quadword (unsigned)

access write only

mechanism by reference

Address to receive symbol value.

Description

A search through SDA's symbol table is made for the specified symbol. If found, its 64-bit value is returned.

Condition Values Returned

SDA$_SUCCESS Symbol found.

SDA$_BADSYM Symbol not found.

Example


int status; VOID_PQ address; ... status = sda$symbol_value ("EXE_STD$ALLOCATE_C", (uint64 *)&address);

This call returns the start address of the prologue of routine
EXE_STD$ALLOCATE to location ADDRESS.

SDA$SYMBOLIZE

Converts a value to a symbol name and offset.

Format

int sda$symbolize (uint64 value, char *symbol_buf, uint32 symbol_len);

Arguments

value

OpenVMS usage quadword_unsigned

type quadword (unsigned)

access read only

mechanism by value

Value to be translated.
symbol_buf

OpenVMS usage char_string

type character string

access write only

mechanism by reference

Address of buffer to which to return string.
symbol_len

OpenVMS usage longword_unsigned

type longword (unsigned)

access read only

mechanism by value

Maximum length of string buffer.

Description

This routine accepts a value and returns a string that contains a symbol and offset corresponding to that value. First the value is checked in the symbol table. If no symbol can be found (either exact match or up to 0XFFF less than the specified value), the value is then checked to see if it falls within one of the loaded or activated images.

Condition Values Returned

SS$_NORMAL Successful completion.

SS$_BUFFEROVF Buffer too small, string truncated.

SS$_NOTRAN No symbolization for this value (null string returned).

Example


VOID_PQ va = VOID_PQ(0xFFFFFFFF80102030); char buffer [64] status = sda$symbolize (va, buffer, sizeof(buffer)); sda$print ("FFFFFFFF.80102030 = \"!AZ\"", buffer);

This example outputs the following:


FFFFFFFF.80102030 = "EXE$WRITE_PROCESS_C+00CD0"

SDA$TRYMEM

Reads dump or system memory and returns the error status (without signaling) if inaccessible.

Format

int sda$trymem (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$TRYMEM does not signal any warning or errors. It returns the error status if the data is inaccessible.
Related Routines

SDA$GETMEM and SDA$REQMEM

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.

Example


int status; DDB *ddb; ... status = sda$trymem (ddb->ddb$ps_link, ddb, DDB$K_LENGTH); if ($VMS_STATUS_SUCCESS (status)) sda$print ("Next DDB is successfully read from dump"); else sda$print ("Next DDB is inaccessible");

int status; 
DDB *ddb; 
... 
status = sda$trymem (ddb->ddb$ps_link, ddb, DDB$K_LENGTH); 
if ($VMS_STATUS_SUCCESS (status)) 
    sda$print ("Next DDB is successfully read from dump"); 
else 
    sda$print ("Next DDB is inaccessible");

This example attempts to read the next DDB in the DDB list from the dump.

Contents

Index

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

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

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

OpenVMS usage	procedure
type	rocedure value
access	read only
mechanism	by value

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

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

SS$_NORMAL	Successful completion.
SS$_BUFFEROVF	Buffer too small, string truncated.
SS$_NOTRAN	No symbolization for this value (null string 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.