May 1996
& Revision Information: This is a new manual.
! OpenVMS Version: VMS V5.5 or higher
Manual Version: V1.0-03
E This manual explains how to write SDA extensions. It is intended for E the system programmer who want to add new commands to SDA and extend D its capabilities to format and display the contents of various data structures.
3 This manual is divided into the following sections:
o Chapter 1 contains a short introduction to SDA extensions. It 2 explains the purpose and how they are implemented.
t Chapter 2 explains in detail how extensions are activated. It also H gives you some hints how to code the extension's initialization routine.
n Chapter 3 explains in detail the SDA environment wherein the @ extension runs and gives a first introduction to SDA's callback routines.
l Appendix A shows how to link and debug your extension.
u Finally, Appendix B contains a detailed description of all SDA extension callbacks.
H It is assumed that the reader is familiar with the SDA utility and with D the VMS programming concepts. The following OpenVMS manuals contain 2 information about these topics and may be helpful:
H This manual was written and inspected carefully. You may find, however, G some errors or have comments and suggestions. Please feel free to mail D to the author, any input is very appreciated. The E-mail address is:
Ing. Ferry Bolhár-Nordenkampf
E-mail: bol@adv.magwien.gv.at.
9 And now: enjoy and good luck when writing your extension!
Note
2 Addendum to this manual, release date 20-AUG-1997:@ As indicated in the OpenVMS V7.2 pre-release notes, writing SDA F extensions becomes a supported task under OpenVMS Alpha V7.2 (it will @ still remain unsupported on OpenVMS VAX). The names of callback G routines may change and their behaviour may change as well, to confirm H the OpenVMS calling standard and to make the routines callable from any high-level language.
F If you plan to write SDA extensions for OpenVMS Alpha V7.2 or higher, G you should read carefully the OpenVMS Alpha V7.2 Release Notes as well E as the System Dump Analyzer (Alpha) Utility manual, version D 7.2. However, if you write your extension for earlier OpenVMS Alpha H versions, as well for OpenVMS VAX, this manual contains all information you need.
u A description of already known changes is given in Appendix C.
@ Starting with VAX/VMS V5.5, SDA (System Dump Analyzer) H supports extensions to provide additional, product-specific or A customer-specific commands and to increase SDA's capabilities to H interpret and display various data structures. This manual explains how 7 to write your own SDA extension tailored to your needs.
D When analyzing a dump file or the running system, you need intimate G knowledge of data structures that are not known to SDA. For example, a E user-written ACP (ancilliary control process) may allocate non-paged C pool and record some data or place I/O buffers therein. Without an D extension, the only way to examine this data is to create a hexdump B with the EXAMINE command and manually decode the contents of the dump.
E With a SDA extension, you can make the format of the data structures H and buffers known to SDA and provide a way to display their contents in - an interpreted, much more understandable way.
: DEC's TCP/IP Services for OpenVMS, also known as @ UCX, is an example for a layered product which E provides its own SDA extension to display information about its data structures ¹.
6 Another example (which exists on Alpha only) might be C CLUE(Crash Log Utility Extractor), which H allows you to maintain system dump history logs and provides additional C commands to display more detailed information about OpenVMS system cells and data structures ².
E SDA invokes an extension when the extension's name is entered at the F SDA> prompt. Once activated, SDA performs a small version check to H ensure that the command and data passing mechanism is still the one the > extension expects. SDA then passes control to the extension's F initialization (or main) routine. The way SDA invokes an extension is R described in detail in Chapter 2.
H Once the extension receives control, it may do some initialization work @ and then execute the given user commands. These commands may be E supplied either with the extension name at the SDA> prompt or the D extension is activated without additional commands in which case it G should prompt for them. If the extension was activated with a command, E it should execute the command and return control back to SDA. In the C latter case, it should prompt for commands and execute them, until F EXIT was entered or [CTRL] [Z] C was typed. This is the usual behaviour of most VMS utilities which provide their own subcommands.
F The extension should also provide online help, either with a built-in H text, or better, by an external help library whose topics may be called with HELP.
w Chapter 2 gives some hints how to build an extension 'skeleton' which t provides the above functions and commands. Chapter 2 contains code examples as well.
F While activated, the extension operates in SDA's environment A and may call SDA's extension callback routines, shorter ? callbacks. SDA provides over 20 callbacks for various G purposes: examining memory, validating queues, executing SDA commands, F displaying data in various formats, and much more. Whenever possible, G you should use these callbacks instead of native commands or functions G provided by your language. This ensures that your extension behaves in H an usual manner. For example, in C, you could use the printf() E function to display data on the screen. If, however, the user enters H SDA's SET OUTPUT command, SDA writes further text into E the given output file whereas your extension still would continue to H send its data to the screen. For this reason, SDA provides callbacks to F display data. By using these callbacks, your extension sends its data always to the expected location.
G Another reason for using callbacks is SDA's environment which E may change from time to time. Let's assume that you want to access a H cell in the process-control (P1) space. Most languages provide a way to D declare the name of VMS cells as global symbols whose addresses are A substituted by the linker when linked against SYS$SYSTEM:SYS.STB H ³. In the program, the cell may be further accessed like any other variable.
G The P1 space, however, is process-specific. Every process contains its G own, separate P1 space. There is no (easy) way for a program to access - the P1 (and P0) space of a different process.
H SDA provides the SET PROCESS command for this purpose. G This will change SDA's process context; the specified process : becomes the current process. By convention, when H process-specific data is addressed, it's always the data of the current H process. For this reason, SDA provides routines, which, when a P0 or P1 D address is given, obtain the data from the current process' address F space. In addition, these routines allow you to access data from user G mode which would be accessible otherwise from executive or kernel mode B only. Finally, the routines contain their own condition handlers, > preventing the system to crash when you specify an invalid or non-existent address.
g The SDA environment is described further in Chapter 3.
@ SDA extensions may be written in any high-level language (HLL). E However, not all callbacks confirm the OpenVMS calling standard. For H example, some routines return results in processor registers or must be H called as subroutines, not as procedures. Unless your language provides B a way to access processor register directly and call subroutines, H jacket routines, mostly written in MACRO-32, must be provided. H The purpose of a jacket routine is simple: it calls the appropriate SDA C callback in the required fashion and places the returned data in a G location where it can be accessed by the HLL. From the HLL, you invoke 9 the jacket routine instead of the corresponding callback.
y Appendix A explains how to link and debug SDA extensions. Examples H for jackets are provided in the description of the appropriate callback.
u Finally, Appendix B contains a detailed description of all SDA H extension callbacks as well tables giving an overview about them, their & purpose and their calling conventions.
F This chapter explains how extensions are activated and how SDA passes control to them. C 2.1 SDA Extension Implementation
F SDA extensions are implemented as shareable images, either located in E the directory SYS$SHARE or found by translating a logical name. When H the extension's name is entered at the SDA> prompt, SDA uses the RTL = routine LIB$FIND_IMAGE_SYMBOL to load the extension. See the ? description in the RTL Library (LIB$) manual for more ? information about this routine and the VMS run-time image load mechanism.
D By convention, SDA extensions are named name $SDA, E where name is the extension's name. For example, in case of F UCX, the extension would be named UCX$SDA. You may define this string F as a logical name pointing to the actual shareable image, or (in this 4 example) the image SYS$SHARE:UCX$SDA.EXE must exist.
B SDA tries to activate an extension whenever an unknown command is H entered at the SDA> prompt. If the activation fails for some reason, SDA displays this message:
- %CLI-W-SYNTAX, error parsing 'name'
C When you enter a command, SDA first looks in its table of built-in @ commands. If the command (or a valid abbreviation) can be found E therein, it is executed, instead of activating an extension with the F same name. For example, if you call your extension EXAM$SDA and enter ? EXAM, SDA assumes that an abbreviation of its G EXAMINEcommand was entered, not an extension name. In G this case, you must force SDA to interpret the given name as extension ; by specifying the undocumented DO command:
SDA> DO EXAM
D With DO, when the activation fails, SDA displays a different message:
7 %SDA-E-SUPPNOTINS, name support not installed
4 where name is the specified extension name.
Note
G The above message may be confusing. SDA displays this message whenever H it fails to activate the specified extension. This does not necessarily F mean that the extension is not installed; the activation may fail for C other reasons as well (e.g., ident mismatches with other shareable images).B To find out what causes the activation to fail, try to invoke the F extension with the DCL command RUN. In most cases, you will receive a H %IMGACT-F-... message. This is an error message created by the F image activator and is also passed to LIB$FIND_IMAGE_SYMBOL as return H status. In most cases, this message can help you to isolate the problem.
F Also keep in mind that the activation fails when compilation warnings > were detected by the linker in one or more extension modules.
q As described in Section 2.1, extensions are activated by calling the H RTL routine LIB$FIND_IMAGE_SYMBOL. In addition to the shareable image's B name, this routine requires a symbol name to load the image. This C symbol must be included in the shareable image's symbol table when z linking the extension (Appendix A describes how to compile and link ; your extension and how to build a symbol table). SDA calls < LIB$FIND_IMAGE_SYMBOL twice with the following symbol names:
F If these symbols are not found in the shareable image's symbol table, A the activation fails with one of the error messages described in 8 Section 2.1.
ˇ Section 2.2.1 and Section 2.2.2 describe the purpose and contents of these symbols in detail. M 2.2.1 Activation interface version check
@ SDA $EXTEND _VERSION contains the address of a A longword which holds the extension's activation version. This is B not the version of the extension; it just determines the G version of the activation interface. It consists of two parts, a major G and minor version number. Before passing control to the extension, SDA @ compares its own interface version with the one supplied by the @ extension to ensure that the interfaces are compatible. Further activation occurs only if:
F For example, if the SDA version number would be V1.2, the extension's F number may be one of V1.2, V1.3, V1.4 ... V1.9, but not V1.0, V1.1 or V2.0.
Note
G The version number of the SDA extension interface is still V1.0 in all E current VMS releases. It is recommended that your extension uses the D same version number. In the case of an activation interface change, G this will prevent your extension from being activated in an unexpected " manner.
? The following example shows how to set the version number in C:
+ const int SDA$EXTEND_VERSION = 0x00000001;
w See Appendix A how to include the variable name in the shareable G image's symbol table. Note that the variable must be defined in global & scope (in C, outside of any function). M 2.2.2 Calling the initialization routine
E SDA $EXTEND contains the address of the extension's G initialization routine. Once the version check is performed, SDA calls F the extension at this address. The following two arguments are passed to this routine:
1 These arguments are now described more in detail.
H Note that SDA does not expect a return value from the extension; if the & extension supplies one, it is ignored. ? 2.2.2.1 Callback pointer
D The first argument passed to the initialization routine is the base E address of an array containing pointers to all callback routines. In @ order to understand the use of this argument, you should become ' familiar with SDA's callback mechanism.
B Callbacks are internal SDA routines, located at various places in ; SYS$SYSTEM:SDA.EXE, the system dump analyzer (invoked with ( ANALYZE/CRASH _DUMP or F ANALYZE/SYSTEM). Since these addresses may vary from G VMS to VMS version, an array consisting of longword pointers is built. E Every longword points to a callback routine in SDA.EXE. Although the D base address of this array, which is located itself in SDA.EXE, may H change in new VMS versions, the position of a particular routine within B the array never changes; new routines are added at the end of the F array. In other words, the purpose of this array is very similar to a H transfer vector in a shareable image. Note, however, that SDA.EXE is an < executable image which can't be used as input to the linker.
0 The interface to SDA.EXE is the shareable image D SYS$SHARE:SDA_EXTEND_VECTOR.EXE ¹ which your extension must be G linked against. This image contains jacket routines for every D callback in SDA.EXE. When you call one of these jacket routines, it D first adds the array offset of the corresponding SDA routine to the E array's base address. The resultant value is the absolute address of C the longword which points to the callback routine in SDA.EXE. This routine is then invoked.
G All jacket routines expect the array's base address in global location F SDA $EXTEND _VECTOR _TABLE _ADDR. This is a writable 5 longword in SYS$SHARE:SDA_EXTEND_VECTOR.EXE (VAX) or C SYS$SHARE:SDA_EXTEND_VECTOR.OBJ (Alpha). Before invoking the first C callback, you must fill this location with the array base address, D which is passed as first argument to your extension. An example for this could be:
, int globalref SDA$EXTEND_VECTOR_TABLE_ADDR; > void sda$extend(int array_addr, struct dsc$descriptor_s *cmd) { , SDA$EXTEND_VECTOR_TABLE_ADDR = array_addr; . . . } B From this point, you can use all callbacks. They are described in A Appendix B. > 2.2.2.2 Command pointer
H The second argument passed to the initialization routine is the address F of a fixed-length string descriptor pointing to the specified command G string, if any was given. If no command was given, the length field of the descriptor contains 0.
H Note that the extension name (and a preceeding DO) were already removed from the string. For example, if
SDA> MYEXT SHOW ALL
B was entered, the string passed in this argument would be SHOW ALL.
p As described in Chapter 1, the usual behaviour of an extension ) providing its own commands is as follows:
G It is up to the extension to parse the supplied command string. A good E and easy way to do this are the CLI$ routines in conjunction with an E object module containing binary language definitions. This module is H written in CDL (Command Definition Language) and compiled with n CDU (Command Definition Utility). See Section 2.3 for an example.
, This chapter contains some code examples of:
G All relevant coding techniques in the following examples are described E in the previous chapters. In the following examples, the extension's name becomes MYEXT. A 2.3.1 Initialization routine
: The following code fragment, written in C, may be used as s initialization routine. It behaves as described in Section 2.2.2.2.
K #include <cli$routines.h> /* CLI$xxx routine definitions */ F #include <descrip.h> /* Descriptor definitions */ K #include <rmsdef.h> /* RMS$_xxx status definitions */ B #include <string.h> /* strxxx() functions */ J #include <ssdef.h> /* SS$_xxx status definitions */ % typedef struct dsc$descriptor_s dsc; /* SDA callback definitions. */ > void SDA$EXTEND_PRINT(), /* Print a line of text */ 9 SDA$EXTEND_NEW_PAGE(), /* Insert new page */ > SDA$EXTEND_SKIP_LINES(), /* Insert blank line(s) */ B SDA$EXTEND_GET_INPUT(); /* Get a line from the user */ L int globalref SDA$EXTEND_VECTOR_TABLE_ADDR; /* Callback array base addr. */ C const int SDA$EXTEND_VERSION = 0x00000001; /* Activation vers. */ c int globalvalue MYEXT$CDL; /* CDL Module */ (1) i int G_exit_flg; /* Global exit flag */ (2) > dsc* desc(); /* Descriptor function */ < /* ======== Initialization routine starts here. ======== */ * void sda$extend(int array_addr, dsc *cmd) { ; int status; /* CLI return status */ 7 $DESCRIPTOR(prp,"MYEXT$SDA>" ); /* Our prompt */ ; /* First, store array base address in shareable image. */ , SDA$EXTEND_VECTOR_TABLE_ADDR = array_addr; o if (cmd->dsc$w_length) /* If command was given */ (3) { g status = cli$dcl_parse(cmd,MYEXT$CDL); /* Parse it */ (4) 0 /* If parsing was OK, execute the command. */ 6 if (status == CLI$_NORMAL) status = cli$dispatch(); < return; /* Return back to SDA *. } 3 else /* Otherwise */ { g SDA$EXTEND_NEW_PAGE(); /* Insert new page */ (5) ! /* Display welcome message. */ F SDA$EXTEND_PRINT(desc("Welcome to MYEXT, my nice SDA extension!")); : SDA$EXTEND_SKIP_LINES(2); /* Insert two lines */ D /* Prompt for command - use SDA callback instead of LIB$GET_INPUT to read the command. */ i status = cli$dcl_parse(0,MYEXT$CDL,SDA$EXTEND_GET_INPUT, (6) 9 SDA$EXTEND_GET_INPUT,&prp); o while (status != RMS$_EOF) /* Loop until EOF (CTRL-Z) */ (7) { N if (status == CLI$_NORMAL) status = cli$dispatch(); /* Execute command */ j if (G_exit_flg) return; /* If EXIT, terminate */ (8) M status = cli$dcl_parse(0,MYEXT$CDL,SDA$EXTEND_GET_INPUT, /* Prompt for */ S SDA$EXTEND_GET_INPUT,&prp); /* next command */ } 7 return; /* Return to SDA */ } }
Notes to this example:
2 The code for the desc() function follows:
dsc *desc(char *str) { static $DESCRIPTOR(x,""); x.dsc$w_length = strlen(str); x.dsc$a_pointer= str; return &x; } B Since the descriptor must survive the function's exit, it must be declared as 'static' (in C). 7 2.3.2 EXIT command
H If the extension was invoked without a command, it must prompt for them F until the EXIT command is entered. As you can see in r the code example in Section 2.3.1, this is indicated by setting the H global variable G_exit_flag to 1. So the only thing we must do here is setting this variable:
void myext_exit() { G_exit_flg = 1; } G If your favorite language does not support global variables, you could A indicate the execution of the EXIT command by a E special return status. In the main command loop, you could check the G status returned by CLI$DISPATCH and terminate the loop if this special status is encountered. 7 2.3.3 HELP command
B Every program which supports more than one command should provide H online-help. Although you can give this help by a built-in text, a more C friendly and VMS-conform way is to provide a HELP C command and a help text library. By entering HELP D without a topic, the user receives a general help text, including a H list of all topics for which help is available. He may further select a * topic to obtain more information about it.
= You can create help text files with any text editor. You use E LIBRARY/HELP/CREATE to create your help library and E LIBRARY/HELP/INSERT to insert help topics into your ? library. See the Command Definition, Librarian and Message + Utilities manual for more information.
F This is the code fragment of the HELP command in the command definition file:
$ define verb HELP routine MYEXT_HELP 8 parameter P1, prompt="Topic", value(type=$rest_of_line)
And here comes the help routine:
#include <descrip.h> int cli$get_value(); void SDA$EXTEND_DISPLAY_HELP(); void myext_help() { char dcl_buf[120]; short len; $DESCRIPTOR(dcl,dcl_buf); $DESCRIPTOR(dcl_p1,"P1"); $DESCRIPTOR(lib,"MYEXT_HELP"); C cli$get_value(&dcl_p1,&dcl,&len); /* Get topic */ ; dcl.dsc$w_length = len; /* Update length */ B SDA$EXTEND_DISPLAY_HELP(&lib,&hlp); /* Display help */ } G In this example, the name of the help library is MYEXT_HELP. This must F be either a logical name pointing to the help library, or the library * is expected to be SYS$HELP:MYEXY_HELP.HLB.
D As you can see, SDA even provides a callback to display online-help < which you should use instead of the appropriate VMS routine LBR$OUTPUT_HELP.
= Once activated, the extension runs under control of SDA. SDA C establishes a default environment from which it interprets certain F commands. Your extension should behave exactly in the same manner, so E it's important to understand in which environment you're running and how commands may be interpreted.
, SDA's environment consists of the following: