HP OpenVMS Systems Documentation

HP OpenVMS System Analysis Tools Manual

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.

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.

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.

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

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.

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.

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.

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.

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.

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"

      

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");
      

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