1 Extension_Routines 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. 2 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 " and "FORMAT UCB" to obtain the address of the nonpaged pool structure. o Invoke the SDA command "EXAMINE
;" 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
" 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. 3 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. 3 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
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 #include 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; } 3 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
' SDA> mbx summary ... SDA> mbx
... %DEBUG-I-DYNMODSET, setting module MBX$SDA %SYSTEM-E-INVARG, invalid argument ... DBG> 2 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 , ,, 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. 2 Routines The following subtopics describe the SDA extension callable routines. 3 SDA$ADD_SYMBOL Adds a symbol to SDA's local symbol table. Format void sda$add_symbol (char *symbol_name, uint64 symbol_value); 4 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. 3 SDA$ALLOCATE Allocates dynamic memory. Format void sda$allocate (uint32 size, void **ptr_block); 4 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 Condition_Values_Returned None If no memory is available, the error is signaled and the SDA session aborted. 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 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 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. 3 SDA$CBB_CLEAR_BIT Clears the specified bit in a CBB. Format int sda$cbb_clear_bit (CBB_PQ cbb, int bit); 4 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 Condition_Values_Returned SS$NORMAL Successful completion SS$BADPARAM The bit number is out of range 3 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 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. 3 SDA$CBB_FFC Locates the first clear bit in a CBB. Format int sda$cbb_ffc (CBB_PQ cbb, int start_bit); 4 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 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. 3 SDA$CBB_FFS Locates the first set bit in a CBB. Format int sda$cbb_ffs (CBB_PQ cbb, int start_bit); 4 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 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. 3 SDA$CBB_INIT Initializes a CBB structure to a known state. Format void sda$cbb_init (CBB_PQ cbb); 4 Argument cbb OpenVMS usage address type CBB structure access read only mechanism by reference The address of the CBB structure to be initialized. 3 SDA$CBB_SET_BIT Sets the specified bit in a CBB. Format int sda$cbb_set_bit (CBB_PQ cbb,int bit); 4 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 Condition_Values_Returned SS$NORMAL Successful completion. SS$BADPARAM The bit number is out of range. 3 SDA$CBB_TEST_BIT Tests the specified bit in a CBB. Format int sda$cbb_test_bit (CBB_PQ cbb,int bit); 4 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 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. 3 SDA$DEALLOCATE Deallocates and frees dynamic memory. Format void sda$deallocate (void *ptr_block, uint32 size); 4 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 Condition_Values_Returned None If an error occurs, it is signaled and the SDA session aborted. 3 SDA$DELETE_PREFIX Deletes all symbols with the specified prefix. Format void sda$delete_prefix (char *prefix); 4 Argument prefix OpenVMS usage char_string type character string access read only mechanism by reference The address of the prefix string. 3 SDA$DISPLAY_HELP Displays online help. Format void sda$display_help (char *library_desc, char *topic_desc); 4 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. 3 SDA$ENSURE Ensures sufficient space on the current output page. Format void sda$ensure (uint32 lines); 4 Argument lines OpenVMS usage longword_unsigned type longword (unsigned) access read only mechanism by value Number of lines to fit on a page. 3 SDA$FAO Formats data into a buffer. Format char * sda$fao (char * ctrstr, char * buffer, int buflen, __optional_params); 4 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 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. 3 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 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 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 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. 3 SDA$FORMAT Displays the formatted contents of a data structure. Format void sda$format (VOID_PQ struct_addr, __optional_params); 4 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). 3 SDA$FORMAT_HEADING Formats a new page heading. Format void sda$format_heading (char *ctrstr, __optional_params); 4 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 Condition_Values_Returned None If the $FAOL_64 call issued by SDA$FORMAT_HEADING fails, the control string is used as the page heading. 3 SDA$GET_ADDRESS Gets the address value of the current memory location. Format void sda$get_address (VOID_PQ *address); 4 Argument address OpenVMS usage quadword_unsigned type quadword (unsigned) access write only mechanism by reference Location to store the current 64-bit memory address. 3 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 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. 3 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 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. 3 SDA$GET_CURRENT_CPU Gets the CPU database address of the currently selected CPU. Format void sda$get_current_cpu (CPU **cpudb); 4 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. 3 SDA$GET_CURRENT_PCB Gets the PCB address of the "SDA current process" currently selected. Format void sda$get_current_pcb (PCB **pcbadr); 4 Argument pcbadr OpenVMS usage quadword_unsigned type quadword (unsigned) access write only mechanism by reference Location in which to store the current PCB address. 3 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 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 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 3 SDA$GET_FLAGS Obtain environment flags that indicate how SDA is being used. Format int sda$get_flags (SDA_FLAGS *flagaddr); 4 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 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. 3 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 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. 3 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 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. 3 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 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 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 3 SDA$GET_INPUT Reads input commands. Format int sda$get_input (char *prompt, char *buffer, uint32 buflen); 4 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 Condition_Values_Returned SS$_NORMAL Successful completion. RMS$_EOF User pressed 3 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 Argument line_count OpenVMS usage longword_unsigned type longword (unsigned) access write only mechanism by reference The number of lines printed on current page. 3 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 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: is a virtual address. This is the default. 1: is a physical address. 4 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. 3 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 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 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 3 SDA$NEW_PAGE Begins a new page of output. Format void sda$new_page (); 3 SDA$PARSE_COMMAND Parses and executes an SDA command line. Format void sda$parse_command (char *cmd_line, __optional_params); 4 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. 3 SDA$PRINT Formats and prints a single line. Format int sda$print (char *ctrstr, __optional_params); 4 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 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. 3 SDA$READ_SYMFILE Reads symbols from a given file. Format int sda$read_symfile (char *filespec, uint32 options, __optional_params); 4 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 SDA_OPT$M_READ_IMAGE read/image SDA_OPT$M_READ_SYMVA read/symva SDA_OPT$M_READ_RELO read/relo SDA_OPT$M_READ_EXEC read/exec [] SDA_OPT$M_READ_NOLOG /nolog, suppress count of symbols read SDA_OPT$M_READ_ or 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 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. 3 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 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: is a virtual address. This is the default. 1: is a physical address. 4 Condition_Values_Returned SDA$_SUCCESS Successful completion. Any failure is signaled as an error and the current command aborts. 3 SDA$SET_ADDRESS Stores a new address value as the current memory address ("."). Format void sda$set_address (VOID_PQ address); 4 Argument address OpenVMS usage quadword_unsigned type quadword (unsigned) access read only mechanism by value Address value to store in current memory location. 3 SDA$SET_CPU Sets a new SDA CPU context. Format int sda$set_cpu (int cpu_id); 4 Arguments cpu_id OpenVMS usage longword_unsigned type longword (unsigned) access read only mechanism by value The desired CPU ID. 4 Condition_Values_Returned SDA$_SUCCESS Successful completion. Any failure is signaled as an error and the current command aborts. 3 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 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. 3 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 Argument line_count OpenVMS usage longword_unsigned type longword (unsigned) access read only mechanism by value The number of lines printed on current page. 3 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 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 Condition_Values_Returned SDA$_SUCCESS Successful completion. Any failure is signaled as an error and the current command aborts. 3 SDA$SKIP_LINES This routine outputs a specified number of blank lines. Format void sda$skip_lines (uint32 lines); 4 Argument lines OpenVMS usage longword_unsigned type longword (unsigned) access read only mechanism by value Number of lines to skip. 3 SDA$SYMBOL_VALUE Obtains the 64-bit value of a specified symbol. Format int sda$symbol_value (char *symb_name, uint64 *symb_value); 4 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 Condition_Values_Returned SDA$_SUCCESS Symbol found. SDA$_BADSYM Symbol not found. 3 SDA$SYMBOLIZE Converts a value to a symbol name and offset. Format int sda$symbolize (uint64 value, char *symbol_buf, uint32 symbol_len); 4 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 Condition_Values_Returned SS$_NORMAL Successful completion. SS$_BUFFEROVF Buffer too small, string truncated. SS$_NOTRAN No symbolization for this value (null string returned). 3 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 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: is a virtual address. This is the default. 1: is a physical address. 4 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. 3 SDA$TYPE Formats and types a single line to SYS$OUTPUT. Format int sda$type (char *ctrstr, __optional_params); 4 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 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. 3 SDA$VALIDATE_QUEUE Validates queue structures. Format void sda$validate_queue (VOID_PQ queue_header, __optional_params); 4 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 Condition_Values_Returned None If an error occurs, it is signaled by SDA$VALIDATE_QUEUE.