Document revision date: 30 March 2001

## OpenVMS Alpha System Analysis Tools Manual

Previous | Contents | Index

## SDA$GET_BUGCHECK_MSG

> Gets the text associated with a bugcheck code.

### Format

> void sda$get_bugcheck_msg (uint32 bugcheck_code, char *buffer_ptr, uint32 buffer_size);

### Arguments

> #### bugcheck_code

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

> The bugcheck code to look up.

> #### buffer_ptr

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

> Address of buffer to save bugcheck message.

> #### buffer_len

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

> Length of buffer to receive message.

### Description

> Gets the string representing the bugcheck code passed as the argument. The bugcheck message string is passed in the buffer (represented as a pointer and length) as a zero-terminated ASCII string.

> Note The buffer should be large enough to accomodate the largest possible bugcheck message (128 bytes including the termination byte). The text is terminated if it is too long for the supplied buffer.

### Condition Values Returned

> None |

### Example

    char buffer[128];
    ...
    sda$get_bugcheck_msg (0x108, buffer, sizeof(buffer));
    sda$print ("Bugcheck code 108 (hex) =");
    sda$print ("!_\"!AZ\"", buffer);

> This example produces the following output:

       Bugcheck code 108 (hex) =
                    "DOUBLDALOC, Double deallocation of swap file space"

## SDA$GET_CURRENT_CPU

> Gets the CPU database address of the currently selected CPU.

### Format

> void sda$get_current_cpu (cpu **cpudb);

### Arguments

> #### cpudb

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

> Location to which the address of the CPU database is to be returned.

### Description

> This routine causes SDA to return the address of the database for the currently selected CPU.

### Condition Values Returned

> None |

### Example

    #include  <cpudef>
    CPU  *current_cpu;
    sda$get_current_cpu  (  &current_cpu  );

> In this example, the system address of the database for the current CPU is returned in variable current_cpu.

## SDA$GET_CURRENT_PCB

> Gets the PCB address of the "SDA current process" currently selected.

### Format

> void sda$get_current_pcb (PCB **pcbadr);

### Argument

> #### pcbadr

> OpenVMS usage | quadword_unsigned
> type | quadword (unsigned)
> access | write only
> mechanism | by reference

> Location in which to store the current PCB address.

### Description

> The PCB address of the process currently selected by SDA is returned in the specified location.

### Condition Values Returned

> None |

### Example

    PCB *current_pcb;
    ...
    sda$get_current_pcb ( &current_pcb );

> This call stores the system address of the PCB of the process currently being referenced by SDA in the pointer CURRENT_PCB.

## SDA$GET_HEADER

> Returns pointers to local copies of the dump file header and the error log buffer together with the sizes of those data structures.

### Format

> void sda$get_header (DMP **dmp_header, uint32 *dmp_header_size, void **errlog_buf, uint32 *errlog_buf_size);

### Arguments

> #### dmp_header

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

> Location in which to store the address of the copy of the dump file header held by SDA.

> #### dmp_header_size

> OpenVMS usage | longword_unsigned
> type | longword (unsigned)
> access | write only
> mechanism | by reference

> Location in which to store the size of the dump file header.

> #### errlog_buf

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

> Location in which to store the address of the copy of the error log buffer held by SDA.

> #### errlog_buf_size

> OpenVMS usage | longword_unsigned
> type | longword (unsigned)
> access | write only
> mechanism | by reference

> Location in which to store the size of the error log buffer.

### Description

> This routine returns the addresses and sizes of the dump header and error logs read by SDA when the dump file is opened. If this routine is called when the running system is being analyzed with ANALYZE/SYSTEM, then the following occurs:
> - Returns the address and size of SDA's dump header buffer, but the header contains zeroes
> - Returns zeroes for the address and size of SDA's error log buffer

### Condition Values Returned

> None |

### Example

    DMP *dmp_header;
    uint32 dmp_header_size;
    char *errlog_buffer;
    uint32 errlog_buffer_size;
    ...
    sda$get_header (&dmp_header,
            &dmp_header_size,
            (void **)&errlog_buffer,
            &errlog_buffer_size);

> This call stores the address and size of SDA's copy of the dump file header in DMP_HEADER and DMP_HEADER_SIZE, and stores the address and size of SDA's copy of the error log buffers in ERRLOG_BUFFER and ERRLOG_BUFFER_SIZE, respectively.

## SDA$GET_HW_NAME

> Returns the full name of the hardware platform where the dump was written.

### Format

> void sda$get_hw_name (char *buffer_ptr, uint32 buffer_len);

### Arguments

> #### buffer_ptr

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

> Address of buffer to save HW name.

> #### buffer_len

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

> Length of buffer to receive HW name.

### Description

> Returns a zero-terminated ASCII string representing the platform hardware name and puts it in the buffer passed as the argument.

> Note The buffer should be large enough to accomodate the largest possible hardware platform name (120 bytes including the termination byte). The name is truncated if it is too long for the supplied buffer.

### Condition Values Returned

> None |

### Example

    char hw_name[64];
    ...
    sda$get_hw_name (hw_name, sizeof(hw_name));
    sda$print ("Platform name: \"!AZ\"", hw_name);

> This example produces output of the form:

                    Platform name: "DEC 3000 Model 400"

## SDA$GET_IMAGE_OFFSET

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

SDA_CIO$V_xxx flags set: | img_info type: | subimg_info type:
--- | --- | ---
valid | LDRIMG | n/a
valid && sliced | LDRIMG | ISD_OVERLAY
valid && process | IMCB | n/a
valid && process && sliced | IMCB | KFERES_SECTION

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

## SDA$GET_INPUT

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

## SDA$GET_LINE_COUNT

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

## SDA$GETMEM

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

Previous | Next | Contents | Index

| privacy and legal statement |
6549PRO_027.HTML