Document revision date: 30 March 2001

## OpenVMS Alpha System Analysis Tools Manual

Previous | Contents | Index

## SDA$INSTRUCTION_DECODE

> 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

Status returns one of the above.

### 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).

## SDA$NEW_PAGE

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

## SDA$PARSE_COMMAND

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

## SDA$PRINT

> 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, a blank line 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

## SDA$READ_SYMFILE

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

Others errors are signaled and/or returned, exactly as though the equivalent SDA READ command had been used. Use HELP/MESSAGE for explanations.

### Example

    sda$read_symfile ("SDA$READ_DIR:SYSDEF", SDA_OPT$M_READ_NOLOG);

> The symbols in SYSDEF.STB are added to SDA's internal symbol table, and the number of symbols found is not output to the terminal.

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

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

Previous | Next | Contents | Index

| privacy and legal statement |
6549PRO_028.HTML