HP OpenVMS Systems Documentation

OpenVMS Alpha System Analysis Tools Manual

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.

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.

Translates one Alpha machine instruction into the assembler string equivalent.

Format

int sda$instruction_decode (void *istream_ptr, char *buffer, uint32 buflen);

Arguments

istream_ptr

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

Address of the pointer that points to a copy of the i-stream in a local buffer.

buffer

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

Address of a string buffer into which to store the output assembler string.

buflen

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

Maximum size of the string buffer.

Description

Translates an Alpha machine instruction into the assembler string equivalent. Alpha instructions are always 4 bytes long. The instruction stream must first be read into local memory and then the address of a pointer to the local copy of the instruction stream is passed to the routine. For every successful translated instruction, the pointer is automatically updated to point to the next instruction.

The output assembler string is zero-terminated and in case of a failure a null string is returned.

Condition Values Returned

SS$_NORMAL	Successful completion.
SS$_BADPARAM	Any of the following failures:
	Output buffer too small Invalid register Invalid opcode class/format Could not translate instruction

Example

int status;
VOID_PQ va = (VOID_PQ)0xFFFFFFFF80102030;
uint32 instruction;
uint32 *istream = &instruction;
char buffer[64];
...
sda$reqmem (va, &instruction, 4);
status = sda$instruction_decode (&istream, buffer, sizeof (buffer));
      

This example reads the instruction at dump location VA and decodes it, putting the result into BUFFER. Pointer ISTREAM is incremented (to the next longword).

Begins a new page of output.

Format

void sda$new_page ();

Arguments

None.

Description

This routine causes a new page to be written and outputs the page heading (established with SDA$FORMAT_HEADING) and the current subheading (established with SDA$SET_HEADING_ROUTINE).

Condition Values Returned

None

Example

sda$new_page ();
      

This call outputs a page break and displays the current page heading and subheading (if any).

Parses and executes an SDA command line.

Format

void sda$parse_command (char *cmd_line, __optional_params);

Arguments

cmd_line

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

Address of a valid SDA command line (zero-terminated).

options

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

The options argument has the following values:

Value	Meaning
SDA_OPT$K_PARSE_DONT_SAVE	Indicates "do not save this command." This is the default.
SDA_OPT$K_PARSE_SAVE	Indicates "save this command." That is, it can be recalled with KP0 or REPEAT.

Description

Not every SDA command has a callable extension interface. For example, to redirect SDA's output, you would pass the command string "SET OUTPUT MBX.LIS" to this parse command routine. Abbreviations are allowed.

Condition Values Returned

None

Example

sda$parse_command ("SHOW ADDRESS 80102030");
      

This call produces the following output:

        FFFFFFFF.80102030 is an S0/S1 address

                  Mapped by Level-3 PTE at: FFFFFFFD.FFE00408
                  Mapped by Level-2 PTE at: FFFFFFFD.FF7FF800
                  Mapped by Level-1 PTE at: FFFFFFFD.FF7FDFF8
                  Mapped by Selfmap PTE at: FFFFFFFD.FF7FDFF0

                  Also mapped in SPT window at: FFFFFFFF.FFDF0408
      

The "SHOW ADDRESS" command is not recorded as the most recent command for use with the KP0 key or the REPEAT command.

Formats and prints a single line.

Format

int sda$print (char *ctrstr, __optional_params);

Arguments

ctrstr

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

Address of a zero-terminated control string.

prmlst

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

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

Description

Formats and prints a single line. This is normally output to the terminal, unless you used the SDA commands SET OUTPUT or SET LOG to redirect or copy the output to a file.

Condition Values Returned

SDA$_SUCCESS	Indicates a successful completion.
SDA$_CNFLTARGS	Indicates more than twenty FAO parameters given.
Other	Returns from the $PUT issued by SDA$PRINT (the error is also signaled). If the $FAOL_64 call issued by SDA$PRINT fails, the control string is output.

Example

char buffer[32];
...
sda$get_block_name (0x6F, 0x20,
        buffer,
        sizeof (buffer));
sda$print ("Block type: !AZ", buffer);
      

This example outputs the following line:

Block type: VCC_CFCB
      

Reads symbols from a given file.

Format

int sda$read_symfile (char *filespec, uint32 options, __optional_params);

Arguments

filespec

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

Address of file or directory specification from which to read the symbols (zero-terminated ASCII string).

options

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

Indicates type of symbol file and flags, as shown in the following:

Flags	Effect
SDA_OPT$M_READ_FORCE	read/force <file>
SDA_OPT$M_READ_IMAGE	read/image <file>
SDA_OPT$M_READ_SYMVA	read/symva <file>
SDA_OPT$M_READ_RELO	read/relo <file>
SDA_OPT$M_READ_EXEC	read/exec [<dir>]
SDA_OPT$M_READ_NOLOG	/nolog, suppress count of symbols read
SDA_OPT$M_READ_FILESPEC	<file> or <dir> given
SDA_OPT$M_READ_NOSIGNAL	return status, without signaling errors

relocate_base

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

Base address for symbols (nonsliced symbols).

symvect_va

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

The symbol vector address (symbols are offsets into the symbol vector).

symvect_size

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

Size of symbol vector.

loaded_img_info

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

The address of $LDRIMG data structure with execlet information.

Description

This command reads symbols from a given file to add symbol definitions to the working symbol table by reading GST entries. The file is usually a symbol file (.STB) or an image (.EXE). If SDA_OPT$M_READ_EXEC is specified in the options, then the filespec is treated as a directory specification, where symbol files and/or image files for all execlets may be found (as with READ/EXECUTIVE). If no directory specification is given, the logical name SDA$READ_DIR is used.

Note that when SDA reads symbol files and finds routine names, the symbol name that matches the routine name is set to the address of the procedure descriptor. A second symbol name, the routine name with "_C" appended, is set to the start of the routine's prologue.

Condition Values Returned

SDA$_SUCCESS	Successful completion.
SDA$_CNFLTARGS	No filename given and SDA_OPT$M_READ_EXEC not set.