                           7                      Municipality of the City of Vienna 4                        Ing. Ferry Bolhr-Nordenkampf                              Writing SDA Extensions      ;           This manual explains how to write SDA extensions.                      May 1996  =           Revision Information:         This is a new manual.   :           OpenVMS Version:              VMS V5.5 or higher  /           Manual Version:               V1.0-03                        A           _______________________________________________________              Contents  A                 _________________________________________________ A                 PREFACE                                         v   A           _______________________________________________________ A           CHAPTER 1  INTRODUCTION TO SDA EXTENSIONS           1-1     A           _______________________________________________________ -           CHAPTER 2  EXTENSION ACTIVATION AND A                      INITIALIZATION                           2-1   A                 _________________________________________________ A                 2.1   SDA EXTENSION IMPLEMENTATION            2-1   A                 _________________________________________________ A                 2.2   EXTENSION ACTIVATION                    2-2   6                 2.2.1     Activation interface versionA                           check  _________________________    2-3   4                 2.2.2     Calling the initializationA                           routine  _______________________    2-4 1                 2.2.2.1     Callback pointer, 2-4 0                 2.2.2.2     Command pointer, 2-6  A                 _________________________________________________ A                 2.3   EXTENSION CODE EXAMPLES                 2-7   A                 2.3.1     Initialization routine  ________    2-7   A                 2.3.2     EXIT command  __________________   2-10   A                 2.3.3     HELP command  __________________   2-11           A                                                               iii                     Contents          A           _______________________________________________________ A           CHAPTER 3  RUNNING IN SDA'S ENVIRONMENT             3-1   A                 _________________________________________________ A                 3.1   ANALYSIS MODE                           3-1   A                 _________________________________________________ A                 3.2   OUTPUT MODE                             3-3   A                 _________________________________________________ A                 3.3   PROCESS AND CPU CONTEXT                 3-4   A                 _________________________________________________ A                 3.4   CURRENT ADDRESS                         3-6   A                 _________________________________________________ A                 3.5   CONDITION HANDLING AND INTERRUPTS      3-10   A                 _________________________________________________ A                 3.6   OVERRIDE MODE                          3-13   A                 _________________________________________________ A                 3.7   CALLBACK ROUTINES                      3-14     A           _______________________________________________________ 0           APPENDIX A  LINKING AND DEBUGGING YOURA                       EXTENSION                               A-1   A                 _________________________________________________ A                 A.1   LINKING ON VAX                          A-1   A                 _________________________________________________ A                 A.2   LINKING ON ALPHA                        A-4   A                 _________________________________________________ A                 A.3   DEBUGGING YOUR EXTENSION                A-6                  iv         A                                                          Contents           A           _______________________________________________________ A           APPENDIX B  SDA CALLBACK DESCRIPTION                B-1 :                 SDA$EXTEND_ADD_SYMBOL                  B-3:                 SDA$EXTEND_ALLOCATE                    B-6:                 SDA$EXTEND_DEALLOCATE                  B-9:                 SDA$EXTEND_DISPLAY_HELP               B-11:                 SDA$EXTEND_ENSURE                     B-13:                 SDA$EXTEND_FORMAT                     B-15:                 SDA$EXTEND_FORMAT_SUBHEADING          B-22:                 SDA$EXTEND_GETMEM                     B-25:                 SDA$EXTEND_GET_ADDRESS                B-30:                 SDA$EXTEND_GET_BUGCHECK_MSG           B-32:                 SDA$EXTEND_GET_CURRENT_PCB            B-35:                 SDA$EXTEND_GET_DYN_INFO               B-37:                 SDA$EXTEND_GET_HEADER                 B-40:                 SDA$EXTEND_GET_HW_NAME                B-43:                 SDA$EXTEND_GET_IMAGE_OFF              B-45:                 SDA$EXTEND_GET_INPUT                  B-52:                 SDA$EXTEND_GET_LINE_COUNT             B-55:                 SDA$EXTEND_HANDLER                    B-57:                 SDA$EXTEND_LIB$INS_DECODE             B-60:                 SDA$EXTEND_NEW_PAGE                   B-67:                 SDA$EXTEND_ON_CURRENT_SYSTEM          B-69:                 SDA$EXTEND_PARSECOMMAND               B-71:                 SDA$EXTEND_PRINT                      B-75:                 SDA$EXTEND_PRINT_COLUMNS              B-79:                 SDA$EXTEND_PRINT_COLUMN_VALUE         B-97:                 SDA$EXTEND_READ_SYMFILE              B-103:                 SDA$EXTEND_REQMEM                    B-119:                 SDA$EXTEND_SET_ADDRESS               B-124:                 SDA$EXTEND_SET_HEADING               B-127:                 SDA$EXTEND_SET_HEADING_ROUTINE       B-129:                 SDA$EXTEND_SET_LINE_COUNT            B-132:                 SDA$EXTEND_SKIP_LINES                B-134:                 SDA$EXTEND_SYMBOLIZE                 B-136:                 SDA$EXTEND_SYMBOL_VALUE              B-141:                 SDA$EXTEND_TRANSLATE_ADDRESS         B-143:                 SDA$EXTEND_TRANSLATE_BITS            B-146:                 SDA$EXTEND_TRYMEM                    B-152:                 SDA$EXTEND_TYPE                      B-162  A                                                                 v                     Contents          :                 SDA$EXTEND_VALIDATE_QUEUE            B-166    A           _______________________________________________________ A           APPENDIX C  OPENVMS V7.2 ALPHA ADDENDUM             C-1     A           _______________________________________________________            TABLES  A                 3-1       SDA Callbacks  _________________   3-15   A                 3-2       SDA Callbacks - Purpose  _______   3-18   4                 B-1       SDA$EXTEND_FORMAT signaledA                           conditions  ____________________   B-19   A                 B-2       FAO directive codes  ___________   B-84   A                 B-3       SDA message status codes  ______  B-172                                                    vi                   A           _______________________________________________________              Preface   ;           This manual explains how to write SDA extensions. >           It is intended for the system programmer who want to=           add new commands to SDA and extend its capabilities <           to format and display the contents of various data           structures.   =           This manual is divided into the following sections:   8           Chapter 1 contains a short introduction to SDA>           extensions. It explains the purpose and how they are           implemented.  9           Chapter 2 explains in detail how extensions are =           activated. It also gives you some hints how to code 1           the extension's initialization routine.   :           Chapter 3 explains in detail the SDA environment6           wherein the extension runs and gives a first2           introduction to SDA's callback routines.  @           Appendix A shows how to link and debug your extension.  @           Finally, Appendix B contains a detailed description of&           all SDA extension callbacks.  <           It is assumed that the reader is familiar with the@           SDA utility and with the VMS programming concepts. The=           following OpenVMS manuals contain information about *           these topics and may be helpful:  !           o  Programming Concepts   @           o  Command Definition, Librarian and Message Utilities  6           o  Macro (VAX) Instruction Set and Reference             o  Linker Utility   5           o  System Dump Analyzer (VAX/Alpha) Utility   :           o  Documentation about your favorite programming              language   A                                                                 v                     Preface           >           This manual was written and inspected carefully. You=           may find, however, some errors or have comments and >           suggestions. Please feel free to mail to the author,?           any input is very appreciated. The E-mail address is:   '           Ing. Ferry Bolhr-Nordenkampf (           E-mail: bol@adv.magwien.gv.at.  8           And now: enjoy and good luck when writing your           extension!  5           Note: Addendum to this manual, release date            20-AUG-1997:  >            As indicated in the OpenVMS V7.2 pre-release notes,?           writing SDA extensions becomes a supported task under >           OpenVMS Alpha V7.2 (it will still remain unsupported=           on OpenVMS VAX). The names of callback routines may ;           change and their behaviour may change as well, to >           confirm the OpenVMS calling standard and to make the9           routines callable from any high-level language.   @            If you plan to write SDA extensions for OpenVMS Alpha?           V7.2 or higher, you should read carefully the OpenVMS =           Alpha V7.2 Release Notes as well as the System Dump @           Analyzer (Alpha) Utility manual, version 7.2. However,9           if you write your extension for earlier OpenVMS >           Alpha versions, as well for OpenVMS VAX, this manual,           contains all information you need.  =            A description of already known changes is given in            Appendix C.                            vi                     A           _______________________________________________________   (    1      Introduction to SDA extensions      @           Starting with VAX/VMS V5.5, SDA (System Dump Analyzer)=           supports extensions to provide additional, product- @           specific or customer-specific commands and to increase=           SDA's capabilities to interpret and display various <           data structures. This manual explains how to write8           your own SDA extension tailored to your needs.  ;           When analyzing a dump file or the running system, =           you need intimate knowledge of data structures that ;           are not known to SDA. For example, a user-written <           ACP (ancilliary control process) may allocate non->           paged pool and record some data or place I/O buffers@           therein. Without an extension, the only way to examine;           this data is to create a hexdump with the EXAMINE ?           command and manually decode the contents of the dump.   >           With a SDA extension, you can make the format of the@           data structures 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 provides@           its own SDA extension to display information about its           data structures [1].  ?           Another example (which exists on Alpha only) might be >           CLUE (Crash Log Utility Extractor), which allows you;           to maintain system dump history logs and provides 6           additional commands to display more detailed             ________________  $         [1] UCX V3.2 or higher only.  A                                                               1-1          (           Introduction to SDA extensions          9           information about OpenVMS system cells and data            structures [2].   <           SDA invokes an extension when the extension's name<           is entered at the SDA> prompt. Once activated, SDA;           performs a small version check to ensure that the =           command and data passing mechanism is still the one ?           the extension expects. SDA then passes control to the ?           extension's initialization (or main) routine. The way <           SDA invokes an extension is described in detail in           Chapter 2.  =           Once the extension receives control, it may do some =           initialization work and then execute the given user >           commands. These commands may be supplied either with@           the extension name at the SDA> prompt or the extension;           is activated without additional commands in which :           case it should prompt for them. If the extension=           was activated with a command, it should execute the ?           command and return control back to SDA. In the latter ?           case, it should prompt for commands and execute them, >           until EXIT was entered or <CTRL> <Z> was typed. This<           is the usual behaviour of most VMS utilities which(           provide their own subcommands.  ?           The extension should also provide online help, either >           with a built-in text, or better, by an external help7           library whose topics may be called with HELP.              ________________@         [2] On VAX, CLUE exists as well, however, it is provided=             as external utility, invoked with the DCL command ;             $ MCR CLUE.  Unlike Alpha, VAX CLUE provides no 9             additional displays and is used to create and =             maintain system dump logs and history files only. >           The author of this manual wrote a CLUE SDA extension6             for OpenVMS VAX; it provides the same (and=             additional) information as its Alpha counterpart. @             If you're interested in obtain a copy, please send a  *             mail to bol@adv.magwien.gv.at.  
           1-2          A                                    Introduction to SDA extensions           >           Chapter 2 gives some hints how to build an extension;           'skeleton' which provides the above functions and =           commands. Chapter 2 contains code examples as well.   :           While activated, the extension operates in SDA's;           environment and may call SDA's extension callback ;           routines, shorter callbacks. SDA provides over 20 ;           callbacks for various purposes: examining memory, ?           validating queues, executing SDA commands, displaying :           data in various formats, and much more. Whenever:           possible, you should use these callbacks instead:           of native commands or functions provided by your<           language. This ensures that your extension behaves>           in an usual manner. For example, in C, you could use?           the printf()  function to display data on the screen. @           If, however, the user enters SDA's SET OUTPUT command,<           SDA writes further text into the given output file=           whereas your extension still would continue to send ?           its data to the screen. For this reason, SDA provides >           callbacks to display data. By using these callbacks,>           your extension sends its data always to the expected           location.   5           Another reason for using callbacks is SDA's ?           environment which may change from time to time. Let's ?           assume that you want to access a cell in the process- =           control (P1) space. Most languages provide a way to ?           declare the name of VMS cells as global symbols whose =           addresses are substituted by the linker when linked =           against SYS$SYSTEM:SYS.STB [3]. In the program, the ?           cell may be further accessed like any other variable.   ;           The P1 space, however, is process-specific. Everyh?           process contains its own, separate P1 space. There is ?           no (easy) way for a program to access the P1 (and P0) '           space of a different process.5             ________________  ,         [3] or linked with /SYSEXE on Alpha.  A                                                               1-3_ _  _    (           Introduction to SDA extensions          @           SDA provides the SET PROCESS command for this purpose.?           This will change SDA's process context; the specified_=           process becomes the current process. By convention, >           when process-specific data is addressed, it's always;           the data of the current process. For this reason, 7           SDA provides routines, which, when a P0 or P1 <           address is given, obtain the data from the current=           process' address space. In addition, these routines =           allow you to access data from user mode which would :           be accessible otherwise from executive or kernel<           mode only. Finally, the routines contain their own<           condition handlers, preventing the system to crash>           when you specify an invalid or non-existent address.  @           The SDA environment is described further in Chapter 3.  9           SDA extensions may be written in any high-level_@           language (HLL). However, not all callbacks confirm the>           OpenVMS calling standard. For example, some routines:           return results in processor registers or must be?           called as subroutines, not as procedures. Unless your >           language provides a way to access processor register@           directly and call subroutines, jacket routines, mostly?           written in MACRO-32, must be provided. The purpose of_>           a jacket routine is simple: it calls the appropriate=           SDA callback in the required fashion and places the >           returned data in a location where it can be accessed9           by the HLL. From the HLL, you invoke the jacket 8           routine instead of the corresponding callback.  7           Appendix A explains how to link and debug SDAD>           extensions. Examples for jackets are provided in the2           description of the appropriate callback.  @           Finally, Appendix B contains a detailed description of>           all SDA extension callbacks as well tables giving an>           overview about them, their purpose and their calling           conventions.    
           1-4_ _  _                A           _______________________________________________________   1    2      Extension activation and initialization_      @           This chapter explains how extensions are activated and)           how SDA passes control to them._  L           __________________________________________________________________  &    2.1    SDA Extension Implementation  =           SDA extensions are implemented as shareable images, <           either located in the directory SYS$SHARE or found=           by translating a logical name. When 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.  ;           By convention, SDA extensions are named name$SDA,A=           where name is the extension's name. For example, in_@           case of UCX, the extension would be named UCX$SDA. You>           may define this string as a logical name pointing to>           the actual shareable image, or (in this example) the1           image SYS$SHARE:UCX$SDA.EXE must exist._  8           SDA tries to activate an extension whenever an?           unknown command is entered at the SDA> prompt. If theD=           activation fails for some reason, SDA displays thisX           message:  >                            %CLI-W-SYNTAX, error parsing 'name'  @           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 therein, it is executed, @           instead of activating an extension with the same name.>           For example, if you call your extension EXAM$SDA and=           enter EXAM, SDA assumes that an abbreviation of its @           EXAMINE command was entered, not an extension name. In  A                                                               2-1T N  F    1           Extension activation and initializationA          >           this case, you must force SDA to interpret the given=           name as extension by specifying the undocumented DO            command:  '                            SDA> DO EXAM-  <           With DO, when the activation fails, SDA displays a           different message:  H                            %SDA-E-SUPPNOTINS, name support not installed  5           where name is the specified extension name.   @           Note: The above message may be confusing. SDA displays8           this message whenever it fails to activate the=           specified extension. This does not necessarily mean =           that the extension is not installed; the activation99           may fail for other reasons as well (e.g., ident72           mismatches with other shareable images).  A            To find out what causes the activation to fail, try to @           invoke the extension with the DCL command RUN. In most?           cases, you will receive a %IMGACT-F-... message. This <           is an error message created by the image activator?           and is also passed to LIB$FIND_IMAGE_SYMBOL as return$=           status. In most cases, this message can help you toE           isolate the problem.  ;            Also keep in mind that the activation fails when =           compilation warnings were detected by the linker in (           one or more extension modules.  L           __________________________________________________________________      2.2    Extension activation  ?           As described in Section 2.1, extensions are activated >           by calling the RTL routine LIB$FIND_IMAGE_SYMBOL. In>           addition to the shareable image's name, this routine?           requires a symbol name to load the image. This symbol @           must be included in the shareable image's symbol table>           when linking the extension (Appendix A describes how?           to compile and link your extension and how to build al  
           2-2_ _       A                           Extension activation and initialization3          >           symbol table). SDA calls LIB$FIND_IMAGE_SYMBOL twice*           with the following symbol names:  ;           o  SDA$EXTEND_VERSION - this symbol must point to_;              a longword containing the activation interfacet              version;   @           o  SDA$EXTEND - this is the extension's initialization              routine._  9           If these symbols are not found in the shareable =           image's symbol table, the activation fails with one 9           of the error messages described in Section 2.1.a  >           Section 2.2.1 and Section 2.2.2 describe the purpose2           and contents of these symbols in detail.  %           ___________________________t  ,    2.2.1  Activation interface version check  ?           SDA$EXTEND_VERSION contains the address of a longwordt9           which holds the extension's activation version.p;           This is not the version of the extension; it justp=           determines the version of the activation interface.e=           It consists of two parts, a major and minor versione:           number. Before passing control to the extension,9           SDA compares its own interface version with thex:           one supplied by the extension to ensure that the>           interfaces are compatible. Further activation occurs           only if:  ,           o  the major numbers are the same;  =           o  the minor number of the extension is the same or.-              greater than SDA's minor number.f  ?           For example, if the SDA version number would be V1.2,g?           the extension's number may be one of V1.2, V1.3, V1.4m/           ... V1.9, but not V1.0, V1.1 or V2.0.e  A           Note: The version number of the SDA extension interfaceD:           is still V1.0 in all current VMS releases. It is?           recommended that your extension uses the same versiont  A                                                               2-3          1           Extension activation and initialization           @           number. In the case of an activation interface change,?           this will prevent your extension from being activatedh"           in an unexpected manner.  <           The following example shows how to set the version           number in C:  E                            const int SDA$EXTEND_VERSION = 0x00000001;u  @           See Appendix A how to include the variable name in the@           shareable image's symbol table. Note that the variable?           must be defined in global scope (in C, outside of any            function).  %           ___________________________a  ,    2.2.2  Calling the initialization routine  <           SDA$EXTEND contains the address of the extension's;           initialization routine. Once the version check is =           performed, SDA calls the extension at this address. 8           The following two arguments are passed to this           routine:  <           o  a pointer to the base address of SDA's callback)              routines (callback pointer);   @           o  a pointer to the command string specified to invoke-              the extension (command pointer).S  ;           These arguments are now described more in detail.   ;           Note that SDA does not expect a return value fromt=           the extension; if the extension supplies one, it is2           ignored.&                  _____________________*                  2.2.2.1  Callback pointer9           The first argument passed to the initializationr<           routine is the base address of an array containing8           pointers to all callback routines. In order to@           understand the use of this argument, you should become1           familiar with SDA's callback mechanism.   
           2-4t D  x    A                           Extension activation and initializationA          9           Callbacks are internal SDA routines, located att:           various places in SYS$SYSTEM:SDA.EXE, the system;           dump analyzer (invoked with ANALYZE/CRASH_DUMP ora>           ANALYZE/SYSTEM). Since these addresses may vary from=           VMS to VMS version, an array consisting of longwordd@           pointers is built. Every longword points to a callback?           routine in SDA.EXE. Although the base address of this ?           array, which is located itself in SDA.EXE, may change ;           in new VMS versions, the position of a particular >           routine within the array never changes; new routines@           are added at the end of the array. In other words, the=           purpose of this array is very similar to a 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.u  9           The interface to SDA.EXE is the shareable imagee8           SYS$SHARE:SDA_EXTEND_VECTOR.EXE [1] which your?           extension must be linked against. This image containss=           jacket routines for every callback in SDA.EXE. When >           you call one of these jacket routines, it first adds>           the array offset of the corresponding SDA routine to>           the array's base address. The resultant value is the>           absolute address of the longword which points to the;           callback routine in SDA.EXE. This routine is then            invoked.  @           All jacket routines expect the array's base address in?           global location SDA$EXTEND_VECTOR_TABLE_ADDR. This is @           a writable longword in SYS$SHARE:SDA_EXTEND_VECTOR.EXE;           (VAX) or SYS$SHARE:SDA_EXTEND_VECTOR.OBJ (Alpha).n@           Before invoking the first callback, you must fill this?           location with the array base address, which is passeds=           as first argument to your extension. An example forf           this could be:             ________________;         [1] On Alpha, there is no shareable image, instead, =             an object file SYS$SHARE:SDA_EXTEND_VECTOR.OBJ is   *             provided for the same purpose.  A                                                               2-5t         1           Extension activation and initializationc          F                            int globalref SDA$EXTEND_VECTOR_TABLE_ADDR;  X                            void sda$extend(int array_addr, struct dsc$descriptor_s *cmd)                            {F                             SDA$EXTEND_VECTOR_TABLE_ADDR = array_addr;                             .h                             .t                             .                             }  >           From this point, you can use all callbacks. They are"           described in Appendix B.&                  _____________________)                  2.2.2.2  Command pointer<:           The second argument passed to the initialization9           routine is the address of a fixed-length stringd>           descriptor pointing to the specified command string,?           if any was given. If no command was given, the length -           field of the descriptor contains 0.l  <           Note that the extension name (and a preceeding DO)?           were already removed from the string. For example, ift  .                            SDA> MYEXT SHOW ALL  ?           was entered, the string passed in this argument would            be SHOW ALL.  >           As described in Chapter 1, the usual behaviour of an=           extension providing its own commands is as follows:t  >           o  If a command was given, the extension executes it,              and passes control back to SDA;  ?           o  If no command was given, the extension prompts for @              commands. Prompting continues until EXIT is entered=              or <CTRL> <Z> is typed. In this case, control is                passed back to SDA.  9           It is up to the extension to parse the suppliedt<           command string. A good and easy way to do this are@           the CLI$ routines in conjunction with an object module=           containing binary language definitions. This moduleo=           is written in CDL (Command Definition Language) andn  
           2-6          A                           Extension activation and initialization           =           compiled with CDU (Command Definition Utility). Seee%           Section 2.3 for an example.   L           __________________________________________________________________  !    2.3    Extension code examples   6           This chapter contains some code examples of:  A           o  A 'skeleton' providing an initialization routine and ,              a command loop (Section 2.3.1);  =           o  An example for the EXIT command (Section 2.3.2);c  =           o  An example for the HELP command (Section 2.3.3).o  9           All relevant coding techniques in the followingu=           examples are described in the previous chapters. Ino>           the following examples, the extension's name becomes           MYEXT.  %           ___________________________s       2.3.1  Initialization routine  @           The following code fragment, written in C, may be used?           as initialization routine. It behaves as described inn           Section 2.2.2.2.  N           #include <cli$routines.h>          /* CLI$xxx routine definitions */I           #include <descrip.h>               /* Descriptor definitions */ N           #include <rmsdef.h>                /* RMS$_xxx status definitions */E           #include <string.h>                /* strxxx() functions */YM           #include <ssdef.h>                 /* SS$_xxx status definitions */l  .           typedef struct dsc$descriptor_s dsc;  )           /* SDA callback definitions. */   G           void SDA$EXTEND_PRINT(),           /* Print a line of text */aB                SDA$EXTEND_NEW_PAGE(),        /* Insert new page */G                SDA$EXTEND_SKIP_LINES(),      /* Insert blank line(s) */nK                SDA$EXTEND_GET_INPUT();       /* Get a line from the user */   U           int globalref SDA$EXTEND_VECTOR_TABLE_ADDR; /* Callback array base addr. */   A                                                               2-7  s  l    1           Extension activation and initialization           L           const int SDA$EXTEND_VERSION = 0x00000001;  /* Activation vers. */  @           int globalvalue MYEXT$CDL;          /* CDL Module */ 1  F           int G_exit_flg;                     /* Global exit flag */ 2  G           dsc* desc();                        /* Descriptor function */   E           /* ======== Initialization routine starts here. ======== */o  3           void sda$extend(int array_addr, dsc *cmd)            {iD            int status;                       /* CLI return status */  =            $DESCRIPTOR(prp,"MYEXT$SDA>" );   /* Our prompt */v  D            /* First, store array base address in shareable image. */  5            SDA$EXTEND_VECTOR_TABLE_ADDR = array_addr;s  I            if (cmd->dsc$w_length)            /* If command was given */ 3y            {D             status = cli$dcl_parse(cmd,MYEXT$CDL);  /* Parse it */ 4  9             /* If parsing was OK, execute the command. */   ?             if (status == CLI$_NORMAL) status = cli$dispatch();   E             return;                          /* Return back to SDA *.e            }<            else                              /* Otherwise */            {D             SDA$EXTEND_NEW_PAGE();           /* Insert new page */ 5  *             /* Display welcome message. */  O             SDA$EXTEND_PRINT(desc("Welcome to MYEXT, my nice SDA extension!"));a  C             SDA$EXTEND_SKIP_LINES(2);        /* Insert two lines */c  M             /* Prompt for command - use SDA callback instead of LIB$GET_INPUTt&                to read the command. */  F             status = cli$dcl_parse(0,MYEXT$CDL,SDA$EXTEND_GET_INPUT, 6>                                    SDA$EXTEND_GET_INPUT,&prp);  
           2-8e p  r    A                           Extension activation and initializationc          L             while (status != RMS$_EOF)       /* Loop until EOF (CTRL-Z) */ 7
             {eW              if (status == CLI$_NORMAL) status = cli$dispatch();  /* Execute command */   G              if (G_exit_flg) return;         /* If EXIT, terminate */ 8_  V              status = cli$dcl_parse(0,MYEXT$CDL,SDA$EXTEND_GET_INPUT, /* Prompt for */X                                     SDA$EXTEND_GET_INPUT,&prp);       /* next command */
             }_@             return;                          /* Return to SDA */            }           }n              Notes to this example:  <           1  The module MYEXT$CDL contains the definition of<              all known extension commands. It was written in=              CDL (Command Definition Language) and built with                SET COMMAND/OBJECT.  :           2  This global location initially contains 0. It=              is set to 1 by the extension's EXIT command (seea              Section 2.3.2).  ?           3  The length of the command given when the extensionaA              was activated is tested. If the length is not 0, thea>              extension was activated with one of its commands.  :           4  We parse the command using the CDL module and?              dispatch to it. After this, we return back to SDA.p  =           5  If no command was given, we must prompt for one.m=              First, let's clear the screen and display a nice >              welcome message. This is done with SDA callbacks.@              Given a null-terminated string, the function desc()?              returns a fixed-length descriptor pointing to this ;              string. This is required since most callbacks, :              when strings are supplied, expect pointers to              descriptors.   A                                                               2-9r a  n    1           Extension activation and initializationt          @           6  Prompt for a command and parse it. In the argumentsA              to CLI$DCL_PARSE, we use SDA callbacks as prompt ands@              read routines, instead of LIB$GET_INPUT. This givesA              access to SDA's command recall buffer and predefined               keys.  <           7  If <CTRL> <Z> was typed, we can leave the loop.?              Otherwise, we execute the command and prompt for aD              new one.n  >           8  This location is set to 1 by the EXIT command. If8              so, we must leave the command loop as well.  4           The code for the desc()  function follows:  /                            dsc *desc(char *str)                             {5                             static $DESCRIPTOR(x,"");   9                             x.dsc$w_length = strlen(str); 1                             x.dsc$a_pointer= str;   &                             return &x;                            }  @           Since the descriptor must survive the function's exit,1           it must be declared as 'static' (in C).a  %           ___________________________d      2.3.2  EXIT command  9           If the extension was invoked without a command, 8           it must prompt for them until the EXIT command;           is entered. As you can see in the code example ine@           Section 2.3.1, this is indicated by setting the global>           variable G_exit_flag to 1. So the only thing we must+           do here is setting this variable:r  ,                            void myext_exit()                            {+                             G_exit_flg = 1;i                            }             2-10 o  l    A                           Extension activation and initializationx          ;           If your favorite language does not support global_<           variables, you could indicate the execution of the>           EXIT command by a special return status. In the main>           command loop, you could check the status returned by=           CLI$DISPATCH and terminate the loop if this speciale            status is encountered.  %           ___________________________       2.3.3  HELP command  <           Every program which supports more than one command;           should provide online-help. Although you can give @           this help by a built-in text, a more friendly and VMS-=           conform way is to provide a HELP command and a helpo=           text library. By entering HELP without a topic, the_@           user receives a general help text, including a 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.9           You use LIBRARY/HELP/CREATE to create your helps8           library and LIBRARY/HELP/INSERT to insert help?           topics into your library. See the Command Definition,r9           Librarian and Message Utilities manual for more            information.  >           This is the code fragment of the HELP command in the"           command definition file:  >                            define verb HELP routine MYEXT_HELPR                            parameter P1, prompt="Topic", value(type=$rest_of_line)  *           And here comes the help routine:  /                            #include <descrip.h>s  /                            int cli$get_value();i  :                            void SDA$EXTEND_DISPLAY_HELP();  ,                            void myext_help()                            {.                             char dcl_buf[120];  A                                                              2-11e         1           Extension activation and initializations          &                             short len;  5                             $DESCRIPTOR(dcl,dcl_buf);e  5                             $DESCRIPTOR(dcl_p1,"P1");':                             $DESCRIPTOR(lib,"MYEXT_HELP");  Q                             cli$get_value(&dcl_p1,&dcl,&len);     /* Get topic */V  U                             dcl.dsc$w_length = len;               /* Update length */b  T                             SDA$EXTEND_DISPLAY_HELP(&lib,&hlp);   /* Display help */                            }  :           In this example, the name of the help library is8           MYEXT_HELP. This must be either a logical name9           pointing to the help library, or the library is 1           expected to be SYS$HELP:MYEXY_HELP.HLB.i  9           As you can see, SDA even provides a callback toi=           display online-help which you should use instead of 6           the appropriate VMS routine LBR$OUTPUT_HELP.                                               2-12    c                A           _______________________________________________________d  &    3      Running in SDA's environment      =           Once activated, the extension runs under control of ?           SDA. SDA establishes a default environment from whichn?           it interprets certain commands. Your extension should >           behave exactly in the same manner, so it's important?           to understand in which environment you're running ande*           how commands may be interpreted.  6           SDA's environment consists of the following:  @           o  Analysis mode - either a system dump or the running"              system (Section 3.1);  ;           o  Output mode - either the screen or a specified)'              output file (Section 3.2);n  3           o  Process and CPU context (Section 3.3);n  +           o  Current address (Section 3.4);t  =           o  Condition handling and interrupts (Section 3.5);o  -           o  Override mode (Section 3.6); and   -           o  Callback routines (Section 3.7).   <           These components are now described in more detail.  L           __________________________________________________________________      3.1    Analysis mode   1           SDA can be invoked in one of two modes:   =           o  with ANALYZE/CRASH_DUMP to analyze a system dump A              written to a designated dump file or to the system's               primary page file;a  ?           o  with ANALYZE/SYSTEM to access data structures frome               the running system.  A                                                               3-1a         &           Running in SDA's environment          @           Not all SDA commands apply to both modes. For example,<           SDA's SHOW CPU or SHOW HEADER commands are allowed,           only when examining a system dump.  @           Your extension may provide such commands as well - or,?           in contrast, commands which are useful on the runningd           system only.  ;           On Alpha, you may use the callback SDA$EXTEND_ON_ 9           CURRENT_SYSTEM. This callback returns 1, if the ?           current (running) system is analyzed, else it returns 9           0. On VAX, however, the callback doesn't exist. 9           You may use the following MACRO-32 routine as ae           replacement:  &           SYM: .ascid  /EXE$GL_ABSTIM/           SEC: .float  1.0  ;                 .entry  SDA$EXTEND_ON_CURRENT_SYSTEM,^m<r2>r                 pushal  SYM 4                 calls   #1,g^sda$extend_symbol_value                 movl    (r1),r2                  pushal  SECt%                 calls   #1,g^lib$waits                 pushal  SYMo4                 calls   #1,g^sda$extend_symbol_value                 movzbl  #1,r0i                 cmpl    (r1),r2                  bneq    10$D                 decb    r0           10:   ret   ;           This routine obtains the value of the system cello?           EXE$GL_ABSTIM twice, while waiting one second between.@           the accesses. This cell contains the number of seconds;           since last reboot; its value is incremented everyl>           second. Of course, this occurs on the running system=           only; in a dump, the value at the time of the crashV=           is frozen and never changes. So if the values stillo<           are the same after waiting a second, a system dump:           is analyzed and 0 (on_current_system = false) is           returned.n  
           3-2o A  x    A                                      Running in SDA's environment           =           Note: If you must decide between running system ando<           system dump, call this routine once as part of the>           extension's initialization and store the result in a>           global variable. Whenever you must decide, check the<           global variable only. Otherwise, every check would1           delay command execution for one second.A  ;           There is another thing you should consider when ad?           system dump is analyzed: the dump may exist partially 9           only. This may occur when it was written to ther?           primary page file or it was written to the designated =           dump file, but the dump file was too small to store =           the entire dump. In this case, some data may not beh@           available although system cells point to it. Also keep<           in mind that you may work with a dump written by a           different system.   @           Note: It is strongly recommended that you use only SDA<           callbacks when accessing system cells or addresses?           where system cells point to. The callbacks check that >           the requested data is available and valid, and, when=           analyzing a system dump, the data is taken from thei           dump file.  L           __________________________________________________________________      3.2    Output mode   =           Output of SDA command is usually written to screen, @           but can be sent to a file as well (with the SET OUTPUT=           or SET LOG commands). SDA callbacks ensure that them:           output of your extension is written at the place;           where the user expects it. For this reason, avoida@           using standard I/O commands provided by your language,7           always use the appropriate callbacks instead.u  ;           Output created by SET OUTPUT is written in a wellh9           formatted, printable form. In addition, a table 9           of contents is created at the top of the output <           file. User-supplied commands or error messages are;           not included here. The output width is always 132e<           characters (suitable for print on a line printer).  A                                                               3-3          &           Running in SDA's environment          =           In contrast, output created by SET LOG contains allw:           SDA output in an unformatted, as-is form. As the9           command name indicates, the output created with_<           this command is a complete log of a particular SDA=           session (or part of a session), including all error ?           messages and user-supplied commands. The output widtht>           corresponds to the terminal width; if a logfile with;           the same name exists from a previous session, new)5           output is appended at the end of this file.t  <           Unfortunately, current SDA versions provide no way:           to determine whether output is sent to screen or=           to a file (or to obtain the current output device's'@           width) - this would allow an extension to display more?           information when longer lines would be available. Forl>           this reason, you should always assume a screen width?           of 80 characters. Avoid to display longer lines, thiso1           may produce confusing output on screen.   L           __________________________________________________________________  !    3.3    Process and CPU context   >           When displaying process data structures or examining?           per-process addresses, SDA always makes references tox>           the current process. The initial current process is:  1           o  on the running system: your process;e  ?           o  in a dump: the process which was executing (in CURi?              state) at the time of the crash. If no process was A              executing, a current process must be selected before 5              you can reference process-specific data.S  7           You can use the SET PROCESS command to selectT:           and change the current process. From within your@           extension, you can change the current process by using=           the SDA$EXTEND_PARSECOMMAND callback. This callback ;           executes any SDA command; by specifying the abovei>           command with a valid process index (or PID), you can#           access any process' data.t  
           3-4          A                                      Running in SDA's environment           :           Whenever you want to display per-process data or=           access per-process address space, you should always =           reference only the amount of data you're willing to=<           display in a single line. Always keep in mind that:           the current process may have changed between two>           calls of your extension. This occurs when the screen>           becomes full, SDA displays its Press RETURN for more@           prompt, and the user enters a new SET PROCESS command.=           Currently, there is no way to notify your extensionh?           from a current process change. You must use callbacks =           whenever you want to reference per-process data and >           addresses; only the callbacks ensure that data about1           the actual current process is returned.i  9           When the subject of analysis is an uniprocessor =           system, SDA's context is solely process context. In =           the case of symmetric multiprocessor (SMP) systems,D?           there are more than one CPU; the one which caused the >           system to crash (which becomes the current CPU), and>           up to 31 other CPU's. Each of these CPU's may have a=           current process; when changing CPU context, process ;           context may change as well. In addition, some SDAd/           commands affect the current CPU only.m  A           Note: CPU context is available on SMP systems only, and_=           only when a system dump is analyzed. On the running_>           system, the current CPU is always the CPU which your           process executes on.  :           In general, the notes for process context in the@           sentence above apply for CPU context as well. Entering:           a SET CPU command may change the process context>           implicitly. In addition, when examining CPU-specific=           data (from the per-CPU database), keep in mind thatc=           references to this data may become invalid due to a &           previous CPU context change.  <           In addition to the commands described above, there?           are some other SDA commands which may cause a process =           or CPU context change. See the System Dump Analyzer ;           (VAX/Alpha) Utility manuals for more information.   A                                                               3-5     L    &           Running in SDA's environment        L           __________________________________________________________________      3.4    Current address   ?           SDA provides the dot (.) as current address indicatorn5           when used in commands which accepts addressn;           specifications, e.g. EXAMINE, FORMAT or VALIDATE.f@           The current address is always set by the last EXAMINE,>           FORMAT or VALIDATE command. For example, if the user9           enters EXAMINE 10000, 10000 becomes the currentt:           address. This address may be referenced later by7           supplying the dot (.) in place of an address.e  :           SDA provides two callbacks to access the current           address:  9           o  SDA$EXTEND_GET_ADDRESS to obtain the currents              address; and   1           o  SDA$EXTEND_SET_ADDRESS to change it.n  :           There is one situation where these callbacks may9           be very useful: when parsing and evaluating SDAp<           expressions. Assume, in your extension, there is a;           command which accepts an address as parameter. To :           behave in the usual SDA way, your command should=           not accept a hexadecimal value only, but a standards<           SDA expression, including logical and arithmetical@           operators, parentheses and previously defined symbols.  =           SDA provides no callback for expression evaluation.e=           However, using the above callbacks, you can do thist           the following way:  =           o  Using SDA$EXTEND_GET_ADDRESS, obtain the current !              address and save it.   0           o  Build the following command string:  .                               EXAMINE string;0  -              where string is your expression.n  
           3-6          A                                      Running in SDA's environment           =           o  Build a TPA (table-driven parser) block, fill in :              the appropriate fields and invoke SDA$EXTEND_>              PARSECOMMAND. SDA will parse the command and call@              its EXAMINE routine. EXAMINE will compute the given@              expression and will store the result as new current              address.i  ?           o  Again, invoke SDA$EXTEND_GET_ADDRESS, this time toc2              obtain the result of your expression.  :           o  Using SDA$EXTEND_SET_ADDRESS, restore the old              current address.r  ;           The following code example shows this way in more.?           detail. Given the address of a null-terminated stringG@           containing a valid SDA expression, the C routine comp_=           expr()  computes and returns the binary result. The_@           code assumes that initialization work (as described in*           Section 2.3.1) was already done.  H           #include <string.h>                   /* strxxx() functions */L           #include <tpadef.h>                   /* TPA parser definitions */  K           void SDA$EXTEND_GET_ADDRESS(),        /* Get current address */ 1eI                SDA$EXTEND_SET_ADDRESS(),        /* Set current address */ D                SDA$EXTEND_PARSECOMMAND();       /* Command parser */  )           int comp_expr(char *expression)e           {tD            char cmdbuf[132];                    /* Command buffer */  I            int oldaddr,                         /* Old current address */mC                result;                          /* Binary result */   N            struct tpadef tpa;                   /* TPA (parser) structure */ 2  L            strcpy(cmdbuf,"EXA ");               /* Command is 'EXAMINE' */ 3  M            strcat(cmdbuf,str);                  /* Append our expression */ 4i  C            strcat(cmdbuf,";0");                 /* Append ';0' */ 5f  M            SDA$EXTEND_GET_ADDRESS(&oldaddr);    /* Save current address. */ 6   A                                                               3-7     R    &           Running in SDA's environment          J            tpa.tpa$l_count = TPA$K_COUNT0;      /* 8 addit. longwords */ 7  K            tpa.tpa$l_options = TPA$M_ABBREV;    /* Abbreviations allowed */l  M            tpa.tpa$l_stringcnt = strlen(cmdbuf);/* Command length in bytes */H  L            tpa.tpa$l_stringptr = (int) cmdbuf;  /* Command string address */  K            SDA$EXTEND_PARSECOMMAND(&tpa);       /* Now execute command */ 8P  E            SDA$EXTEND_GET_ADDRESS(&result);     /* Obtain result */ 9t  M            SDA$EXTEND_SET_ADDRESS(oldaddr);     /* Restore old address. */ 10   C            return result;                       /* Return result */i           }D  ?           1  This makes the callbacks known as functions to the =              C compiler. Since there are no includes or otherbA              external declarations for SDA callbacks, it is up to A              you to declare them in a way your compiler requires.z  =           2  This defines the parser block for the VMS table- A              driven (TPA) parser. SDA$EXTEND_PARSECOMMAND must be A              called with the address of this block. The structure >              and the following TPA$xxx literals are defined inA              module $TPADEF. A detailed description of the table- >              driven parser (LIB$TPARSE/LIB$TABLE_PARSE) can be4              found in the RTL Library (LIB$) manual.  <           3  We want to execute an EXAMINE command. Since we?              set the TPA$M_ABBREV bit later (which allows us torA              abbreviate commands), we can write 'EXA' ('EX' would '              be ambiguous with 'EXIT').t  <           4  The given expression is appended to the command              string.  @           5  We append ;0. This means 'examine the given address:              and display null bytes'. It causes EXAMINE to9              suppress any output. Otherwise, we would get 4              displayed the result of the expression.  
           3-8_ _  _    A                                      Running in SDA's environmentv          >           6  We must save the initial current address since itA              will be changed by our EXAMINE command. Once the newc>              current address (the result of our expression) is2              obtained, we can restore the old one.  @           7  Fill in the structure for the parser. The structure<              consists of nine longwords where only the first=              four (shown in the example) must be initialized. ?              The remaining longwords are used to store internal ;              parser states. The 'options' longword containst@              parsing options; we will allow abbreviated commands?              here (otherwise, we had to write 'EXAMINE' instead               of 'EXA').e  =           8  Invoke the parser. If the expression was spelledp@              incorrectly or contains unknown symbols, the parser;              signals an exception, causing SDA to abort our <              routine, display an error message and print its@              SDA> prompt. You can declare a condition handler to4              avoid this situation (see Section 3.5).  <           9  Obtain the current address again, this time, it!              contains our result.   ;           10 Restore the old current address and return thee              result.  >           Note that SDA interprets the '/' as division sign in=           its expressions. For this reason, you cannot supply >           qualifiers following SDA expressions. If you use CDL=           (Command Definition Language) and the corresponding >           CLI$ routines, the expression parameter or qualifier@           value should be declared as value(type = $end_of_line)>           which prevents DCL from parsing the expression (and,;           if the expression contains characters like '@' ors;           '*', returning a syntax error). You should notifym>           your users that qualifiers, if any, must be supplied>           immediately after the command verb (this is the same!           for most SDA commands).t  A                                                               3-9a a  d    &           Running in SDA's environment        L           __________________________________________________________________  +    3.5    Condition handling and interrupts   :           Most SDA callbacks do not return a status value,>           instead, in case of errors, they signal a condition.7           Unless otherwise changed, this results in the 8           invocation of SDA's condition handler which is@           established by default. The condition handler examines@           the reason for the condition, displays the appropriate=           error message and - in case of errors - performs an @           unwind. This causes the routine, wherein the condition<           was signaled, to abort and to return to SDA's main=           command loop (see SDA$EXTEND_HANDLER for a detailedh2           description of SDA's condition handler).  ?           In most cases, this is a good practice. You can write <           your code simply; there is no need to check return;           states (in fact, many callbacks do not return anyf=           state). If your code is executed until its end, you =           can assume that all involved callbacks had executeda;           successfully. In contrast, in case of errors, youd?           can assume that the appropriate messages were already ;           displayed on screen and the condition was handled /           correctly by SDA's condition handler.   :           In some situations, however, it may be useful to<           establish your own condition handler. Consider the?           example in Section 3.4, wherein SDA's current address 9           location is used in conjunction with the parser ?           callback and the EXAMIME command to compute numericalh<           or logical expressions. When the parser detects an?           error, it signal a condition. EXAMINE is not executedn>           in this case, leaving the current address unchanged.=           If, however, a syntactically correct, but otherwisep?           invalid address is given, the parser forces executionn?           of EXAMINE which computes the expression, changes thel=           current address, and, since the address is invalid,n;           signals an exception. This causes your routine tor9           abort before the initial current address can bet           restored.              3-10 h  a    A                                      Running in SDA's environmentt          >           By declaring a condition handler, you can avoid this?           situation. The condition handler restores the currents>           address and resignals the condition, passing control@           to SDA's condition handler. In this case, the longword<           holding the saved current address must be declared1           global (in C, outside of any function):f  S           int G_addr_changed,                /* 1 if current address was changed */tH               G_curr_addr;                   /* Saved current address */             int my_handler()           {eS            if (G_addr_changed)                   /* Was current address changed? */             {F             SDA$EXTEND_SET_ADDRESS(G_curr_addr); /* Yes, restore it */  C             G_addr_changed = 0;                  /* OK, restored */d            }I            return SS$_RESIGNAL;                  /* Resignal condition */i           }l  >           This code fragment shows the condition handler which:           should be established as part of the extension's<           initialization work. It checks whether the current>           address was changed (if our internal EXAMINE command=           was executed), and, if so, restores the address. Ino>           the get_expr()  routine, the change flag must be set           accordingly:                .              .              .L            SDA$EXTEND_GET_ADDRESS(&G_curr_addr);  /* Save current address */  M            G_addr_changed = 1;                    /* Force handler restore */e  K            SDA$EXTEND_PARSECOMMAND(&tpa);         /* Now execute command */t              .              .              .K            SDA$EXTEND_SET_ADDRESS(G_curr_addr);   /* Restore old address */d  A                                                              3-11v i       &           Running in SDA's environment          M            G_addr_changed = 0;                    /* Clear handler restore */c              .              .              .  <           Without the change flag, the current address would?           be restored whenever a condition occurs - even in thes<           case, that no address was saved previously. By the@           way: i prefer to prefix all global variables with 'G_'5           - this makes easy to recognize their scope._  >           SDA's condition handler is provided as callback; you?           can establish it in your program or call it from youre@           own handler. This allows you to display error messages>           like SDA does, but prevents you from loosing control8           over the execution flow in case of conditions.  >           There is another thing you should be aware of: there9           is no guarantee that your routines are executed =           entirely. Due to SDA's behaviour of reprompting for =           a new command whenever the screen becomes full, thei>           user may invoke a command of your extension, display?           some data, but may enter another command before yours ?           has completed. For this reason, you should be careful @           when allocating resources at the begin of your command=           and returning them at the end (for example, virtual            memory or locks).o  8           It is highly recommended that you allocate all<           required resources, perform all work and free them;           before the first line of data is displayed. Never <           allocate resources beyond your routines or as part<           of the extension initialization. Since there is no:           'state' maintained by SDA for this purpose, your<           extension (and its initialization routine) may and9           may invoked many times from within the same SDA =           session; uncontrolled resource allocation can cause >           your extension to fail and the SDA session to abort.               3-12 s  e    A                                      Running in SDA's environmentt        L           __________________________________________________________________      3.6    Override modeu  @           On Alpha, with OpenVMS V7.0 and higher, when analyzing=           a system dump, SDA can be invoked in override mode.e?           This mode can be used when SDA would reject otherwises>           the dump stored in the dump file (since it is either=           incomplete or contains invalid data in the header).e;           You tell SDA to run in override mode by supplyingt>           the /OVERRIDE qualifier. SDA uses a different prompt(           (SDA>>) to indicate that mode.  :           Only few commands are available in this mode; in8           general, all commands accessing memory are not;           available. Override mode is mainly used to repair :           a corrupted dump file. It provides a MODIFY DUMP>           command which allows you to change every byte, word,>           longword or quadword in the dump. Once the dump file;           is repaired, SDA can be invoked in the usual way.   7           From the programmers point of view, callbacks ?           accessing data in memory or from the dumpfile are notn@           available. If you try to invoke one of these callbacks<           in override mode, the error SDA$_MEMNOTACC (memory=           locations not accessible) is returned. This affects )           mainly the following callbacks:   /                               SDA$EXTEND_FORMATr1                               SDA$EXTEND_GETMEM64 8                               SDA$EXTEND_GET_CURRECT_PCB6                               SDA$EXTEND_GET_IMAGE_OFF1                               SDA$EXTEND_REQMEM64e1                               SDA$EXTEND_TRYMEM64i;                               SDA$EXTEND_VALIDATE_QUEUE[64]   =           SDA provides no way to tell an extension whether isr:           invoked in override mode. You may, however, find;           out this yourself: try to get data at the base S0 ?           address (FFFFFFFF80000000) as part of the extension'so?           initialization. This address always exists in a dump; ;           if you receive the above error, you're running in >           override mode and are not able to access and display=           data from memory. Since most extensions are useless   A                                                              3-13r .  i    &           Running in SDA's environment          =           in override mode, you should display an appropriated            message and terminate.  L           __________________________________________________________________      3.7    Callback routinesn  >           As described earlier, callback routines are provided?           by SDA to make some work easier and let our extensione@           behave in a SDA-conform manner. There are 28 callbacks>           on VAX and 36 callbacks on Alpha (44 on Alpha V7 due>           its 64-bit support); some of the Alpha callbacks not=           available on VAX can be written easily by yourself;x9           see the example of SDA$EXTEND_ON_CURRENT_SYSTEMi<           in Section 3.1. Some others are Alpha-specific and<           therefore not available on VAX. For every callback?           described in Appendix B, information is given whether,:           it exists on VAX and Alpha, or on Alpha only. In;           addition, some callbacks have different argumentso>           on VAX and Alpha; this is described in Appendix B as           well.f  >           Since callbacks are internal routines in the SDA.EXE>           image, a shareable image containing transfer vectors=           to these routines is provided, which your extensionR@           must be linked against (on Alpha, it's an object file;<           see Appendix A). You must initialize a location in:           the shareable image with the base address of the;           routine pointer array in SDA.EXE; this address isI9           passed as first argument to your extension (seep8           Section 2.2.2.1). If you do not so, invoking a2           callback results in an access violation.  :           Not all callbacks confirm to the OpenVMS calling@           standard in the way that they are called as procedures:           or pass a return status back to their caller. In<           addition, some callbacks expect and/or return data>           in processor registers. If your programming language>           does not allow direct access to processor registers,?           you must provide jackets which invoke the appropriate 7           callback and copy the data from the processorn@           registers into locations where you can access it. If a             3-14         A                                      Running in SDA's environment           ?           jacket is required for a callback, a MACRO-32 example(4           is given in its description in Appendix B.  =           Table 3-1 contains an overview about all callbacks, <           the SDA modules in which they are defined, and the@           calling conventions. Table 3-2 contains all callbacks,?           sorted by purpose, and a short description. Note that/>           the common name prefix SDA$EXTEND_ is omitted in the-           tables for the reason of shortness.   9           Note: SDA callbacks may be invoked from user ord;           supervisor mode only. In general, unless required >           for protection purposes, an extension should not run>           at higher-privileged processor modes. If it does, it9           should return to user mode as fast as possible.0  "           Table 3-1  SDA Callbacks  A           .)_____________________________________________________   A           Routine_name_______Module_________RetStaNotes__________   2           ADD_SYMBOL         SYMBOLS        yes[1]  ;           ALLOCATE           SYMBOLS        yes    RequiresTA                                                    jacket routine=  /           DEALLOCATE         SYMBOLS        yes   2           DISPLAY_HELP       SDA_EXTEND     yes[1]  .           ENSURE             SDA_EXTEND     no  2           FORMAT             SYMBOLS        yes[1]  .           FORMAT_SUBHEADING  INDEX          no  6           GETMEM             MAPPING        yes    [2]  A           ________________________________________________________>           [1]Returns always success (low bit set), signals any           error.  ;           [2]On OpenVMS Alpha V7.0 and higher, this routine ?           accepts 64-bit addresses and therefore was renamed to ?           include the '64' postfix (e.g., SDA$EXTEND_GETMEM was *           renamed to SDA$EXTEND_GETMEM64).  A                                                              3-15c i       &           Running in SDA's environment          A           Table_3-1_(Cont.)__SDA_Callbacks_______________________D  A           Routine_name_______Module_________RetStaNotes__________b  6           GET_ADDRESS        SDA_EXTEND     no     [3]  =           GET_BUGCHECK_MSG   SDA_EXTEND     no     Alpha onlye  A           GET_CURRENT_PCB    SDA_EXTEND     no     Alpha V7.0 andL>                                                    higher only  =           GET_DYN_INFO       SDA_EXTEND     no     Alpha onlyd  =           GET_HEADER         SDA_EXTEND     no     Alpha onlyl  =           GET_HW_NAME        SDA_EXTEND     no     Alpha only   =           GET_IMAGE_OFF      SDA_EXTEND     yes    Alpha only   /           GET_INPUT          SDA_EXTEND     yesd  A           GET_LINE_COUNT     SDA_EXTEND     no     Alpha V7.0 andi>                                                    higher only  .           HANDLER            HANDLER        no  =           LIB$INS_DECODE     EVAX_DECODE    yes    Alpha onlyt  .           NEW_PAGE           MAIN           no  =           ON_CURRENT_SYSTEM  SDA_EXTEND     yes    Alpha only   /           PARSECOMMAND       SDA_EXTEND     yesn  2           PRINT              MAIN           yes[1]  A           PRINT_COLUMN_      MAIN           yes    Must be callede@           VALUE                                    as subroutine  .           PRINT_COLUMNS      MAIN           no  /           READ_SYMFILE       SDA_EXTEND     yest  A           _______________________________________________________ >           [1]Returns always success (low bit set), signals any           error.  ;           [3]On OpenVMS Alpha V7.0 and higher, this routineo@           accepts 32-bit addresses only, but has a corresponding>           routine for 64-bit support as well. This routine has=           the '64' postfix in its name (e.g., SDA$EXTEND_GET_v@           ADDRESS for 32-bit addresses, SDA$EXTEND_GET_ADDRESS64           for 64-bit addresses)s             3-16         A                                      Running in SDA's environment           A           Table_3-1_(Cont.)__SDA_Callbacks_______________________l  A           Routine_name_______Module_________RetStaNotes__________c  6           REQMEM             MAPPING        yes    [2]  6           SET_ADDRESS        SDA_EXTEND     no     [3]  .           SET_HEADING        INDEX          no  =           SET_HEADING_       SDA_EXTEND     no     Alpha onlye           ROUTINEi  A           SET_LINE_COUNT     SDA_EXTEND     no     Alpha V7.0 andp>                                                    higher only  .           SKIP_LINES         MAIN           no  .           SYMBOLIZE          SYMBOLS        no  ;           SYMBOL_VALUE       SYMBOLS        yes    RequireslA                                                    jacket routineo  A           TRANSLATE_ADDRESS  SYMBOLS        yes    Must be calledc@                                                    as subroutine  2           TRANSLATE_BITS     SYMBOLS        yes[1]  6           TRYMEM             MAPPING        yes    [2]  2           TYPE               SDA_EXTEND     yes[1]  6           VALIDATE_QUEUE     SDA_EXTEND     yes    [3]A           _______________________________________________________s>           [1]Returns always success (low bit set), signals any           error.  ;           [2]On OpenVMS Alpha V7.0 and higher, this routine ?           accepts 64-bit addresses and therefore was renamed to ?           include the '64' postfix (e.g., SDA$EXTEND_GETMEM was *           renamed to SDA$EXTEND_GETMEM64).  ;           [3]On OpenVMS Alpha V7.0 and higher, this routine @           accepts 32-bit addresses only, but has a corresponding>           routine for 64-bit support as well. This routine has=           the '64' postfix in its name (e.g., SDA$EXTEND_GET_s@           ADDRESS for 32-bit addresses, SDA$EXTEND_GET_ADDRESS64           for 64-bit addresses)aA           _______________________________________________________X  A                                                              3-17n n  r    &           Running in SDA's environment          A           Table_3-2__SDA_Callbacks_-_Purpose_____________________h  A           Purpose____________Callback____________Description_____n  ?           Formatting and     DISPLAY_HELP        Display online A           displaying data                        help from a help 8                                                  library  >                              ENSURE              Ensure that n>                                                  lines of dataA                                                  can be displayed   ;                              FORMAT_SUBHEADING   Format ando8                                                  display;                                                  subheadersa  >                              GET_INPUT           Get a line of6                                                  input  ?                              NEW_PAGE            Insert a <FF>;,=                                                  clear screent  ;                              PRINT               Format and ?                                                  display a linei8                                                  of data  ;                              PRINT64             Format and >                                                  display 64bit5                                                  data   A                              PRINT_COLUMNS       Print columns of >                                                  data (tables)  ?                              PRINT_COLUMN_       Print a singley;                              VALUE               value in a 7                                                  column   A                              SET_HEADING         Set heading line   <                              SET_HEADING_        Establish aA                              ROUTINE             routine to printl8                                                  headers  >                              SKIP_LINES          Insert one orA                                                  more empty linesd             3-18         A                                      Running in SDA's environment           A           Table_3-2_(Cont.)__SDA_Callbacks_-_Purpose_____________D  A           Purpose____________Callback____________Description_____r  ;                              TYPE                Format and}?                                                  display a linen8                                                  of data  ;                              TYPE64              Format ande?                                                  display 64-bith5                                                  data   >           Decoding and       ADD_SYMBOL          Add symbol to=           symbol processing                      symbol tablen  ;                              FORMAT              Decode and <                                                  format data:                                                  structure  =                              LIB$INS_DECODE      Decode 21x64r<                                                  instruction  <                              READ_SYMFILE        Read symbol;                                                  table file)  :                              SYMBOLIZE           Symbolize>                                                  numeric value  >                              SYMBOL_VALUE        Obtain symbol6                                                  value  @                              TRANSLATE_ADDRESS   Translate value=                                                  into addressh  :                              TRANSLATE_BITS      Translate;                                                  bitmask toe7                                                  string   A           Interfaces to      ALLOCATE            Allocate virtualo7           SDA routines and                       memorya           locationsr  ;                              DEALLOCATE          Deallocateu?                                                  virtual memory   @                              HANDLER             SDA's condition8                                                  handler  A                                                              3-19a e  u    &           Running in SDA's environment          A           Table_3-2_(Cont.)__SDA_Callbacks_-_Purpose_____________   A           Purpose____________Callback____________Description_____s  ?                              GET_ADDRESS         Obtain currentr8                                                  address  ?                              GET_ADDRESS64       Obtain currentr?                                                  64-bit addressi  ?                              GET_LINE_COUNT      Obtain currentm=                                                  line counterf  <                              SET_ADDRESS         Set current8                                                  address  <                              SET_ADDRESS64       Set current?                                                  64-bit addresso  ?                              SET_LINE_COUNT      Change currento=                                                  line countere  :                              PARSECOMMAND        Parse and<                                                  execute SDA8                                                  command  ?           Accessing memory   GETMEM              Access memory, @                                                  signal warnings  >                              GETMEM64            Access 64-bit?                                                  memory, signalS9                                                  warningsa  ?                              REQMEM              Access memory,e>                                                  signal errors  >                              REQMEM64            Access 64-bit?                                                  memory, signalf7                                                  errorsd  ?                              TRYMEM              Access memory,i>                                                  do not signal  >                              TRYMEM64            Access 64-bit?                                                  memory, do not 7                                                  signal,             3-20 o  u    A                                      Running in SDA's environmentb          A           Table_3-2_(Cont.)__SDA_Callbacks_-_Purpose_____________   A           Purpose____________Callback____________Description_____r  9                              VALIDATE_QUEUE      Validatee<                                                  absolute or?                                                  relative queue   @                              VALIDATE_QUEUE64    Validate 64-bit6                                                  queue  =           System and         GET_BUGCHECK_MSG    Get bugcheckD8           context                                message           information   ;                              GET_CURRENT_PCB     Get PCB of @                                                  current process  ?                              GET_DYN_INFO        Get info about =                                                  dynamic data 6                                                  codes  >                              GET_HEADER          Get dump file7                                                  headeri  =                              GET_HW_NAME         Get hardwarei5                                                  namei  ?                              GET_IMAGE_OFFSET    Get offsets in >                                                  sliced images  A                              ON_CURRENT_SYSTEM   Check for system @                                                  dump or runningA           _______________________________________system__________n            A                                                              3-21_ _                   A           _______________________________________________________r  .    A      Linking and debugging your extension      =           Once you have coded your extension in your favorite >           language and have successfully compiled it, you must@           create a shareable image. This shareable image must be@           either copied into directory SYS$SHARE or you define a<           logical name which points to it (see Section 2.1).:           This chapter explains how to link your extension;           on VAX and Alpha (this is slightly different) and ,           contains some hints for debugging.  L           __________________________________________________________________      A.1    Linking on VAX  8           On VAX, your extension is built by linking the           following components:c  >           o  the object module(s) which your code consists of;  A           o  the shareable image SYS$SHARE:SDA_EXTEND_VECTOR.EXE;e  3           o  in some cases, the system symbol tabler               SYS$SYSTEM:SYS.STB.  8           Depending on your programming language and the<           references in your code, other shareable libraries5           or object modules must be included as well.b  >           You use the LINK/SHARE command to create a shareable<           image. Since you must include universal symbols in?           the shareable image's symbol table (see Section 2.2),i?           you must provide a linker option file (see the Linker =           Utility manual how to create and use linker options            files).   A                                                               A-1  k       .           Linking and debugging your extension          ?           It is recommended that you include all information ina?           the option file. On the command line, you specify theo@           option file name only. Here is the option file for the3           MYEXT extension presented in Section 2.3:o  &                            myext$cld 1'                            myext$main 2                                .                                .R                               . @                            sys$system:sys.stb/selective_search 3>                            sys$share:sda_extend_vector/share 41                            universal=sda$extend 5l7                            universal=sda$extend_versioni=                            identification="V1.0-002/BOL-96" 6 /                            name="MYEXT$SDA_VAX"a    0           1  This object module was created with;              SET COMMAND/OBJECT. It contains the binary CDLr:              definitions of all commands recognized by the              extension.o  =           2  This is the extension's main module. It contains =              the definitions of the universal symbols and the =              extension's initialization routine. In addition, @              it contains the dispatcher to all command routines.A              These routines may or may not be in the same module._A              An example of initialization and command dispatchingd,              code is given in Section 2.3.1.  @              Other extension modules may follow, as indicated by              the ellipsis.  ;           3  SYS$SYSTEM:SYS.STB is the system symbol table.j<              You must include this table when using names of=              executive cells or constants (examples are names >              starting with CTL$, EXE$, IOC$, LCK$, MMG$, PIO$,=              SCH$ or SWP$). If you do not use such names, youN@              can omit this line. The /SELECTIVE_SEARCH qualifier<              causes the linker to process only those symbols  
           A-2_         A                              Linking and debugging your extensionr          ?              in the input file that have been referenced in the               previous modules.  ;           4  This is the shareable image containing all SDA(A              callbacks (since it's shareable, you must supply theM@              /SHARE qualifier). As described in Section 2.2.2.1,:              the routines in this image are jackets to the>              internal routines in SDA.EXE. By initializing the@              global location SDA$EXTEND_VECTOR_TABLE_ADDR within@              this image with the first argument passed by SDA to?              your extension, you create the required connectionA?              between your extension and SDA's internal routinesA#              (see Section 2.2.2.1).   :           5  To include a global symbol into the shareable9              image's symbol table, you must declare it asE<              universal using the linker option universal. As=              described in Section 2.2, these two symbols must '              exist in the symbol table.   @           6  This line and the following line are optional. They@              place naming and version information into the imageA              header. This information is displayed when analyzing *              the image with ANALYZE/IMAGE.  =           To link your extension with this option file, entero  ;                            $ LINK/SHARE=MYEXT MYEXT/OPTIONS   <           assuming that the option file was named MYEXT.OPT.  ?           Unless you copy the resultant image to SYS$SHARE, you 1           must define a logical name in this way:O  E                            $ DEFINE MYEXT$SDA directory:MYEXT$SDA.EXE   >           You can now invoke the extension by starting SDA and,           entering MYEXT at the SDA> prompt.  ?           Note: If you have SDA.EXE installed, you must install_;           the extension image as well (/OPEN/HEADER/SHARE).   A                                                               A-3O p  M    .           Linking and debugging your extension        L           __________________________________________________________________      A.2    Linking on Alpha  :           On Alpha, your extension is built by linking the           following components:a  >           o  the object module(s) which your code consists of;  ?           o  the object module SYS$SHARE:SDA_EXTEND_VECTOR.OBJ;   9           o  executive symbols taken from ALPHA$LOADABLE_->              IMAGES:SYS$BASE_IMAGE.EXE, included by specifying              /SYSEXE._  8           Depending on your programming language and the<           references in your code, other shareable libraries#           must be included as well.   >           You use the LINK/SHARE command to create a shareable@           image. Since you must include symbols in the shareable<           image's symbol vector, (see Section 2.2), you must>           provide a linker option file (see the Linker Utility=           manual how to create and use linker options files).Y  ?           It is recommended that you include all information inS?           the option file. On the command line, you specify the @           option file name only. Here is the option file for the3           MYEXT extension presented in Section 2.3:   &                            myext$cld 1'                            myext$main 2M                               .R                               .e                               . 8                            sys$share:sda_extend_vector 3A                            symbol_vector=(sda$extend=procedure) 4_B                            symbol_vector=(sda$extend_version=data)=                            identification="V1.0-002/BOL-96" 5p/                            name="MYEXT$SDA_AXP"   
           A-4t d  s    A                              Linking and debugging your extension.            0           1  This object module was created with;              SET COMMAND/OBJECT. It contains the binary CDLi:              definitions of all commands recognized by the              extension.   =           2  This is the extension's main module. It contains =              the definitions of the universal symbols and the =              extension's initialization routine. In addition, @              it contains the dispatcher to all command routines.>              These routines may or may not in the same module.A              An example of initialization and command dispatchingS,              code is given in Section 2.3.1.  @              Other extension modules may follow, as indicated by              the ellipsis.  9           3  This is the object module containing all SDAY<              callbacks. As described in Section 2.2.2.1, the@              routines in this module are jackets to the internal<              routines in SDA.EXE. By initializing the global>              location SDA$EXTEND_VECTOR_TABLE_ADDR within this<              module with the first argument passed by SDA to?              your extension, you create the required connection ?              between your extension and SDA's internal routines #              (see Section 2.2.2.1).   :           4  To include a global symbol into the shareable@              image's symbol table, you must declare it using the?              linker option symbol_vector. The extension's entry @              point SDA$EXTEND must be declared as procedure, the8              global location SDA$EXTEND_VERSION as data.  @           5  This line and the following line are optional. They@              place naming and version information into the imageA              header. This information is displayed when analyzing *              the image with ANALYZE/IMAGE.  =           To link your extension with this option file, enter   B                            $ LINK/SHARE=MYEXT/SYSEXE MYEXT/OPTIONS  A                                                               A-5          .           Linking and debugging your extension          1           assuming that the option file was named 6           MYEXT.OPT. The /SYSEXE qualifier directs the6           linker to process the system shareable image>           ALPHA$LOADABLE_IMAGES:SYS$BASE_IMAGE.EXE in the link@           operation. This image contains references to executive;           data cells. The names of these cells mostly startr:           with CTL$, EXE$, IOC$, LCK$, MMG$, PIO$, SCH$ or?           SWP$; if you do not use such names, you can omit this            qualifier.  ?           Unless you copy the resultant image to SYS$SHARE, you 1           must define a logical name in this way:n  E                            $ DEFINE MYEXT$SDA directory:MYEXT$SDA.EXEl  >           You can now invoke the extension by starting SDA and,           entering MYEXT at the SDA> prompt.  ?           Note: If you have SDA.EXE installed, you must install ;           the extension image as well (/OPEN/HEADER/SHARE).   L           __________________________________________________________________  "    A.3    Debugging your extension  6           Debugging an extension isn't possible in the<           normal way. Since the extension runs under control6           of SDA and the SDA.EXE image was linked with;           /NODEBUG/NOTRACEBACK, there is no way to run your ?           extension under the control of the debugger. Instead, =           if your extension behaves in an unexpected way, youa8           should use checkpoints to watch its behaviour.  ?           A checkpoint is simply a point where you display some6@           data or signal a particular condition. For example, if>           you receive an access violation while accessing data>           via a pointer, you should display the pointer value.<           If it contains a wrong value, you may look for the)           reason causing the wrong value.   
           A-6          A                              Linking and debugging your extension           =           You can use the statements or functions provided byT;           your programming language to display data in your =           program. Since checkpoints are used temporary only, =           there is no need to use callbacks (although you can @           do so as well). Assume that ptr is a pointer variable,           the C call  .                            printf("%08X",ptr);  ?           will show the value of ptr - it's up to you to decide =           whether it is correct. Once you have recompiled and ;           relinked your extension with the above statement, +           invoke SDA to load the new image.   ;           Note: You cannot force SDA to use a new extension @           image during one SDA session. Once loaded, the current=           version remains active for the rest of the session. ?           You must terminate and restart SDA to work with a new            extension image.  <           If you're not sure whether a particular checkpoint?           is reached in a routine, you may also call LIB$SIGNAL ;           with particular condition values. When LIB$SIGNAL 9           generates an condition, SDA's condition handler <           displays the condition value, telling you at which;           point in your routine the condition has occurred. @           Calls to LIB$SIGNAL at various points can help to find5           out the actual execution flow in your code.   =           Debugging SDA extensions is primary a 'run-and-try' =           job. It may be a time-consuming task, however, with @           checkpoints, it is always possible to locate any error           in your code.               A                                                               A-7g u  n                A           _______________________________________________________   "    B      SDA callback description      @           This appendix contains a detailed description of every,           callback. The description includes  9           o  whether or not the callback returns a value;A  :           o  whether or not the callback requires a jacket<              routine since it doesn't confirm to the OpenVMS              calling standard;  @           o  whether the callback exists on VAX and Alpha, or on              Alpha only;  >           o  on Alpha V7 only, whether the callback accepts or'              requires 64-bit addresses.   <           The callbacks are described in alphabetical order.;           For every callback, a detailed description of all =           arguments is given as well as an example in C. Note =           that some callbacks have different arguments on VAX            and Alpha.  ;           Table 3-1 contains an alphabetical listing of all >           callbacks. Table 3-2 contains a short description of1           all callbacks, sorted by their purpose.   ?           The following abbreviations for VMS versions are used #           throughout this appendix:   =           o  VAX - all VMS versions on VAX, from V5.5 to V7.1R              inclusive;n  6           o  VAX V5 - VAX/VMS V5.5, V5.5-1 and V5.5-2;  >           o  VAX V6 - VAX/VMS V6.0, V6.1 and OpenVMS/VAX V6.2;  0           o  VAX V7 - OpenVMS/VAX V7.0 and V7.1;  A                                                               B-1          "           SDA callback description          A           o  Alpha - all VMS versions on Alpha, from V6.1 to V7.1               inclusive;d  2           o  Alpha V6 - OpenVMS/AXP V6.1 and V6.2;  4           o  Alpha V7 - OpenVMS/Alpha V7.0 and V7.1.  <           All versions include hardware-related subversions;=           for example VAX V5 includes VAX/VMS V5.5-2, as well !           VAX/VMS V5.5-2H1 to H4.B                                                            
           B-2          A                                                     SDA Callbacks A                                             SDA$EXTEND_ADD_SYMBOL         A           _______________________________________________________E             SDA$EXTEND_ADD_SYMBOL   .           Adds a symbol to SDA's symbol table.  A           _______________________________________________________              FORMAT  =           SDA$EXTEND_ADD_SYMBOL  symlen, symnam, symval (VAX)I  ?           SDA$EXTEND_ADD_SYMBOL  symlen, symnam, symval, symflg   (                                  (Alpha)  A           _______________________________________________________              RETURNS            VMS Usage: cond_value (           type:      longword (unsigned)           access:    write only            mechanism: by value   >           Always SDA$_SUCCESS (0x00F48009). All conditions are           signaled._  A           _______________________________________________________n             ARGUMENTS            symlen  $           VMS Usage: longword_signed&           type:      longword (signed)           access:    read only           mechanism: by valuee>           A longword containing the length of the symbol name./           The maximum length are 31 characters.a             symnam              VMS Usage: char_string%           type:      character stringe           access:    read only!           mechanism: by referencen  A                                                               B-3_ _  _               SDA Callbacks_           SDA$EXTEND_ADD_SYMBOL         ?           The symbol name you want to assign to the new symbol.e;           The symnam argument is the address of a character =           string holding the symbol name. The string must note:           exceed 31 characters. Note that this argument is;           not passed by descriptor, only the string addressS@           is supplied. The string length is passed in the symlen           argument.e             symval  7           VMS Usage: longword_signed or quadword_signedtA           type:      longword (VAX, Alpha V6)/quadword (Alpha V7)t           access:    read only           mechanism: by valuen;           A longword (VAX, Alpha V6) or quadword (Alpha V7)b<           holding the binary value you want to assign to the           symbol.L             symflg (Alpha only)h  "           VMS Usage: word_unsigned$           type:      word (unsigned)           access:    read only           mechanism: by value =           On Alpha only, if this argument is set to 1, symval =           is treated as procedure descriptor address. This is @           equivalent to SDA's DEFINE/PD command. SDA will create:           a symbol with the given name, and a second named>           symnam_C holding the actual procedure entry address.>           In this case, symval must be a valid virtual address?           (mostly in S0 space) and symnam cannot have more than            29 characters.  A           _______________________________________________________e             DESCRIPTION >           This callback provides a callable interface to SDA's@           DEFINE command. The specified symbol is added to SDA's>           symbol table; if it already exists, the old value is&           replaced with the new value.  
           B-4     m    A                                                     SDA CallbackshA                                             SDA$EXTEND_ADD_SYMBOL         :           On Alpha only, procedures are addressed by their<           procedure descriptors. For a particular procedure,<           the procedure descriptor holds the procedure entry9           address, as well as other information (register ;           save mask, how many arguments are passed in whiche>           registers, and some others). It is equivalent to the?           callframe used and maintained by the VAX CALLS, CALLGl>           and RET instructions. If you set symflg to 1, symval>           must be the address of a valid procedure descriptor.@           SDA uses the contents of this descriptor to obtain the=           actual procedure entry address and creates a symbolm+           named symnam_C with that address.   >           See the description of SDA's DEFINE command for more           information.  A           _______________________________________________________u  #           CONDITION VALUES RETURNED >           Returns always SDA$_SUCCESS (0x00F48009). Conditions9           returned by LIB$GET_VM (which is used to create ;           virtual memory for the SDA symbol descriptor) area-           catched by SDA's condition handler.   A           _______________________________________________________              EXAMPLE     =        "MY_SYMBOL";  @           In this example, a new symbol named MY_SYMBOL is added@           to SDA's symbol table with the value 0x00FF00FF. Since@           this callback returns always SDA$_SUCCESS, there is no,           need to check for a return status.            A                                                               B-5A T  _               SDA Callbacks            SDA$EXTEND_ALLOCATEr        A           _______________________________________________________e             SDA$EXTEND_ALLOCATEb  #           Allocates virtual memory.l  A           _______________________________________________________n             FORMAT  3           SDA$EXTEND_ALLOCATE  size (VAX, Alpha V6),  8           SDA$EXTEND_ALLOCATE  size, [retadr] (Alpha V7)  A           _______________________________________________________e             RETURNS            VMS Usage: cond_valuet(           type:      longword (unsigned)           access:    write only            mechanism: by valuee  0           All conditions returned by LIB$GET_VM.  A           _______________________________________________________a             ARGUMENTS            size  $           VMS Usage: longword_signed&           type:      longword (signed)           access:    read only           mechanism: by value /           Number of bytes you want to allocate.e              retadr (Alpha V7 only)             VMS Usage: address(           type:      longword (unsigned)           access:    write onlyY!           mechanism: by reference =           Address of a longword receiving the base address of >           the allocated virtual memory. This optional argument"           exists on Alpha V7 only.  
           B-6     h    A                                                     SDA Callbacks A                                               SDA$EXTEND_ALLOCATE       A           ________________________________________________________             DESCRIPTION_9           This callback allocates the specified amount of 7           virtual memory. It invokes LIB$GET_VM for the ;           allocation and signals all conditions. The memoryo#           is allocated in P0 space.   @           The callback returns the base address of the allocated8           virtual memory in register R1 and, on Alpha V7=           only, in the retadr argument as well, if specified.i>           Therefore, on other VMS versions, you must provide a4           jacket routine to obtain the base address:  /                .entry  SDA_EXTEND_ALLOCATE,^m<>nF                clrl    @8(ap)                   ; Clear return addressF                pushl   4(ap)                    ; Pass number of bytesG                calls   #1,g^SDA$EXTEND_ALLOCATE ; Invoke SDA's callback ?                blbc    r0,10$                   ; Exit on error H                movl    r1,@8(ap)                ; Return VM base address           10$: ret  @           This jacket is invoked in the same way as the Alpha V7)           version of SDA$EXTEND_ALLOCATE.n  @           You might also consider to invoke LIB$GET_VM directly,;           if you do not want conditions signaled. Note that :           SDA$EXTEND_ALLOCATE expects the byte count to be;           passed by value, whereas LIB$GET_VM expects it to !           be passed by reference.   <           Note: Whenever virtual memory is allocated by your:           extension, be sure to return it before the first?           line of output is displayed. Always keep in mind thatd>           routines in your extension may be interrupted at any=           time when the screen becomes full, SDA displays its @           Press RETURN to continue prompt, and the user enters a           new command.      A                                                               B-7  T  M               SDA Callbacksb           SDA$EXTEND_ALLOCATEt      A           _______________________________________________________   #           CONDITION VALUES RETURNEDu=           All conditions given by LIB$GET_VM are returned and            also signaled.  A           _______________________________________________________i             EXAMPLEc      = SDA_EXTEND_?           ALLOCATE(5000,&retptr);  /* VAX, Alpha V6 (jacket) */m  5  = SDA$EXTEND_ALLOCATE(5000,&retptr);  /* Alpha V7 */m    &       1)) return status;c  >           This example allocates 5000 bytes of virtual memory.?           On VAX and Alpha prior V7, the jacket described above =           is used. retptr is a longword receiving the virtual             memory's base address.                                      
           B-8o e  e    A                                                     SDA CallbackszA                                             SDA$EXTEND_DEALLOCATEw        A           _______________________________________________________              SDA$EXTEND_DEALLOCATEt  :           Deallocates previously allocated virtual memory.  A           _______________________________________________________              FORMAT  ,           SDA$EXTEND_DEALLOCATE  inadr, size  A           _______________________________________________________              RETURNSo           VMS Usage: cond_value (           type:      longword (unsigned)           access:    write only            mechanism: by valueE  1           All conditions returned by LIB$FREE_VM.o  A           _______________________________________________________n             ARGUMENTSe           inadra             VMS Usage: address(           type:      longword (unsigned)           access:    read only           mechanism: by valueh=           Base address of the virtual memory area you want toR           deallocate.T             size  $           VMS Usage: longword_signed&           type:      longword (signed)           access:    read only           mechanism: by valuei>           Size in bytes of the virtual memory area you want to           deallocate.t  A                                                               B-9  H  O               SDA CallbacksE           SDA$EXTEND_DEALLOCATEo      A           _______________________________________________________              DESCRIPTIONl=           This callback deallocates virtual memory previouslyH<           allocated by SDA$EXTEND_ALLOCATE or LIB$GET_VM. It>           invokes LIB$FREE_VM for the deallocation and signals           all conditions.E  ?           You may also call LIB$FREE_VM directly. Note that the 8           argument sequence is inverted for LIB$FREE_VM.  <           Note: Whenever virtual memory is allocated by your:           extension, be sure to return it before the first?           line of output is displayed. Always keep in mind that >           routines in your extension may be interrupted at any=           time when the screen becomes full, SDA displays its_@           Press RETURN to continue prompt, and the user enters a           new command.  A           _______________________________________________________r  #           CONDITION VALUES RETURNEDE>           All conditions given by LIB$FREE_VM are returned and           also signaled.  A           _______________________________________________________              EXAMPLE   ?           This example deallocates the virtual memory allocateds@           in the example given in the description of SDA$EXTEND_           ALLOCATE.s                             B-10 i  a    A                                                     SDA Callbacks A                                           SDA$EXTEND_DISPLAY_HELPh        A           _______________________________________________________t  !           SDA$EXTEND_DISPLAY_HELPg  3           Displays online help from a help library.   A           _______________________________________________________              FORMAT  0           SDA$EXTEND_DISPLAY_HELP  hlplib, topic  A           _______________________________________________________e             RETURNS            VMS Usage: cond_value (           type:      longword (unsigned)           access:    write onlys           mechanism: by valuea  >           Always SDA$_SUCCESS (0x00F48009). All conditions are           signaled.   A           _______________________________________________________h             ARGUMENTSc           hlplib              VMS Usage: char_string%           type:      character string            access:    read only8           mechanism: by descriptor - fixed-length string                      descriptoru;           Name of the help library. The library argument iss?           the address of a character string descriptor pointingu>           to the extension's help library or to a logical name6           which translates to the actual library name.  9           Use the LIBRARY/HELP/CREATE command to create am;           new help library. Use the LIBRARY/HELP/INSERT and =           LIBRARY/HELP/REPLACE commands to insert and replace''           help topics into the library.t  A                                                              B-11t                    SDA Callbacks !           SDA$EXTEND_DISPLAY_HELPs                   topic               VMS Usage: char_string%           type:      character stringn           access:    read only8           mechanism: by descriptor - fixed-length string                      descriptorc;           Topic or topics for which help is requested. This 7           argument is the address of a character string ?           descriptor pointing to the requested help topic or to ?           a blank-separated list of help topics in hierarchical ?           order. In most cases, this is the entire user commandi+           without the leading HELP keyword.   A           _______________________________________________________              DESCRIPTIONa=           This callback provides a SDA-conform way to display 7           online help. The display occurs on the screent9           unless it was redirected to an output file withw9           SDA's SET OUTPUT command. Therefore, instead of ;           calling LBR$OUTPUT_HELP, you should better invokee:           this callback. It calls LBR$OUTPUT_HELP with the            appropriate arguments.  =           For more information, please see the description of <           the LBR$OUTPUT_HELP routine in the OpenVMS Utility           Routines Manual.  A           _______________________________________________________   #           CONDITION VALUES RETURNED->           Returns always SDA$_SUCCESS (0x00F48009). Conditions;           returned by LIBR$OUTPUT_HELP are catched by SDA'sl           condition handler.  A           _______________________________________________________   3           EXAMPLEple can be found in Section 2.3.3.V             B-12    V    A                                                     SDA Callbacks A                                                 SDA$EXTEND_ENSURE         A           _______________________________________________________a             SDA$EXTEND_ENSURE   7           Ensures sufficient lines on the current page.   A           _______________________________________________________l             FORMAT  #           SDA$EXTEND_ENSURE  lincntc  A           _______________________________________________________              RETURNSp  :           This callback does not return a condition value.  A           _______________________________________________________A             ARGUMENTS            lincnt  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only           mechanism: by value <           A longword containing the requested number of free           lines.  A           ________________________________________________________             DESCRIPTION <           This callback ensures that the specified number of=           lines is available on the current display. If it is_@           not available, it invokes SDA$EXTEND_NEW_PAGE to issue?           a page break. It may be useful if you want to displayD6           a particular block of text on a single page.    A                                                              B-13_ _  _               SDA Callbacks            SDA$EXTEND_ENSURE       A           _______________________________________________________c  #           CONDITION VALUES RETURNEDs           None.   A           _______________________________________________________              EXAMPLE   =           This code ensures that 8 lines are available in the            current display.                                                                       B-14    g    A                                                     SDA Callbacks A                                                 SDA$EXTEND_FORMAT         A           _______________________________________________________              SDA$EXTEND_FORMAT   @           Formats and displays the contents of a data structure.  A           _______________________________________________________              FORMAT  4           SDA$EXTEND_FORMAT  options, typnam, basadr  A           _______________________________________________________t             RETURNS            VMS Usage: cond_valueg(           type:      longword (unsigned)           access:    write onlya           mechanism: by value   >           Always SDA$_SUCCESS (0x00F48009). All conditions are           signaled.r  A           _______________________________________________________i             ARGUMENTS            optionse  "           VMS Usage: mask_longword(           type:      longword (unsigned)           access:    read only           mechanism: by value ?           Longword containing a bitmask with on ore more of theu            following options set:            A                                                              B-15a g  o               SDA Callbacks            SDA$EXTEND_FORMAT       A           _______________________________________________________)$                              Bitmask"                              valueA           Bit_Name___________(hex)______Description______________s  @           OPT$M_TYPE         00000001   When set, indicates that<                                         the data structure'sA                                         name was specified in theh8                                         typnam argument.  @           OPT$M_PHYSICAL     10000000   When set, indicates that<                                         the address given in@                                         the basadr argument is a?                                         physical address (Alpha A           ______________________________V7_only).________________h  <           Note that the bit names shown in the table are not?           defined anywhere; if you want to use it in your code, <           you must define the appropriate literals yourself.             typnam              VMS Usage: char_string%           type:      character string$           access:    read only8           mechanism: by descriptor - fixed-length string                      descriptorr9           Data structure name. The typnam argument is ther>           address of a character string descriptor pointing to>           the data structure name. This argument is meaningful=           only when the OPT$M_TYPE bit was set in the options            argument.              basddr             VMS Usage: address(           type:      longword (unsigned)           access:    read only           mechanism: by values<           A longword holding the virtual base address of the?           data structure whose contents should be formatted. Ife@           the OPT$M_PHYSICAL bit is set in the options argument,=           basadr is interpreted as physical address (Alpha V7N           only).             B-16 o       A                                                     SDA Callbacks A                                                 SDA$EXTEND_FORMAT_      A           _______________________________________________________              DESCRIPTION >           This callback provides a callable interface to SDA's:           FORMAT command. Given the base address of a data:           structure, SDA determines the structure type and<           uses the appropriate symbols from its symbol table<           to format and display the contents of all elements>           of the structure. Most VMS data structures provide a1           xxx$B_TYPE byte which holds their type.   >           To determine the type of the structure, SDA examines9           the 'type' byte at offset 0x0A (relative to theT:           structure's base address). Using the type value,=           SDA determines the structure's name from one of its_           internal tables.  ;           All 'type' values and the corresponding names arel>           defined in module $DYNDEF). The names are usually an?           abbreviation of the structure's purpose; for example, =           the type value 2 corresponds to an ACB (AST controlr           block).   8           Once the structure name is known, SDA uses all;           symbols whose names start with the structure name =           to display the contents of the structure. The valuei=           of each symbol is treated as relative offset to thet<           structure's base address; the data at this address?           is displayed together with the symbol name. For every >           symbol, SDA uses the size indicator to determine how<           many data should be displayed. For example, if the?           structure name was PCB (a process control block), allt<           symbols starting with PCB$ are used in the display@           (the dollar sign is used as structure name delimiter).;           In the case of PCB$L_PHD, SDA displays a longwordc?           since the size indicator (the character following the <           dollar sign) means a longword. The following table*           shows all known size indicators:      A                                                              B-17                     SDA Callbacks            SDA$EXTEND_FORMATD      A           ________________________________________________________A           IndicatorMeaning____________Displayed_as_______________c  .           A        Address            Longword  *           B        Byte               Byte  )           C        Literal            [1]n  .           G        Global longword    Longword  .           L        Longword           Longword  .           P        Pointer            Longword  1           Q        Quadword           2 Longwordsr  .           R        Reference          Longword                    (Address)  @           T        Text string        ASCIC (counted ASCII) text  *           W        Word               WordA           _______________________________________________________l:           [1]Only literals of the form typnam$C_LENGTH are:           recognized. They are displayed in a single line,A           mostly_at_the_end_of_the_structure.____________________   7           Symbols with other indicators (K,M,V) are notm           displayed.  ?           There are some structures with different formats; the =           'type' field is used to store other data (the PHD - ;           process header - is an example for this). In thiso=           case, you must tell SDA the type name by specifyingo<           the typnam argument and setting the OPT$M_TYPE bit:           in the options argument. This corresponds to the:           FORMAT/TYPE=typnam command; SDA formats the data<           structure using all symbols with the supplied type           name as prefix.   9           Note: For most data structures, the appropriatei7           symbol definitions are provided in the system :           symbol table file SYS$SYSTEM:SYSDEF.STB (VAX) or?           SYS$LOADABLE_IMAGES:SYSDEF.STB (Alpha). This table is >           not read by default; you must use SDA's READ command?           or invoke SDA$EXTEND_READ_SYMFILE to make known these            symbols to SDA.-             B-18         A                                                     SDA Callbacks_A                                                 SDA$EXTEND_FORMATT        <           For more information, see the description of SDA's           FORMAT command.l  A           ________________________________________________________  #           CONDITION VALUES RETURNED =           Returns always SDA$_SUCCESS (0x00F48009). Table B-1a@           shows the conditions which may be signaled. A signaled@           condition causes the callback to abort, to display the>           appropriate message text and to return to your code,7           unless you have declared a condition handler.u  <           In addition to the conditions listed in Table B-1,=           all conditions returned by SDA$EXTEND_GETMEM (which =           is used to read data from within the structure) are            signaled.k  A           Table_B-1__SDA$EXTEND_FORMAT_signaled_conditions_______w  A           Name_______________Value______Meaning___________________  >           SDA$_INVBLKTYP     0x00F480BA "Invalid block type in@                                         specified block." Occurs@                                         when you try to format aA                                         data structure which does_?                                         not contain its type inN@                                         the byte at offset 0x0A.@                                         The PHD (process header)?                                         is an example for this.o@                                         To format the structure,<                                         you must provide the?                                         type name in the typnam 1                                         argument.a              A                                                              B-19e o  e               SDA Callbacks            SDA$EXTEND_FORMATd        7           Table B-1 (Cont.)  SDA$EXTEND_FORMAT signaledaA           ___________________conditions__________________________t  A           Name_______________Value______Meaning__________________   ;           SDA$_INVSUBTYP     0x00F4827A "Invalid subtype in A                                         specified block." This is A                                         the same as the condition_=                                         above for the subtypea>                                         at offset 0x0B. OccursA                                         with data types requiring <                                         a valid subtype only@                                         (types in the range 0x600                                         - 0x7F).  <           SDA$_NOSYMBOLS     0x00F480C2 "No symbols found to@                                         format this block." This<                                         may occur if you try=                                         to format a structure =                                         but the system symbol >                                         table was not yet read@                                         in. It may also occur if>                                         you specify an unknown?                                         type name in the typnamaA           ______________________________argument._________________  A           _______________________________________________________s             EXAMPLEt    OPT$M_TYPE  1            ?           In this example, a PHD (process header) is formatted. 9           Since the PHD does not contain type and subtype              B-20         A                                                     SDA Callbacks A                                                 SDA$EXTEND_FORMAT_        =           information at the expected offsets, the OPT$M_TYPEX@           bit is set in the first, and the type name is supplied           as second argument._                                                                          A                                                              B-21_ _  _               SDA Callbacks_&           SDA$EXTEND_FORMAT_SUBHEADING        A           _______________________________________________________   &           SDA$EXTEND_FORMAT_SUBHEADING  -           Formats and stores a header string.0  A           ________________________________________________________             FORMAT  >           SDA$EXTEND_FORMAT_SUBHEADING  hdrstr, [p1..pn] (VAX)  @           SDA$EXTEND_FORMAT_SUBHEADING  hdrstr, [prmlst] (Alpha)  A           _______________________________________________________:             RETURNSd  :           This callback does not return a condition value.  A           _______________________________________________________s             ARGUMENTS            hdrstr              VMS Usage: char_string%           type:      character string            access:    read only8           mechanism: by descriptor - fixed-length string                      descriptor =           String to be displayed at the top of each new page.R;           The hdrstr argument is the address of a characterp:           string descriptor pointing to the header string.=           The string may contain FAO (Formatted ASCII Output)            directives.D             p1 to pn (VAX only)               VMS Usage: varying_arg&           type:      longword (signed)           access:    read only           mechanism: by valuen@           Values to be passed as FAO directive parameters. These;           arguments are longwords containing the parameterse>           needed by the FAO directives specified in the header             B-22 t  p    A                                                     SDA Callbacks A                                      SDA$EXTEND_FORMAT_SUBHEADINGs        <           string. Up to 17 parameters may be supplied; their@           number and contents depend on the used FAO directives.@           If you do not use FAO directives in the header string,)           you can omit further arguments.              prmlst (Alpha only)c  -           VMS Usage: vector_longword_unsignede(           type:      longword (unsigned)           access:    read only!           mechanism: by referenceB?           List of FAO directive parameters. The prmlst argument.:           is the address of a longword vector wherein each>           longword contains a parameter. The vector must start<           on a longword boundary; the number and contents of@           longwords depend on the used FAO directives. If you do>           not use FAO directives in the header string, you can           omit this argument.e  A           _______________________________________________________d             DESCRIPTIONc?           This callback prepares and stores a header string for_@           further use. The header string is displayed on the top>           of every new page (when you call SDA$EXTEND_NEW_PAGE>           or SDA inserts a page when the screen or the current0           page in the output file becomes full).  <           Formatting occurs via FAO directives. The callback>           invokes the SYS$FAO (VAX) or SYS$FAOL (Alpha) system;           service to format the string. Most FAO directives <           require parameters, they are supplied as arguments?           (VAX) or passed in a vector of longwords (Alpha). The <           callback further invokes SDA$EXTEND_SET_HEADING to&           store the new header string.  >           Note: On Alpha V7, the 64-bit version (SYS$FAO64) is=           not currently supported, only 32-bit FAO directivesA%           and parameters may be used.c  A                                                              B-23n r  u               SDA Callbacks &           SDA$EXTEND_FORMAT_SUBHEADING        7           If you do not want to use FAO directives, you 8           can format the header string with the commands9           or functions provided by your language and call *           SDA$EXTEND_SET_HEADING directly.  7           See the System Service Reference Manual for ai=           description of the SYS$FAO/SYS$FAOL system service,D8           the available FAO directives, and the required           parameters.a  A           _______________________________________________________   #           CONDITION VALUES RETURNED :           This callback returns no condition value. If the8           SYS$FAO/SYS$FAOL system service fails (invalid;           FAO directives or too few parameters supplied), aD=           null string is stored as header; errors returned by_8           SYS$FAO/SYS$FAOL are not passed to the caller.  A           _______________________________________________________i             EXAMPLEr  $  #!UL,                   VA = !XL");  va;    :  /***                                             VAX ***/  <  =     gsd_num; prm_lst[1] = va;             /*** Alpha ***/  <     /***                                          Alpha ***/  8           Formats and stores a header string to which is;           displayed at the top of every page. On Alpha, theo:           arguments are supplied in a vector of longwords.                   B-24 _  _    A                                                     SDA CallbacksEA                                                 SDA$EXTEND_GETMEM_        A           _______________________________________________________s             SDA$EXTEND_GETMEMe  "           Copies data from memory.  A           _______________________________________________________l             FORMAT  7           SDA$EXTEND_GETMEM  inadr, [retadr, len] (VAX)   ;           SDA$EXTEND_GETMEM  inadr, [retadr, len], [phyflg]   '                              (Alpha V6)   ?           SDA$EXTEND_GETMEM64  inadr64, [retadr, len], [phyflg]   )                                (Alpha V7)   A           _______________________________________________________              RETURNSh           VMS Usage: cond_valuee(           type:      longword (unsigned)           access:    write only            mechanism: by valueD  :           All conditions are signaled as warnings as well.  A           _______________________________________________________              ARGUMENTS "           inadr (VAX and Alpha V6)             VMS Usage: address(           type:      longword (unsigned)           access:    read only           mechanism: by value =           Longword holding the 32-bit virtual base address of >           the data you want to copy from memory. This argument>           is used with SDA$EXTEND_GETMEM only; on Alpha, inadr#           must be longword-aligned.h  A                                                              B-25d s  i               SDA Callbacks            SDA$EXTEND_GETMEMa                   inadr64 (Alpha V7)             VMS Usage: address(           type:      quadword (unsigned)           access:    read only           mechanism: by valuei=           Quadword holding the 64-bit virtual base address of >           the data you want to copy from memory. This argument>           is used with SDA$EXTEND_GETMEM64 only; the specified+           address must be longword-aligned.              retadr             VMS Usage: address(           type:      longword (unsigned)           access:    write only !           mechanism: by referencer@           Return address wherein the data should be written. The@           retadr argument is a longword holding the base address?           of a buffer receiving the copied data. This must be a$?           32-bit address in either P0 or P1 space. The argument ;           is optional; if you do not supply it, an internal 5           buffer is used to retrieve the copied data.   @           If you specify this argument, you must also supply the           len argument.   ?           When programming in MACRO-32 or BLISS, you can obtain >           the first four bytes of the copied data in processor           register R1 as well.  
           lens  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only           mechanism: by value 8           Number of bytes to copy. This argument must be=           specified unless the retadr argument was omitted as =           well. The lowest value of len is 4, in other words,c=           the smallest unit to copy is a longword (on VAX and            Alpha).a             B-26 r  S    A                                                     SDA CallbacksmA                                                 SDA$EXTEND_GETMEMt                   phyflg (Alpha only)s  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only           mechanism: by valuee=           Physical address indicator. If you set phyflg to 1,i>           the address given in inadr/inadr64 is interpreted as           physical address.n  A           _______________________________________________________              DESCRIPTIONl<           This callback is a jacket to SDA's general-purpose;           memory access routine SDA$EXTEND_TRYMEM. The onlyn?           difference between them is their behaviour in case ofl@           error: while SDA$EXTEND_TRYMEM returns the error only,=           this callback also signals it as warning condition. <           Unless you have declared a condition handler, this;           causes SDA to display the appropriate message and ?           then return to your code. Use this callback when data <           inaccessibility at the given address is unexpected7           but does prevent the current executed command <           from continuing. Since control is returned to your<           code, you must always check the status returned by           SDA$EXTEMD_GETMEM.  @           On Alpha V7, the input address (inadr64 argument) is a>           64-bit address, allowing you to access every virtual@           address in P0, P1, P2, S0/S1 and S2 space. To indicate?           this, the routine was renamed to SDA$EXTEND_GETMEM64;(?           the 32-bit version SDA$EXTEND_GETMEM is not availablew           on Alpha V7.  6           For more information, see the description of           SDA$EXTEND_TRYMEM.        A                                                              B-27     $               SDA Callbacks            SDA$EXTEND_GETMEM_      A           _______________________________________________________a  #           CONDITION VALUES RETURNED   7           SDA$_SUCCESS       Memory copied successfully   4           SDA$_INVLDADR      Invalid virtual address  <           SDA$_INVRANGE      Invalid address range specified  ?           SDA$_MEMNOTACC     Memory locations not accessible inP:                              override mode (Alpha V7 only)  ?           SDA$_MEMNOTSVD     Specified memory not saved in dumpo!                              file   >           SDA$_NOREAD        Could not access specified memory  @           SDA$_NOTINPHYS     Virtual data not in physical memory  ?           SDA$_NOTVALID      Information not in physical memorye  :           SDA$_OUTSIDPT      Virtual address range exceeds6                              process page table bounds  >           SDA$_PFNNOTMPD     PFN from PTE not mapped by memory'                              descriptor   :           SDA$_REGNOTVALID   Register reference is invalid  ?           SDA$_UNALIGNED     Unaligned address specified (Alpha "                              only)  >           For a detailed description of these condition codes,=           please see the Condition values returned section ofy;           SDA$EXTEND_TRYMEM. Table B-3 contains the numerice<           values for all error codes; if you want to use the<           names listed here, you must define the appropriate           literals yourself.  A           _______________________________________________________t             EXAMPLEr             B-28 y  l    A                                                     SDA CallbacksYA                                                 SDA$EXTEND_GETMEMS          pcbdeft      __PCB my_pcb;        __            PCB)) & 1) return;  <           Assuming that pcbadr contains the address of a PCB@           (process control block), this example moves the entire:           PCB from S0 space into a user buffer for further=           analysis. In case of error, the appropriate messageD?           was already displayed, so there is no more to do than            return.s                                                A                                                              B-29D O  A               SDA Callbacksu            SDA$EXTEND_GET_ADDRESS        A           _______________________________________________________n              SDA$EXTEND_GET_ADDRESS  &           Returns the current address.  A           _______________________________________________________n             FORMAT  (           SDA$EXTEND_GET_ADDRESS  retadr  <           SDA$EXTEND_GET_ADDRESS64  retadr64 (Alpha V7 only)  A           _______________________________________________________a             RETURNSe  :           This callback does not return a condition value.  A           ________________________________________________________             ARGUMENTSn           retadr             VMS Usage: address(           type:      longword (unsigned)           access:    write only !           mechanism: by reference ?           Address of a longword to receive the current address. ;           This argument is used with SDA$EXTEND_GET_ADDRESS            only.   "           retadr64 (Alpha V7 only)             VMS Usage: address(           type:      quadword (unsigned)           access:    write only !           mechanism: by reference ?           Address of a quadword to receive the current address. =           This argument is used with SDA$EXTEND_GET_ADDRESS64            only.              B-30         A                                                     SDA CallbackstA                                            SDA$EXTEND_GET_ADDRESS       A           _______________________________________________________1             DESCRIPTION @           This callback returns the current address. The current>           address is always set by the last EXAMINE, FORMAT or?           VALIDATE command; it may be supplied with the dot (.)e=           character in any command accepting SDA expressions. ;           If you want to allow the current address as valid @           specification in your commands, you can obtain it with           this callback.  5           There is also a way to compute standard SDA <           expressions with this callback in conjunction with=           SDA$EXTEND_PARSECOMMAND and SDA$EXTEND_SET_ADDRESS.            See Section 3.4.  8           On Alpha V7, this callback exists in a version:           supporting 64-bit addresses as well. If you want9           to work in a 64-bit environment, you should use 6           SDA$EXTEND_GET_ADDRESS64. Note that on Alpha8           V7, both callbacks, SDA$EXTEND_GET_ADDRESS and1           SDA$EXTEND_GET_ADDRESS64 are available.   <           Note: Since the current address may change between@           calls of your extension, you should obtain it from SDA>           whenever the user specifies it. Do not store and use1           the same address in different commands.   A           _______________________________________________________   #           CONDITION VALUES RETURNEDn           None.   A           ________________________________________________________             EXAMPLE_  @           This code obtains the current address and saves it for           further use.    A                                                              B-31  n  i               SDA Callbacksd%           SDA$EXTEND_GET_BUGCHECK_MSG         A           _______________________________________________________   %           SDA$EXTEND_GET_BUGCHECK_MSG            (Alpha only)  9           Translates a bugcheck code into the appropriate_"           bugcheck message string.  A           _______________________________________________________s             FORMAT  ;           SDA$EXTEND_GET_BUGCHECK_MSG  code, retbuf, buflen   A           _______________________________________________________              RETURNS   :           This callback does not return a condition value.  A           ________________________________________________________             ARGUMENTS_           code  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only!           mechanism: by reference_8           Longword holding the bugcheck code you want to           translate.             retbuf  &           VMS Usage: ASCIC_char_string%           type:      character string            access:    write only_!           mechanism: by reference 9           Address of a buffer which receives the bugcheck ?           string. The buffer should be large enough to hold the_>           entire message string which may have up to 128 bytes=           in length. Note that this argument is not passed bya;           descriptor, the buffer length is given in buflen.n             B-32 f  d    A                                                     SDA CallbackseA                                       SDA$EXTEND_GET_BUGCHECK_MSGm                   buflen  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only           mechanism: by valuee0           Longword holding the length of retbuf.  A           _______________________________________________________              DESCRIPTION :           Given a bugcheck code, this callback returns the>           corresponding bugcheck message. It allows you easily<           to display the textual form of bugcheck codes. The>           message is returned in ASCIC (Counted ASCII) format.=           On Alpha V7, SDA provides the SHOW BUGCHECK commandD           for the same purpose.   :           All bugcheck codes and messages are hardcoded in?           SDA. If you specify a non-existent bugcheck code, the            message   8                              ** Invalid bugcheck code **  "           is copied to the buffer.  ?           This callback is available on Alpha only, there is no(           replacement on VAX.s  A           _______________________________________________________e  #           CONDITION VALUES RETURNED            None.b  A           _______________________________________________________a             EXAMPLEs      A                                                              B-33n    a               SDA Callbacks %           SDA$EXTEND_GET_BUGCHECK_MSGu          	  prm_lst;   /  Message                           = \"!AC\"");e          =  (int) retbuf;     ;           In this example, a bugcheck code is obtained fromt>           another source and is converted into a user-readable,           text which is displayed on screen.                                                               B-34         A                                                     SDA CallbackseA                                        SDA$EXTEND_GET_CURRENT_PCBi        A           _______________________________________________________f  4           SDA$EXTEND_GET_CURRENT_PCB-(Alpha V7 only)  9           Returns the PCB address of the current process.X  A           _______________________________________________________              FORMAT  ,           SDA$EXTEND_GET_CURRENT_PCB  pcbadr  A           _______________________________________________________l             RETURNS   :           This callback does not return a condition value.  A           _______________________________________________________i             ARGUMENTSs           pcbadr             VMS Usage: address(           type:      longword (unsigned)           access:    write only !           mechanism: by reference :           Address of a longword wherein the PCB address is           written.  A           _______________________________________________________s             DESCRIPTIONm?           This callback returns the PCB (process control block)o<           address of the current process. This may be useful?           if you want to provide the current process as defaulta<           process in your commands (like SDA does in some of=           its commands). Since the current process may changeu<           between calls of your extension, you should always>           use this callback when you want to reference data in1           current process' PCB (see Section 3.3).n  A                                                              B-35  v  d               SDA Callbacks $           SDA$EXTEND_GET_CURRENT_PCB        <           This callback exists on Alpha V7 only. On previous<           versions, as well as on OpenVMS VAX, the following/           routine obtains the same information:_             SYM: .ascid   /PCB/U  7                .entry   SDA_EXTEND_GET_CURRENT_PCB,^m<>                 pushab   SYMNAM4                calls    #1,g^SDA$EXTEND_SYMBOL_VALUE!                movl     r1,@4(ap)                 ret  =           This code invokes SDA$EXTEND_SYMBOL_VALUE to obtaina<           the value of SDA's PCB symbol. This symbol contain>           always the address of the current process' PCB. This<           value is written back to the longword specified by>           the caller. The routine is called in the same way as%           SDA$EXTEND_GET_CURRENT_PCB.   A           ________________________________________________________  #           CONDITION VALUES RETURNED            None.T  A           ________________________________________________________             EXAMPLE_  :           This code will copy the current PCB address into           pcbadr;r                               B-36 E  G    A                                                     SDA Callbacks(A                                           SDA$EXTEND_GET_DYN_INFO,        A           ________________________________________________________  .           SDA$EXTEND_GET_DYN_INFO-(Alpha only)  9           Returns pointers to SDA's internal dynamic data            tables.n  A           _______________________________________________________s             FORMAT  1           SDA$EXTEND_GET_DYN_INFO  offtab, strtab.  A           _______________________________________________________              RETURNST  :           This callback does not return a condition value.  A           _______________________________________________________              ARGUMENTS            offtab             VMS Usage: address(           type:      longword (unsigned)           access:    write onlym!           mechanism: by references?           Address of a longword which receives the base addresst9           of a table containing word-sized offsets to the            strings in strtab.             strtab             VMS Usage: address(           type:      longword (unsigned)           access:    write onlys!           mechanism: by referenceq?           Address of a longword which receives the base addressh<           of a table containing ASCIC strings with the names;           of all dynamic data structures. These strings arem3           addressed by the offsets given in offtab.N  A                                                              B-37i d                  SDA Callbacks !           SDA$EXTEND_GET_DYN_INFOe      A           _______________________________________________________e             DESCRIPTION <           In order to translate type codes stored in dynamic>           data structures (these structures are mostly located?           in paged or non-paged pool), SDA contains two tables: =           the first table contains word-sized byte offsets tom<           ASCIC (Counter ASCII) strings stored in the second<           table. This callback returns the base addresses of;           these tables, allowing you to translate a dynamicy;           structure's type code into the corresponding namei           string.,  8           The contents of the tables whose addresses are9           returned are readable from user mode. Note that ?           subtype codes cannot be translated with these tables.y  <           All type codes and the related names are stored in           module $DYNDEF.   >           The Example section contains code showing the use of@           this callback. See also the description of SDA$EXTEND_?           FORMAT for more information about types and subtypes.   ?           This callback is available on Alpha only, there is noh           replacement on VAX.   A           _______________________________________________________m  #           CONDITION VALUES RETURNED            None.E  A           _______________________________________________________s             EXAMPLEd  
   .long     0 
   .long     0u                 B-38 s       A                                                     SDA CallbacksiA                                           SDA$EXTEND_GET_DYN_INFOi        &    .entry   GET_TYPSTR,^m<r2,r3,r4,r5>    pushal   STRTAB    pushal   OFFTAB(    calls    #2,g^SDA$EXTEND_GET_DYN_INFO3    movzbl   4(ap),r1        ; r1 = type code (byte)s:    movzwl   OFFTAB[r1],r2   ; r2 = word-offset into STRTAB:    movab    STRTAB[r2],r3   ; r3 = address of ASCIC string3    movzbl   (r3)+,r4        ; r4 = length of string :    movc3    r4,(r3),@8(ap)  ; copy string into user buffer2    clrb     (r3)            ; make an ASCIZ string    ret  @           Given a type code as first argument, this routine uses<           the SDA$EXTEND_GET_DYN_INFO callback to obtain the=           base addresses of the tables described above and to >           locate the appropriate string. This string is copied<           into the user buffer whose address is given in the=           second argument. In order to make processing from Co>           easier, the string is converted from ASCIC to ASCIZ.;           If you do not use C, you can remove the clrb (r3)n?           instruction and return the resultant string length asc1           additional argument or as ASCIC string.,                                    A                                                              B-39     h               SDA CallbacksE           SDA$EXTEND_GET_HEADER         A           _______________________________________________________   ,           SDA$EXTEND_GET_HEADER-(Alpha only)  >           Returns pointers to the dump header and to the error           log buffers.  A           ________________________________________________________             FORMAT  ;           SDA$EXTEND_GET_HEADER  hdrbuf, hdrlen, errlogbuf,   *                                  errloglen  A           _______________________________________________________              RETURNS   :           This callback does not return a condition value.  A           _______________________________________________________o             ARGUMENTSo           hdrbuf             VMS Usage: address(           type:      longword (unsigned)           access:    write only$!           mechanism: by referencec?           Address of a longword to receive the dump header basep           address.             hdrsiz             VMS Usage: address(           type:      longword (unsigned)           access:    write only !           mechanism: by referencep@           Address of a longword to receive the dump header size.             errlogbuf              VMS Usage: address(           type:      longword (unsigned)           access:    write only              B-40 U  i    A                                                     SDA Callbacks A                                             SDA$EXTEND_GET_HEADER         !           mechanism: by referenced>           Address of a longword to receive the errorlog buffer           base address.u             errloglen              VMS Usage: address(           type:      longword (unsigned)           access:    write onlyu!           mechanism: by reference_>           Address of a longword to receive the errorlog buffer           size.   A           _______________________________________________________a             DESCRIPTION ?           This callback returns pointers to the dump header ande<           to the errorlog buffers. For both data structures,?           their base address and length (in bytes) is returned.B  >           The dump header contains information about the crash>           (date and time when the crash occured, size and type@           of the dump stored in the dumpfile, the bugcheck code,:           processor registers and others). The dump header=           is held by SDA in virtual memory for the entire SDA @           session. You can use the SHOW CRASH command to display:           its contents in a readable way. You can use SHOW3           HEADER to display it as unformatted dump._  9           The errlog buffers contain errorlog informationE/           not yet written to the errorlog file,d8           SYS$ERRORLOG:ERRLOG.SYS. The system parameters?           ERRORLOGBUFFERS and ERLBUFFERPAGES determine the sizeT           of this area.   >           The hdrbuf and errlogbuf arguments point to internal<           SDA buffers, readable from user mode. Although the<           contents of these buffers is writable as well, you@           should avoid to change information therein. Otherwise,=           the SDA commands SHOW CRASH and SHOW HEADER may notr           work correctly.d  A                                                              B-41w e  l               SDA Callbackse           SDA$EXTEND_GET_HEADERl        <           The contents of the buffers listed above is useful9           only when analyzing a system dump. On a running 9           system, these buffers exist as well, but do nots@           contain useful data. Therefore, you should always call=           SDA$EXTEND_ON_CURRENT_SYSTEM before you invoke thiss           callback.c  ?           This callback is available on Alpha only, there is noA>           replacement on VAX. SDA's SHOW HEADER command may be1           used to display the dump header on VAX.   A           _______________________________________________________A  #           CONDITION VALUES RETURNED_           None._  A           _______________________________________________________              EXAMPLEu      8           This example uses SDA$EXTEND_GET_HEADER to get;           pointers to the dump header and errorlog buffers,a0           as well information about their sizes.                                         B-42 o       A                                                     SDA Callbacks A                                            SDA$EXTEND_GET_HW_NAME         A           _______________________________________________________   -           SDA$EXTEND_GET_HW_NAME-(Alpha only)t  -           Returns the system's hardware name.D  A           _______________________________________________________p             FORMAT  (           SDA$EXTEND_GET_HW_NAME  retbuf  A           _______________________________________________________n             RETURNS   :           This callback does not return a condition value.  A           _______________________________________________________D             ARGUMENTSa           retbuf  &           VMS Usage: ASCIC_char_string%           type:      character stringy           access:    write onlyi!           mechanism: by referenceu>           Address of a buffer which receives the hardware name<           string. This buffer should provide enough space to;           accomodate the largest possible hardware name (upU<           to 80 bytes). Note that this argument is passed by'           reference, not by descriptor.   A           _______________________________________________________              DESCRIPTION ?           This callback returns the system hardware name stored ?           at global location EXE$GT_HWNAME. If this location is >           unreadable (as it may be the case with an incomplete;           system dump), SDA uses the system marketing model$?           number (SMMN) from the SCB (system control block) andn<           an internal table to obtain the hardware name. The=           string is returned in ASCIC (Counted ASCII) format._  A                                                              B-43G B  H               SDA Callbacks             SDA$EXTEND_GET_HW_NAME        ;           This callback is available on Alpha only. On VAX, <           you can obtain the hardware name directly from the7           location shown above (see 'Example' section)._  A           _______________________________________________________w  #           CONDITION VALUES RETURNEDw           None.   A           _______________________________________________________              EXAMPLEg    :                   /*                              Alpha */  8                 /*                                VAX */  /           ptr);        /* Get ptr to hw name */   A  /*                                                  Copy name */f  :           In this example, the hardware name is written to;           buffer hw_nam_buf for further use. The last threem8           lines show how to emulate the callback on VAX.                                         B-44 a       A                                                     SDA Callbacks A                                          SDA$EXTEND_GET_IMAGE_OFF         A           _______________________________________________________H  /           SDA$EXTEND_GET_IMAGE_OFF-(Alpha only)   4           Maps an image and returns image and offset           information.  A           _______________________________________________________d             FORMAT  ;           SDA$EXTEND_GET_IMAGE_OFF  basadr, imgptr, subptr,_  *                                     offset  A           _______________________________________________________o             RETURNSm           VMS Usage: bitmsk "           type:      mask_longword           access:    write only            mechanism: by value(  ?           A bitmask containing additional information about theW<           nature of the resultant image or image section. If<           0 is returned (no bits are set), the given virtual;           address could not be mapped in any of the current 8           process activated or system loaded images. The4           following bits may be set in the bit mask:  A           _______________________________________________________ &                                Bitmask$                                valueA           Bit_Name_____________(hex)______Description____________   ;           SDA$M_VALID          0001       An image could be_<                                           mapped (status OK)      A                                                              B-45  D  a               SDA CallbacksD"           SDA$EXTEND_GET_IMAGE_OFF      A           _______________________________________________________t&                                Bitmask$                                valueA           Bit_Name_____________(hex)______Description____________   >           SDA$M_PROCESS        0002       If set, the image is<                                           process-activated,=                                           otherwise, it is an <                                           system (executive)<                                           image in S0 space.  >           SDA$M_SLICED         0004       If set, the image is?                                           sliced, otherwise, its8                                           is not sliced.  <           SDA$M_COMPRESSED     0008       If set, the mappedA                                           section is a compressed_<                                           image data section:                                           (sliced process-A                                           activated images only).R  @           SDA$M_ISD_INDEX      0070       These 3 bits determine:                                           the section type;                                           in case of sliced A           ________________________________executive_images.______   <           Note that the bit names shown in the table are not?           defined anywhere; if you want to use it in your code, <           you must define the appropriate literals yourself.  A           _______________________________________________________t             ARGUMENTS            basadr             VMS Usage: address(           type:      longword (unsigned)           access:    read only           mechanism: by value 8           A longword holding the virtual address to map.             imgptr             VMS Usage: address(           type:      longword (unsigned)           access:    write only              B-46    3    A                                                     SDA CallbacksEA                                          SDA$EXTEND_GET_IMAGE_OFF         !           mechanism: by reference <           The address of a longword receiving a pointer to a=           data structure containing image-related information (           (see the Description section).             subptr             VMS Usage: address(           type:      longword (unsigned)           access:    write only !           mechanism: by referencec<           The address of a longword receiving a pointer to a?           data structure containing additional information (fort;           sliced images only; see the Description section).              offset             VMS Usage: address(           type:      longword (unsigned)           access:    write onlyE!           mechanism: by reference_=           The address of a longword receiving the byte offset ;           from the image's base address or - in the case of >           sliced images - from the appropriate image section's           base address.   A           _______________________________________________________r             DESCRIPTION :           This callback provides an interface to SDA's MAP8           command. Given a virtual address, the callback@           searches the loaded execlets data structures and user-<           activated images data structures to find the image>           section which the address belongs to. If an image is>           found, information about it can be obtained from the9           data structures addressed by imgptr and subptr._  <           The requested address can be found in one of three<           areas: in an image section from a loaded executive<           image (also called execlec), in a resident section?           for an installed user-activated image, or in a normal_<           user-activated image. The first two cases apply to  A                                                              B-47  e                  SDA Callbacks "           SDA$EXTEND_GET_IMAGE_OFF        ?           system (S0) addresses only, the third applies to per-s)           process (P0/P1) addresses only.n  8           On Alpha, the following kinds of images exist:  >           o  Executive images. An executive image (also calledA              system image) is loaded during system initialization ?              or system startup. It is mapped contiguously in S0r              space.b  @              For this type of image, imgptr points to the LDRIMG=              (loaded executive image block) and subptr is not               used.  @           o  Sliced executive images. This is an executive image<              linked in a special way (LINK/SECTION_BINDING),@              allowing the executive to map its image sections atA              different non-contiguous addresses. This is required <              to load the image into special, memory-resident3              areas called granularity hint regions.s  @              For this type of image, the SDA$M_SLICED bit is setA              in the returned bitmask, imgptr points to the LDRIMG-@              (loaded executive image block) and subptr points to?              the appropriate LDRIMG_ISD (loaded executive images'              section descriptor block).l  @           o  Process-activated images. They are mapped as result:              of image activation requested by the process,@              usually in response to a user-entered command. They@              may be either main images or shareable images; most,              of them are mapped in P0 space.  =              For this type of image, the SDA$M_PROCESS bit is >              set in the returned bitmask, imgptr points to the?              appropriate IMCB (per-process image control block)e$              and subptr is not used.  9           o  Sliced process-activated images. Like sliced @              executive images, they are linked in a way allowing>              them to be loaded into a special granularity hint>              region by installing them memory-resident. Unlike=              normal shareable images, their code is mapped at_<              S0 addresses, where shareable data sections are             B-48         A                                                     SDA Callbacks A                                          SDA$EXTEND_GET_IMAGE_OFF         @              mapped in a reserved region in P1 space (the system?              parameter IMGREG_PAGES determines the size of thisE              region).m  :              For this type of image, the SDA$M_PROCESS and@              SDA$M_SLICED bits are set in the returned bit mask,A              imgptr points to the IMCB (per-process image control A              block) and subptr points to the corresponding KFERESn6              (memory-resident known file entry) block.  ?           The following table gives an overview about the imagem=           types, the address spaces at which they are mapped,a<           the bits set in the returned bitmask, and the data9           structures addressed by imgptr and subptr. Noter=           that the SDA$M_ prefix is omitted for the reason ofe?           shortness. In addition, note that the SDA$M_VALID bitm           is always set.  A           _______________________________________________________ .                                    Bits set inC           Image_type________AdrSpc_return_status___imgptr____subptrc  >           Executive image   S0     -               LDRIMG    -  D           Sliced exec.      S0     SLICED          LDRIMG    LDRIMG_@           image                                              ISD  >           Process-          P0     PROCESS         IMCB      -           activated_           image   C           Process-act.      S0,P1  PROCESS+SLICED  IMCB      KFERESsA           sliced_image___________________________________________   @           Note that imgptr and subptr do not point to the actual?           data structures in S0 or P1 space, instead they point,?           to buffers wherein the data structures were copied by 9           SDA. These buffers are readable from user mode._  8           In case of sliced executive images, the SDA$M_=           INDEX bits determine the type of image section. The_,           following table lists these types:  A                                                              B-49  y                  SDA Callbacks "           SDA$EXTEND_GET_IMAGE_OFF      A           _______________________________________________________tA           Bitmask____Section_type________________________________   /           00000000   Nonpaged read-only sectionw  0           00000010   Nonpaged read/write section  ,           00000020   Paged read-only section  -           00000030   Paged read/write section.  "           00000040   Fixup section  =           00000050   Initialization section (used only during A           ___________image_initialization)_______________________   9           In case of sliced process-activated images, the :           SDA$M_COMPRESS bit determine the section type in8           conjunction with the KFERES$L_SECTION_TYPE and?           KFERES$L_SECTION_FLAGS longwords in the KFERES block:   >           o  If the SDA$M_COMPRESS bit is cleared, the section?              is a read-only, memory-resident code section in S0 ?              space (part of the resident image granularity hintr              region).c  9           o  Otherwise, if the SDA$M_COMPRESS is set, the_@              KFERES$L_SECTION_TYPE longword determines the type:  A              ____________________________________________________eA              Value_____Section_type______________________________,  .              0         Compressed data section  -              1         Read-only data sectiont  ,              2         Pageable code section  6              3         DZRO (demand zero) data section  .              4         Read/write data section  A              5_________Address_(linkage)_data_section____________   3           o  If the KFERES$_SHAREABLE bit is set in >              KFERES$L_SECTION_FLAGS, the section is shareable;>              otherwise, it is not. In order to be shareable, a<              section must have the SHR attribute set and the>              image must be installed with /OPEN/HEADER/SHARED,?              and for writable sections, with /WRITABLE as well.G             B-50 e  a    A                                                     SDA CallbackszA                                          SDA$EXTEND_GET_IMAGE_OFFa        ?           See the description of the SDA's MAP command for moree           information.  =           This callback is available on Alpha only; it is noth=           required on VAX since there are no sliced images on            this platform.  A           _______________________________________________________   #           CONDITION VALUES RETURNED <           Only bit 0 is used to indicate a condition. If bit>           0 is set, the specified address could be mapped into<           an image and the remaining bits contain additional@           information about this image. If bit 0 is cleared, the=           specified address could not be mapped and all othere@           bits, as well imgptr and subptr, do not contain useful           information.  A           _______________________________________________________              EXAMPLE     *subptr,        *offset;D  >  =  SDA$EXTEND_GET_IMAGE_OFF(0x22000,&imgptr,&subptr,&offset);  :           This call obtains information about the image at9           address 0x22000. Since this is a P0 address, itR/           belongs to a process-activated image._                      A                                                              B-51a e  e               SDA Callbackst           SDA$EXTEND_GET_INPUT        A           _______________________________________________________i             SDA$EXTEND_GET_INPUT  &           Obtains input from the user.  A           _______________________________________________________              FORMAT  :           SDA$EXTEND_GET_INPUT  outbuf, [prompt], [outlen]  A           _______________________________________________________D             RETURNSn           VMS Usage: cond_valuet(           type:      longword (unsigned)           access:    write only_           mechanism: by valueM  A           ________________________________________________________             ARGUMENTS_           outbuf              VMS Usage: char_string%           type:      character stringd           access:    write only_8           mechanism: by descriptor - fixed-length string                      descriptor >           String that SDA$EXTEND_GET_INPUT gets from the input9           device. The outbuf argument is the address of a <           character string descriptor pointing to the buffer?           into which the text received from the input device isd           written.             prompt              VMS Usage: char_string%           type:      character stringe           access:    read only8           mechanism: by descriptor - fixed-length string                      descriptor_             B-52         A                                                     SDA CallbacksrA                                              SDA$EXTEND_GET_INPUT         7           Prompt message that is displayed on the input ;           device. This argument is optional; if you omit itt=           and prompting must occur, the string DATA>  is usedl           instead.             outlen  "           VMS Usage: word_unsigned$           type:      word (unsigned)!           access:    by reference            mechanism:<           Number of bytes written into outbuf. This argument<           is the address of an unsigned word containing this:           number. It is optional; if you do not supply it,=           information about the returned string length is not            given.  A           ________________________________________________________             DESCRIPTION_>           This routine is the SDA replacement for the general-@           purpose input routine LIB$GET_INPUT. You should always<           use this routine since it provides access to user-:           defined keys (defined with DEFINE/KEY) and SDA's)           enhanced command recall buffer.)  ?           The routine takes the same arguments as LIB$GET_INPUT ?           and internally invokes SMG$READ_COMPOSED_LINE to read,=           data from keyboard or file. If you're unsure how ito;           behaves, look at the RTL Screen Management (SMG$)m           manual.o  A           _______________________________________________________   #           CONDITION VALUES RETURNED   :           SS$_NORMAL         Normal successful completion.  ?           RMS$_EOF           End of file detected or <CTRL> <Z>_'                              was typed.   A                                                              B-53m                    SDA Callbacks            SDA$EXTEND_GET_INPUT          <                              Any other condition returned by4                              SMG$READ_COMPOSED_LINE.  A           _______________________________________________________   2           EXAMPLE 2.3.1 contains a code example of             SDA$EXTEND_GET_INPUT.                                                                          B-54 w  e    A                                                     SDA CallbacksgA                                         SDA$EXTEND_GET_LINE_COUNTn        A           _______________________________________________________e  3           SDA$EXTEND_GET_LINE_COUNT-(Alpha V7 only)n  )           Returns the current line count.a  A           _______________________________________________________              FORMAT  +           SDA$EXTEND_GET_LINE_COUNT  lincnt_  A           _______________________________________________________              RETURNSv  :           This callback does not return a condition value.  A           _______________________________________________________d             ARGUMENTS            lincnt             VMS Usage: address(           type:      longword (unsigned)           access:    write only !           mechanism: by reference :           Address of a longword receiving the current line           count.  A           _______________________________________________________              DESCRIPTION ;           This callback returns the current line count. The_?           line count is used by SDA to maintain a page-oriented :           display. Whenever the line count reaches the end<           of current page, SDA invoke SDA$EXTEND_NEW_PAGE to*           perform page-related operations.  >           You can use the SDA$EXTEND_ENSURE callback to ensure?           that a required number of lines is available. If they0?           aren't, SDA$EXTEND_ENSURE invokes SDA$EXTEND_NEW_PAGE ?           to insert a new page. In contrast, this callback lets @           you obtain the current line position without inserting  A                                                              B-55o s  c               SDA Callbacks #           SDA$EXTEND_GET_LINE_COUNTc        =           a new page, even if the current page end is already            reached.  ?           This callback is available on Alpha V7 only, there isE=           no replacement on earlier Alpha VMS versions and on            VAX.  A           _______________________________________________________s  #           CONDITION VALUES RETURNED_           None.x  A           _______________________________________________________t             EXAMPLE     ?           This will return the current line count into longword            lines.                                                     B-56 _  _    A                                                     SDA Callbacks A                                                SDA$EXTEND_HANDLERw        A           _______________________________________________________u             SDA$EXTEND_HANDLER  0           A callback to SDA's condition handler.  A           _______________________________________________________)             FORMAT  -           SDA$EXTEND_HANDLER  sigarg, mecharg   A           _______________________________________________________              RETURNS   :           This callback does not return a condition value.  A           _______________________________________________________              ARGUMENTS            sigarg             VMS Usage: address(           type:      longword (unsigned)           access:    read only!           mechanism: by referencey<           A longword containing a pointer to the condition's?           signal array. This argument is passed to your handlerl           as first argument.             mechargr             VMS Usage: address(           type:      longword (unsigned)           access:    read only!           mechanism: by reference <           A longword containing a pointer to the condition's:           mechanism array. This argument is passed to your%           handler as second argument.n  A                                                              B-57r    -               SDA Callbacksl           SDA$EXTEND_HANDLER      A           ________________________________________________________             DESCRIPTION_@           This callback provides a way to invoke SDA's condition9           handler. You can either establish it as defaultv?           condition handler or invoke it from your own handler. ?           This may be useful if you must take special action int?           case of a condition, but let SDA perform the standards>           condition processing (including the display of error?           messages). In your handler, you may take all required =           actions and invoke SDA$EXTEND_HANDLER as last step.e@           Since SDA establishes this handler as default, you may=           also simply resignal the condition (see Section 3.5            for an example).  0           SDA$EXTEND_HANDLER behaves as follows:  @           o  It first invokes SYS$PUTMSG to obtain the condition9              message text and displays them on SYS$ERROR.   :           o  If the condition had a severity of success or?              warning, the handler terminates with SS$_CONTINUE, ;              passing control back after the point where thee               condition occurred.  ;           o  In case of error severity, the handler unwindsa<              the condition, causing the current procedure to<              terminate and pass control to the caller of the>              procedure wherein the condition occurred. In mostA              cases, this will terminate your extension and returnD!              control back to SDA.e  :           o  If the condition had a severity of fatal, the<              handler resignals the condition, causing SDA to              abort.a  ;           SDA establishes this handler by default before it <           invokes your extension. If you do not want to take@           further action in case of conditions, there is no need=           to establish any handler again from your extension.l?           All conditions signaled by your extension are trappedm@           by SDA's handler which behaves in the same way as with&           conditions generated by SDA.             B-58 u  e    A                                                     SDA Callbacks_A                                                SDA$EXTEND_HANDLER)        @           Note: SDA$EXTEND_HANDLER invokes SYS$PUTMSG to display<           error messages. Therefore, you must invoke it from#           executive or kernel mode.r  A           _______________________________________________________r  #           CONDITION VALUES RETURNEDm           None.   A           _______________________________________________________i             EXAMPLEi  =           This will establish SDA's condition handler in yourr>           code. By doing so, you change the handlers behaviour;           in case of error and fatal conditions: in case ofm@           error, control is not longer returned to SDA, instead,?           it is passed to the procedure wherein the handler was =           established. When a fatal condition occurs, SDA not->           longer terminates; instead your extension terminates2           only, and control is passed back to SDA.                                      A                                                              B-59                     SDA Callbacks #           SDA$EXTEND_LIB$INS_DECODE_        A           _______________________________________________________h  #           SDA$EXTEND_LIB$INS_DECODE_  +           Decodes Alpha 21x64 instructions.   A           _______________________________________________________a             FORMAT  ;           SDA$EXTEND_LIB$INS_DECODE  inadr, retbuf, retlen,i  -                                      [symrtn]o  A           _______________________________________________________n             RETURNSy           VMS Usage: cond_value.(           type:      longword (unsigned)           access:    write only            mechanism: by valuet  A           _______________________________________________________a             ARGUMENTS            inadrd             VMS Usage: address(           type:      longword (unsigned)           access:    modify !           mechanism: by referencet>           Address of a longword pointing to the instruction to<           be decoded. This address must be longword-aligned.8           It is updated to point to the next instruction>           before the callback returns. This allows you to call>           SDA$EXTEND_LIB$INS_DECODE from within a loop without!           manually setting inadr.E             retbuf              VMS Usage: char_string%           type:      character string            access:    write only              B-60 C       A                                                     SDA Callbacks A                                         SDA$EXTEND_LIB$INS_DECODEe        8           mechanism: by descriptor - fixed-length string                      descriptort=           Buffer to receive the decoded assembler instructione=           string. This argument is the address of a characters8           string descriptor pointing to the buffer which@           receives the decoded assembler instruction. The buffer?           should provide at least 40 bytes of space; if you usec;           a symbolization routine, you may need more space.              retlen             VMS Usage: address(           type:      longword (unsigned)           access:    write onlyT!           mechanism: by reference_;           Address of a longword receiving the length of thei$           string returned in retbuf.             symrtn             VMS Usage: procedure$           type:      procedure value1           access:    call without stack unwinding !           mechanism: by reference <           Symbolization routine address. The symrtn argument?           is a longword holding this address. The symbolizatione>           routine is used to symbolize offsets (displacements)?           in instructions with memory-operand or branch-operande:           format. See section Symbolization routine below.  A           _______________________________________________________a             DESCRIPTIONC;           This callback translates Alpha 21x64 opcodes into >           the corresponding assembler (MACRO-64) instructions.6           SDA invokes the callback internally with the=           EXAMINE/INSTRUCTION command; you can use it in your ;           extension to translate instructions at particularM           addresses.  A                                                              B-61                     SDA Callbacks_#           SDA$EXTEND_LIB$INS_DECODE         =           When translating PAL function codes, note that only0<           function codes used by OpenVMS are recognized; PAL=           function codes used by DEC OSF/1 (Digital UNIX) andc'           Windows NT are not processed.n  :           Note: This callback performs no memory checks at;           the address given in inadr. Before you invoke thet;           callback, you must use one of SDA's memory access <           routines to ensure that you can read the opcode at=           the given address. You should first copy the entire <           block of instructions you want to translate into a>           user-supplied buffer and translate instructions from=           this buffer only. This is especially important whenT=           analyzing the running system since some code may be =           protected against user mode, resulting in an access -           violation when trying to decode it._  8           This routine exists on Alpha only, there is no?           replacement on VAX. Note that this routine can decodeb>           Alpha 21x64 (MACRO-64) instructions only; you cannot0           use it to decode VAX MACRO-32 opcodes.             Symbolization routine_  9           To symbolize displacements in branch-operand or <           memory-operand instructions, the callback provides=           the symrtn argument. This is the address of a user-e9           supplied symbolization routine which translatesr;           16- or 21-bit signed displacements (offsets) into :           corresponding symbol names. You may first invoke:           SDA$EXTEND_ADD_SYMBOL or SDA$EXTEND_READ_SYMFILE;           to define and read symbols, and later SDA$EXTEND_o8           SYMBOLIZE in the symbolization routine to show-           displacement values by their names.*  7           The symbolization routine is invoked with the2           following arguments:  @           o  First argument: a longword containing the 16-bit or@              21-bit signed displacement value (passed by value);             B-62 t  t    A                                                     SDA Callbacks A                                         SDA$EXTEND_LIB$INS_DECODE         A           o  Second argument: a longword containing the processor_8              register number (0...32) (passed by value);  >           o  Third argument: a longword pointing to the output>              buffer descriptor (passed \by descriptor - fixed-'              length string descriptor);T  ?           o  Fourth argument: the address of a longword holding_?              the length of the output string given in the thirdM,              argument (passed by reference).  ?           This routine is invoked for instructions with memory-n=           operand or branch-operand format only. Instructions_8           with memory-operand format use a 16-bit signed+           displacement and are of the form:   ,                              ins Ra,disp(Rb)  >           Instructions with branch-operand format use a 21-bit2           signed displacement and are of the form:  (                              ins Ra,disp  <           The branch-operand format is a special form of the>           memory-operand format where the program counter (PC)?           is used instead of a general-purpose ('Rb') register.e  <           Note: The symbolization routine is not invoked for=           instructions with special memory-operand 'function' :           format (e.g. MB, FETCH, FETCH_M, EXCB or TRAPB).  >           The purpose of this routine is to replace the 16- or=           21-bit displacement value (disp in the instructions >           above) with a meaningful symbol name. The routine is=           called for both formats (memory-operand and branch-a;           operand); to distinguish between them, SDA passesg;           the reserved register value 32 in case of branch-u>           operand format, whereas the register number from the=           instruction (in range 0...31) is passed for memory-y           operand format.   A                                                              B-63b o  y               SDA Callbacks #           SDA$EXTEND_LIB$INS_DECODE         =           The symbolization routine must append its output toy=           the string whose descriptor address is given in thes:           third argument. The fourth argument contains the>           current string length before the routine is invoked;>           the routine must update it with the resultant string1           length when the symbolization was done._  :           In case of successful symbolization, the routine2           must return a non-zero value. Otherwise,<           SDA$EXTEND_LIB$INS_DECODE assumes that nothing was?           appended to the output string and displays the offseta           as hexadecimal value.n  A           _______________________________________________________   #           CONDITION VALUES RETURNEDi  :           SS$_NORMAL         Normal successful completion.  <           LIB$_NOINSTRAN     Could not translate instruction-           (2)                (invalid opcode)T  >           LIB$_NOSPACE (4)   Not enough space in output buffer  -           LIB$_INVREG (6)    Invalid registerE  ;           LIB$_INVCLASS (8)  Invalid opcode class or format   =           Note that these LIB$ message codes are not declared <           in module $LIBDEF; if you want to use it, you must>           declare the appropriate literals yourself, using the.           integer values given in parentheses.  A           ________________________________________________________             EXAMPLE_  	  address)_  !  retlen,       argvec[2], locadr;s  :  =  SDA$EXTEND_GETMEM(address,&locadr); /* Fetch memory */             B-64         A                                                     SDA Callbacks A                                         SDA$EXTEND_LIB$INS_DECODE         #  !=      SS$_NORMAL) return status;_  A  =  SDA$EXTEND_LIB$INS_DECODE(&locadr,&bufdsc,&retlen,symbolize);_  =  !=      SS$_NORMAL) return status;     /* Return on error */y  C  =     address; argvec[1] = &bufdsc;    /* Setup argument vector */_  8  !AS",argvec);                          /* Print line */    SS$_NORMAL;  E  offset,            int reg, struct dsc$descriptor *out, int *outlen)_    workbuf[8];    8   /*                                 Try to symbolize */    ?           length) return 0;    /* No success, let SDA decode */_  :  =                       0;       /* Build ASCIZ string */  ,  !=   32)                         /* Memory-            format instruction? */  B           /*                         Yes, include register (Rb) */  =                 /*                   Append to symbol name */n  A  =               strlen(symbuf);  /* Set our descriptor length */_  B                /*                    Append to given descriptor */    =   out->dsc$w_=           length;           /* Set resultant output length */m  B  1;                               /* OK, symbolization was done */  8           Given an address as input, the routine decode_:           and_print tries to fetch the instruction at this  A                                                              B-65                     SDA Callbackse#           SDA$EXTEND_LIB$INS_DECODEr        >           address, invokes SDA$EXTEND_LIB$INS_DECODE to decode=           it and finally displays a line containing the givenb>           address and the decoded instruction with SDA$EXTEND_9           PRINT. Remember that you should copy the memory =           containing the instruction yourself before invoking_$           SDA$EXTEND_LIB$INS_DECODE.  :           For instructions with memory-operand and branch->           operand format, a symbolization routine is provided.?           This routine uses SDA$EXTEND_SYMBOLIZE to convert the >           displacement into a symbol name, supplies a register<           name (for memory-operand instructions) and appends1           this information to the initial string._  5           If the symbolization fails for some reason, 8           the routine returns 0, telling SDA to show the-           displacement in hexadecimal format.                                                          B-66         A                                                     SDA Callbacks A                                               SDA$EXTEND_NEW_PAGE_        A           _______________________________________________________E             SDA$EXTEND_NEW_PAGEk             Inserts a new page.   A           _______________________________________________________              FORMAT             SDA$EXTEND_NEW_PAGEg  A           ________________________________________________________             RETURNS   :           This callback does not return a condition value.  A           ________________________________________________________             ARGUMENTS              None.   A           _______________________________________________________r             DESCRIPTIONc;           This callback inserts a new page into the current            output stream.  =           In screen mode, the screen is erased, the cursor isn?           set to the 'home' position, and the subheader (if one @           was defined with SDA$EXTEND_SET_HEADING) is displayed.=           On Alpha only, if a heading routine was established ?           with SDA$EXTEND_SET_HEADING_ROUTINE, it is invoked asn           well.i  >           In file mode (output was redirected to a file), a FF@           (form-feed) character, followed by a header containing;           SDA's version, a time stamp, the current (already =           incremented) page number and the subheader (if any) 9           are written to the file. The heading routine is            invoked as well.  A                                                              B-67     d               SDA Callbacks            SDA$EXTEND_NEW_PAGEt        ?           See Section 3.2 for more information about SDA outputs           modes.  A           _______________________________________________________r  #           CONDITION VALUES RETURNED            None.d  A           _______________________________________________________a             EXAMPLE   =           A new page is displayed or inserted into the output            file.                                                                B-68 i  l    A                                                     SDA Callbacks A                                      SDA$EXTEND_ON_CURRENT_SYSTEMn        A           _______________________________________________________p  3           SDA$EXTEND_ON_CURRENT_SYSTEM-(Alpha only)o  ?           Checks whether the current system or a system dump ise           analyzed.T  A           _______________________________________________________              FORMAT  &           SDA$EXTEND_ON_CURRENT_SYSTEM  A           _______________________________________________________n             RETURNSr"           VMS Usage: boolean value(           type:      longword (unsigned)           access:    write onlyn           mechanism: by value   ;           1 if the analysis source is the current (running) 1           system; 0 in the case of a system dump.o  A           _______________________________________________________t             ARGUMENTSD             None.a  A           _______________________________________________________              DESCRIPTIONe:           This callback returns 1 if the current (running)8           system is analyzed (ANALYZE/SYSTEM) or 0, if a?           system dump is analyzed (ANALYZE/CRASH_DUMP). If youro@           extension provides commands or functions available for@           one source of analysis only, you can use this callback3           to find out in which environment you are.   >           This callback is available on Alpha only. A MACRO-326           replacement for VAX is given in Section 3.1.  A                                                              B-69P S  o               SDA Callbackss&           SDA$EXTEND_ON_CURRENT_SYSTEM        A           ________________________________________________________             EXAMPLE_        >           In this example, a check is made whether the running8           system is the source of analysis. If it is, an;           error ("command not valid on the running system")s=           is signaled. This causes SDA's condition handler to,=           display the above error message and to pass controla=           back either to SDA or to the caller of this routineo#           (see SDA$EXTEND_HANDLER).                                                                B-70    s    A                                                     SDA CallbacksrA                                           SDA$EXTEND_PARSECOMMANDt        A           _______________________________________________________   !           SDA$EXTEND_PARSECOMMAND   *           Parse and execute a SDA command.  A           ________________________________________________________             FORMAT  "           SDA$EXTEND_PARSE  tpablk  A           _______________________________________________________              RETURNS            VMS Usage: cond_value_(           type:      longword (unsigned)           access:    write onlyB           mechanism: by valuel  >           A return value, either from SDA's parser or from the@           executed command. All conditions are signaled as well.  A           _______________________________________________________              ARGUMENTS            tpablk             VMS Usage: address(           type:      longword (unsigned)           access:    read only!           mechanism: by reference 9           A longword holding the address of a TPA (table-y<           driven parser) argument block. This block consists<           of 9 longwords where the first 4 longwords must be?           initialized; the remaining longwords should be set tod           zero.w      A                                                              B-71                     SDA CallbacksT!           SDA$EXTEND_PARSECOMMANDD        Q                                            -------------------------------------- Q                            TPA$L_COUNT     I Remaining # of longwords (8)       IsQ                                            -------------------------------------- Q                            TPA$L_OPTIONS   I Parsing options (see below)        I Q                                            ---------------------------------------Q                            TPA$L_STRINGCNT I Length of supplied command string  I Q                                            --------------------------------------oQ                            TPA$L_STRINGPTR I Address of supplied command string I Q                                            --------------------------------------   ?           The offsets and parsing options are defined in modulet7           $TPADEF. The following parsing options exist:   A           _______________________________________________________ A           Name__________Value__Meaning___________________________   6           TPA$M_BLANKS  01     Process blanks and tabs)                                explicitly   9           TPA$M_ABBREV  02     Allow command abbreviation   8           TPA$M_ABBRFM  04     Allow first match commandA           _____________________abbreviation______________________y  9           A detailed description of these options and thes=           table-driven command parser can be found in the RTL :           Library (LIB$) manual, in the description of the.           LIB$TPARSE/LIB$TABLE_PARSE routines.  A           _______________________________________________________.             DESCRIPTION_<           Not all SDA commands provide a callable interface.?           Using this callback, you can invoke every SDA commandi           directly.o  =           The callback provides a way to change SDA's currento?           process and/or current CPU context (see Section 3.3).O<           By creating the appropriate SET PROCESS or SET CPU=           command strings and invoking this callback, you can <           easily access the per-process address space of any:           process or examine CPU-specific data of any CPU.             B-72         A                                                     SDA Callbacks A                                           SDA$EXTEND_PARSECOMMANDc        @           Another use of this callback (compute SDA expressions)"           is shown in Section 3.4.  A           _______________________________________________________e  #           CONDITION VALUES RETURNED   :           SDA$_NORMAL        Normal successful completion.<                              Command was parsed and executed*                              successfully.  ?           SDA$_SYNTAX        Error parsing the supplied commandt:                              string. You have specified an?                              unknown command or invalid commandr$                              syntax.  A           _______________________________________________________r             EXAMPLEn  
  _tpadef tpa;         PROC/IND=%X",prc_index);       =          TPA$K_COUNT0;e  =            TPA$M_ABBREV;   =              strlen(cmdbuf);   =              (int) cmdbuf;d  +  &                               1) return;n  :           In this example, SDA's current process is change<           to the process whose index or PID is given in prc_=           index. The appropriate command string is built, thee?           TPA structure initialized and SDA$EXTEND_PARSECOMMANDg?           is invoked to execute the SET PROCESS command. If thei<           commands fails for some reason (e.g., non-existent  A                                                              B-73s o  a               SDA Callbacks$!           SDA$EXTEND_PARSECOMMANDD        <           index or PID was given), control is passed back to?           SDA. There is no need to do more; since the condition ;           was signaled as well, SDA's condition handler hasb3           already displayed the approbiate message.l  ?           Note that the TPA$M_ABBREV bit was set in the parsingi=           options; otherwise, we had to spell out the command '           entirely (SET PROCESS/INDEX).                                                                            B-74         A                                                     SDA Callbacks A                                                  SDA$EXTEND_PRINT         A           _______________________________________________________m             SDA$EXTEND_PRINT              Prints a line of data.  A           _______________________________________________________r             FORMAT  2           SDA$EXTEND_PRINT  txtstr, [p1..pn] (VAX)  4           SDA$EXTEND_PRINT  txtstr, [prmlst] (Alpha)  @           SDA$EXTEND_PRINT64  txtstr, [prmlst64] (Alpha V7 only)  A           _______________________________________________________              RETURNSr           VMS Usage: cond_value (           type:      longword (unsigned)           access:    write onlye           mechanism: by value   >           Always SDA$_SUCCESS (0x00F48009). All conditions are           signaled.f  A           _______________________________________________________:             ARGUMENTS            txtstr              VMS Usage: char_string%           type:      character string            access:    read only8           mechanism: by descriptor - fixed-length string                      descriptor :           Text to be displayed. The txtstr argument is the>           address of a character string descriptor pointing to@           the text string. The string may contain FAO (Formatted#           ASCII Output) directives.s  A                                                              B-75t i  r               SDA Callbackst           SDA$EXTEND_PRINT                   p1 to pn (VAX only)t              VMS Usage: varying_arg&           type:      longword (signed)           access:    read only           mechanism: by value @           Values to be passed as FAO directive parameters. These;           arguments are longwords containing the parameters <           needed by the FAO directives specified in the text<           string. Up to 17 parameters may be supplied; their@           number and contents depend on the used FAO directives.>           If you do not use FAO directives in the text string,)           you can omit further arguments.d             prmlst (Alpha only)s  -           VMS Usage: vector_longword_unsignedo(           type:      longword (unsigned)           access:    read only!           mechanism: by reference ?           List of FAO directive parameters. The prmlst argumentt:           is the address of a longword vector wherein each>           longword contains a parameter. The vector must start<           on a longword boundary; the number and contents of=           longwords depend on the used FAO directives. If youo?           do not use FAO directives in the text string, you can_           omit this argument._  ;           This argument is used with SDA$EXTEND_PRINT only.   "           prmlst64 (Alpha V7 only)  -           VMS Usage: vector_quadword_unsignedd(           type:      quadword (unsigned)           access:    read only!           mechanism: by referencet8           List of FAO directive parameters. The prmlst64>           argument is the address of a quadword vector wherein=           each quadword contains a parameter. The vector muste?           start on a quadword boundary; the number and contentst@           of quadwords depend on the used FAO directives. If you?           do not use FAO directives in the text string, you can.           omit this argument._             B-76 _  _    A                                                     SDA CallbackseA                                                  SDA$EXTEND_PRINTm        =           This argument is used with SDA$EXTEND_PRINT64 only.   A           _______________________________________________________              DESCRIPTIOND>           This callback formats and displays a line of data on=           the current output device; either on the screen or,!;           if output was redirected via SET OUTPUT, into the             specified output file.  :           The callback provides a screen-oriented display.>           Therefore, it should be used when a particular block=           of information should be presented on a single page <           or should be presented on multiple pages where the@           user may switch to the next page on demand. Before the=           first line of data is displayed, invoke SDA$EXTEND_A;           NEW_PAGE to start the display on the top of a new-;           page. Subsequent lines are shown by invoking this <           callback. Whenever the screen becomes full, output=           is suspended unit the user presses the <RETURN> key <           in response to the SDA> prompt. Most of SDA's SHOW&           commands behave in this way.  8           Text formatting occurs via FAO directives. The8           callback invokes the SYS$FAO (VAX) or SYS$FAOL6           (Alpha) system service to format the string.:           Most FAO directives require parameters, they are;           supplied as arguments (VAX) or passed in a vector )           of longwords/quadwords (Alpha).   >           On Alpha V7, this callback exists in a version using>           the SYS$FAOL_64 system service as well. This service<           accepts 64-bit parameters, allowing you to display?           64-bit data with the appropriate FAO directives. Noten@           that on Alpha V7, both callbacks, SDA$EXTEND_PRINT and+           SDA$EXTEND_PRINT64 are available.   7           See the System Service Reference Manual for a 9           description of the SYS$FAO/SYS$FAOL/SYS$FAOL_64o<           system services, the available FAO directives, and"           the required parameters.  A                                                              B-77                     SDA Callbacksm           SDA$EXTEND_PRINT      A           _______________________________________________________i  #           CONDITION VALUES RETURNED >           Returns always SDA$_SUCCESS (0x00F48009). Conditions6           returned by RMS (which is used for the write>           operations) are signaled and displayed on the screen%           by SDA's condition handler.   8           Error conditions given by SYS$FAO/SYS$FAOL are:           not returned. If SYS$FAO/SYS$FAOL fails for some;           reason (you have specified invalid FAO directives_@           or insufficient directive arguments), a null string is           displayed.  A           ________________________________________________________             EXAMPLE   2  of                     !UL !AZ sections found.");  =        "group-global";_    prmlst[2];_  0     /*                                    VAX */  2  =    seccnt;                          /* Alpha */2  =    (int) sectyp;                    /* Alpha */  2            /*                             Alpha */  ;           This example shows the use of SDA$EXTEND_PRINT on_9           VAX and Alpha. Some other examples are given inl=           Section 2.3.1 and in the description of SDA$EXTEND_r9           GET_BUGCHECK_MSG and SDA$EXTEND_LIB$INS_DECODE.                          B-78 '  e    A                                                     SDA CallbacksEA                                          SDA$EXTEND_PRINT_COLUMNSd        A           _______________________________________________________,  "           SDA$EXTEND_PRINT_COLUMNS  #           Displays rows of columns.d  A           _______________________________________________________y             FORMAT  :           SDA$EXTEND_PRINT_COLUMNS  datbas, datsva, coll1,  0                                     [...,coll10]  A           _______________________________________________________i             RETURNS   :           This callback does not return a condition value.  A           _______________________________________________________$             ARGUMENTS            datbas             VMS Usage: address&           type:      longword_unsigned           access:    read only!           mechanism: by reference :           Base address of the data structure against which>           the offsets specified in the column table apply. The=           datbas argument is a longword holding this address.i             datsva             VMS Usage: address&           type:      longword_unsigned           access:    read only           mechanism: by value ;           System virtual address of the data structure. The ;           datsva argument is a longword containing the data_<           structure's virtual address. This argument is used9           only when processing queue headers (see below).   A                                                              B-79n z  T               SDA Callbacks_"           SDA$EXTEND_PRINT_COLUMNS                   coll<n>              VMS Usage: address&           type:      longword_unsigned           access:    read only!           mechanism: by reference =           Address(es) of one or more column list entries. Theg?           coll<n> arguments are longwords holding the addressesa<           of the column entries. The format of these entries<           is described below. You must pass at least one and>           may pass up to 10 entries. The columns are displayed>           from left to right (the coll1 argument describes the:           leftmost column). See section Column entries and;           line entries for a detailled description of thesec           arguments.  A           _______________________________________________________m             DESCRIPTIONE>           This callback allows you to easily print information?           in columns. The callback is table-driven; with columny;           entries, you pass information how the columns arer<           formatted, give a description of each column entry:           and either pass an offset value which is used in?           cojunction with the datbas argument to obtain a value >           from a data structure or pass the address of a user-=           written formatting routine and a value to format by_<           this routine. Once the column entries are defined,@           you may invoke this callback many times with different?           datbas arguments to display multiple instances of thes<           same data structure. For example, you could define?           column entries containing PCB (process control block)t>           information and could invoke this callback with each=           PCB address taken from the SCH$GL_PCBVEC array (then>           vector array holding all PCB addresses) from a loop.>           An example of this is shown in the Examples section.  7           The remaining description is divided into ther           following sections:              B-80 D  R    A                                                     SDA Callbacks_A                                          SDA$EXTEND_PRINT_COLUMNSa        A           o  Column entries and line entries - how to setup these_>              data structures and how they are processed by the              callback;  A           o  FAO directives codes - how to code FAO directives in =              line entries and which directives are supported;y  A           o  User-written formatting routines - how to write your $              own formatting routine.  ?           SDA$EXTEND_PRINT_COLUMNS is mainly and best used fromc=           MACRO-32 programs. There exist some macros to built =           the line entries and column entries in an easy way. <           Most language provide their own features to format<           data and display columns; it is recommended to use<           these features instead of this callback. Note also=           that user-written formatting routines, if provided,r<           are invoked as subroutines, not as procedures; and=           since data to these routines is passed in processort8           registers, direct access to these registers is           required as well.   9           The callback uses SDA$EXTEND_PRINT to print the =           formatted lines on screen. This results in the sameN=           prompt behaviour and may cause the callback to pass->           control back to SDA and not return to your code. See0           SDA$EXTEND_PRINT for more information.  )           Column entries and line entries-  ?           Information about columns is given in column entries.T@           A column consists of one or more lines where each line@           is represented by its own line entry. The column entry<           is an array of line entries; it is terminated by a@           longword of 0. To display multiple columns in a single?           display, all column entries must have the same number            of line entries.      A                                                              B-81     -               SDA Callbacks-"           SDA$EXTEND_PRINT_COLUMNS        :           A line entry consists of a string describing its<           meaning, a formatted value and a column separator.;           For example, type SHOW PROCESS (while in SDA) and_=           look at the line starting with "PCB address". Here,_;           "PCB address" is the description string, followed >           by the formatted value (a hexadecimal longword), and?           followed by 4 blanks to separate this column from them=           next column. The string starting with "JIB address"_=           is already part of another line entry in the secondp           column.   :           A line entry may be described by this structure:  ,                            struct LINE_ENTRY                            {V                             char  *string;   /* Address of ASCIC description string */e                             int   offset;    /* NEGATIVE offset to the value in the data structure */ [                             int   fao_cod;   /* FAO directive code to display this value */ N                             char  des_wid;   /* Width of description string */H                             char  val_wid;   /* Width of value string */L                             char  sep_wid;   /* Width of column separator */I                             char  0;         /* Alignment byte, unused */                             };U  ;           'string' is a pointer to the counted-ASCII string >           holding the description text. 'offset' is the offset=           to the desired location in the data structure whosec?           base address is given in the datbas argument; it mustr@           specified as negative offset. 'fao_cod' is the code of@           the FAO directive which should be used for formatting;?           see section FAO directive codes for more information.c  :           The last three bytes determine the width for the=           description string, the value string and the column =           separator. In most cases, these values are the samen=           for all line entries in a column. The callback uses =           them to specify a width count in the FAO directivesr>           (which all start with "!#"). The width of the entire?           column is the sum of these three bytes, rounded up ton           a multiple of 4.             B-82 )       A                                                     SDA Callbacks A                                          SDA$EXTEND_PRINT_COLUMNS         =           Note that 'sep_wid' should be set to 0 for the lastc           (rightmost) column.   :           The above example shows the line entry using FAO:           directives to format data. If you do not want to>           use FAO directives or want to format data in way not;           supported by FAO directives (e.g., floating pointh=           data), you may provide your own formatting routine.t@           This is the layout of a line entry to activate a user-%           written formatting routine:k  ,                            struct LINE_ENTRY                            {V                             char  *string;   /* Address of ASCIC description string */]                             void  *rtnadr;   /* Address of user-written formatting routine */aH                             int   value;     /* Value to be formatted */N                             char  des_wid;   /* Width of description string */H                             char  val_wid;   /* Width of value string */L                             char  sep_wid;   /* Width of column separator */I                             char  0;         /* Alignment byte, unused */                             };S  9           The only difference to the format above are the_9           'rtnadr' and 'value' fields: 'rtnadr' holds theT>           address of the formatting routine and 'value' is the?           value to be formatted. The formatting routine and its ?           input is described in the Formatting routine section.D  =           You may combine both line entry formats in a singleP=           column entry. Whether or not a user-written routine_:           is invoked is determined only by the sign of the9           'offset'/'rtnadr' field in the line entry. If ae@           routine is specified, this field must be positive (the?           P0 or P1 routine's address), else it must contain theF>           negative offset into the structure where the desired>           value is stored. For example, if you want to display=           the PHD address taken from a PCB, you would specifyt@           -PCB$L_PHD. The callback recognizes the negative value?           as offset, converts them back to positive and performi<           its own formatting, according to the FAO directive,           code given in the 'fao_cod' field.  A                                                              B-83e s  n               SDA Callbacks "           SDA$EXTEND_PRINT_COLUMNS        ;           There is no restriction how many line entries may =           build a column entry (i.e., how many lines a columnD<           may consist of). You can even build columns across$           screen or page boundaries.               FAO directive codes   9           SDA$EXTEND_PRINT_COLUMNS uses the SYSFAO system =           service and FAO (formatted ASCII output) directives <           to format data. Only a subset of FAO directives is'           available with this callback.e  ?           The FAO directive code is an integer value describingp>           the FAO directive which should be used to format the?           data (actually, it's an offset into an internal table ?           of FAO directives). The Table B-2 shows the supported %           directives and their codes:M  A           Table_B-2__FAO_directive_codes_________________________s  A           Name___Value___Meaning_________________________________e  8           0      AC      Counted ASCII string (passed by#                          reference)o  <           1      AS      ASCID string (passed by descriptor)  #           2      OB      octal byte   )           3      XB      hexadecimal byten  ;           4      ZB      unsigned decimal byte, zero-filled.  .           5      UB      unsigned decimal byte  ,           6      SB      signed decimal byte  #           7      OW      octal wordu  )           8      XW      hexadecimal word   ;           9      ZW      unsigned decimal word, zero-filledd  .           10     UW      unsigned decimal word  ,           11     SW      signed decimal word  '           12     OL      octal longwordA             B-84 s  h    A                                                     SDA CallbackseA                                          SDA$EXTEND_PRINT_COLUMNS         A           Table_B-2_(Cont.)__FAO_directive_codes_________________   A           Name___Value___Meaning_________________________________n  -           13     XL      hexadecimal longword.  ?           14     ZL      unsigned decimal longword, zero-filled   2           15     UL      unsigned decimal longword  0           16     SL      signed decimal longword  9           17     Q2      absolute queue header (passed byu#                          reference)   >           18     Q2S     self-relative queue header (passed byA           _______________reference)______________________________p  >           If you require other FAO directives, you must invoke@           them from user-written formatting routines. See below.  @           If you add 0x80 (decimal 128) to the above values, the?           approbiate line entry in the column is displayed only,?           if the value obtained from the data structure is non-i=           zero; otherwise, the line is omitted - resulting ine,           possibly different column lengths.  >           This does, however, not apply to the last two values;           which provide a way to format queue headers. They <           require you to specify the datsva argument and use<           this argument to determine whether the queue whose<           header is assumed to be at the specified offset in@           the data structure is empty. This is done by comparing=           the queue header forward link with the value passed >           in datsva; if they match, the forward link points to?           itself and the string <empty> is displayed instead ofO)           the hexadecimal header address.m  *           User-written formatting routines  A                                                              B-85r e                  SDA Callbacks "           SDA$EXTEND_PRINT_COLUMNS        :           By specifying the address of a routine in a line:           entry's 'value' field, the callback invokes this?           routine when the value must be formatted. The routines?           is invoked as subroutine with the following processorN           registers:  ;           o  R2 - value taken from the line entry's 'value'$              field;a  =           o  R5 - width of the 'value' string (taken from the +              line entry's 'val_wid' field);F  >           o  R7 - address of a descriptor pointing to a buffer=              into which the formatted string must be written;   8           o  R11 - base address of the structure (datbas              argument).l  :           The routine must ensure that the returned string9           contains exactly the number of characters which :           is passed in R5. Unused character positions must:           be filled with blanks; the string must be right->           justified. The routine is responsible for formatting1           only, printing is done by the callback.i  ;           Registers R1-R5 may be used as scratch registers,Y<           all other registers (except R0) must be preserved.>           R0 is used to indicate whether the line entry should=           be displayed (1) or not (0). If you return 0 in R0,s<           the entire line entry is skipped. You can use this9           to suppress the display of line entries with no '           interesting values (e.g., 0).o  <           Note: When displaying multiple columns on a single>           screen, this may result in different column lengths.;           In addition, all columns must have the same width >           in this case, since line entries may be displayed in?           different columns. For example, if you have 2 columnsE>           and the line entry of the column 1 is skipped by the;           formatting routine, the line entry of column 2 isD            displayed in column 1.             B-86 I  N    A                                                     SDA Callbacks A                                          SDA$EXTEND_PRINT_COLUMNS         >           You may use SDA$EXTEND_PRINT_COLUMN_VALUE to perform=           formatting with the FAO directives provided by this <           callback. See the description of SDA$EXTEND_PRINT_           COLUMN_VALUE._  @           Examples of user-written formatting routines are given"           in the Examples section.  A           _______________________________________________________.  #           CONDITION VALUES RETURNED_           None._  A           _______________________________________________________              EXAMPLEd  3  code  shows the usage of SDA$EXTEND_PRINT_COLUMNS._=  example,  we obtain all PCB addresses from the SCH$GL_PCBVECa5  array, and display some information (a subset of the 8  displayed      by SDA's SHOW PROCESS commands. For some8  we use special formatting routines. Since this routines8  as     subroutines, we build MACRO-32 jackets to invoke  C            routine. */     <pcbdef.h>   <starlet.h>
  <statedef.h>n  <stdlib.h>   <string.h>i    code constants. */                 A                                                              B-87e    r               SDA Callbacks:"           SDA$EXTEND_PRINT_COLUMNS        
  FAO_AC  0
  FAO_AS  1
  FAO_OB  2
  FAO_XB  3
  FAO_ZB  4
  FAO_UB  5
  FAO_SB  6
  FAO_OW  7
  FAO_XW  8
  FAO_ZW  9  FAO_UW  10i  FAO_SW  11   FAO_OL  12   FAO_XL  13r  FAO_ZL  14e  FAO_UL  15   FAO_SL  16   FAO_Q2  17   FAO_Q2S  18    struct  dsc$descriptor_s dsc;  :  /*                          Jacket to get a symbol value,;                              see SDA$EXTEND_SYMBOL_VALUE */s      6        /*            Jacket to format process state */,         /*           Jacket to format UIC */6         /*           Jacket to format AST's enabled */  .             /*       Convert ASCIZ to ASCID */    entry  structure. */                        B-88 l       A                                                     SDA Callbacks A                                          SDA$EXTEND_PRINT_COLUMNSe          line_entryd  ;          /*          Pointer to ASCIC description string */e    *            /*        Negative offset or */'      /*              routine address */a      #           /*         FAO code or */ -             /*       value to be formatted */_  0           /*         Description string width */*           /*         Value string width */5           /*         Column separator string width */a3            /*        Spare byte for lw alignment */e    routine.     ****/   4  routine  traverses the PCB vector array and invokes3  to                      print information from all   4  data        in 2 colums. Define now the description4  Remember,      they are formatted as ASCIC (counted  */a      #  =              {"\013PCB address",e#                  "\013PHD address",i$                  "\014Internal PID",$                  "\014External PID",                  "\005State",a(                  "\020Current priority",%                  "\015Base priority",i                  "\003UIC"};      A                                                              B-89  o  n               SDA Callbackse"           SDA$EXTEND_PRINT_COLUMNS        #  =              {"\013JIB address",h-                  "\025Swapfile disk address",C(                  "\020Subprocess count",#                  "\013Creator PID",.+                  "\023Termination mailbox",e$                  "\014ASTs enabled",#                  "\013ASTs active",h'                  "\016ASTs remaining"};   2  both     column entries. Each entry consists of 85  entries   and is terminated with a longword of 0. */     lin_entry  col1[9] =A    FAO_XL,16,14,8,0,  FAO_XL,16,14,8,0,  #  0,                      16,14,8,0,w  FAO_UB,16,14,8,0,  #   0,                     16,14,8,0,       lin_entry  col2[9] =       FAO_XL,26,8,0,0,   FAO_XL,26,8,0,0,i    FAO_XL,26,8,0,0,d   FAO_XW,26,8,0,0,$     0,                     26,8,0,0,$      0,                    26,8,0,0,                           B-90 e       A                                                     SDA CallbacksDA                                          SDA$EXTEND_PRINT_COLUMNSR        +           /*        Address of curr. PCB */ ,           /*        Address of PCB vector */*         /*          Address of NULL PCB */)          /*         Max # of processes */a"              /*     Aux storage */&  =    1;         /* Process counter */  (  __PCB  pcb;     /* Local copy of PCB */  ,  let's    start... first obtain the value of  relevant  system cells. */               $  loop   through PCB vector array. */    (cnt != maxproc)t  '  next   PCB address from PCB vector. */i  6  it's  the address of the NULL PCB, this array element  unsed.  Try next. */   %  ==       nullpcb) {cnt++; continue;}   4  the     PCB is use. Copy it to our local buffer. */  1  our  copy, overwrite the PCB$L_SQBL (state queuey1  link)        longword with the S0 address of thek1  We    do not display the contents of PCB$L_SQBL, &  want   to display the PCB address. */    =           curpcb;      A                                                              B-91o n  t               SDA Callbacksn"           SDA$EXTEND_PRINT_COLUMNS        2  priorities       are stored internally in reverse2  (highest     priority = 0). Translate them to the2  external          order (highest priority = 31 on  or   63 on Alpha). */  -   =          abs(pcb.PCB$B_PRI-31); /* VAX */e3  =           abs(pcb.PCB$B_PRIB-31);      /* VAX */e/   =          abs(pcb.PCB$L_PRI-63); /* Alpha */ 5  =           abs(pcb.PCB$L_PRIB-63);      /* Alpha */a  5  the      line entries values with special formatting   the    PCB. */y    =          pcb.PCB$W_STATE;  =          pcb.PCB$L_UIC;  =          pcb.PCB$B_ASTEN;;a  =          pcb.PCB$B_ASTACT;t  :  that's     all here. The rest is done by the callback. */  7         /*                      Insert empty line and*/e  9                            /*   switch to next process */r      *str)  =  a    null-terminated (ASCIZ) string, this function returns a 9  descriptor           pointing to this string (ASCID). */s    $DESCRIPTOR  (x,"");a    =          strlen(str);  str;     &x;                   B-92 p       A                                                     SDA CallbacksuA                                          SDA$EXTEND_PRINT_COLUMNS         7  routines.        These routine are invoked by MACRO-32 5  (see     below). The routines and their jackets have 7  names     except the jacket names start wih "m_" wherel$  C routine names start with "c_". */  +  value,int             val_wid,dsc *retbuf)e  5  routine   is invoked to translate the binary process 3  (from    PCB$W_STATE) into a corresponding string.n-  states      are defined in module $STATEDEF.;  %     value     passed from PCB$W_STATE    width       of value string;:    address      of descriptor pointing to return buffer */  &      /*            Temporary buffer */  .  SCH$C_COLPG: {strcpy(locstat,"COLPG");break;}.  SCH$C_MWAIT: {strcpy(locstat,"MWAIT");break;}.  SCH$C_CEF:   {strcpy(locstat,"CEF");  break;}.  SCH$C_PFW:   {strcpy(locstat,"PFW");  break;}.  SCH$C_LEF:   {strcpy(locstat,"LEF");  break;}.  SCH$C_LEFO:  {strcpy(locstat,"LEFO"); break;}.  SCH$C_HIB:   {strcpy(locstat,"HIB");  break;}.  SCH$C_HIBO:  {strcpy(locstat,"HIBO"); break;}.  SCH$C_SUSP:  {strcpy(locstat,"SUSP"); break;}.  SCH$C_SUSPO: {strcpy(locstat,"SUSPO");break;}.  SCH$C_FPG:   {strcpy(locstat,"FPG");  break;}.  SCH$C_COM:   {strcpy(locstat,"COM");  break;}.  SCH$C_COMO:  {strcpy(locstat,"COMO"); break;}.  SCH$C_CUR:   {strcpy(locstat,"CUR");  break;}  /  the           string to fill the outbuf buffero$  the   required number of blanks. */    3  1;       /* Yes, we want to display our result! */       A                                                              B-93n                    SDA Callbacksn"           SDA$EXTEND_PRINT_COLUMNS        *  value,int            val_wid,dsc *retbuf)  /  routine   is invoked to translate a binary UIC 1  PCB$L_UIC)    into a corresponding identifier orR.  string.  This must be done external since the1  directives        in the callback do not provideg%  !%I  directive which we use here. */   #     value     passed from PCB$L_UIC    width       of value stringd:    address      of descriptor pointing to return buffer */  %      /*           Temporary buffer */     retlen;  5   /*                                  Format value */y  3  =          0;                     /* Make ASCIZ */   /  the           string to fill the outbuf buffere$  the   required number of blanks. */  3  1;       /* Yes, we want to display our result! */       *  value,int            val_wid,dsc *retbuf)  1  routine   is invoked to translate the AST activen7  AST  enabled access mode bit mask into a corresponding/.  If      no bits are set, the string "NONE" is2  otherwise,        the letters K,E,S,U for all bit  in  the mask are returned. */    2  strcpy(locbuf,"NONE");           /* No bit set */                 B-94         A                                                     SDA Callbacks A                                          SDA$EXTEND_PRINT_COLUMNS             
  =      0;  .  &      1) strcat(locbuf,"K");    /* Kernel */1  &      2) strcat(locbuf,"E");    /* Executive */y2  &      4) strcat(locbuf,"S");    /* Supervisor */,  &      8) strcat(locbuf,"U");    /* User */  /  the           string to fill the outbuf buffer $  the   required number of blanks. */  3  1;       /* Yes, we want to display our result! */n        jackets    0  jackets  are invoked as user-written formatting2  We      just push the required arguments on stack2  the       corresponding C routines as procedures.     value to be formattedk   value string width1   address of descriptor pointing to output stringl7  base address of structure (callback 'datbas' argument)d  6  we  do not need the contents of R11 here; R2 contains        the    value       we             want                         to                                                 format.        pass    R11       to             our                         C                                                 procedures.     :  pushl        r7               ; 3. arg: output descriptor:        pushl  r5               ; 2. arg: value string size.        pushl  r2               ; 1. arg: value7        calls  #3,g^C_STAT_RTN  ; Invoke C state routine 5        rsb                     ; Return as subroutines    A                                                              B-95                     SDA Callbackst"           SDA$EXTEND_PRINT_COLUMNS        :   pushl       r7               ; 3. arg: output descriptor:        pushl  r5               ; 2. arg: value string size.        pushl  r2               ; 1. arg: value9        calls  #3,g^C_UIC_RTN   ; Invoke C UIC format rtn.e5        rsb                     ; Return as subroutinet  :   pushl       r7               ; 3. arg: output descriptor:        pushl  r5               ; 2. arg: value string size.        pushl  r2               ; 1. arg: value=        calls  #3,g^C_AST_RTN   ; Invoke C AST bit format rtn.c5        rsb                     ; Return as subroutiney  ;           This example shows in full detail how you can usec7           SDA$EXTEND_PRINT_COLUMNS for automatic columne=           processing. The most work here is the definition ofc=           the line and column entries. Once they are defined,i>           you can easily create nice column-oriented displays.                                                         B-96 n  o    A                                                     SDA Callbacks A                                     SDA$EXTEND_PRINT_COLUMN_VALUEc        A           _______________________________________________________   '           SDA$EXTEND_PRINT_COLUMN_VALUE   &           Formats a single line entry.  A           _______________________________________________________              FORMAT  '           SDA$EXTEND_PRINT_COLUMN_VALUE   A           _______________________________________________________a             RETURNS1  :           This callback does not return a condition value.  A           _______________________________________________________              ARGUMENTS            R2             VMS Usage: address(           type:      longword (unsigned)           access:    read only!           mechanism: by reference_=           When invoking this callback, the processor register_<           R2 must contain the address of the data item to be           formatted.             R4  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only           mechanism: by value @           When invoking this callback, the processor register R4?           must contain the code of the FAO directive to be usedq<           for formatting. See the description of SDA$EXTEND_?           PRINT_COLUMNS, section FAO directive codes for a listO2           and description of available directives.  A                                                              B-978 d  m               SDA Callbackst'           SDA$EXTEND_PRINT_COLUMN_VALUEe                   R5  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only           mechanism: by valueo@           When invoking this callback, the processor register R5@           must contain the predefined width of the value string.<           The callback uses this argument to select a "!#xx">           from its table (according the value given in R4) and>           pass this argument as width parameter to the SYS$FAO           system service.              R7              VMS Usage: char_string%           type:      character stringf           access:    write only 8           mechanism: by descriptor - fixed-length string                      descriptors@           When invoking this callback, the processor register R7>           must contain the address of a descriptor pointing to?           a buffer wherein the formatted string can be written.8<           The buffer must be large enough to hold the string=           with the maximum of possible characters inserted bya;           the FAO directive (for example, with UL (unsignedb:           longword), you should provide at least a 10-byte           buffer).  7           See the System Service Reference manual for ar=           description of all available FAO directives and the ;           required maximum output space for each directive.   A           _______________________________________________________              DESCRIPTIONi@           This routine is the single column entry action routine@           used by SDA$EXTEND_PRINT_COLUMNS when a data structure?           offset is specified in place of an action routine. It >           locates the specified data, converts it to ASCII and.           stores it in the buffer given in R7.             B-98 a  r    A                                                     SDA Callbacks A                                     SDA$EXTEND_PRINT_COLUMN_VALUE         =           You can invoke this callback from your user-writtenr>           formatting routine if the FAO directives provided by<           the callback suit your needs. The callback accepts<           all FAO directive codes listed in Table B-2. Using<           this callback may become necessary when data to be?           formatted does not come from a data structure or mustn@           processed in a special way before it can be displayed.<           In your formatting routine, first prepare the data>           in the required way and then invoke this callback to           format it.  <           The callback is invoked as subroutine. When called?           from a high level language, a MACRO-32 jacket must be @           provided. The jacket must load the processor registers?           with the required values and invoke the callback withi?           a JSB instruction. See the Examples section how to dor           this.e  8           Note: Although the name of the callback starts;           with PRINT, nothing is printed, the callback just ;           formats data with the FAO directive whose code is =           passed in R4. In addition, not a column entry, only 9           a single line entry is processed. It is assumedm;           that the name of this callback will change to onea@           describing better its purpose in future releases (e.g.#           SDA$EXTEND_FORMAT_ENTRY).r  @           The callback will destroy registers R0 - R4. All other"           registers are preserved.  A           _______________________________________________________S  #           CONDITION VALUES RETURNED            None._            A                                                              B-99t u  e               SDA Callbacks_'           SDA$EXTEND_PRINT_COLUMN_VALUEf        A           _______________________________________________________h             EXAMPLEy  4  example in the description SDA$EXTEND_PRINT_COLUMNS8  the      internal process priority to an external value<  modifies the approbiate locations in the PCB data structure9  SDA$EXTEND_PRINT_COLUMNS    is invoked. In this example,l5  use     user-written formatting routines which first :  the     priority and then invoke SDA$EXTEND_PRINT_COLUMN_  to   format it.  7  example  show only the relevant changes from the aboveT  */M    line      entries. */                0  is  the MACRO-32 jacket to invoke the c_pri_rtn1  Note      that this time, we pass the address ofi5  data structure (in R11) to the C routine as well. */e  ;  pushl        r11              ; 4. arg. data struct. addr.r:        pushl  r7               ; 3. arg: output descriptor:        pushl  r5               ; 2. arg: value string size.        pushl  r2               ; 1. arg: value:        calls  #4,g^C_PRI_RTN   ; Invoke C priority routine5        rsb                     ; Return as subroutinec      the   C_PRI_RTN routine: */                 B-100n t  C    A                                                     SDA CallbackslA                                     SDA$EXTEND_PRINT_COLUMN_VALUEa        ?  pri_typ,int             val_wid,dsc *retbuf,struct __PCB *pcb)N  >  is    the routine to convert and format the process priority./  'pri_typ'   determines which priority is used:N  &  = current priority (offset PCB$B_PRI)(  = base priority (offset PCB$B_PRIB). */  '                 /*          Priority */   4               /*            On Alpha, subtract 63 */  0  1:  {priority = abs(pcb->PCB$B_PRI-31); break;}1  2:  {priority = abs(pcb->PCB$B_PRIB-31); break;}o.  priority      = 255;    /* Indicates error */  2  invoke   SDA$EXTEND_PRINT_COLUMN ENTRY to format.3  time,    we need a MACRO-32 jacket which to invoket  callback   as subroutine. */f  4  1;        /* Yes, we want to display our result! */    -  is  the print_column jacket. Registers R1-R4t.  destroyed by the callback, R5 and R7 are used1  additional     arguments, so all these registersd  be  saved.   #  PRINT_COLUMN,^m<r1,r2,r3,r4,r5,r7> !    4(ap),r2            ; Priority +    8(ap),r4            ; FAO directive code"$   12(ap),r5            ; Value width&   16(ap),r7            ; Output buffer#     g^SDA$EXTEND_PRINT_COLUMN_VALUE ,                        ; Return to C_PRI_RTN  <           This example shows how to invoke SDA$EXTEND_PRINT_?           COLUMN_VALUE. This can be done from MACRO-32 or BLISS @           only since the callback must be invoked as subroutine.  A                                                             B-101     0               SDA Callbacks '           SDA$EXTEND_PRINT_COLUMN_VALUE                    Therefore, our code   ;           o  invokes SDA$EXTEND_PRINT_COLUMNS from the mainh?              program (see example of SDA$EXTEND_PRINT_COLUMNS);d  @           o  SDA$EXTEND_PRINT_COLUMNS invokes our first MACRO-32"              jacket as subroutine;  =           o  the jacket invokes the formatting routine c_pri_,               rtn() as procedure;  >           o  c_pri_rtn() invokes the second MACRO-32 jacket as              procedure;   ?           o  the second jacket invokes SDA$EXTEND_PRINT_COLUMN_,!              VALUE as subroutine.0  
           [1]   >           As you can see, several layers are required, but you;           can use SDA$EXTEND_PRINT_COLUMN_VALUE even from CN=           and other high level languages, as long as MACRO-32            jackets are provided.o                                       ________________  ,         [1] You're not confused, aren't you?             B-102g /  =    A                                                     SDA CallbacksoA                                           SDA$EXTEND_READ_SYMFILE         A           _______________________________________________________(  !           SDA$EXTEND_READ_SYMFILEs  =           Reads symbols from a symbol table or from an image.s  A           _______________________________________________________c             FORMAT  @           SDA$EXTEND_READ_SYMFILE  filnam, reloc (VAX V5 and V6)  @           SDA$EXTEND_READ_SYMFILE  filnam, reloc, [options] (VAX  &                                    V7)  <           SDA$EXTEND_READ_SYMFILE  filnam, reloc, symvec_va,  =                                    symvec_siz, options, suppr   -                                    (Alpha V6)   <           SDA$EXTEND_READ_SYMFILE  filnam, reloc, symvec_va,  @                                    symvec_siz, options, nullarg,  6                                    [ldrimg] (Alpha V7)  A           _______________________________________________________              RETURNS3           VMS Usage: cond_valuep(           type:      longword (unsigned)           access:    write onlyA           mechanism: by valueP  @           Unless you set the OPT$M_NOSIGNAL_READ bit in options,?           all conditions are signaled as warnings as well (this_:           bit exists on Alpha V7 only, so you must declare8           a condition handler on other VMS versions; see.           Section 3.5 and SDA$EXTEND_HANDLER).  A                                                             B-103                     SDA Callbackso!           SDA$EXTEND_READ_SYMFILEt      A           _______________________________________________________              ARGUMENTS            filnam              VMS Usage: char_string%           type:      character string            access:    read only8           mechanism: by descriptor - fixed-length string                      descriptor =           Name of the file containing symbol definitions. The >           filnam argument is the address of a character string@           descriptor pointing to the filename. The filename must?           not contain wildcard characters. If you do not supplyv?           a file type, SDA first loos for a symbol table (.STB)e>           or, if no matching file is found, for a system image$           or shareable image (.EXE).  ?           Alpha only: if the filename is the same as that of an$?           loaded system image or activated shareable image, butr=           the symbols in the file are not those of the image,a>           you must set the OPT$M_FORCE_READ bit in options and;           optionally supply additional information with the 4           reloc, symvec_va and symvec_siz arguments.  =           If the OPT$M_EXEC_READ flag is set in options, this @           argument is optional and, if specified, is the address?           of a character string descriptor pointing to the names<           of the directory wherein all system images reside.             relocO  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only           mechanism: by values;           A longword containing the relocation (base) value,@           which is added to all relative symbols. If you specify=           0, no base value is added. This argument is ignored ;           with the OPT$M_IMAGE_READ or OPT$M_EXEC_READ bits >           in options; it is also ignored for sliced images. It5           corresponds to SDA's READ/RELOCATE command.S             B-104t         A                                                     SDA Callbacks A                                           SDA$EXTEND_READ_SYMFILE                     symvec_va (Alpha only)             VMS Usage: address(           type:      longword (unsigned)           access:    read only           mechanism: by value <           A longword holding the base virtual address of the=           symbol vector in a shareable image or system image. <           All universal symbols in these images are found by>           looking it up in the symbol vector (the symbol value@           is an offset into the symbol vector). This argument is>           ignored with the OPT$M_IMAGE_READ or OPT$M_EXEC_READ9           bits in options and is meaningful for loaded oru            activated images only.  !           symvec_siz (Alpha only)   &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only           mechanism: by value @           A longword holding the size of the symbol vector whose>           address is given in symvec_va. This argument is used;           in conjunction with symvec_va only; if you supply 8           symvec_va, you must supply symvec_siz as well.             options   "           VMS Usage: mask_longword(           type:      longword (unsigned)           access:    read only           mechanism: by value*<           A longword holding a bit mask of read options. The(           following options are defined:  A           _______________________________________________________eA           Name______________Value__Meaning_______________________   ?           OPT$M_FORCE_      0001   Read symbols from image file 0           READ                     (Alpha only).  A                                                             B-105h    r               SDA Callbacks !           SDA$EXTEND_READ_SYMFILEr      A           _______________________________________________________RA           Name______________Value__Meaning_______________________   :           OPT$M_IMAGE_      0002   For loaded or activated;           READ                     images, read symbols and >                                    relocation info from memory0                                    (Alpha only).  <           OPT$M_EXEC_READ   0010   Read symbol tables of all?                                    loaded system images, either =                                    from the default directoryt@                                    or the directory given in the>                                    filnam argument (VAX V7 and/                                    Alpha only).   <           OPT$M_NOLOG_      0020   Suppress display of SDA's<           READ                     READSYM message (Alpha V7)                                    only).   @           OPR$M_NOSIGNAL_   0080   Return condition only, do notA           READ_____________________signal_it_(Alpha_V7_only).____R  <           Note that the bit names shown in the table are not?           defined anywhere; if you want to use it in your code,e<           you must define the appropriate literals yourself.             suppr (Alpha V6 only)v  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only           mechanism: by value ?           A longword holding the suppress indicator. If you set =           this longword to 1, SDA's %SDA-I-READSYM message is            not displayed.  9           On Alpha V7, this argument is not used; set the 2           OPT$M_NOLOG_READ bit in options instead.              ldrimg (Alpha V7 only)             VMS Usage: address(           type:      longword (unsigned)           access:    read only!           mechanism: by referenceL             B-106          A                                                     SDA Callbacks A                                           SDA$EXTEND_READ_SYMFILEn        <           A longword holding the address of a LDRIMG (loaded<           system image) block. The contents of this block is=           used to determine the image's symbol vector address_>           and size, as well additional relocation information.:           If you specify this argument, the reloc, symvec_9           va and symvec_siz arguments are meaningless. InU@           addition, you must not set any bits in options, except3           OPT$M_NOLOG_READ and OPT$M_NOSIGNAL_READ.a  A           _______________________________________________________h             DESCRIPTIONr5           This callback is an interface to SDA's READe7           command. This command symbolically identifies 3           locations in memory for which the defaulte6           symbol tables (SYS$SYSTEM:SYS.STB on VAX and;           SYS$LOADABLE_IMAGES:SYS$BASE_IMAGE.EXE as well ash>           SYS$LOADABLE_IMAGES:REQSYSDEF.STB on Alpha) provides?           no definition. In other words, the global symbols areg?           located in modules that have been compiled and linkedc(           separately from the executive.  <           Depending on the specified arguments and bits, the>           following operations are performed by this callback:  >           o  If you set the OPT$M_EXEC_READ bit in the options@              argument, the symbol tables of all currently loaded@              system images and driver images are processed. This=              is equivalent to the READ/EXECUTIVE command; seen.              section Reading executive images.  ;           o  On Alpha only, if you set the OPT$M_IMAGE_READ >              bit in the options argument, SDA assumes that the=              filename given in filnam is the name of a loaded <              system or activated shareable image and obtains?              symbol information from the memory data structurescA              representing these images. This is equivalent to thes>              READ/IMAGE command; see section Processing loaded"              and activated images.  A                                                             B-107e 7                  SDA Callbackse!           SDA$EXTEND_READ_SYMFILE         1           o  On Alpha only, if you do not set the8=              OPT$M_IMAGE_READ bit in the options argument and =              you specify the name of a loaded system image or ;              activated shareable image, you must supply the <              image's symbol vector address and size with theA              symvec_va and symvec_siz arguments. In addition, fora@              loaded system images, you supply their virtual base>              address with the reloc argument. This corresponds;              to READ/SYMVA/RELOC; see Processing loaded and_              activated images.  >           o  On Alpha only, if the image is a loaded system or<              activated shareable image, but you want to read=              symbol information directly from the image file, >              set the OPT$M_FORCE_READ bit. This corresponds to<              READ/FORCE; see Processing loaded and activated              images.  =           o  If you do not set one of the bits above, you cana@              read the symbols from an object file (.OBJ), symbol:              table (.STB) or image file (.EXE; see section@              Processing non-activated images and symbol tables).@              On Alpha, the image must not be loaded or activated              in this case.  9           The following table gives an overview about all =           arguments and lists the corresponding SDA commands.o=           Note that the OPT$M_ prefix is omitted from the bit            names in the table.r  A           _______________________________________________________rI                                                                   symvec_ E           Bit_Name______SDA_command________image_type______reloc_ xxxt  C           EXEC_READ     READ/EXECUTIVE     [1]             -      -e  C           IMAGE_        READ/IMAGE         system,shar.    -      -s           READ[2]h  A           _______________________________________________________n>           [1]Optional name of the directory wherein all system           images reside.           [2]Alpha onlyc             B-108  h  I    A                                                     SDA Callbacks A                                           SDA$EXTEND_READ_SYMFILEo      A           _______________________________________________________ I                                                                   symvec_aE           Bit_Name______SDA_command________image_type______reloc_ xxx   C           FORCE_        READ/FORCE         system,shar.    opt    -             READ[2]       [/RELOC]  E           [2]           READ/SYMVA         shareable       opt    req_                          [/RELOC]  E           [2]           READ/RELOC         system          req    opt !                         [/SYMVA]]   C           -             READ [/RELOC]      non-activated   opt    -D  C           -             READ [/RELOC]      symbol table    opt    -_A           _______________________________________________________iA           [2]Alpha_only__________________________________________e  =           Note that the OPT$M_EXEC_READ, OPT$M_IMAGE_READ ando@           OPT$M_FORCE_READ bits are mutually exclusive, only one(           of them can be set in options.  A           _______________________________________________________k  "           READING EXECUTIVE IMAGES  ;           By setting the OPT$M_EXEC_READ bit in the optionsv9           argument, you tell SDA to read all symbols frome;           all currently loaded executive (system) images. As:           list of these images can be displayed with SDA's8           SHOW EXECUTIVE command. If you do not supply a=           directory name with the filnam argument, the target =           directory defaults to SYS$LOADABLE_IMAGES (VAX) and2;           SDA$READ_DIR (Alpha). Note that SDA$READ_DIR is a ?           search list currently pointing to SYS$LOADABLE_IMAGESu           and SYS$SHARE.  =           Use this bit if you want to set global entry points ?           into system images to their absolute addresses within =           these images, instead to the entry points in the S0 ?           pointer page. Note that on VAX, this bit is availablet           in VMS V7 only.e  A                                                             B-109t p  e               SDA Callbackst!           SDA$EXTEND_READ_SYMFILE         ?           When reading the executive images, the reloc, symvec_I?           va, symvec_siz, and ldrimg arguments are meaningless. >           In addition, you must not set other bits in options,@           except OPT$M_NOLOG_READ and OPT$M_NOSIGNAL_READ (Alpha           V7 only).r  A           _______________________________________________________T  =           PROCESSING LOADED AND ACTIVATED IMAGES (ALPHA ONLY)c  ;           On Alpha, shareable images and some system imagese?           (or their associated symbol tables) contain universala>           symbol definitions in the following data structures:  =           o  The GST (global symbol table). This table, whichs;              exists on VAX as well, is used at link time to =              reference universal symbols within the image. Ond@              Alpha, you can create shareable images without GST,?              making these images not usable for link operations ?              (sometimes also called run-time shareable images).h?              If the image has a symbol vector, the symbol valueb<              in the GST is an offset into the symbol vector.  @           o  The symbol vector. This data structure contains all?              actual symbol values, addressed by an offset whicha?              comes from the symbol entry in the GST. The symbol @              vector is loaded into memory and initialized by the?              image activator when it must create the connectionE=              between a main image and references in shareable A              images which the main image was linked against. With @              few exceptions, only shareable images have a symbol?              vector; system images mostly have no symbol vectort<              but have an associated symbol table (.STB) file;              wherein the GST and the symbol vector resides.   <              The symbol vector is an array of quadword pairs;              holding the addresses of the image's procedure A              entry points, procedure descriptors, and global datan>              locations, as well the values of global constantsA              (literals). Note that addresses in the symbol vector_?              are offsets to the shareable image's base address.              B-110          A                                                     SDA Callbacks A                                           SDA$EXTEND_READ_SYMFILE         :              When the image is mapped into the per-process=              address space, the image activator relocates the A              offsets by adding the shareable image's base address_A              to the values stored in the symbol vector, producing >              absolute virtual addresses. Since the contents of?              the symbol vector is required at run-time, it must >              remain into memory as long as the shareable image              remains activated.v  @           When reading GST and symbol vector from an image file,;           all addresses therein are relative to the image's @           base address. In contrast, when the image is activated=           (or, in the case of system images, loaded at system >           initialization), the symbol vector contains absolute@           addresses. Therefore, when examining the symbol vector:           of an activated shareable image, you must decide?           whether you want to process the memory-version of the >           symbol vector, or you want to read it from the image           file.D  ?           By specifying the OPT$M_IMAGE_READ bit in options and ?           the name of an activated shareable image, SDA locatest=           the data structure representing the activated images=           and, using the in-memory symbol vector, creates all 7           symbols with their actual absolute addresses.   ;           In order to process an image in this way, it must_=           be either a system image, loaded as part of the VMS_;           executive (you can check this with SHOW EXECUTVE, >           or it must be activated by the current process (must>           appear in the current process' activated image list;>           you can display this list with SHOW PROCESS/IMAGES).  9           If you do not set the OPT$M_IMAGE_READ bit, buto?           specify the name of an activated or loaded image, you -           must supply additional information:l  >           o  For system images, you must specify their virtual=              base address in the reloc argument; if the image A              has a symbol vector, you must supply its address andu.              size in symnam_va and symnam_siz.  A                                                             B-111t    a               SDA Callbacksm!           SDA$EXTEND_READ_SYMFILEu        >           o  For shareable images, you must specify the symbol?              vector in symnam_va and symnam_siz and may specify @              a relocation value in reloc. Note that a relocation>              value applies to relative symbols only, constants)              (literals) are not affected.   ?           Specifying symnam_va and symnam_siz explicitly allows <           you to process symbols from an activated shareable7           image using the symbol vector (and relocationr=           information) from a different shareable image. Thisi?           is, however, useful only if two different versions of 3           the same activated shareable image exist.   <           Note that you cannot process sliced images in this9           way. A sliced image consists of different parts =           (called execlets) and is loaded in a non-contiguous ?           manner. Each execlet is loaded at a different virtual @           address and may have its own symbol vector. For sliced?           images, you must always set OPT$M_IMAGE_READ, telling @           SDA to obtain execlet-related information from memory.  >           Whenever you specify the name of an activated image,;           SDA expects either the OPT$M_IMAGE_READ to be set <           or additional information supplied with the reloc,=           symnam_va and symnam_siz arguments. However, if you >           want to read symbol information from the image file,?           set the OPT$M_FORCE_READ bit in the options argument.e>           This causes SDA to bypass all information in memory,>           the image is processed like any other, non-activated>           image. Note, however, that in this case, all symbols?           are set to their relative addresses within the image;D>           they do not point to the actual locations in memory.  ;           When setting the OPT$M_IMAGE_READ bit, the reloc,n=           symvec_va and symvec_siz arguments are meaningless. 5           In addition, you must not set other bits iny=           options, except (on Alpha V7 only) OPT$M_NOLOG_READt7           and/or OPT$M_NOSIGNAL_READ. Note that settingg>           OPT$M_IMAGE_READ and specifying the name of an image@           which is not either loaded or activated, results in an           error.             B-112     p    A                                                     SDA CallbackswA                                           SDA$EXTEND_READ_SYMFILE:        8           When setting the OPT$M_FORCE_READ bit, you may@           specify an additional relocation offset with the reloc>           argument; the symvec_va and symvec_siz arguments are?           meaningless here since this information is taken from .           the image file or symbol table file.  3           If you do not specify OPT$M_IMAGE_READ orn<           OPT$M_FORCE_READ, but specify the name of either a:           loaded or activated image, an error is returned.  A           ________________________________________________________  ;           PROCESSING NON-ACTIVATED IMAGES AND SYMBOL TABLESu  >           If you specify the name of a symbol table file or of@           an image which is not activated by the current process?           or found in the loaded system image list, symbols arel@           defined using the information from the specified file.=           On VAX, this is the only way to read symbol tables.e  <           Depending on the image type, SDA reads the symbols?           either from the GST (global symbol table) or from thei=           symbol vector, or from both (Alpha only). Remember,i?           if you have not supplied a file type, SDA looks firstA@           for a symbol table (.STB) file, before it looks for an           image (.EXE) file.  @           You can use the reloc argument to specify a relocation9           value (an offset which is added to all relativel=           symbols). This may be useful if you want to addressy:           symbols from a given offset (e.g., the image was7           mapped at a non-zero base address). Note thatw7           a relocation does not affect absolute symbolsu           (literals).   <           When reading images in this way, the symvec_va and@           symvec_siz arguments are meaningless. In addition, you@           must not set bits in options except (on Alpha V7 only)6           OPT$M_NOLOG_READ and/or OPT$M_NOSIGNAL_READ.  A                                                             B-113                     SDA CallbacksA!           SDA$EXTEND_READ_SYMFILEo      A           _______________________________________________________   )           FURTHER OPTIONS (ALPHA V7 ONLY)n  @           On Alpha V7 only, you may set the following additional           bits in options:  ?           o  OPT$M_NOLOG_READ - when you set this bit, SDA doesh0              not display the following messages:  G                               %SDA-I-READSYM, reading symbol table name H                               %SDA-I-READSYM, cnt symbols read from name  >              If you do not set this bit, the above message are              displayed.T  =           o  OPT$M_NOSIGNAL_READ - when you set this bit, theg?              callback returns any error but does not signal it,l<              preventing SDA's or your condition handler fromA              being invoked. This allows you to handle read errorse#              directly in your code.o  A           _______________________________________________________D  -           THE LDRIMG ARGUMENT (ALPHA V7 ONLY)_  ;           Loaded system images are represented in memory byC=           an LDRIMG image block. This data structure containse<           the image name, its virtual start and end address,9           the date and time when the image was linked, as =           well the address of its symbol vector (if any). ForO:           sliced images, it contains information about the@           image's execlets as well. SDA's SHOW EXECUTIVE command@           interprets and displays the contents of LDRIMG blocks.  =           When you set the OPT$M_IMAGE_READ bit, SDA uses thea?           image name given in the filnam argument to locate thea<           appropriate LDRIMG block and takes the information)           found therein to build symbols.                B-114C A  i    A                                                     SDA CallbacksnA                                           SDA$EXTEND_READ_SYMFILEs        7           With the ldrimg argument, you can specify thed;           address of the image's LDRIMG block directly. All :           information is taken from this block; the reloc,=           symvec_va and symvec_siz arguments are not used. In ;           addition, you must not set other bits in options, =           except OPT$M_NOLOG_READ and/or OPT$M_NOSIGNAL_READ. >           Nevertheless, you must specify the image name in the           filnam argument.  A           Note: SDA compares the link time of the image specifiedn;           in filnam with the link time stored in the LDRIMGi9           block and signals the SDA$_LINKTIMEMISM warning )           condition if they do not match.   A           _______________________________________________________O  #           CONDITION VALUES RETURNED   =           SS$_NORMAL         The READ operation was performed *                              successfully.  7           SDA$_IMAGENF       "Image is not in activated ;           (Alpha only)       image lists". You have set thea@                              OPT$M_IMAGE_READ bit, but the image>                              wasn't found in the loaded system?                              image or activated shareable imaget<                              list. To read symbols from this>                              image, clear the OPT$M_IMAGE_READ!                              bit.   =           SDA$_LINKTIMEMISM  "Image link times do not match". >           (Alpha V7 only)    You have supplied an IMGLDR block>                              in the imgldr argument whose link>                              time does not match the link time>                              of the image specified in filnam.<                              This may or may not be an error=                              condition, depending on what youB(                              want to do.    A                                                             B-115     h               SDA Callbackse!           SDA$EXTEND_READ_SYMFILEs          =           SDA$_NOFILENAME    "Image in EXEC list has no valid ?                              file name". The LDRIMG contains no ?                              (valid) image file name; see SDA$_ &                              NOLDRIMG.  @           SDA$_NOLDRIMG      "No loaded image list found". There?                              were no loaded system images. This <                              can never happen on the running?                              system; however, it may occur when ;                              analyzing an incomplete systeme"                              dump.  ;           SDA$_NOREADLDRIMG  "Unable to access loaded image_9                              block". A LDRIMG image blockr=                              was not accessible. See previousl'                              condition.   ;           SDA$_OPENIN        "Error opening specified image <                              or symbol table file". An error9                              occured while trying to open_=                              the file specified in the filnam >                              argument. In most cases, you have<                              supplied an invalid filename or;                              specified a non-existent file.D  =           SDA$_RD_IMAGE_ERR  "Image is sliced or has a symbols<           (Alpha only)       vector". You have specified the;                              name of an activated shareabler:                              image; either an image with a=                              symbol vector or a sliced image. >                              Sliced images cannot be processed=                              without OPT$M_IMAGE_READ; if the_;                              image has a symbol vector, you_=                              must set either OPT$M_IMAGE_READI=                              or OPT$M_FORCE_READ, or you mustc=                              supply symbol vector information ;                              with symvec_va and symvec_siz._               B-116N X  T    A                                                     SDA CallbacksnA                                           SDA$EXTEND_READ_SYMFILE           9           SDA$_RD_SYSIMG_    "Error reading loaded systemi@           ERR (Alpha only)   image." You have specified the name?                              of a loaded system image, but havew<                              not set either OPT$M_IMAGE_READ=                              or OPT$M_FORCE_READ; or you have(@                              specified not enough information in@                              the reloc, symvec_va and symvec_siz'                              arguments.   ;           See Table B-3 for the numeric values of all erroro           codes.  A           _______________________________________________________              EXAMPLEe    symbols  from symbol table */  1       /*                                   VAX */   1            /*                              VAX */   3                  /*                        Alpha */E  3    /*                                      Alpha */e  *  all  executive images (READ/EXECUTIVE) */    OPT$M_EXEC_READ  0x10  >        /*                                        VAX V7 only*/  9  /*                                              Alpha */   2           The above example shows some ways to use>           SDA$EXTEND_READ_SYMFILE. The first example reads the?           contents of the system symbol table, SYSDEF.STB. ThisN;           table contains definition for various system datai<           structures; if you want to format these structures=           with SDA$EXTEND_FORMAT, you must first read in thiss>           table. Note that on VAX, you must supply a directory8           as well; on Alpha, the logical SDA$READ_DIR is-           translated to locate symbol tables.s  A                                                             B-117s e  e               SDA Callbacks !           SDA$EXTEND_READ_SYMFILE         =           The second example is similar to READ/EXECUTIVE, ite@           reads the symbol tables of all currently loaded system           images.   ;           In both examples, on Alpha, the suppr argument is >           set to 1, causing SDA to suppress the display of its;           READSYM message (on VAX, you cannot suppress thisa           message).f                                                                           B-118m r  n    A                                                     SDA CallbackstA                                                 SDA$EXTEND_REQMEM         A           _______________________________________________________t             SDA$EXTEND_REQMEM,  "           Copies data from memory.  A           _______________________________________________________              FORMAT  7           SDA$EXTEND_REQMEM  inadr, [retadr, len] (VAX)t  ;           SDA$EXTEND_REQMEM  inadr, [retadr, len], [phyflg]o  '                              (Alpha V6)   ?           SDA$EXTEND_REQMEM64  inadr64, [retadr, len], [phyflg]   )                                (Alpha V7)l  A           _______________________________________________________t             RETURNSi           VMS Usage: cond_valueh(           type:      longword (unsigned)           access:    write onlyd           mechanism: by value   8           All conditions are signaled as errors as well.  A           _______________________________________________________R             ARGUMENTS "           inadr (VAX and Alpha V6)             VMS Usage: address(           type:      longword (unsigned)           access:    read only           mechanism: by values=           Longword holding the 32-bit virtual base address of >           the data you want to copy from memory. This argument>           is used with SDA$EXTEND_REQMEM only; on Alpha, inadr#           must be longword-aligned.m  A                                                             B-119a v  d               SDA CallbacksG           SDA$EXTEND_REQMEMi                   inadr64 (Alpha V7)             VMS Usage: address(           type:      quadword (unsigned)           access:    read only           mechanism: by valuem=           Quadword holding the 64-bit virtual base address ofo>           the data you want to copy from memory. This argument>           is used with SDA$EXTEND_REQMEM64 only; the specified+           address must be longword-aligned.o             retadr             VMS Usage: address(           type:      longword (unsigned)           access:    write only !           mechanism: by reference_@           Return address wherein the data should be written. The@           retadr argument is a longword holding the base address?           of a buffer receiving the copied data. This must be as?           32-bit address in either P0 or P1 space. The argumentb;           is optional; if you do not supply it, an internali5           buffer is used to retrieve the copied data.e  @           If you specify this argument, you must also supply the           len argument.   ?           When programming in MACRO-32 or BLISS, you can obtain >           the first four bytes of the copied data in processor           register R1 as well.  
           lenM  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only           mechanism: by valueu8           Number of bytes to copy. This argument must be=           specified unless the retadr argument was omitted asd=           well. The lowest value of len is 4, in other words,s=           the smallest unit to copy is a longword (on VAX andz           Alpha).s             B-120          A                                                     SDA Callbacks A                                                 SDA$EXTEND_REQMEM                    phyflg (Alpha only)   &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only           mechanism: by valuei:           Physical address indicator. If you set phyflg to=           1, the address given in inadr/inadr64 is treated as            physical address.a  A           _______________________________________________________t             DESCRIPTION <           This callback is a jacket to SDA's general-purpose;           memory access routine SDA$EXTEND_TRYMEM. The only <           difference between them is their behaviour in case=           of error: while SDA$EXTEND_TRYMEM returns the errore;           code only, this callback also signals it as error.9           condition. Unless you have declared a conditionl@           handler, this causes SDA to interrupt the code of your=           extension, displaying the appropriate error messager@           and return to its main loop, printing its SDA> prompt.<           Use this callback when data inaccessibility at the?           given address will prevent your code from continuing. 9           You will not receive control in case of errors.   @           On Alpha V7, the input address (inadr64 argument) is a>           64-bit address, allowing you to access every virtual@           address in P0, P1, P2, S0/S1 and S2 space. To indicate?           this, the routine was renamed to SDA$EXTEND_REQMEM64;h?           the 32-bit version SDA$EXTEND_REQMEM is not availablec           on Alpha V7.  6           For more information, see the description of           SDA$EXTEND_TRYMEM.          A                                                             B-121     t               SDA Callbacksn           SDA$EXTEND_REQMEMd      A           _______________________________________________________t  #           CONDITION VALUES RETURNED   7           SDA$_SUCCESS       Memory copied successfully   4           SDA$_INVLDADR      Invalid virtual address  <           SDA$_INVRANGE      Invalid address range specified  ?           SDA$_MEMNOTACC     Memory locations not accessible in :                              override mode (Alpha V7 only)  ?           SDA$_MEMNOTSVD     Specified memory not saved in dump !                              file   >           SDA$_NOREAD        Could not access specified memory  @           SDA$_NOTINPHYS     Virtual data not in physical memory  ?           SDA$_NOTVALID      Information not in physical memoryy  :           SDA$_OUTSIDPT      Virtual address range exceeds6                              process page table bounds  >           SDA$_PFNNOTMPD     PFN from PTE not mapped by memory'                              descriptori  :           SDA$_REGNOTVALID   Register reference is invalid  ?           SDA$_UNALIGNED     Unaligned address specified (Alphae"                              only)  >           For a detailed description of these condition codes,=           please see the Condition values returned section ofG;           SDA$EXTEND_TRYMEM. Table B-3 contains the numerics<           values for all error codes; if you want to use the<           names listed here, you must define the appropriate           literals yourself.  A           _______________________________________________________t             EXAMPLE     retval;    to           */             B-122  l  e    A                                                     SDA Callbacks A                                                 SDA$EXTEND_REQMEM           =        SDA$EXTEND_A=           TRYMEM(pcbadr,&retval,4)) & 1)) lib$signal(status);l  5           This example shows the relationship betweenS>           SDA$EXTEND_GETMEM and SDA$EXTEND_REQMEM. If you want<           to terminate immediately when the requested memory=           is not available, you should use SDA$EXTEND_REQMEM.l9           Otherwise, use SDA$EXTEND_GETMEM if you want tor?           display an error message and want to continue, or use ?           SDA$EXTEND_TRYMEM if you want to continue, but do not $           want to display a message.                                                          A                                                             B-123m s  e               SDA Callbacksu            SDA$EXTEND_SET_ADDRESS        A           _______________________________________________________O              SDA$EXTEND_SET_ADDRESS  ,           Establishes a new current address.  A           _______________________________________________________L             FORMAT  (           SDA$EXTEND_SET_ADDRESS  curadr  <           SDA$EXTEND_SET_ADDRESS64  curadr64 (Alpha V7 only)  A           _______________________________________________________              RETURNS   :           This callback does not return a condition value.  A           _______________________________________________________              ARGUMENTSI           curadr             VMS Usage: address(           type:      longword (unsigned)           access:    read only           mechanism: by valuet<           A longword holding the new 32-bit current address.;           This argument is used with SDA$EXTEND_SET_ADDRESS            only.n  "           curadr64 (Alpha V7 only)             VMS Usage: address(           type:      quadword (unsigned)           access:    read only           mechanism: by value <           A quadword holding the new 64-bit current address.=           This argument is used with SDA$EXTEND_SET_ADDRESS64G           only.N             B-124o d  s    A                                                     SDA CallbackscA                                            SDA$EXTEND_SET_ADDRESSt      A           _______________________________________________________s             DESCRIPTIONe:           This callback establishes or changes the current9           address. The current address is also set by the =           last EXAMINE, FORMAT or VALIDATE command; it may be =           specified with the dot (.) character in any command ?           accepting SDA expressions. You may change the current >           address in your code to a particular value, allowing9           the user to reference this value later in other            commands.i  5           There is also a way to compute standard SDA <           expressions with this callback in conjunction with=           SDA$EXTEND_GET_ADDRESS and SDA$EXTEND_PARSECOMMAND.Y           See Section 3.4.  8           On Alpha V7, this callback exists in a version:           supporting 64-bit addresses as well. If you want9           to work in a 64-bit environment, you should usey6           SDA$EXTEND_SET_ADDRESS64. Note that on Alpha8           V7, both callbacks, SDA$EXTEND_SET_ADDRESS and2           SDA$EXTEND_SET_ADDRESS64, are available.  <           Note: Since the current address may change between=           calls of your extension, you should re-establish ito@           always if you want to provide it for later references.?           Do not assume that it remains unchanged between callsn           of your extension.  A           ________________________________________________________  #           CONDITION VALUES RETURNED_           None.               A                                                             B-125     f               SDA Callbacks             SDA$EXTEND_SET_ADDRESS        A           _______________________________________________________              EXAMPLEv          ?           This code establishes a new current address, possiblye'           from a previous memory fetch.n                                                                       B-126a    g    A                                                     SDA Callbacks A                                            SDA$EXTEND_SET_HEADING         A           _______________________________________________________d              SDA$EXTEND_SET_HEADING  (           Establishes a new header text.  A           _______________________________________________________              FORMAT  (           SDA$EXTEND_SET_HEADING  hdrstr  A           _______________________________________________________              RETURNS   :           This callback does not return a condition value.  A           _______________________________________________________.             ARGUMENTS            hdrstr              VMS Usage: char_string%           type:      character string            access:    read only8           mechanism: by descriptor - fixed-length string                      descriptor ;           The new header string. The hdrstr argument is the >           address of a character string descriptor pointing to            the new header string.  A           _______________________________________________________              DESCRIPTIONo>           This callback stores a new header string for further;           use. The header string is displayed on the top ofe>           every new page (when you call SDA$EXTEND_NEW_PAGE or$           SDA inserts a page break).  8           This callback is invoked by SDA$EXTEND_FORMAT_>           SUBHEADING when it has formatted a string containing8           FAO directives. If you want to format a header6           string with the tools and functions provided  A                                                             B-127c e  m               SDA Callbacks             SDA$EXTEND_SET_HEADING        6           by your language, you can do this and invoke>           SDA$EXTEND_SET_HEADING yourself to store the string.  A           _______________________________________________________   #           CONDITION VALUES RETURNEDl           None.   A           _______________________________________________________              EXAMPLE"  5  =        "Summary of %s Pool Usage, %3.2f%% in use";                 =              strlen(outbuf);     ?           Using the sprintf()  function, this example formats a =           header string and invokes SDA$EXTEND_SET_HEADING to >           store it for further displays. Note that the SYS$FAO9           services do not provide directives for floating <           point values; you must use language-specific tools;           to display such values (as shown in the example).                                  B-128E A       A                                                     SDA Callbacks A                                    SDA$EXTEND_SET_HEADING_ROUTINE         A           _______________________________________________________   5           SDA$EXTEND_SET_HEADING_ROUTINE-(Alpha only)   6           Establishes a new subheader display routine.  A           _______________________________________________________r             FORMAT  0           SDA$EXTEND_SET_HEADING_ROUTINE  dsprtn  A           _______________________________________________________              RETURNS   :           This callback does not return a condition value.  A           _______________________________________________________              ARGUMENTSi           dsprtn             VMS Usage: procedure$           type:      procedure value1           access:    call without stack unwinding !           mechanism: by referencee9           A longword holding the address of the subheader_           display routine.  A           _______________________________________________________o             DESCRIPTION @           This callback establishes a subheader display routine.<           This routine is invoked every time when a new page<           is displayed. Its output appears immediately under=           the header text established with SDA$EXTEND_FORMAT_ /           SUBHEADING or SDA$EXTEND_SET_HEADING.   >           In most cases, you use this callback when displaying<           large tables containing many rows and columns. The9           subheader ensures that the description of everyL:           column appears at the top of every new page. You9           can see an example of a subheader in the outputi  A                                                             B-129w    f               SDA Callbacks (           SDA$EXTEND_SET_HEADING_ROUTINE        8           of CLUE MEMORY/LAYOUT. The line containing the7           Item/Base/End/Length string is displayed by aA;           subheader routine established with this callback.   ?           The subheader display routine is called as procedure,s9           with no arguments. SDA expects no return value.D  ?           To delete a previously established subheader routine,R?           specify 0 in the dsprtn argument. Note that it's youre<           responsibility to delete a subheading routine when>           it is not longer required; otherwise, SDA will still<           continue to invoke it at the top of every new page=           (even outside of your code), until a new routine is )           established by another command.   :           On VAX, there is no way to establish a subheader>           routine. If you want to display subheaders, you must;           obtain the terminal's page size (using SYS$GETDVI <           with the DVI$_TT_PAGE item code), maintain a count:           of already displayed lines and write a subheader?           whenever the count reaches the value of DVI$_TT_PAGE._>           In this case, reset the line counter to 2 (since the=           underscored heading line at the top of the new pageD!           was already displayed).f  A           _______________________________________________________E             EXAMPLE         >    /*                               Clear subheader routine */          <  =         "Start VA         End VA         Size       Use";             B-130          A                                                     SDA Callbacks A                                    SDA$EXTEND_SET_HEADING_ROUTINE                 9           This example shows how to establish a subheader_@           routine and what to do within this routine. It ensures<           that a subheader, showing the meaning of the table=           columns, is displayed at the top of every new page.                                                                 A                                                             B-131  a  u               SDA Callbacksi#           SDA$EXTEND_SET_LINE_COUNTA        A           _______________________________________________________   3           SDA$EXTEND_SET_LINE_COUNT-(Alpha V7 only)   )           Changes the current line count.a  A           _______________________________________________________V             FORMAT  +           SDA$EXTEND_SET_LINE_COUNT  lincntu  A           _______________________________________________________u             RETURNSd  :           This callback does not return a condition value.  A           _______________________________________________________h             ARGUMENTSl           lincnt  $           VMS Usage: longword_signed&           type:      longword (signed)           access:    read only           mechanism: by value 9           A longword containing the new line count value.e  A           _______________________________________________________e             DESCRIPTIONn;           This callback changes the current line count (thee?           number of lines that have been printed on the currentd<           page). The line count is used by SDA to maintain a@           page-oriented display. Whenever the line count reaches=           the end of current page, SDA invoke SDA$EXTEND_NEW_t2           PAGE to perform page-related operations.  >           This callback enables you to change the current line@           count, controlling SDA's behaviour in page processing.;           For example, you can obtain the current line withM=           SDA$EXTEND_GET_LINE_COUNT, decrement this value and ;           store the new value with this callback. This will              B-132u         A                                                     SDA CallbackseA                                         SDA$EXTEND_SET_LINE_COUNTo        <           result in the display of larger pages which may be?           useful when output was redirected to a file (with SET            OUTPUT).  ?           This callback is available on Alpha V7 only, there is =           no replacement on earlier Alpha VMS versions and onQ           VAX.  A           _______________________________________________________d  #           CONDITION VALUES RETURNEDe           None.e  A           _______________________________________________________a             EXAMPLEy      4;y    9           This example performs the task described in thet?           Description section. SDA will display four additional_+           lines on the current output page.                                 A                                                             B-133y c                  SDA Callbackse           SDA$EXTEND_SKIP_LINESe        A           _______________________________________________________Y             SDA$EXTEND_SKIP_LINESo  *           Inserts a number of empty lines.  A           _______________________________________________________              FORMAT  '           SDA$EXTEND_SKIP_LINES  lincnt   A           _______________________________________________________              RETURNSn  :           This callback does not return a condition value.  A           _______________________________________________________t             ARGUMENTSi           lincnt  $           VMS Usage: longword_signed&           type:      longword (signed)           access:    read only           mechanism: by valuel<           A longword containing the number of empty lines to           insert.   A           _______________________________________________________T             DESCRIPTION =           This callback inserts the specified number of empty :           lines. The current line count is incremented and?           SDA$EXTEND_NEW_PAGE is invoked when the bottom of the ?           current page is reached. You can use this callback to 8           separate different text blocks in your output.               B-134_ _  _    A                                                     SDA CallbacksSA                                             SDA$EXTEND_SKIP_LINESl      A           _______________________________________________________D  #           CONDITION VALUES RETURNEDs           None.   A           _______________________________________________________              EXAMPLEe  9           This will insert two empty lines in the currente           display.                                                            A                                                             B-135  $  T               SDA Callbacksn           SDA$EXTEND_SYMBOLIZE        A           _______________________________________________________I             SDA$EXTEND_SYMBOLIZE  '           Symbolizes a numerical value.p  A           _______________________________________________________p             FORMAT  7           SDA$EXTEND_SYMBOLIZE  value, retstr, [symblk]V  A           _______________________________________________________U             RETURNSi  :           This callback does not return a condition value.  A           _______________________________________________________e             ARGUMENTSe           valuen  ;           VMS Usage: longword_unsigned or quadword_unsignedi@           type:      longword (unsigned: VAX, Alpha V6)/quadword)                      (unsigned: Alpha V7)e           access:    read only           mechanism: by value_;           A longword (VAX, Alpha V6) or quadword (Alpha V7) )           holding the value to symbolize./             retstr              VMS Usage: char_string%           type:      character stringa           access:    write only 8           mechanism: by descriptor - fixed-length string                      descriptorb<           Translated symbol name. The retstr argument is the;           address of a character string descriptor pointingG>           to a buffer into which the translated symbol name is>           written. The buffer should provide at least 40 bytes           of space.A             B-136          A                                                     SDA CallbackseA                                              SDA$EXTEND_SYMBOLIZEY                   symblk             VMS Usage: address(           type:      longword (unsigned)           access:    read only!           mechanism: by reference @           A longword holding the address of a symbol block. When<           you specify this argument, SDA does not look for a?           matching symbol in its symbol table; instead, it uses <           this argument in conjunction with value to build a=           symbolization string. This argument is optional; if_@           you do not specify it or specify it as 0, SDA looks in1           its symbol table for a matching symbol.S  A           ________________________________________________________             DESCRIPTION_@           This callback symbolizes a value. Symbolization occurs;           when a numerical value is substituted by a symbol_;           name; either based on the symbols stored in SDA's >           symbol table or on the symbol whose block address is           given in symadr.  >           When a symbol is defined, SDA creates a symbol block;           to store it. The symbol block contains the symbol :           name, its value and its attributes (if any). SDA@           inserts the symbol block in several trees at different@           positions; this allows the creation of symbol listings-           in alphabetical or numerical order.a  @           Given a symbol value, this callback traverses one tree=           (the 'numerical' tree which holds symbols sorted by ?           value) to find a symbol whose value matches the given >           value. If a symbol is found, its name is returned in<           retstr. If more symbols with the same value exist,>           the first matching symbol from the numerical tree is@           returned; there is no rule which symbol is returned in           this case.    A                                                             B-137  t  A               SDA Callbacksa           SDA$EXTEND_SYMBOLIZE        =           If no such symbol exist, SDA tries to find a symbol @           with a value not less than 0xFFF from the given value;@           if such symbol exist, its name is returned in the form@           name+offset where offset is the difference between the?           symbol value and the given value. For example, if youi=           specify 20004 as symbol value and there is a symbolD?           named TEST1 with a value of 20000, the callback would @           return the string TEST1+00004. Note that the offset is@           returned as five-digit hexadecimal number (although it(           cannot be greater than 0xFFF).  >           SDA always tries to find the symbol with the closest>           value to value. Consider the example above: if there=           would be another symbol named TEST2 with a value ofe?           20002, the string TEST2+00002 would be returned sincef?           this difference (2) is lower than the difference 4 in            the above example.  ?           SDA recognizes differences up to 0xFFF (decimal 4095)e<           only as offsets. If the difference is greater than=           this value, the corresponding symbol is not further            used.R  =           If no matching symbol is found in the symbol table, ;           SDA interprets the given value as virtual address ;           and scans the base addresses of all loaded system ;           images and device drivers. If a base address (and_8           an additional offset) matches, the name of the?           corresponding image and the offset value is returned.e?           For example, if the image SYSGETSYI starts at address 9           81922000 and you specify 81922C00 in value, the 6           callback returns the string SYSGETSYI+00C00.  ;           On Alpha only, if the specified address points to <           a sliced image section, SDA returns the image name<           and appends an underscore and one of the following           abbreviations:  8           o  NPRO - non-pageable read-only image section              (execlet)  9           o  NPRW - non-pageable read-write image section               (execlet)             B-138_ _  _    A                                                     SDA CallbacksrA                                              SDA$EXTEND_SYMBOLIZE_        3           o  PRO - pageable read-only image section   4           o  PRW - pageable read-write image section  *           o  INIT - initialization section  "           o  FIXUP - fixup section  ;           For example, if you specify 8021C800 in value ando=           8021C000 would be the base address of the non-paged <           read-only RMS execlet, SDA would return the string           RMS_NPRO+00800.r  9           If you specify the address of a symbol block in_<           symadr, SDA uses the information in this block for;           the symbolization. First, the value stored in theT<           symbol block is compared with the given value; the;           difference must not be greater than 0x0FFF. Then, >           if the difference is lower (or 0), the name from the:           symbol block and an optional offset is returned.  6           If no matching symbol is found, SDA sets the)           descriptor's length field to 0.t  A           _______________________________________________________   #           CONDITION VALUES RETURNED            None.   A           _______________________________________________________y             EXAMPLEa            return;    A                                                             B-139     _               SDA Callbacks_           SDA$EXTEND_SYMBOLIZE        @           This example invokes SDA$EXTEND_SYMBOLIZE to translate=           the value given in my_val into a symbol name. If noM>           symbol was found (the length field of the descriptor0           is 0) the routine returns immediately.  <           Another example how to use SDA$EXTEND_SYMBOLIZE is@           given in the description of SDA$EXTEND_LIB$INS_DECODE.                                                                             B-140s         A                                                     SDA CallbackslA                                           SDA$EXTEND_SYMBOL_VALUEi        A           _______________________________________________________   !           SDA$EXTEND_SYMBOL_VALUE   !           Obtains a symbol value.   A           _______________________________________________________              FORMAT  9           SDA$EXTEND_SYMBOL_VALUE  symnam (VAX, Alpha V6)D  >           SDA$EXTEND_SYMBOL_VALUE  symanm, [retval] (Alpha V7)  A           ________________________________________________________             RETURNS_           VMS Usage: cond_value (           type:      longword (unsigned)           access:    write only_           mechanism: by value_  =           Returns 1, if the specified symbol exists; 0, if itt           does not exist.   A           _______________________________________________________              ARGUMENTS            symnam              VMS Usage: char_string%           type:      character string            access:    read only8           mechanism: by descriptor - fixed-length string                      descriptor @           Name of the symbol whose value you want to obtain. The>           symnam argument is the address of a character string@           descriptor pointing to a buffer which holds this name.              retval (Alpha V7 only)             VMS Usage: address(           type:      longword (unsigned)           access:    write only !           mechanism: by referenceA  A                                                             B-141                     SDA Callbacks !           SDA$EXTEND_SYMBOL_VALUE         @           Address of a quadword receiving the symbol value. This           argument is optional.r  A           _______________________________________________________              DESCRIPTION 8           Given a symbol name, this callback returns the?           corresponding symbol value from SDA's internal symbol <           table; it is the opposite of SDA$EXTEND_SYMBOLIZE.?           If the symbol exists, the callback returns 1, else it            returns 0.  >           The callback returns the symbol value in register R1@           and, on Alpha V7 only, in the retval argument as well.>           Therefore, on other VMS versions, you must provide a-           jacket routine to obtain the value:r  3                .entry  SDA_EXTEND_SYMBOL_VALUE,^m<>cG                clrl    @8(ap)                       ; Init return valueiF                pushl   4(ap)                        ; Push symbol nameE                calls   #1,g^SDA$EXTEND_SYMBOL_VALUE ; Invoke callbacktC                blbc    r0,10$                       ; On error exitnI                movl    r1,@8(ap)                    ; Return symbol valueV@           10$: ret                                  ; That's all  @           This jacket is invoked in the same way as the Alpha V7-           version of SDA$EXTEND_SYMBOL_VALUE.   A           _______________________________________________________a  #           CONDITION VALUES RETURNEDr>           Returns 1, if the symbol exists; else, returns 0. No            condition is signaled.  A           _______________________________________________________a  ;           EXAMPLES how to use this callback can be found in   ?           Section 3.1 and in the description of SDA$EXTEND_GET_E           CURRENT_PCB.             B-142          A                                                     SDA Callbacks A                                      SDA$EXTEND_TRANSLATE_ADDRESS         A           _______________________________________________________   &           SDA$EXTEND_TRANSLATE_ADDRESS  -           Translates a value into an address.   A           _______________________________________________________              FORMAT  &           SDA$EXTEND_TRANSLATE_ADDRESS  A           _______________________________________________________              RETURNSo           VMS Usage: address(           type:      longword (unsigned)           access:    write only            mechanism: by value   @           Returns the address associated with the matched value,1           or zero if no matching value was found._  A           _______________________________________________________S             ARGUMENTS            R2  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only           mechanism: by valueX=           When invoking this callback, the processor register_@           R2 must contain the value for which you want to obtain$           the corresponding address.             R3             VMS Usage: address(           type:      longword (unsigned)           access:    read only!           mechanism: by referencer=           When invoking this callback, the processor registere8           R3 must contain the address of a table holding  A                                                             B-143_ _  _               SDA Callbacks_&           SDA$EXTEND_TRANSLATE_ADDRESS        :           value/address pairs. The format of this table is           described later.  A           _______________________________________________________e             DESCRIPTION ;           This callback translates a value into an address,s;           based on a supplied table. It returns the addressW@           associated with the matched value; or 0, if the values           does not match.   :           The callback is invoked by SDA$EXTEND_TRANSLATE_=           BITS which uses it to translate bit values to theiro=           corresponding names; the names strings are found byN;           their addresses which are coded in the table. Seei?           the description of SDA$EXTEND_TRANSLATE_BITS for more            information.  <           This callback does not conform the OpenVMS calling:           standard. It must be invoked as subroutine, with8           input arguments in CPU registers R2 and R3. If:           your programming language does not allow to call?           subroutines or pass arguments in processor registers,l+           you can provide a jacket routine:e  =                .entry  SDA_EXTEND_TRANSLATE_ADDRESS,^m<r2,r3> 6                movl    4(ap),r2                ; Value>                movl    8(ap),r3                ; Table address5                jsr     g^SDA$EXTEND_TRANSLATE_ADDRESS_F                movl    r0,@12(ap)              ; Return address (or 0)G                beql    10$                     ; If 0, no value matcheswB                movzbl  #1,r0                   ; Otherwise success;           10$: ret                             ; That's all   >           This jacket routine is invoked with three arguments:@           the first argument is the value you want to translate,8           the second is the address of the table and the:           third is the address of a longword receiving the=           corresponding address. The routine returns 1 if the_8           translation was successful, else it returns 0.             B-144I I       A                                                     SDA Callbacks_A                                      SDA$EXTEND_TRANSLATE_ADDRESSt        ,           The table is formatted as follows:  -                              value1, address1 -                              value2, address2                               .                              .                              .-                              valuen, addressng#                              -1, -1i  3           where value is a value and address is its_=           corresponding address. value and address are storedO?           in longwords. The table is terminated with a quadword            of -1.  A           Note: Most HLL (high level languages) provide an easierP=           way to translate values to addresses. This callbacki:           was intended primarily for MACRO-32 programmers.7           Unless you are programming in MACRO-32, it is3<           recommended that you use the features or functions9           provided by your language for this purpose. For <           example, in C, a switch/case construct can be used           here easier.  A           _______________________________________________________o             RETURNS_?           Returns the address whose value matches the specified 0           value. Returns 0, if no value matches.  A           _______________________________________________________   :           EXAMPLESle showing the coding of a value/address  >           table can be found in the description of SDA$EXTEND_           TRANSLATE_BITS.E        A                                                             B-145_ _  _               SDA CallbacksS#           SDA$EXTEND_TRANSLATE_BITSm        A           ________________________________________________________  #           SDA$EXTEND_TRANSLATE_BITS   1           Translates a bitmask into a bit string.   A           _______________________________________________________              FORMAT  <           SDA$EXTEND_TRANSLATE_BITS  tabadr, bitmsk, buflen,  1                                      bufadr (VAX)_  ;           SDA$EXTEND_TRANSLATE_BITS  tabadr, bitmsk, retdsc   ,                                      (Alpha)  A           _______________________________________________________d             RETURNS            VMS Usage: cond_value (           type:      longword (unsigned)           access:    write only(           mechanism: by valueh  +           Always SDA$_SUCCESS (0x00F48009).e  A           _______________________________________________________              ARGUMENTSr           tabadr             VMS Usage: address(           type:      longword (unsigned)           access:    read only!           mechanism: by reference @           Address of a bit definition table. The tabadr argument>           is a longword holding the address of this table. The1           format of the table is described later.e             bitmsk  "           VMS Usage: longword_mask(           type:      longword (unsigned)           access:    read only             B-146  l  k    A                                                     SDA Callbacks A                                         SDA$EXTEND_TRANSLATE_BITS                    mechanism: by value =           Longword holding the bitmask you want to translate.              buflen (VAX only)d  $           VMS Usage: longword_signed&           type:      longword (signed)           access:    read only           mechanism: by valuee;           A longword holding the length of the buffer whoseu(           address is supplied in bufadr.             bufadr (VAX only)i             VMS Usage: address(           type:      longword (unsigned)           access:    write onlyh!           mechanism: by reference_;           Translated bit string. The bufadr argument is theE;           address of a buffer into which the translated bitl>           string is written. Note that this argument is passed6           by reference, it's not a descriptor address.             retdsc (Alpha only)b              VMS Usage: char_string%           type:      character string.           access:    write onlyf8           mechanism: by descriptor - fixed-length string                      descriptoro;           Translated bit string. The retdsc argument is theA;           address of a character string descriptor pointinge=           to a buffer into which the translated bit string isi=           written. The length field of this descriptor, which @           initially contains the length of the string buffer, is>           updated by the callback to contain the length of the           returned string.      A                                                             B-147s m  s               SDA Callbacksr#           SDA$EXTEND_TRANSLATE_BITS       A           _______________________________________________________              DESCRIPTIONs;           This callback translates a bit mask into a comma- >           separated string consisting of the names of the bits;           set in the mask. The bit values and bit names areE=           supplied in a bit definition table whose address isi@           given in tabadr. The bit definition table is formatted           as follows:   -                              value1, address1d-                              value2, address2t                              .                              .                              .-                              valuen, addressnh#                              -1, -1T  :           where value is the bit number and address is the:           address of the counted ASCII (ASCIC) name string@           associated with that bit. value and address are stored?           in longwords. The table is terminated with a quadwordi           of -1.  ;           On VAX, the translated bit string is written intoo<           the buffer, but no information about its length is=           returned. Therefore, you should provide a mechanisme>           to obtain this length. For example, in C, you should<           pre-initialize the buffer with binary null's; upon>           return, you can use the strlen()  function to obtain?           the actual string length. An example of this is givenh!           in the Example section.i  <           On VAX, if no matching bits are set in bitmsk, the<           return buffer remains unchanged. On Alpha, in this?           case, the length field of the descriptor is set to 0.a  :           Note: Most HLL (high level languages) provide an9           easier way to translate bits. This callback wass=           intended primarily for MACRO-32 programmers. Unless <           you are programming in MACRO-32, it is recommended<           that you use the features or functions provided by             B-148n l       A                                                     SDA Callbacks A                                         SDA$EXTEND_TRANSLATE_BITSl        >           your language for this purpose. For example, in C, a8           switch/case construct may be used here easier.  ?           This callback invokes SDA$EXTEND_TRANSLATE_ADDRESS to 6           perform the bitvalue-to-address translation.  A           ________________________________________________________  #           CONDITION VALUES RETURNED 3           Returns always SDA$_SUCCESS (0x00F48009).   A           _______________________________________________________              EXAMPLE     <psldef.h>     i;     =               {"Xinited",                   "Xpagflful",                   "Xswpflful",                   "Xdinspen"};        '  [5]   = {PFL$V_INITED,    bit_name[0],c'           PFL$V_PAGFILFUL, bit_name[1],1'           PFL$V_SPWFILFUL, bit_name[2],-'           PFL$V_DINSPEN,   bit_name[3],S           -1,-1};                 A                                                             B-149b b  k               SDA Callbackss#           SDA$EXTEND_TRANSLATE_BITS         I  i<5;    i++)                                /* Convert ASCIZ to ASCIC */k  (  =          (char) strlen(bit_name[i]) -*           1;  /* The 'X' is overwritten */x                                                   /*    with       the             string                         length  >                            /*                           VAX */  >         /*                                              VAX */  >  SDA$EXTEND_PRINT(desc("Bits:         !AZ"),retbuf); /* VAX */  @        /*                                               Alpha */  @                                    /*                   Alpha */  @  "!AS"),&retdsc);                                    /* Alpha */  ?           This example shows the callback invocation on VAX and =           Alpha. It is used here to obtain a list of all bitsv6           set in a page/swap file control block (PFL).  >           First, since the bit strings in the table must be in?           ASCIC (counted ASCII) format, they are converted from ?           ASCIZ (zero-terminated ASCII) format used in C. ASCICu?           strings contain the length of the string in the first =           byte. In the declaration of the bit names, 'X's are ?           used as placeholder; they are overwritten at run-time <           with the actual string length. To accomplish this,@           you must declare the strings in RW (data) area (not as!           'const' or 'readonly')._  >           On VAX, the output buffer is pre-initialized with 0;@           otherwise, there would no way to retrieve the returned@           string length. Once the callback is invoked, the first>           byte in the output buffer is checked; if it is still<           0, there was no string retured. Otherwise, the FAO;           "!AZ" directive can be used to display the buffer_<           contents; since the buffer was initialized with 0,@           the string is still zero-terminated (assuming that the@           buffer was large enough to hold a string even with all?           bits set - it is the programmers job to ensure this).              B-150          A                                                     SDA Callbacks A                                         SDA$EXTEND_TRANSLATE_BITS         @           On Alpha, things are easier - if the descriptor length=           field contains a non-zero value on callback return, =           the string is displayed directly with the FAO "!AS"e           directive.  A           The desc()  function can be found in the description of #           SDA$EXTEND_PRINT_COLUMNS.e                                                                  A                                                             B-151)                    SDA Callbacks            SDA$EXTEND_TRYMEMc        A           _______________________________________________________              SDA$EXTEND_TRYMEMk  "           Copies data from memory.  A           _______________________________________________________              FORMAT  7           SDA$EXTEND_TRYMEM  inadr, [retadr, len] (VAX)_  ;           SDA$EXTEND_TRYMEM  inadr, [retadr, len], [phyflg]   '                              (Alpha V6)s  ?           SDA$EXTEND_TRYMEM64  inadr64, [retadr, len], [phyflg]o  )                                (Alpha V7)A  A           _______________________________________________________r             RETURNS            VMS Usage: cond_valuea(           type:      longword (unsigned)           access:    write onlyo           mechanism: by valuew  A           _______________________________________________________              ARGUMENTSe"           inadr (VAX and Alpha V6)             VMS Usage: address(           type:      longword (unsigned)           access:    read only           mechanism: by valuel=           Longword holding the 32-bit virtual base address of >           the data you want to copy from memory. This argument>           is used with SDA$EXTEND_TRYMEM only; on Alpha, inadr#           must be longword-aligned.              B-152e n  m    A                                                     SDA CallbackssA                                                 SDA$EXTEND_TRYMEMh                   inadr64 (Alpha V7)             VMS Usage: address(           type:      quadword (unsigned)           access:    read only           mechanism: by valuee=           Quadword holding the 64-bit virtual base address ofo>           the data you want to copy from memory. This argument>           is used with SDA$EXTEND_TRYMEM64 only; the specified+           address must be longword-aligned.o             retadr             VMS Usage: address(           type:      longword (unsigned)           access:    write only !           mechanism: by referencea<           Return address wherein the data should be written.<           The retadr argument is a longword holding the base?           address of the buffer receiving the copied data. ThisD<           must be a 32-bit address in either P0 or P1 space.@           This argument is optional; if you do not supply it, an>           internal buffer is used to retrieve the copied data.  @           If you specify this argument, you must also supply the           len argument.   ?           When programming in MACRO-32 or BLISS, you can obtain >           the first four bytes of the copied data in processor           register R1 as well.  
           lenh  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only           mechanism: by value 8           Number of bytes to copy. This argument must be=           specified unless the retadr argument was omitted as =           well. The lowest value of len is 4, in other words, =           the smallest unit to copy is a longword (on VAX and            Alpha).h  A                                                             B-153r .                  SDA Callbacks            SDA$EXTEND_TRYMEMe                   phyflg (Alpha only)c  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only           mechanism: by valueh:           Physical address indicator. If you set phyflg to=           1, the address given in inadr/inadr64 is treated asD           physical address.X  A           _______________________________________________________r             DESCRIPTION >           This callback is SDA's interface to access data from?           memory or from the dump file and write it into a user ?           buffer where you can further process it. The callbacke9           is invoked by SDA$EXTEND_GETMEM and SDA$EXTEND_s?           REQMEM; while these callbacks signal all return codeso<           as condition, SDA$EXTEND_TRYMEM returns the status>           code in cond_value only. Use this callback when data=           inaccessibility at the given address is an expecteds>           situation and you want to handle all possible memory           errors yourself.  <           On the running system, you can access any location6           in P0, P1 and S0/S1 space, assuming that the8           virtual address does not point to non-existent<           memory or is currently unmapped (null pages). With;           SDA$EXTEND_GETMEM64 (Alpha V7 only), you can alsot:           access data in P2 or S2 space. The callback runs=           mainly in kernel mode, allowing you to access everye?           valid page in system or per-process space, regardless3:           of their page protection (except N/A (no access);           pages). For addresses in per-process space and ins@           system space occupied by process headers, SDA triggers@           a special kernel AST to the target process to fault-in8           the page into the target process' working set.  >           Note: On Alpha, when phyflg is set to 1, the address@           given in inadr/inadr64 is treated as physical address.;           Unlike with virtual addresses, there is no way toh;           check whether a physical address is valid (points              B-154          A                                                     SDA CallbackseA                                                 SDA$EXTEND_TRYMEMs        >           to main memory or I/O space). Always be careful when>           specifying physical addresses; specifying an address@           pointing to non-existent physical memory can cause the+           CPU to halt with a machine check.T  @           When analyzing a system dump, SDA copies the requested@           memory from the dump file. Of course, this is possible;           only if the given virtual address range was valid ?           (mapped to physical memory) at the time of the crash. =           In addition, the page must exist in the dump file - <           this may or may not be the case when the dump file8           write was not or was partially only completed.  9           SDA uses a set of 'pseudo' virtual addresses toi=           represent the contents of some processor registers.t=           The following table shows this pseudo addresses ando@           the corresponding registers. Note that process context>           and CPU context will affect these registers as well.  A           _______________________________________________________eA           Register___VAX_______Alpha_V6___Alpha_V7_______________   ;           SP         FFFFFE00  C0000000   80000000.CFFFFFF0t  ;           KSP        FFFFFE20  C0000080   80000000.C0000000_  ;           ESP        FFFFFE24  C0000088   80000000.C0000008U  ;           SSP        FFFFFE28  C0000090   80000000.C0000010c  ;           USP        FFFFFE2C  C0000098   80000000.C0000018   ;           R0         FFFFFE30  D0000050   80000000.D0000050   ;           R1         FFFFFE34  D0000058   80000000.D0000058   ;           R2         FFFFFE38  D00000D0   80000000.D00000D0   ;           R3         FFFFFE3C  D00000D8   80000000.D00000D8   ;           R4         FFFFFE40  D00000E0   80000000.D00000E0D  ;           R5         FFFFFE44  D00000E8   80000000.D00000E8   ;           R6         FFFFFE48  D00000F0   80000000.D00000F0   ;           R7         FFFFFE4C  D00000F8   80000000.D00000F8a  ;           R8         FFFFFE50  D0000000   80000000.D0000000_  A                                                             B-155D X  D               SDA Callbackss           SDA$EXTEND_TRYMEM       A           _______________________________________________________ A           Register___VAX_______Alpha_V6___Alpha_V7_______________l  ;           R9         FFFFFE54  D0000008   80000000.D0000008_  ;           R10        FFFFFE58  D0000010   80000000.D0000010u  ;           R11        FFFFFE5C  D0000018   80000000.D0000018   ;           R12        FFFFFE60  D0000020   80000000.D0000020a  ;           R13        FFFFFE64  D0000028   80000000.D0000028_  ;           R14        -         D0000030   80000000.D0000030   ;           R15        -         D0000038   80000000.D0000038   ;           R16        -         D0000060   80000000.D0000060   ;           R17        -         D0000068   80000000.D0000068t  ;           R18        -         D0000070   80000000.D0000070   ;           R19        -         D0000078   80000000.D0000078s  ;           R20        -         D0000080   80000000.D0000080l  ;           R21        -         D0000088   80000000.D0000088   ;           R22        -         D0000090   80000000.D0000090   ;           R23        -         D0000098   80000000.D0000098   ;           R24        -         D00000A0   80000000.D00000A0   ;           R25        -         D00000A8   80000000.D00000A8i  ;           R26        -         D00000B0   80000000.D00000B0   ;           R27        -         D00000B8   80000000.D00000B8   ;           R28        -         D00000C0   80000000.D00000C0   ;           R29 (FP)   -         D0000040   80000000.D0000040   ;           R30 (SP)   -         C0000000   80000000.CFFFFFF0   ;           R31        -         C0000008   80000000.CFFFFFF8   ;           PC         FFFFFE68  D0000100   80000000.D0000100w  ;           PSL/PS     FFFFFE6C  D0000108   80000000.D0000108l  +           P0BR       FFFFFE70  -          -   +           P0LR       FFFFFE74  -          -s  +           P1BR       FFFFFE78  -          -h  +           P1LR       FFFFFE7C  -          -n             B-156r o  d    A                                                     SDA CallbackstA                                                 SDA$EXTEND_TRYMEMw      A           _______________________________________________________ A           Register___VAX_______Alpha_V6___Alpha_V7_______________r  ;           PTBR       -         C00000A0   80000000.C0000020   ;           ASN        -         C00000A8   80000000.C0000028s  ;           AST        -         C00000B0   80000000.C0000030i  ;           FEN        -         C00000B8   80000000.C0000038f  ;           FP0        -         C0000100   80000000.C0000080n  ;           FP1        -         C0000108   80000000.C0000088                .                .                .   ;           FP29       -         C00001E8   80000000.C0000168E  ;           FP30       -         C00001F0   80000000.C0000170_  ;           FPCR       -         C00001F8   80000000.C0000178   ;           CYCLE_     -         C0000080   80000000.C0000040            COUNTERn  ;           PAL_       -         C0000090   80000000.C0000050eA           RESERVED_______________________________________________i  ?           Note: When you specify one of these pseudo addresses,n>           you must not specify another length than the default:           value (4 on VAX, 8 on Alpha). You can access one>           register at a time only, otherwise, SDA$_REGNOTVALID           is returned.  @           On Alpha V7, the input address (inadr64 argument) is a>           64-bit address, allowing you to access every virtual@           address in P0, P1, P2, S0/S1 and S2 space. To indicate?           this, the routine was renamed to SDA$EXTEND_TRYMEM64;t?           the 32-bit version SDA$EXTEND_TRYMEM is not available            on Alpha V7.  A                                                             B-157d t  r               SDA Callbacks            SDA$EXTEND_TRYMEMi      A           _______________________________________________________   #           CONDITION VALUES RETURNEDl  8           SDA$_SUCCESS       Memory copied successfully.  ;           SDA$_INVLDADR      "Invalid virtual address". Youa>                              have specified an invalid virtual%                              address.h  ?           SDA$_INVRANGE      "Invalid address range specified".c:                              You have specified an invalid=                              address range. This may occur iff=                              you specify a valid base addressL=                              in inadr, but specify a value inn<                              len which exceeds the amount of6                              available virtual memory.  =           SDA$_MEMNOTACC     "Memory locations not accessiblee?                              in override mode" (Alpha V7 only). =                              When SDA was invoked in overridea;                              mode (see Section 3.7), memoryS3                              access is not allowed.p  ;           SDA$_MEMNOTSVD     "Specified memory not saved ina?                              dump file". You have specified theE=                              address of a page whose contentsr>                              was not written to the dump file.>                              This may occur when the dump file5                              write was not completed.   7           SDA$_NOREAD        "No read access". You have_<                              specified the address of a page@                              which does not allow read access (a5                              N/A - "no access" page).                        B-158  b  n    A                                                     SDA CallbacksFA                                                 SDA$EXTEND_TRYMEM           :           SDA$_NOTINPHYS     "Virtual data not in physical?                              memory". You have specified eithers:                              the address of a null page (a<                              page not currently mapped), or,>                              when analyzing a system dump, the=                              address of a page which does not ?                              point to physical memory (in other ;                              words, is not represented by a 5                              block in the dump file).   9           SDA$_NOTVALID      "Information not in physicals:                              memory." You have specified a<                              virtual address whose PTE (page<                              table entry) is not in physical8                              memory. This may occur when@                              analyzing a dump; you cannot access2                              data at this address.  ;           SDA$_OUTSIDPT      "Virtual address range exceedsL<                              process page table bounds". The<                              VAX CPU provides three internal=                              registers, holding the length of ?                              the P0, P1 and system page tables.i=                              If you specify a virtual addresse?                              range which exceeds these lengths, 4                              this error is returned.  ?           SDA$_PFNNOTMPD     "PFN from PTE not mapped by memory(:                              descriptor". This indicates a8                              corrupt or incomplete dump.  =           SDA$_REGNOTVALID   "Register reference is invalid".n9                              You have specified a virtualt<                              address which is used by SDA to=                              store CPU registers (see above),,=                              but have specified a value otherb>                              than 4 (VAX) or 8 (Alpha) in len.    A                                                             B-159                     SDA Callbacksh           SDA$EXTEND_TRYMEM           :           SDA$_UNALIGNED     "Unaligned address specified"<                              (Alpha only). This condition is=                              not returned, but is signaled as <                              warning and displayed on screen<                              even with SDA$EXTEND_TRYMEM. It@                              informs the user that the specified=                              address was not longword-alignedt?                              and that SDA has converted it to ap@                              longword boundary by ANDing it with(                              0xFFFFFFFC.  A           _______________________________________________________5             EXAMPLE     clidata,      ppddata;     '  = SDA$EXTEND_TRYMEM(clidata,&ppddata);_    &       1))  /  has                          no CLI mapped"));$    =           In this example, a check is made to see whether the_=           process has a CLI mapped - in this case, clidata is ;           be a pointer to the CLI data area. If the processn=           does not have a CLI mapped, the pointer contains 0,[;           resulting in a non-successful return status. This <           status is detected, a message is displayed and the           routine terminates.(  @           As shown in the example, you can use SDA$EXTEND_TRYMEM;           do perform a particular memory check and, in case_=           of unavailability, display a context-specific, moree!           understandable message.n               B-160     _    A                                                     SDA CallbacksUA                                                 SDA$EXTEND_TRYMEMa        A           The desc()  function can be found in the description of #           SDA$EXTEND_PRINT_COLUMNS.                                                                             A                                                             B-161e i  S               SDA Callbacksh           SDA$EXTEND_TYPE         A           _______________________________________________________              SDA$EXTEND_TYPED  "           Displays a line of data.  A           _______________________________________________________              FORMAT  1           SDA$EXTEND_TYPE  txtstr, [p1..pn] (VAX)   5           SDA$EXTEND_TYPE  txtstr, [prmlst] (Alpha) )h  >           SDA$EXTEND_TYPE6  txtstr, [prmlst64] (Alpha V7 only)  A           _______________________________________________________              RETURNSs           VMS Usage: cond_valuel(           type:      longword (unsigned)           access:    write only            mechanism: by valuea  8           Always SDA$_SUCCESS (0x00F48009). Any error is           signaled.   A           _______________________________________________________n             ARGUMENTSt           txtstr              VMS Usage: char_string%           type:      character stringb           access:    read only8           mechanism: by descriptor - fixed-length string                      descriptorn:           Text to be displayed. The txtstr argument is the>           address of a character string descriptor pointing to@           the text string. The string may contain FAO (Formatted#           ASCII Output) directives.i             B-162L ,  u    A                                                     SDA CallbackseA                                                   SDA$EXTEND_TYPE                    p1 to pn (VAX only)               VMS Usage: varying_arg&           type:      longword (signed)           access:    read only           mechanism: by valueu@           Values to be passed as FAO directive parameters. These;           arguments are longwords containing the parameterso<           needed by the FAO directives specified in the text<           string. Up to 17 parameters may be supplied; their@           number and contents depend on the used FAO directives.>           If you do not use FAO directives in the text string,)           you can omit further arguments.:             prmlst (Alpha only)e  -           VMS Usage: vector_longword_unsignedr(           type:      longword (unsigned)           access:    read only!           mechanism: by reference ?           List of FAO directive parameters. The prmlst argument :           is the address of a longword vector wherein each>           longword contains a parameter. The vector must start<           on a longword boundary; the number and contents of=           longwords depend on the used FAO directives. If you ?           do not use FAO directives in the text string, you can            omit this argument.G  :           This argument is used with SDA$EXTEND_TYPE only.  "           prmlst64 (Alpha V7 only)  -           VMS Usage: vector_quadword_unsigneds           type:      quadwordo           access:    read only!           mechanism: by referenceg8           List of FAO directive parameters. The prmlst64>           argument is the address of a quadword vector wherein=           each quadword contains a parameter. The vector must ?           start on a quadword boundary; the number and contents @           of quadwords depend on the used FAO directives. If you?           do not use FAO directives in the text string, you canG           omit this argument.n  A                                                             B-163                     SDA Callbacksn           SDA$EXTEND_TYPE         <           This argument is used with SDA$EXTEND_TYPE64 only.  A           _______________________________________________________              DESCRIPTIONe>           This callback formats and displays a line of data on=           the current output device; either on the screen or,t;           if output was redirected via SET OUTPUT, into thee            specified output file.  9           Unlike SDA$EXTEND_PRINT, this callback does noti=           provide a screen-oriented display, the current line =           count is not maintained. If the display reaches theh?           bottom of the screen, the screen scrolls; no new page5?           will be displayed and no page break is written to the            output file.  =           Use this callback instead of SDA$EXTEND_PRINT, when >           you want to display only few lines, for example, the?           result of a simple memory access. This will allow thes@           user to display data without unnecessary "Press Return?           to Continue" prompts. SDA's EVALUATE, EXAMINE, FORMATa3           and VALIDATE commands behave in this way.   8           Text formatting occurs via FAO directives. The8           callback invokes the SYS$FAO (VAX) or SYS$FAOL6           (Alpha) system service to format the string.:           Most FAO directives require parameters, they are;           supplied as arguments (VAX) or passed in a vector )           of longwords/quadwords (Alpha).   >           On Alpha V7, this callback exists in a version using>           the SYS$FAOL_64 system service as well. This service<           accepts 64-bit parameters, allowing you to display?           64-bit data with the appropriate FAO directives. Notet?           that on Alpha V7, both callbacks, SDA$EXTEND_TYPE andf*           SDA$EXTEND_TYPE64 are available.  7           See the System Service Reference Manual for a 9           description of the SYS$FAO/SYS$FAOL/SYS$FAOL_64_<           system services, the available FAO directives, and"           the required parameters.             B-1640 C  0    A                                                     SDA Callbacks A                                                   SDA$EXTEND_TYPE       A           _______________________________________________________   #           CONDITION VALUES RETURNED0>           Returns always SDA$_SUCCESS (0x00F48009). Conditions6           returned by RMS (which is used for the write>           operations) are signaled and displayed on the screen%           by SDA's condition handler.F  8           Error conditions given by SYS$FAO/SYS$FAOL are:           not returned. If SYS$FAO/SYS$FAOL fails for some;           reason (you have specified invalid FAO directives7@           or insufficient directive arguments), a null string is           displayed.  A           _______________________________________________________              EXAMPLE5  2  of                     !UL !AZ sections found.");  =        "group-global";     prmlst[2];_  /     /*                                   VAX */   1  =    seccnt;                         /* Alpha */_1  =    (int) sectyp;                   /* Alpha */   1            /*                            Alpha */   >           This example shows the use of SDA$EXTEND_TYPE on VAX           and Alpha.                  A                                                             B-1651                    SDA Callbacks0#           SDA$EXTEND_VALIDATE_QUEUE         A           _______________________________________________________0  #           SDA$EXTEND_VALIDATE_QUEUE1  @           Validates a double-linked queue. On Alpha V7, may also)           validate a singly-linked queue.t  A           _______________________________________________________              FORMAT  2           SDA$EXTEND_VALIDATE_QUEUE  options,inadr  @           SDA$EXTEND_VALIDATE_QUEUE64  options,inadr64 (Alpha V7  ,                                        only)  A           _______________________________________________________              RETURNS            VMS Usage: cond_value (           type:      longword (unsigned)           access:    write only            mechanism: by value   A           _______________________________________________________0             ARGUMENTS            options   "           VMS Usage: mask_longword(           type:      longword (unsigned)           access:    read only           mechanism: by value07           A longword holding a bit mask of options. The0(           following options are defined:  A           _______________________________________________________FA           Name______________Value__Meaning_______________________F  9           OPT$M_SELF        0001   Queue is self-relativeF             B-166          A                                                     SDA Callbacks7A                                         SDA$EXTEND_VALIDATE_QUEUE       A           _______________________________________________________ A           Name______________Value__Meaning_______________________   ;           OPT$M_QUADLINK    0002   Queue has linked list of_<                                    quadword addresses (Alpha+                                    V7 only)   @           OPT$M_SINGLINK    0004   Queue has no backward pointer2                                    (Alpha V7 only)  :           OPT$M_LISTQUEUE   0008   Display address of each>                                    element in the queue (AlphaA           _________________________V7_only)______________________   <           Note that the bit names shown in the table are not?           defined anywhere; if you want to use it in your code, <           you must define the appropriate literals yourself.             inadr              VMS Usage: address(           type:      longword (unsigned)           access:    read only           mechanism: by value8;           Longword holding the virtual address of the queue 8           head. This is a 32-bit address. If you specify=           OPT$M_SELF or OPT$M_QUADWORD (Alpha V7 only), inadr #           must be quadword-aligned.s  >           This argument is used with SDA$EXTEND_VALIDATE_QUEUE           only.t             inadr64o             VMS Usage: address(           type:      quadword (unsigned)           access:    read only           mechanism: by value 8           Quadword holding the 64-bit virtual address of6           the queue head. If you specify OPT$M_SELF or;           OPT$M_QUADWORD, inadr64 must be quadword-aligned.T  @           This argument is used with SDA$EXTEND_VALIDATE_QUEUE64           only.   A                                                             B-167n p  V               SDA Callbacks #           SDA$EXTEND_VALIDATE_QUEUE-      A           _______________________________________________________              DESCRIPTION_?           This callback is an interface to SDA's VALIDATE QUEUET;           command. Given the starting (header) address of ao@           queue, the callback checks the integrity of the queue.>           If the validation succeeds, SDA prints this message:  P                            Queue is complete, total of cnt elements in the queue  ;           where cnt are the elements the queue consists of.   5           On VAX, a queue is a list of elements (data ?           structures), where the first longword in each element :           holds the base address of the next element (also<           called forward link) and the second longword holds<           the base address of the previous element (backward;           link). The queue can be accessed by its header, aO<           pair of longwords holding the address of the first?           element in the first longword, and the address of the >           last element in the second longword. In other words,<           the header is a 'dummy' element at a known address;           (usually in the S0 pointer page), allowing you toD=           'enter' the queue and to traverse all its elements. <           Since each element is linked twice (by its forward;           and backward link), a queue is sometimes called a            doubly-linked list.   ;           The VAX processor provides instructions to inserte@           elements in a queue or remove elements from a queue in@           single, atomar operation. On Alpha, these instructions#           are emulated by PAL code.e  @           If you set the OPT$M_SELF bit in the options argument,@           the queue is assumed to be self-relative, meaning that?           forward and backward links of an element are relative 9           offsets to its neighboors. The VAX architecture @           requires the elements of self-relative queues starting>           on quadword boundaries; therefore, when setting this;           bit, the address given in inadr must be quadword-e>           aligned. This is also true for the emulated PAL code            instructions on Alpha.             B-168d o       A                                                     SDA Callbacks A                                         SDA$EXTEND_VALIDATE_QUEUE         <           If the validate operation fails for some reason, a?           message indicating the reason is displayed on screen, 9           but SS$_NORMAL is returned. In other words, youI<           can use this callback to inform the user whether a<           particular queue is valid, but you can't use it to>           obtain the result of the check. If you must find out=           this, you must traverse the queue elements yourselfm9           (the only condition returned by the callback isa?           SDA$_NOQUEUE, meaning that 0 was specified in inadr).t    #           Options bits for Alpha V7I  >           The following description is meaningful for Alpha V76           only. It explains the remaining option bits.  <           o  OPT$M_QUADLINK. - Even on Alpha V7 (with 64-bit@              support), most queues are still longword-organized,A              meaning that forward and backward links in the queue <              header and in the elements are 32-bit addressesA              stored in longwords. This restricts the queue header @              and all queue elements to reside in P0, P1 or S0/S1              space.y  :              There are, however, queues whose elements may8              reside in P2 or S2 space; for these queues,<              the queue header and forward/backward links are9              64-bit addresses stored in quadwords. If you ;              want to validate such queues, you must set thed<              OPT$M_QUADLINK bit, telling SDA it must process?              the first two longwords of each element as forwarda@              link and the second two longwords as backward link.  @              Note: Note that these queues must start on quadword;              boundaries; the address given in inadr must be               quadword-aligned.  ;           o  OPT$M_SINGLINK. - Some queues do not provide a <              backward link; they provide a forward link onlyA              (this is called a singly-linked queue). In addition, =              in some of these queues, the end of the queue is @              indicated by a forward link of 0 (zero-terminated).  A                                                             B-169                     SDA Callbacksg#           SDA$EXTEND_VALIDATE_QUEUEd        ?              By setting the OPT$M_SINGLINK bit, you tell SDA tooA              skip the backward link checks and to allow a forward A              link of 0 as end-of-queue indicator. If the queue is5*              zero-terminated, SDA displays  Z                               Queue is zero-terminated, total of cnt elements in the queue  0              instead of the message shown above.  :           o  OPT$M_LISTQUEUE. - When you set this bit, SDA:              displays the address of each queue element it@              traverses. This may be useful if the queue contains;              elements with incorrect links or for debuggingt              purposes.  :           If the queue header is itself in P2 or S2 space,:           you must use SDA$EXTEND_VALIDATE_QUEUE64 to pass9           a 64-bit header address. Note that on Alpha V7,M7           both callbacks, SDA$EXTEND_VALIDATE_QUEUE andc5           SDA$EXTEND_VALIDATE_QUEUE64, are available.e  =           Note that the callback currently provides no way to-=           specify a traversation (maximum link) limit (as the =           VALIDATE QUEUE command does with the /MAXIMUM_LINKS ;           qualifier). If you want to specify a traversationi9           limit, build the appropriate command string andD?           invoke SDA$EXTEND_PARSECOMMAND to execute the command            directly.   A           _______________________________________________________6  #           CONDITION VALUES RETURNEDh  9           SS$_NORMAL         Successful invocation of the_>                              callback. This does not mean that:                              the queue was in a consistent#                              state._  :           SDA$_NOQUEUE       No queue was given; the inadr>                              argument was not specified or was,                              specified as 0.             B-170p s  ]    A                                                     SDA Callbacks_A                                         SDA$EXTEND_VALIDATE_QUEUEu        A           _______________________________________________________l             EXAMPLEs    OPT$M_SELF  0x0001         ||      (header & 7))  B  header                        is zero or not quadword aligned"));        ;           This example validates the queue whose address is 9           stored in header. Since this is a self-relative @           queue, a check is made first to ensure that the header>           address is non-zero and quadword aligned, before the           callback is invoked.  A           The desc()  function can be found in the description of #           SDA$EXTEND_PRINT_COLUMNS.t                                  A                                                             B-171e v  i    "           SDA callback description          A           Table_B-3__SDA_message_status_codes____________________   -                                         Value A           Message_Name_______Severity___(hex)______Meaning_______r  >           SDA$_CMDNOTVLD     Error      0x00F4818A command not@                                                    valid in this:                                                    context  ?           SDA$_IMAGENF[1]    Error      0x00F486B2 image is notb<                                                    in loaded?                                                    or activatedc=                                                    image list   :           SDA$_INVBLKTYP     Error      0x00F480BA Invalid=                                                    block type ?                                                    in specified 8                                                    block  :           SDA$_INVLDADR      Error      0x00F4823A invalid:                                                    virtual:                                                    address  :           SDA$_INVRANGE      Error      0x00F48102 invalid@                                                    address range<                                                    specified  :           SDA$_INVSUBTYP     Error      0x00F4827A Invalid=                                                    subtype inY<                                                    specified8                                                    block  =           SDA$_              Warning    0x00F48778 image link ?           LINKTIMEMISM[2]                          times do nott8                                                    match  9           SDA$_MEMNOTACC[2]  Error      0x00F487C2 memorye<                                                    locationsA                                                    not accessiblet>                                                    in override7                                                    mode   A           _______________________________________________________            [1]Alpha onlyn           [2]Alpha V7 only             B-172  s  g    A                                          SDA callback description_          A           Table_B-3_(Cont.)__SDA_message_status_codes____________   -                                         Value A           Message_Name_______Severity___(hex)______Meaning_______   <           SDA$_MEMNOTSVD     Warning    0x00F48228 specified=                                                    memory notR@                                                    saved in dump7                                                    filei  ?           SDA$_              Warning    0x00F486F8 loaded imageh?           NOFILENAME[1]                            has no valido<                                                    file name  <           SDA$_NOLDRIMG      Warning    0x00F48040 no loaded=                                                    image list 8                                                    found  <           SDA$_NOREAD        Warning    0x00F48048 could not9                                                    accessN<                                                    specified9                                                    memoryT  <           SDA$_NOREADLDRIMG  Warning    0x00F48050 unable to@                                                    access loaded>                                                    image block  ?           SDA$_NOQUEUE       Error      0x00F4810A no queue hassA                                                    been specified A                                                    for validationl  =           SDA$_NOSYMBOLS     Error      0x00F480C2 No symbols ;                                                    found tor>                                                    format this8                                                    block  :           SDA$_NOTINPHYS     Error      0x00F480AA virtual;                                                    data not >                                                    in physical9                                                    memory0  A           _______________________________________________________k           [1]Alpha only   A                                                             B-173_ _  _    "           SDA callback description          A           Table_B-3_(Cont.)__SDA_message_status_codes____________S  -                                         Value A           Message_Name_______Severity___(hex)______Meaning_______d  >           SDA$_NOTVALID      Error      0x00F48092 information9                                                    not ina;                                                    physicale9                                                    memorye  @           SDA$_OPENIN        Fatal      0x00F48144 error opening<                                                    specified;                                                    image or ?                                                    symbol tableo7                                                    file   :           SDA$_OUTSIDPT      Error      0x00F48112 virtual:                                                    address@                                                    range exceeds?                                                    process page ?                                                    table bounds   ?           SDA$_PFNNOTMPD     Error      0x00F4811A PFN from PTE0=                                                    not mapped_<                                                    by memory=                                                    descriptorn  ;           SDA$_RD_IMAGE_     Error      0x00F486AA image isi<           ERR[1]                                   sliced or?                                                    has a symbolV9                                                    vectorT  @           SDA$_RD_SYSIMG_    Error      0x00F486A2 error reading@           ERR[1]                                   loaded system8                                                    image  ;           SDA$_REGNOTVALID   Error      0x00F4825A register <                                                    reference=                                                    is invalid_  <           SDA$_SUCCESS       Success    0x00F48009 operation<                                                    completed?                                                    successfullyu  A           _______________________________________________________            [1]Alpha onlye             B-174  _  _    A                                          SDA callback description_          A           Table_B-3_(Cont.)__SDA_message_status_codes____________0  -                                         Value A           Message_Name_______Severity___(hex)______Meaning_______   @           SDA$_SYNTAX        Warning    0x00F48060 error parsing?                                                    the supplied_A                                                    command string_  <           SDA$_UNALIGNED[1]  Warning    0x00F48650 unaligned?                                                    address; wasd<                                                    converted=                                                    to alignedt:                                                    addressA           _______________________________________________________            [1]Alpha onlyeA           _______________________________________________________n                                              A                                                             B-175w e  f                A           _______________________________________________________a  %    C      OpenVMS V7.2 Alpha Addendum       :           As mentioned in the introduction of this manual,=           writing SDA extensions will be supported on OpenVMS ?           Alpha V7.2 (it will still remain unsupported on VAX). >           This appendix lists the known changes in development@           environment and SDA's run-time behaviour under OpenVMS           Alpha V7.2.s  ?           Note: Note that the following information is based on <           the OpenVMS V7.2 Pre-Release Notes (Beta-release).@           There is no guarantee that these or additional changes>           will be included in the Open VMS V7.2 final release.=           Do not assume that the entire following information <           remains valid; before writing your extension under=           OpenVMS Alpha V7.2, read the Release Notes, Versions8           7.2 and the New features, Version 7.2 manuals.    =           Only DEC C supported. - Only DEC C is the supportedn<           language when writing SDA extensions. Arguments of=           callback are optimized for invocation from C (e.g.,_?           strings are not longer passed by descriptor; instead,s?           they are passed as ASCIZ (zero-terminated) strings bym           reference). [1]a                     ________________=         [1] You can still continue to write your extension ine=             your favorite language, but must declare all SDA- @             specific literals yourself and must provide callback  )             arguments in a C-conform way.q  A                                                               C-1  t       %           OpenVMS V7.2 Alpha Addendumw          ;           Callbacks, status codes, literals and option bitse<           are now defined. - All SDA callbacks, literals and?           options bits are now defined in module sda_routines.hk:           in SYS$SHARE:SYS$LIB_C.TLB. In addition, all SDA<           return codes are available from module SDAMSG from>           SYS$SHARE:VMS$VOLATILE_PRIVATE_INTERFACES.OLB. There7           is no longer need to declare it in your code.I    =           Extension jacket object now part of object library.n:           - The object containing the jacket routines (see?           Section A.2) is not longer provided as separate file,l=           it is included as module in SYS$SHARE:VMS$VOLATILE_f=           PRIVATE_INTERFACES.OLB. Therefore, you must includee5           this object library in your link operation.A    ?           Third argument passed to extensions main entry point. <           - The extension's initialization (main) routine is>           now invoked with three arguments. In addition to the@           callback pointer (see Section 2.2.2.1) and the command@           pointer (see Section 2.2.2.2), SDA passes a bitmask as3           third argument, indicating the following:l  ;           o  whether a system dump or the running system ish(              analyzed (see Section 3.1);  :           o  whether SDA was invoked in override mode (see              Section 3.6).  ;           For this reason, the SDA$EXTEND_ON_CURRENT_SYSTEM )           callback does not longer exist..  >           Callbacks removed. - The following callbacks are not           longer available:6  @           o  SDA$EXTEND_GET_DYN_INFO (replaced by SDA$GET_BLOCK_              NAME)  5           o  SDA$EXTEND_ON_CURRENT_SYSTEM (see above)U  
           C-2     f    A                                       OpenVMS V7.2 Alpha Addendumi          9           o  SDA$EXTEND_PRINT_COLUMNS (can be done easieri              manually from C)I  @           o  SDA$EXTEND_PRINT_COLUMN_VALUE (not callable from C)  <           o  SDA$EXTEND_SET_HEADING (replaced by SDA$FORMAT_              HEADING)f  =           o  SDA$EXTEND_TRANSLATE_ADDRESS (can be done easiers              manually from C)   <           o  SDA$EXTEND_TRANSLATE_BITS (not callable from C)  +           SDA$EXTEND_PRINT_COLUMN_VALUE andd9           SDA$EXTEND_TRANSLATE_ADDRESS were removed since >           they do not confirm the calling standard (are called8           as subroutines, expect and return arguments in<           processor registers). For the remaining callbacks,6           were appropriate, replacements are provided.  @           Callbacks added. - The following new callbacks are now           available:  7           o  SDA$DBG_IMAGE_INFO - displays mapped image >              information (mostly used for debugging purposes).@              This is the same information as displayed with CLUE              DEBUG.   @           o  SDA$GET_BLOCK_NAME - given a dynamic data structureA              type (and optional a subtype), this callback returnsh?              the structure's type name (see SDA$EXTEND_FORMAT).e  ;           Callbacks renamed. - All callbacks are renamed inu?           the way that the EXTEND_ prefix is removed from theirl?           names (e.g, SDA$EXTEND_GETMEN becomes SDA$GETMEM). In =           addition, the following callbacks were renamed in al           special way:      A                                                               C-3          %           OpenVMS V7.2 Alpha Addendumu        A           _______________________________________________________mA           Old_name____________________New_name___________________e  8           SDA$EXTEND_FORMAT_          SDA$FORMAT_HEADING           SUBHEADING  :           SDA$EXTEND_GET_IMAGE_OFF    SDA$GET_IMAGE_OFFSET  6           SDA$EXTEND_HANDLER          SDA$COND_HANDLER  <           SDA$EXTEND_LIB$INS_DECODE   SDA$INSTRUCTION_DECODE  A           SDA$EXTEND_PARSECOMMAND_____SDA$PARSE_COMMAND__________   8           Enhanced 64-bit support. - The "64" suffix was?           removed from the approbate callback names since these @           callbacks provide now 64-bit support by default. There?           are no longer 32-bit versions; you can use the 64-bit-7           callbacks to access 32-bit addresses as well.   ;           The following callbacks now accept or return full            64-bit addresses:e             o  FORMAT   !           o  GETMEM/REQMEM/TRYMEMu  $           o  GET_ADDRESS/SET_ADDRESS             o  GET_CURRENT_PCB             o  GET_IMAGE_OFFSETh             o  VALIDATE_QUEUEo  @           The following callbacks accept or return 64-bit symbol           values:o             o  ADD_SYMBOLe             o  SYMBOL_VALUES             o  SYMBOLIZE  9           The following callbacks accept 64-bit argumentst?           suitable for use with the SYS$FAOL_64 system service:s             o  FORMAT_HEADINGc  
           C-4X D  L    A                                       OpenVMS V7.2 Alpha Addendume                     o  PRINT             o  TYPEr  ?           Callbacks enhanced. - Many callbacks provide enhanceda9           features and are optimized to be called from C.y;           Strings are now passed in ASCIZ (zero-terminated)e?           format by reference, not longer by descriptor or withS;           a separate length argument. Where approbate, they >           are returned in ASCIZ format as well. In some cases,=           the argument sequence was changed, making less-used            arguments optional.     =           Debugger image provided. - SDA is now provided in at?           version suitable for extension debugging. To use this ?           version, compile and link your extension with /DEBUG.N           Thereafter, enter:  1                            $ DEFINE SDA SDA_DEBUGe  =           and invoke SDA as usual. The above image will allow 8           you to run your extension under the debugger's           control.                                A                                                               C-5_