The following help topics describe how to write, debug, and
invoke an SDA Extension.
Select the Routines subtopic to access descriptions of all the
routines available to an SDA extension.
1 – Introduction
When analysis of a dump file or a running system requires
intimate knowledge of data structures that are not known to
the System Dump Analyzer, the functionality of SDA can be
extended by the addition of new commands into which the necessary
knowledge has been built. Note that in this description, whenever
a reference is made to accessing a dump file (ANALYZE/CRASH_
DUMP), this also includes accessing memory in the running system
(ANALYZE/SYSTEM).
For example, a user-written device driver allocates nonpaged
pool and records additional data about the device there (logging
different types of I/O, perhaps), and a pointer to the new
structure is saved in the device-specific extension of the UCB.
After a system crash, the only way to look at the data from SDA
is to do the following:
o Invoke the SDA command DEFINE to define a new symbol (for
example, UCB$L_FOOBAR) whose value is the offset in the UCB of
the pointer to the new structure.
o Invoke the SDA commands "SHOW DEVICE <device>" and "FORMAT
UCB" to obtain the address of the nonpaged pool structure.
o Invoke the SDA command "EXAMINE <address>;<length>" to display
the contents of the data in the new nonpaged pool structure as
a series of hexadecimal longwords.
o Decode manually the contents of the data structure from this
hexadecimal dump.
An SDA extension that knows the layout of the nonpaged pool
structure, and where to find the pointer to it in the UCB, could
output the data in a formatted display that alerts the user to
unexpected data patterns.
2 – Description
The following discussion uses an example of an SDA extension
that invokes the MBX command to output a formatted display of
the status of the mailbox devices in the system. The source file,
MBX$SDA.C, is provided in SYS$EXAMPLES.
An SDA extension consists of a shareable image, in this case
MBX$SDA.EXE, either located in the directory SYS$LIBRARY or
found by translating the logical name MBX$SDA. It contains two
universal symbols: SDA$EXTEND, the entry point; and SDA$EXTEND_
VERSION, the address of a longword that contains the version of
the interface used (in the format of major/minor ident), which
allows SDA to confirm it has activated a compatible extension.
The image contains at least two modules: MBX$SDA, the user-
written module that defines the two symbols and provides the
code and data necessary to produce the desired formatted output;
and SDA_EXTEND_VECTOR, which provides jackets for all of the
callable SDA routines, and is found in SYS$LIBRARY:VMS$VOLATILE_
PRIVATE_INTERFACES.OLB. The user-written portion can be split
into multiple modules.
Whenever SDA receives an unrecognized command, like "SDA> MBX",
it attempts to activate the shareable image MBX$SDA at the
SDA$EXTEND entry point. If you choose a command name that matches
the abbreviation of an existing command, SDA can be forced to
activate the extension using the "DO" command. For example, if
you had an SDA extension called VAL$SDA, you could not activate
it with a command like "SDA> VAL" as SDA would interpret that
as an abbreviation of its VALIDATE command. But VAL$SDA can be
activated by issuing "SDA> DO VAL".
With or without the "DO" prefix, the rest of the command line
is passed to the extension; it is up to the extension to parse
it. The example extension MBX$SDA includes support for commands
of the form "SDA> MBX SUMMARY" and "SDA> MBX <address>" to
demonstrate this. If the extension is invoked with no arguments,
it should do no more than display a simple announcement message,
or prompt for input. This assists in the debugging of the
extension, as described in Debugging an Extension.
Compiling and Linking an SDA Extension describes how to compile,
link, and invoke an SDA extension, and describes what an SDA
extension should contain.
2.1 – Compiling and Linking an SDA Extension
The user-written module is only supported when written in HP
C (minimum Version 5.2), following the pattern of the example
extension, MBX$SDA.C. It should be compiled and linked using
commands of the following form:
$cc mbx$sda + sys$library:sys$lib_c /library
$link /share -
mbx$sda.obj, -
sys$library:vms$volatile_private_interfaces /library, -
sys$input /option
symbol_vector = (sda$extend=procedure)
symbol_vector = (sda$extend_version=data)
NOTE
1. You can include the qualifier /INSTRUCTION=NOFLOAT on the
compile command line if floating-point instructions are not
needed.
2. The + SYS$LIBRARY:SYS$LIB_C /LIBRARY is not needed on the
compile command line if the logical name DECC$TEXT_LIBRARY
is defined and translates to SYS$LIBRARY:SYS$LIB_C.TLB.
3. If the user-written extension needs to signal SDA
condition codes, or output their text with $PUTMSG, you
should add the qualifier /INCLUDE=SDAMSG to the parameter
SYS$LIBRARY:VMS$VOLATILE_PRIVATE_INTERFACES /LIBRARY.
2.2 – Invoking an SDA Extension
You can invoke the SDA extension as follows:
$define mbx$sda sys$disk:[]mbx$sda
$analyze /system
SDA>mbx summary
SDA>mbx <address>
2.3 – Contents of an SDA Extension
At a minimum, the user-written module must contain:
o #include statements for DESCRIP.H and SDA_ROUTINES.H
o The global variable SDA$EXTEND_VERSION, initialized as
follows:
int sda$extend_version = SDA_FLAGS$K_VERSION;
o The routine SDA$EXTEND (prototype follows)
Optionally, the user-written module may also contain the
statement:
#define __NEW_STARLET
You should use this option because it provides type checking of
function arguments and gives consistency in casing and naming
conventions.
The entry point in the user-written module, SDA$EXTEND, is
called as a routine with three arguments and no return value.
The declaration is as follows:
void sda$extend (
int *transfer_table,
struct dsc$descriptor_s *cmd_line,
SDA_FLAGS sda_flags)
The arguments in this code example have the following meanings:
Table 3-1 SDA$EXTEND Arguments
Line of
Code Meaning
transfer_ Address of the vector table in the base image. The
table user-written routine SDA$EXTEND must copy this to
SDA$VECTOR_TABLE (declared in SDA_ROUTINES.H) before
any SDA routines can be called.
cmd_line Address of the descriptor of the command line as
entered by the user, less the name of the extension.
So, if you enter "SDA> MBX" or "SDA> DO MBX", the
command line is a zero length string. If you enter
the command "SDA> MBX 80102030", the command line is
" 80102030" (the separating space is not stripped).
sda_flags Definition for the following four bits in this
structure:
Bit Meaning
sda_flags.sda_ Indicates SDA has been activated
flags$v_override with the ANALYZE/CRASH_
DUMP/OVERRIDE command
sda_flags.sda_ Indicates SDA has been activated
flags$v_current with the ANALYZE/SYSTEM command or
was invoked from the kept debugger
during an SCD session
sda_flags.sda_ Indicates that SDA was invoked
flags$v_target from the kept debugger during
an SCD or SDD session or when
analyzing a process dump
sda_flags.sda_ Indicates SDA was activated with
flags$v_process the ANALYZE/CRASH_DUMP command to
analyze a process dump
sda_flags.sda_ Indicates that SDA is analyzing an
flags$v_ia64 Integrity server system or dump
None of the above Indicates SDA was activated with
bits set the ANALYZE/CRASH_DUMP command to
analyze an Alpha system dump
Other bits Reserved to HP:may be nonzero
The first executable statement of the routine must be to copy
TRANSFER_TABLE to SDA$VECTOR_TABLE (which is declared in SDA_
ROUTINES.H):
sda$vector_table = transfer_table;
If this is not done, you cannot call any of the routines
described below. Any attempts to call the routines receive a
status return of SDA$_VECNOTINIT. (For routines defined not to
return a status, this value can be found only by examining the
return value directly.)
The next statement should be one to establish a condition
handler, as it is often difficult to track down errors in
extensions such as access violations because the extension is
activated dynamically with LIB$FIND_IMAGE_SYMBOL. A default
condition handler, SDA$COND_HANDLER, is provided that outputs
the following information in the event of an error:
o The error condition
o The VMS version
o A list of activated images, with start and end virtual
addresses
o The signal array and register dump
o The current call frame chain
You can establish this condition handler as follows:
lib$establish (sda$cond_handler);
NOTE
The error condition, signal array, and register dump are
output directly to SYS$OUTPUT and/or SYS$ERROR, and are not
affected by the use of the SDA commands SET OUTPUT and SET
LOG.
Thus, a minimal extension would be:
#define __NEW_STARLET 1
#include <descrip.h>
#include <sda_routines.h>
int sda$extend_version = SDA_FLAGS$K_VERSION;
void sda$extend (int *transfer_table,
struct dsc$descriptor_s *cmd_line,
SDA_FLAGS sda_flags)
{
sda$vector_table = transfer_table;
lib$establish (sda$cond_handler);
sda$print ("hello, world");
return;
}
2.4 – Debugging an Extension
In addition to the "after-the-fact" information provided by
the condition handler, you can debug SDA extensions using the
OpenVMS Debugger. A second copy of the SDA image, SDA_DEBUG.EXE,
is provided in SYS$SYSTEM. By defining the logical name SDA to
reference this image, you can debug SDA extensions as follows:
o Compile your extension /DEBUG/NOOPT and link it /DEBUG or
/DSF.
o Define logical names for SDA and the extension, and invoke
SDA.
o Type SET BREAK START_EXTENSION at the initial DBG> prompt, and
then type GO.
o Invoke the extension at the SDA> prompt.
o When Debug prompts again, use Debug commands to set
breakpoints, and so on, in the extension and then type GO.
o Invoke the extension, providing the necessary arguments.
An example of the preceding steps is as follows:
$ cc /debug /noopt mbx$sda + sys$library:sys$lib_c /library
$ link /debug /share -
mbx$sda.obj, -
sys$library:vms$volatile_private_interfaces /library, -
sys$input /option
symbol_vector = (sda$extend=procedure)
symbol_vector = (sda$extend_version=data)
$ !
$ define mbx$sda sys$disk:[]mbx$sda
$ define sda sda_debug
$ analyze /system
...
DBG> set break start_extension
DBG> go
...
SDA> mbx
break at routine START\START_EXTENSION
...
DBG> set image mbx$sda
DBG> set language c
DBG> set break /exception
DBG> go
MBX commands: 'MBX SUMMARY' and 'MBX <address>'
SDA> mbx summary
...
SDA> mbx <address>
...
%DEBUG-I-DYNMODSET, setting module MBX$SDA
%SYSTEM-E-INVARG, invalid argument
...
DBG>
3 – Callable Routines Overview
The user-written routine may call SDA routines to accomplish any
of the following tasks:
o Read the contents of memory locations in the dump.
o Translate symbol names to values and vice-versa, define new
symbols, and read symbol table files.
o Map an address to the activated image or executive image that
contains that address.
o Output text to the terminal, with page breaks, page headings,
and so on (or output to a file if the SDA commands SET OUTPUT
or SET LOG have been used).
o Allocate and deallocate dynamic memory.
o Validate queues/lists.
o Format data structures.
o Issue any SDA command.
Note the following points before using the callable routines
described here:
o The following three routines are used to read the contents of
memory locations in the dump:
- SDA$TRYMEM is called from both SDA$GETMEM and SDA$REQMEM
as the lower-level routine that actually does the work.
SDA$TRYMEM returns success/failure status in R0, but does
not signal any errors. Use it directly when you expect that
the location being read might be inaccessible. The caller
of SDA$TRYMEM handles this situation by checking the status
returned by SDA$TRYMEM.
- SDA$GETMEM signals a warning when any error status is
returned from SDA$TRYMEM. Signaling a warning prints out
a warning message, but does not abort the SDA command in
progress. You should use this routine when you expect the
location to be read to be accessible. This routine does
not prevent the command currently being executed from
continuing. The caller of SDA$GETMEM must allow for this
by checking the status returned by SDA$GETMEM.
- SDA$REQMEM signals an error when any error status is
returned from SDA$TRYMEM. Signaling an error prints out
an error message, aborts the SDA command in progress, and
returns to the "SDA>" prompt. You should use this routine
when you expect the location to be read to be accessible.
This routine prevents the command currently being executed
from continuing. The caller of SDA$REQMEM does not resume
if an error occurs.
o You should use only the routines provided to output text.
Do not use printf() or any other standard routine. If you
do, the SDA commands SET OUTPUT and SET LOG will not produce
the expected results. Do not include control characters in
output (except tab); in particular, avoid <CR>, <LF>,<FF>,
and the FAO directives that create them. Use the FAO directive
!AF when contents of memory returned by SDA$TRYMEM, and so
on, are being displayed directly, because embedded control
characters will cause undesirable results. For example,
displaying process names or resource names that contain
particular control characters or escape sequences can lock
up the terminal.
o You should use only the routines provided to allocate and
deallocate dynamic memory. Do not use malloc() and free().
Where possible, allocate dynamic memory once, the first time
the extension is activated, and deallocate it only if it needs
to be replaced by a larger allocation. Because SDA commands
can be interrupted by invoking another command at the "Press
return for more" prompt, it is very easy to cause memory
leaks.
o Some routines expect 32-bit pointers, and others expect 64-
bit pointers. At first this not may appear to be logical,
but in fact it is. All code and data used by SDA and any
extensions must be in P0 or P1 space, as SDA does not need to
(and does not) use P2 space for local data storage. However,
addresses in the system dump (or running system, in the case
of ANALYZE/SYSTEM) are 64-bit addresses, and SDA must provide
access to all locations in the dump.
So, for example, the first two arguments to the routine
SDA$TRYMEM are:
VOID_PQ start /* 64-bit pointer */
void *dest /* 32-bit pointer */
They specify the address of interest in the dump and the
address in local storage to which the dump contents are to
be copied.
o Common Bitmask Block (CBB) routines, SDA$CBB_xxx, are
designed for use with local copies of the CBB structures that
describe the CPUs in use in a system. The CBB structures are
assumed to be at least CBB$K_STATIC_BLOCK bytes in length.
The definitions of the various CBB constants and field
names used by these routines can be found in CBBDEF.H in
SYS$LIBRARY:SYS$LIB_C.TLB.
The set of routines is not intended to be an exhaustive set
of all possible CBB-related operations, but it provides those
operations known to be needed. The routines might not work as
expected with CBB structures that are set up for any purpose
other than to describe CPUs.
4 – Routines
The following subtopics describe the SDA extension callable
routines.
4.1 – SDA$ADD_SYMBOL
Adds a symbol to SDA's local symbol table.
Format
void sda$add_symbol (char *symbol_name, uint64 symbol_value);
4.1.1 – Arguments
symbol_name
OpenVMS usage char_string
type character string
access read only
mechanism by reference
Address of symbol name string (zero-terminated).
symbol_value
OpenVMS usage quadword_unsigned
type quadword (unsigned)
access read only
mechanism by value
The symbol value.
4.2 – SDA$ALLOCATE
Allocates dynamic memory.
Format
void sda$allocate (uint32 size, void **ptr_block);
4.2.1 – Arguments
size
OpenVMS usage longword_unsigned
type longword (unsigned)
access read only
mechanism by value
Size of block to allocate (in bytes).
ptr_block
OpenVMS usage address
type longword (unsigned)
access write only
mechanism by reference
Address of longword to receive address of block.
4.2.2 – Condition Values Returned
None
If no memory is available, the error is signaled and the SDA
session aborted.
4.3 – SDA$CBB_BOOLEAN_OPER
Performs a Boolean operation on a pair of CBBs.
Format
int sda$cbb_boolean_oper (CBB_PQ input_cbb, CBB_PQ output_cbb,
int operation);
4.3.1 – Arguments
input_cbb
OpenVMS usage address
type CBB structure
access read only
mechanism by reference
The address of the first (input) CBB structure.
output_cbb
OpenVMS usage address
type CBB structure
access read/write
mechanism by reference
The address of the second (output) CBB structure.
operation
OpenVMS usage longword
type longword (unsigned)
access read only
mechanism by value
The desired operation from the following list:
CBB$C_OR The logical sum of the two CBBs is performed and the
result (B = A | B) is written to the output CBB.
CBB$C_BIC The logical product with complement of the two CBBs
is performed and the result (B = B & ~A) is written
to the output CBB.
4.3.2 – Condition Values Returned
SS$_BADPARAM The number of valid bits in the input and
output CBBs is different.
SS$_WASCLR All bits in the resulting output CBB are
clear.
SS$_WASSET At least one bit in the resulting output CBB
is set.
4.4 – SDA$CBB_CLEAR_BIT
Clears the specified bit in a CBB.
Format
int sda$cbb_clear_bit (CBB_PQ cbb, int bit);
4.4.1 – Arguments
cbb
OpenVMS usage address
type CBB structure
access read/write
mechanism by reference
The address of the CBB structure to be modified.
bit
OpenVMS usage longword
type longword (unsigned)
access read only
mechanism by value
The bit in the CBB to be cleared. If the bit number is -1, clears
all bits.
4.4.2 – Condition Values Returned
SS$NORMAL Successful completion
SS$BADPARAM The bit number is out of range
4.5 – SDA$CBB_COPY
Copies the contents of one CBB to another.
Format
int sda$cbb_copy (CBB_PQ input_cbb, CBB_PQ output_cbb);
4.5.1 – Arguments
input_cbb
OpenVMS usage address
type CBB structure
access read only
mechanism by reference
The address of the CBB structure to be copied.
output_cbb
OpenVMS usage address
type CBB structure
access write only
mechanism by reference
The address of the CBB structure to receive the copy.
4.6 – SDA$CBB_FFC
Locates the first clear bit in a CBB.
Format
int sda$cbb_ffc (CBB_PQ cbb, int start_bit);
4.6.1 – Arguments
cbb
OpenVMS usage address
type CBB structure
access read only
mechanism by reference
The address of the CBB structure to be searched.
start_bit
OpenVMS usage longword
type longword (unsigned)
access read only
mechanism by value
The first bit in the CBB to be checked.
4.6.2 – Condition Values Returned
bit_number If a clear bit is found, its bit number
is returned. If no clear bit is found (all
bits from start_bit to cbb->cbb$l_valid_bits
are set), then the number of valid bits is
returned.
4.7 – SDA$CBB_FFS
Locates the first set bit in a CBB.
Format
int sda$cbb_ffs (CBB_PQ cbb, int start_bit);
4.7.1 – Arguments
cbb
OpenVMS usage address
type CBB structure
access read only
mechanism by reference
The address of the CBB structure to be searched.
start_bit
OpenVMS usage longword
type longword (unsigned)
access read only
mechanism by value
The first bit in the CBB to be checked.
4.7.2 – Condition Values Returned
bit_number If a set bit is found, its bit number is
returned. If no set bit is found (all bits
from start_bit to cbb->cbb$l_valid_bits are
clear), then the number of valid bits is
returned.
4.8 – SDA$CBB_INIT
Initializes a CBB structure to a known state.
Format
void sda$cbb_init (CBB_PQ cbb);
4.8.1 – Argument
cbb
OpenVMS usage address
type CBB structure
access read only
mechanism by reference
The address of the CBB structure to be initialized.
4.9 – SDA$CBB_SET_BIT
Sets the specified bit in a CBB.
Format
int sda$cbb_set_bit (CBB_PQ cbb,int bit);
4.9.1 – Arguments
cbb
OpenVMS usage address
type CBB structure
access read/write
mechanism by reference
The address of the CBB structure to be modified.
bit
OpenVMS usage longword
type longword (unsigned)
access read only
mechanism by value
The bit in the CBB to be set. If the bit number is -1, set all
bits.
4.9.2 – Condition Values Returned
SS$NORMAL Successful completion.
SS$BADPARAM The bit number is out of range.
4.10 – SDA$CBB_TEST_BIT
Tests the specified bit in a CBB.
Format
int sda$cbb_test_bit (CBB_PQ cbb,int bit);
4.10.1 – Arguments
cbb
OpenVMS usage address
type CBB structure
access read only
mechanism by reference
The address of the CBB structure to be tested.
bit
OpenVMS usage longword
type longword (unsigned)
access read only
mechanism by value
The bit in the CBB to be tested.
4.10.2 – Condition Values Returned
SS$_WASSET The specified bit was set.
SS$_WASCLR The specified bit was clear.
SS$_BADPARAM The bit number is out of range.
4.11 – SDA$DEALLOCATE
Deallocates and frees dynamic memory.
Format
void sda$deallocate (void *ptr_block, uint32 size);
4.11.1 – Arguments
ptr_block
OpenVMS usage address
type longword (unsigned)
access read only
mechanism by value
Starting address of block to be freed.
size
OpenVMS usage longword_unsigned
type longword (unsigned)
access read only
mechanism by value
Size of block to deallocate (in bytes).
4.11.2 – Condition Values Returned
None
If an error occurs, it is signaled and the SDA session aborted.
4.12 – SDA$DELETE_PREFIX
Deletes all symbols with the specified prefix.
Format
void sda$delete_prefix (char *prefix);
4.12.1 – Argument
prefix
OpenVMS usage char_string
type character string
access read only
mechanism by reference
The address of the prefix string.
4.13 – SDA$DISPLAY_HELP
Displays online help.
Format
void sda$display_help (char *library_desc, char *topic_desc);
4.13.1 – Arguments
library
OpenVMS usage char_string
type character string
access read only
mechanism by reference
Address of library filespec. Specify as zero-terminated ASCII
string.
topic
OpenVMS usage char_string
type character string
access read only
mechanism by reference
Address of topic name. Specify as zero-terminated ASCII string.
4.14 – SDA$ENSURE
Ensures sufficient space on the current output page.
Format
void sda$ensure (uint32 lines);
4.14.1 – Argument
lines
OpenVMS usage longword_unsigned
type longword (unsigned)
access read only
mechanism by value
Number of lines to fit on a page.
4.15 – SDA$FAO
Formats data into a buffer.
Format
char * sda$fao (char * ctrstr, char * buffer, int buflen,
__optional_params);
4.15.1 – Arguments
ctrstr
OpenVMS usage char_string
type character-coded text string
access read only
mechanism by reference
Addess of a zero-terminated FAO control string.
buffer
OpenVMS usage char_string
type character string
access write only
mechanism by reference
Address of a string buffer into which to store the formatted
string.
buflen
OpenVMS usage longword_unsigned
type longword (unsigned)
access read only
mechanism by value
Maximum size of the string buffer.
prmlst
OpenVMS usage varying_arg
type quadword (signed or unsigned)
access read only
mechanism by value
Optional FAO parameters. All arguments after buflen are copied
into a quadword parameter list, as used by $FAOL_64.
4.15.2 – Condition Values Returned
Address of SDA$FAO returns the address of the terminating
terminating zero zero in the output buffer. This allows
successive calls to SDA$FAO to append strings.
4.16 – SDA$FID_TO_NAME
Translates a file identification (FID) into the equivalent file
name.
Format
int sda$fid_to_name (char *devptr, unsigned short *fidptr,
char *bufptr, int buflen );
4.16.1 – Arguments
devptr
OpenVMS usage char_string
type character string
access read only
mechanism by reference
The address of the device name string. The device name must be
supplied in allocation-class device name (ALLDEVNAM) format, but
any leading underscore or trailing colon are ignored.
fidptr
OpenVMS usage address
type file identification
access read only
mechanism by reference
The address of the three-word file identification.
bufptr
OpenVMS usage char_string
type character string
access write only
mechanism by reference
The address of a string buffer into which to store the file name
string.
buflen
OpenVMS usage longword
type longword (unsigned)
access read only
mechanism by value
The maximum length of the string buffer.
4.16.2 – Condition Values Returned
SDA$_SUCCESS File identification successfully translated.
SDA$_NOCOLLECT No collection available for the system, the
specified disk, or the file identification.
Others An error occurred when LIB$FID_TO_NAME was
called.
4.16.3 – Example
int status;
char buffer [132];
char *device = $1$DKA0;
unsigned short fid [3] = {1, 1, 0};
status = sda$fid_to_name (device, &fid [0], buffer, 132);
if (status & 1)
sda$print ("Filename is !AZ", buffer);
else
sda$print ("File ID could not be translated");
This example shows the translation of file ID (1,1,0) on
$1$DKA0:, which is $1$DKA0:[000000]INDEXF.SYS;1.
4.17 – SDA$FORMAT
Displays the formatted contents of a data structure.
Format
void sda$format (VOID_PQ struct_addr, __optional_params);
4.17.1 – Arguments
struct_addr
OpenVMS usage address
type quadword (unsigned)
access read only
mechanism by value
The address in the system dump of the data structure to be
formatted.
options
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by value
The following provides more information on options:
Option Meaning
None Uses structure type from the xxx$B_
TYPE and/or xxx$B_SUBTYPE field of the
structure. This is the default.
SDA_OPT$M_FORMAT_TYPE Uses the structure type given in struct_
prefix.
SDA_OPT$M_FORMAT_ Indicates that struct_addr is a physical
PHYSICAL address instead of a virtual address.
struct_prefix
OpenVMS usage char_string
type character string
access read only
mechanism by reference
Address of structure name string (zero-terminated).
4.18 – SDA$FORMAT_HEADING
Formats a new page heading.
Format
void sda$format_heading (char *ctrstr, __optional_params);
4.18.1 – Arguments
ctrstr
OpenVMS usage char_string
type character-coded text string
access read only
mechanism by reference
Address of control string (zero-terminated ASCII string).
prmlst
OpenVMS usage varying_arg
type quadword (signed or unsigned)
access read only
mechanism by value
FAO parameters that are optional. All arguments after the control
string are copied into a quadword parameter list as used by
$FAOL_64.
4.18.2 – Condition Values Returned
None
If the $FAOL_64 call issued by SDA$FORMAT_HEADING fails, the
control string is used as the page heading.
4.19 – SDA$GET_ADDRESS
Gets the address value of the current memory location.
Format
void sda$get_address (VOID_PQ *address);
4.19.1 – Argument
address
OpenVMS usage quadword_unsigned
type quadword (unsigned)
access write only
mechanism by reference
Location to store the current 64-bit memory address.
4.20 – SDA$GET_BLOCK_NAME
Returns the name of a structure, given its type and/or subtype.
Format
void sda$get_block_name (uint32 block_type, uint32
block_subtype,
char *buffer_ptr, uint32 buffer_len);
4.20.1 – Arguments
block_type
OpenVMS usage longword_unsigned
type longword (unsigned)
access read only
mechanism by value
Block type in range 0 - 255 (usually extracted from xxx$b_type
field).
block_subtype
OpenVMS usage longword_unsigned
type longword (unsigned)
access read only
mechanism by value
Block subtype in range 0 - 255 (ignored if the given block type
has no subtypes).
buffer_ptr
OpenVMS usage char_string
type character string
access write only
mechanism by reference
Address of buffer to save block name, which is returned as a
zero-terminated string.
buffer_len
OpenVMS usage longword_unsigned
type longword (unsigned)
access read only
mechanism by value
Length of buffer to receive block name.
4.21 – 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);
4.21.1 – 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.
4.22 – SDA$GET_CURRENT_CPU
Gets the CPU database address of the currently selected CPU.
Format
void sda$get_current_cpu (CPU **cpudb);
4.22.1 – 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.
4.23 – SDA$GET_CURRENT_PCB
Gets the PCB address of the "SDA current process" currently
selected.
Format
void sda$get_current_pcb (PCB **pcbadr);
4.23.1 – Argument
pcbadr
OpenVMS usage quadword_unsigned
type quadword (unsigned)
access write only
mechanism by reference
Location in which to store the current PCB address.
4.24 – SDA$GET_DEVICE_NAME
Gets the device name, given the UCB address of the device.
Format
int sda$get_device_name (VOID_PQ ucb_addr, char *name_buf, int
name_len);
4.24.1 – Arguments
ucb_addr
OpenVMS usage address
type quadword (unsigned)
access read only
mechanism by value
System address of the Unit Control Block of the device.
name_buf
OpenVMS usage char_string
type character string
access write only
mechanism by reference
Address of buffer to receive device name.
name_len
OpenVMS usage longword_unsigned
type longword (unsigned)
access read only
mechanism by value
Length of buffer to receive device name.
4.24.2 – Condition Values Returned
SDA$_SUCCESS Successful completion
SDA$_NOTAUCB The address given is not the address of a UCB
SDA$_NOREAD The data is inaccessible for some reason
Others The data is inaccessible for some reason
4.25 – SDA$GET_FLAGS
Obtain environment flags that indicate how SDA is being used.
Format
int sda$get_flags (SDA_FLAGS *flagaddr);
4.25.1 – Argument
flagaddr
OpenVMS usage address
type SDA_FLAGS structure
access write only
mechanism by reference
The address of the location where the environment flags are to be
returned.
4.25.2 – Examples
1.SDA_FLAGS flags;
sda$get_flags (&flags);
if (flags.sda_flags$v_current)
sda$print (Analyzing the current system);
This example shows the use of SDA$GET_FLAGS.
4.26 – 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; optionally returns pointers and sizes for the crash
error log entry and trap data (if any).
Format
void sda$get_header (DMP **dmp_header, uint32 *dmp_header_size,
void **errlog_buf, uint32 *errlog_buf_size,__optional_params);
4.26.1 – 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.
crasherl_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 crash
error log entry held by SDA.
crasherl_buf_size
OpenVMS usage longword_unsigned
type longword (unsigned)
access write only
mechanism by reference
Location in which to store the size of the crash error log entry.
trapinfo_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 trap
info, if any, held by SDA.
trapinfo_buf_size
OpenVMS usage longword_unsigned
type longword (unsigned)
access write only
mechanism by reference
Location in which to store the size of the trap data, if any.
4.27 – 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);
4.27.1 – 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.
4.28 – 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);
4.28.1 – 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.
4.28.2 – 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_ Set if activated image contains compressed
COMPRESSED data sections
SDA_CIO$V_ISD_ Index into ISD_LABELS table (on Alpha, only
INDEX 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 && IMCB KFERES_SECTION
SLICED
On Integrity servers, SDA_CIO$V_SLICED will always be set if SDA_
CIO$V_VALID is set.
The following table describes the ISD_LABELS index on Alpha:
Index Name Meaning
0 SDA_CIO$K_NPRO Nonpaged read only
1 SDA_CIO$K_NPRW Nonpaged read/write
2 SDA_CIO$K_PRO Paged read only
3 SDA_CIO$K_PRW Paged read/write
4 SDA_CIO$K_FIX Fixup
5 SDA_CIO$K_INIT Initialization
The following table describes the ISD_LABELS index on Integrity
servers:
Index Name Meaning
0 SDA_CIO$K_FIX Fixup
1 SDA_CIO$K_PROMO_CODE Promote (code)
2 SDA_CIO$K_PROMO_DATA Promote (data)
3 SDA_CIO$K_INIT_CODE Initialization (code)
4 SDA_CIO$K_INIT_DATA Initialization (data)
5 SDA_CIO$K_CODE Code
6 SDA_CIO$K_SHORT_RW Short data (read/write)
7 SDA_CIO$K_SHORT_RO Short data (read only)
8 SDA_CIO$K_RW Data (read/write)
9 SDA_CIO$K_RO Data (read only)
10 SDA_CIO$K_SHORT_DZ Short data (demand zero)
11 SDA_CIO$K_SHORT_TDZ Short data (trailing demand zero)
12 SDA_CIO$K_DZERO Demand zero
13 SDA_CIO$K_TR_DZERO Trailing demand zero
4.29 – SDA$GET_INPUT
Reads input commands.
Format
int sda$get_input (char *prompt, char *buffer, uint32 buflen);
4.29.1 – 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.
4.29.2 – Condition Values Returned
SS$_NORMAL Successful completion.
RMS$_EOF User pressed <ctrl/Z>
4.30 – SDA$GET_LINE_COUNT
Obtains the number of lines currently printed on the current
page.
Format
void sda$get_line_count (uint32 *line_count);
4.30.1 – Argument
line_count
OpenVMS usage longword_unsigned
type longword (unsigned)
access write only
mechanism by reference
The number of lines printed on current page.
4.31 – 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);
4.31.1 – 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.
4.31.2 – 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.
4.32 – SDA$INSTRUCTION_DECODE
Translates one machine instruction into the assembler string
equivalent.
Format
int sda$instruction_decode (void *istream_ptr, char *buffer,
uint32 buflen,__optional_params);
4.32.1 – 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.
template_buffer
OpenVMS usage char_string
type character string
access write only
mechanism by reference
(Integrity servers only.) Address of a string buffer into which
to store the template string.
template_buflen
OpenVMS usage longword_unsigned
type longword (unsigned)
access read only
mechanism by value
(Integrity servers only.) Maximum size of the template buffer.
4.32.2 – 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
4.33 – SDA$NEW_PAGE
Begins a new page of output.
Format
void sda$new_page ();
4.34 – SDA$PARSE_COMMAND
Parses and executes an SDA command line.
Format
void sda$parse_command (char *cmd_line, __optional_params);
4.34.1 – 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_ Indicates "do not save this command." This
DONT_SAVE is the default.
SDA_OPT$K_PARSE_SAVE Indicates "save this command." That is, it
can be recalled with KP0 or REPEAT.
4.35 – SDA$PRINT
Formats and prints a single line.
Format
int sda$print (char *ctrstr, __optional_params);
4.35.1 – Arguments
ctrstr
OpenVMS usage char_string
type character-coded text string
access read only
mechanism by reference
Address of a zero-terminated FAO 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.
4.35.2 – 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.
4.36 – SDA$READ_SYMFILE
Reads symbols from a given file.
Format
int sda$read_symfile (char *filespec, uint32 options,
__optional_params);
4.36.1 – 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_ <file> or <dir> given
FILESPEC
SDA_OPT$M_READ_ return status, without signaling errors
NOSIGNAL
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.
4.36.2 – Condition Values Returned
SDA$_SUCCESS Successful completion.
SDA$_CNFLTARGS No filename given and SDA_OPT$M_READ_EXEC not
set.
Other errors are signaled and/or returned, exactly as though the
equivalent SDA READ command had been used. Use HELP/MESSAGE for
explanations.
4.37 – 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);
4.37.1 – 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.
4.37.2 – Condition Values Returned
SDA$_SUCCESS Successful completion.
Any failure is signaled as an error and the current command
aborts.
4.38 – SDA$SET_ADDRESS
Stores a new address value as the current memory address (".").
Format
void sda$set_address (VOID_PQ address);
4.38.1 – Argument
address
OpenVMS usage quadword_unsigned
type quadword (unsigned)
access read only
mechanism by value
Address value to store in current memory location.
4.39 – SDA$SET_CPU
Sets a new SDA CPU context.
Format
int sda$set_cpu (int cpu_id);
4.39.1 – Arguments
cpu_id
OpenVMS usage longword_unsigned
type longword (unsigned)
access read only
mechanism by value
The desired CPU ID.
4.39.2 – Condition Values Returned
SDA$_SUCCESS Successful completion.
Any failure is signaled as an error and the current command
aborts.
4.40 – 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) ());
4.40.1 – Argument
heading_rtn
OpenVMS usage procedure
type procedure value
access read only
mechanism by value
Address of routine to be called after each new page.
4.41 – 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);
4.41.1 – Argument
line_count
OpenVMS usage longword_unsigned
type longword (unsigned)
access read only
mechanism by value
The number of lines printed on current page.
4.42 – SDA$SET_PROCESS
Sets a new SDA process context.
Format
int sda$set_process (const char *proc_name, int proc_index, int
proc_addr);
4.42.1 – 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.
4.42.2 – Condition Values Returned
SDA$_SUCCESS Successful completion.
Any failure is signaled as an error and the current command
aborts.
4.43 – SDA$SKIP_LINES
This routine outputs a specified number of blank lines.
Format
void sda$skip_lines (uint32 lines);
4.43.1 – Argument
lines
OpenVMS usage longword_unsigned
type longword (unsigned)
access read only
mechanism by value
Number of lines to skip.
4.44 – SDA$SYMBOL_VALUE
Obtains the 64-bit value of a specified symbol.
Format
int sda$symbol_value (char *symb_name, uint64 *symb_value);
4.44.1 – 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.
4.44.2 – Condition Values Returned
SDA$_SUCCESS Symbol found.
SDA$_BADSYM Symbol not found.
4.45 – SDA$SYMBOLIZE
Converts a value to a symbol name and offset.
Format
int sda$symbolize (uint64 value, char *symbol_buf, uint32
symbol_len);
4.45.1 – 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.
4.45.2 – Condition Values Returned
SS$_NORMAL Successful completion.
SS$_BUFFEROVF Buffer too small, string truncated.
SS$_NOTRAN No symbolization for this value (null string
returned).
4.46 – 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);
4.46.1 – 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.
4.46.2 – 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.
4.47 – SDA$TYPE
Formats and types a single line to SYS$OUTPUT.
Format
int sda$type (char *ctrstr, __optional_params);
4.47.1 – Arguments
ctrstr
OpenVMS usage char_string
type character-coded text string
access read only
mechanism by reference
Address of a zero-terminated FAO 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.
4.47.2 – 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$TYPE (the
error is also signaled). If the $FAOL_64 call
issued by SDA$TYPE fails, the control string
is output.
4.48 – SDA$VALIDATE_QUEUE
Validates queue structures.
Format
void sda$validate_queue (VOID_PQ queue_header,
__optional_params);
4.48.1 – Arguments
queue_header
OpenVMS usage address
type quadword (unsigned)
access read only
mechanism by value
Address from which to start search.
options
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by value
The following table shows the flags that indicate the type of
queue:
Flag Meaning
None Defaults to doubly-linked longword
queue
SDA_OPT$M_QUEUE_BACKLINK Validates the integrity of a doubly-
linked queue using the back links
instead of the forward links
SDA_OPT$M_QUEUE_LISTQUEUE Displays queue elements for debugging
SDA_OPT$M_QUEUE_QUADLINK Indicates a quadword queue
SDA_OPT$M_QUEUE_SELF Indicates a self-relative queue
SDA_OPT$M_QUEUE_SINGLINK Indicates a singly-linked queue
4.48.2 – Condition Values Returned
None
If an error occurs, it is signaled by SDA$VALIDATE_QUEUE.