Library /sys$common/syshlp/SDA.HLB  —  Extension Routines, Callable Routines Overview
    The user-written routine may call SDA routines to accomplish any
    of the following tasks:

    o  Read the contents of memory locations in the dump.

    o  Translate symbol names to values and vice-versa, define new
       symbols, and read symbol table files.

    o  Map an address to the activated image or executive image that
       contains that address.

    o  Output text to the terminal, with page breaks, page headings,
       and so on (or output to a file if the SDA commands SET OUTPUT
       or SET LOG have been used).

    o  Allocate and deallocate dynamic memory.

    o  Validate queues/lists.

    o  Format data structures.

    o  Issue any SDA command.

    Note the following points before using the callable routines
    described here:

    o  The following three routines are used to read the contents of
       memory locations in the dump:

       -  SDA$TRYMEM is called from both SDA$GETMEM and SDA$REQMEM
          as the lower-level routine that actually does the work.
          SDA$TRYMEM returns success/failure status in R0, but does
          not signal any errors. Use it directly when you expect that
          the location being read might be inaccessible. The caller
          of SDA$TRYMEM handles this situation by checking the status
          returned by SDA$TRYMEM.

       -  SDA$GETMEM signals a warning when any error status is
          returned from SDA$TRYMEM. Signaling a warning prints out
          a warning message, but does not abort the SDA command in
          progress. You should use this routine when you expect the
          location to be read to be accessible. This routine does
          not prevent the command currently being executed from
          continuing. The caller of SDA$GETMEM must allow for this
          by checking the status returned by SDA$GETMEM.

       -  SDA$REQMEM signals an error when any error status is
          returned from SDA$TRYMEM. Signaling an error prints out
          an error message, aborts the SDA command in progress, and
          returns to the "SDA>" prompt. You should use this routine
          when you expect the location to be read to be accessible.
          This routine prevents the command currently being executed
          from continuing. The caller of SDA$REQMEM does not resume
          if an error occurs.

    o  You should use only the routines provided to output text.
       Do not use printf() or any other standard routine. If you
       do, the SDA commands SET OUTPUT and SET LOG will not produce
       the expected results. Do not include control characters in
       output (except tab); in particular, avoid <CR>, <LF>,<FF>,
       and the FAO directives that create them. Use the FAO directive
       !AF when contents of memory returned by SDA$TRYMEM, and so
       on, are being displayed directly, because embedded control
       characters will cause undesirable results. For example,
       displaying process names or resource names that contain
       particular control characters or escape sequences can lock
       up the terminal.

    o  You should use only the routines provided to allocate and
       deallocate dynamic memory. Do not use malloc() and free().
       Where possible, allocate dynamic memory once, the first time
       the extension is activated, and deallocate it only if it needs
       to be replaced by a larger allocation. Because SDA commands
       can be interrupted by invoking another command at the "Press
       return for more" prompt, it is very easy to cause memory
       leaks.

    o  Some routines expect 32-bit pointers, and others expect 64-
       bit pointers. At first this not may appear to be logical,
       but in fact it is. All code and data used by SDA and any
       extensions must be in P0 or P1 space, as SDA does not need to
       (and does not) use P2 space for local data storage. However,
       addresses in the system dump (or running system, in the case
       of ANALYZE/SYSTEM) are 64-bit addresses, and SDA must provide
       access to all locations in the dump.

       So, for example, the first two arguments to the routine
       SDA$TRYMEM are:

               VOID_PQ start   /* 64-bit pointer */

               void *dest      /* 32-bit pointer */

       They specify the address of interest in the dump and the
       address in local storage to which the dump contents are to
       be copied.

    o  Common Bitmask Block (CBB) routines, SDA$CBB_xxx, are
       designed for use with local copies of the CBB structures that
       describe the CPUs in use in a system. The CBB structures are
       assumed to be at least CBB$K_STATIC_BLOCK bytes in length.
       The definitions of the various CBB constants and field
       names used by these routines can be found in CBBDEF.H in
       SYS$LIBRARY:SYS$LIB_C.TLB.

       The set of routines is not intended to be an exhaustive set
       of all possible CBB-related operations, but it provides those
       operations known to be needed. The routines might not work as
       expected with CBB structures that are set up for any purpose
       other than to describe CPUs.
Close Help