k%Writing SDA Extensions.

Writing SDA Extensions


9Previous6 | Contents


HTo determine the type of the structure, SDA examines the 'type' byte at Goffset 0x0A (relative to the structure's base address). Using the type Dvalue, SDA determines the structure's name from one of its internal tables.

DAll 'type' values and the corresponding names are defined in module C$DYNDEF). The names are usually an abbreviation of the structure's Bpurpose; for example, the type value 2 corresponds to an ACB (AST control block).

COnce the structure name is known, SDA uses all symbols whose names Hstart with the structure name to display the contents of the structure. >The value of each symbol is treated as relative offset to the @structure's base address; the data at this address is displayed Ctogether with the symbol name. For every symbol, SDA uses the size Gindicator to determine how many data should be displayed. For example, Eif the structure name was PCB (a process control block), all symbols Gstarting with PCB$ are used in the display (the dollar sign is used as Dstructure name delimiter). In the case of PCB$L_PHD, SDA displays a Flongword since the size indicator (the character following the dollar Asign) means a longword. The following table shows all known size indicators: $ " '                                                    
Indicator Meaning Displayed as
 A Address  Longword
 B Byte Byte
 C Literal ¹
 G  Global longword  Longword
 L  Longword  Longword
 P Pointer  Longword
 Q  Quadword  2 Longwords
 R  Reference (Address)  Longword
 T  Text string ASCIC (counted ASCII) text
 W Word Word



=¹Only literals of the form typnam$C_LENGTH are Frecognized. They are displayed in a single line, mostly at the end of the structure.



8Symbols with other indicators (K,M,V) are not displayed.

FThere are some structures with different formats; the 'type' field is Gused to store other data (the PHD - process header - is an example for Gthis). In this case, you must tell SDA the type name by specifying the ?typnam argument and setting the OPT$M_TYPE bit in the Goptions argument. This corresponds to the FORMAT/TYPE H=typnam command; SDA formats the data structure using 2all symbols with the supplied type name as prefix.





Note

AFor most data structures, the appropriate symbol definitions are Hprovided in the system symbol table file SYS$SYSTEM:SYSDEF.STB (VAX) or BSYS$LOADABLE_IMAGES:SYSDEF.STB (Alpha). This table is not read by Ddefault; you must use SDA's READ command or invoke nSDA$EXTEND_READ_SYMFILE to make known these symbols to SDA. 



3For more information, see the description of SDA's FORMAT command. 


/

Condition values returned

1
rReturns always SDA$_SUCCESS (0x00F48009). Table B-1 shows the Bconditions which may be signaled. A signaled condition causes the Bcallback to abort, to display the appropriate message text and to Breturn to your code, unless you have declared a condition handler.

vIn 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.



U   "                 
Table B-1 SDA$EXTEND_FORMAT signaled conditions
Name Value Meaning
 SDA$_INVBLKTYP  0x00F480BA M "Invalid block type in specified block." Occurs when you try to format M a data structure which does not contain its type in the byte at offset K 0x0A. The PHD (process header) is an example for this. To format the 6 structure, you must provide the type name in the typnam argument.
 SDA$_INVSUBTYP  0x00F4827A N "Invalid subtype in specified block." This is the same as the condition M above for the subtype at offset 0x0B. Occurs with data types requiring < a valid subtype only (types in the range 0x60 - 0x7F).
 SDA$_NOSYMBOLS  0x00F480C2 L "No symbols found to format this block." This may occur if you try to M 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 typnam argument.





Example


#define OPT$M_TYPE 1  int phd_addr;  $DESCRIPTOR(phd_prefix,"PHD");    .   .   .8SDA$EXTEND_FORMAT(OPT$M_TYPE,&phd_prefix,phd_addr);  


DIn this example, a PHD (process header) is formatted. Since the PHD Gdoes not contain type and subtype information at the expected offsets, Fthe OPT$M_TYPE bit is set in the first, and the type name is supplied as second argument.


=

SDA$EXTEND_FORMAT_SUBHEADING



#Formats and stores a header string.



Format

7

SDA$EXTEND_FORMAT_SUBHEADING hdrstr, [p1..pn]

 (VAX)7

SDA$EXTEND_FORMAT_SUBHEADING hdrstr, [prmlst]

 (Alpha)



RETURNS



0This callback does not return a condition value.




ARGUMENTS



hdrstr


                
 VMS usage:  char_string
type:  character string
access:  read only
 mechanism: 4 by descriptor - fixed-length string descriptor

HString to be displayed at the top of each new page. The hdrstr Eargument is the address of a character string descriptor pointing to Cthe header string. The string may contain FAO (Formatted ASCII Output) directives.

p1 to pn (VAX only)


                
 VMS usage:  varying_arg
type:  longword (signed)
access:  read only
 mechanism:  by value

EValues to be passed as FAO directive parameters. These arguments are Alongwords containing the parameters needed by the FAO directives Especified in the header string. Up to 17 parameters may be supplied; Gtheir number and contents depend on the used FAO directives. If you do Bnot use FAO directives in the header string, you can omit further arguments.

prmlst (Alpha only)


                
 VMS usage:  vector_longword_unsigned
type:  longword (unsigned)
access:  read only
 mechanism:  by reference

FList of FAO directive parameters. The prmlst argument is the >address of a longword vector wherein each longword contains a Hparameter. The vector must start on a longword boundary; the number and Gcontents of longwords depend on the used FAO directives. If you do not Duse FAO directives in the header string, you can omit this argument.



DESCRIPTION

GThis callback prepares and stores a header string for further use. The Gheader 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 current page !in the output file becomes full).

GFormatting occurs via FAO directives. The callback invokes the SYS$FAO H(VAX) or SYS$FAOL (Alpha) system service to format the string. Most FAO Gdirectives require parameters, they are supplied as arguments (VAX) or Fpassed in a vector of longwords (Alpha). The callback further invokes hSDA$EXTEND_SET_HEADING to store the new header string.





Note

HOn Alpha V7, the 64-bit version (SYS$FAO64) is not currently supported, 7only 32-bit FAO directives and parameters may be used. 



DIf you do not want to use FAO directives, you can format the header Dstring with the commands or functions provided by your language and Wcall SDA$EXTEND_SET_HEADING directly.

FSee the System Service Reference Manual for a description of Gthe SYS$FAO/SYS$FAOL system service, the available FAO directives, and the required parameters.


/

Condition values returned

1
BThis callback returns no condition value. If the SYS$FAO/SYS$FAOL Csystem service fails (invalid FAO directives or too few parameters Asupplied), a null string is stored as header; errors returned by <SYS$FAO/SYS$FAOL are not passed to the caller.



Example


+$DESCRIPTOR(hdr_str,"GSD #!UL, VA = !XL"); int gsd_num, va;  int prm_lst[2];    .   .   .ESDA$EXTEND_FORMAT_SUBHEADING(&hdr_str,gsd_num,va); /*** VAX ***/  Cprm_lst[0] = gsd_num; prm_lst[1] = va;             /*** Alpha ***/  GSDA$EXTEND_FORMAT_SUBHEADING(&hdr_str,prm_lst);    /*** Alpha ***/  


GFormats and stores a header string to which is displayed at the top of @every page. On Alpha, the arguments are supplied in a vector of longwords.


2

SDA$EXTEND_GETMEM



Copies data from memory.



Format

0

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)



RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


0All conditions are signaled as warnings as well.




ARGUMENTS

!

inadr (VAX and Alpha V6)


                
 VMS usage: address
type:  longword (unsigned)
access:  read only
 mechanism:  by value

FLongword holding the 32-bit virtual base address of the data you want Hto copy from memory. This argument is used with SDA$EXTEND_GETMEM only; 2on Alpha, inadr must be longword-aligned.

inadr64 (Alpha V7)


                
 VMS usage: address
type:  quadword (unsigned)
access:  read only
 mechanism:  by value

FQuadword holding the 64-bit virtual base address of the data you want Dto copy from memory. This argument is used with SDA$EXTEND_GETMEM64 5only; the specified address must be longword-aligned.

retadr


                
 VMS usage: address
type:  longword (unsigned)
access:  write only
 mechanism:  by reference

GReturn address wherein the data should be written. The retadr Fargument is a longword holding the base address of a buffer receiving Bthe copied data. This must be a 32-bit address in either P0 or P1 Fspace. The argument is optional; if you do not supply it, an internal +buffer is used to retrieve the copied data.

DIf you specify this argument, you must also supply the len argument.

EWhen programming in MACRO-32 or BLISS, you can obtain the first four :bytes of the copied data in processor register R1 as well.

len


                
 VMS usage:  longword_unsigned
type:  longword (unsigned)
access:  read only
 mechanism:  by value

DNumber of bytes to copy. This argument must be specified unless the Bretadr argument was omitted as well. The lowest value of Blen is 4, in other words, the smallest unit to copy is a longword (on VAX and Alpha).

phyflg (Alpha only)


                
 VMS usage:  longword_unsigned
type:  longword (unsigned)
access:  read only
 mechanism:  by value

APhysical address indicator. If you set phyflg to 1, the Caddress given in inadr/inadr64 is interpreted as physical address.



DESCRIPTION

AThis callback is a jacket to SDA's general-purpose memory access wroutine SDA$EXTEND_TRYMEM. The only difference between them is their ~behaviour in case of error: while SDA$EXTEND_TRYMEM returns the error only, Dthis callback also signals it as warning condition. Unless you have =declared a condition handler, this causes SDA to display the Dappropriate message and then return to your code. Use this callback Fwhen data inaccessibility at the given address is unexpected but does Gprevent the current executed command from continuing. Since control is Dreturned to your code, you must always check the status returned by SDA$EXTEMD_GETMEM.

GOn Alpha V7, the input address (inadr64 argument) is a 64-bit Eaddress, allowing you to access every virtual address in P0, P1, P2, AS0/S1 and S2 space. To indicate this, the routine was renamed to 9SDA$EXTEND_GETMEM64; the 32-bit version 8SDA$EXTEND_GETMEM is not available on Alpha V7.

qFor more information, see the description of SDA$EXTEND_TRYMEM.


.

Condition values returned

                                                
 SDA$_SUCCESS Memory copied successfully
 SDA$_INVLDADR  Invalid virtual address
 SDA$_INVRANGE % Invalid address range specified
 SDA$_MEMNOTACC F 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 memory
 SDA$_OUTSIDPT = Virtual address range exceeds process page table bounds
 SDA$_PFNNOTMPD 2 PFN from PTE not mapped by memory descriptor
 SDA$_REGNOTVALID # Register reference is invalid
 SDA$_UNALIGNED . Unaligned address specified (Alpha only)


DFor a detailed description of these condition codes, please see the sCondition values returned section of SDA$EXTEND_TRYMEM. tTable B-3 contains the numeric values for all error codes; if you Cwant to use the names listed here, you must define the appropriate literals yourself.




Example


#include pcbdef  int pcbadr;  struct __PCB my_pcb;    .   .   .Rif (!(SDA$EXTEND_GETMEM(pcbadr,&my_pcb,sizeof(struct __PCB)) & 1) return;  


EAssuming that pcbadr contains the address of a PCB (process Gcontrol block), this example moves the entire PCB from S0 space into a Duser buffer for further analysis. In case of error, the appropriate Emessage was already displayed, so there is no more to do than return.


7

SDA$EXTEND_GET_ADDRESS



Returns the current address.



Format

'

SDA$EXTEND_GET_ADDRESS retadr

+

SDA$EXTEND_GET_ADDRESS64 retadr64

 (Alpha V7 only)



RETURNS



0This callback does not return a condition value.




ARGUMENTS



retadr


                
 VMS usage: address
type:  longword (unsigned)
access:  write only
 mechanism:  by reference

GAddress 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

GAddress of a quadword to receive the current address. This argument is (used with SDA$EXTEND_GET_ADDRESS64 only.



DESCRIPTION

HThis callback returns the current address. The current address 4is always set by the last EXAMINE, HFORMAT or VALIDATE command; it may be Asupplied with the dot (.) character in any command accepting SDA ?expressions. If you want to allow the current address as valid Especification in your commands, you can obtain it with this callback.

BThere 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.

AOn Alpha V7, this callback exists in a version supporting 64-bit Daddresses as well. If you want to work in a 64-bit environment, you Ashould use SDA$EXTEND_GET_ADDRESS64. Note that on Alpha V7, both Ccallbacks, SDA$EXTEND_GET_ADDRESS and SDA$EXTEND_GET_ADDRESS64 are available.





Note

FSince the current address may change between calls of your extension, Ayou should obtain it from SDA whenever the user specifies it. Do Cnot store and use the same address in different commands. 


/

Condition values returned

2



Example


int curadr;  %SDA$EXTEND_GET_ADDRESS(&curadr);  


CThis code obtains the current address and saves it for further use.


=

SDA$EXTEND_GET_BUGCHECK_MSG



HTranslates a bugcheck code into the appropriate bugcheck message string.



Format

:

SDA$EXTEND_GET_BUGCHECK_MSG code, retbuf, buflen




RETURNS



0This callback does not return a condition value.




ARGUMENTS

code


                
 VMS usage:  longword_unsigned
type:  longword (unsigned)
access:  read only
 mechanism:  by reference

9Longword holding the bugcheck code you want to translate.

retbuf


                
 VMS usage:  ASCIC_char_string
type:  character string
access:  write only
 mechanism:  by reference

CAddress of a buffer which receives the bugcheck string. The buffer Hshould be large enough to hold the entire message string which may have Cup to 128 bytes in length. Note that this argument is not Dpassed by descriptor, the buffer length is given in buflen.

buflen


                
 VMS usage:  longword_unsigned
type:  longword (unsigned)
access:  read only
 mechanism:  by value

/Longword holding the length of retbuf.



DESCRIPTION

HGiven a bugcheck code, this callback returns the corresponding bugcheck Fmessage. It allows you easily to display the textual form of bugcheck Acodes. The message is returned in ASCIC (Counted ASCII) Eformat. On Alpha V7, SDA provides the SHOW BUGCHECK command for the same purpose.

GAll bugcheck codes and messages are hardcoded in SDA. If you specify a 'non-existent bugcheck code, the message

  ** Invalid bugcheck code ** 


is copied to the buffer.

EThis callback is available on Alpha only, there is no replacement on VAX.


/

Condition values returned

2



Example


char retbuf[80];  int bugchk_code, prm_lst;  6$DESCRIPTOR(bugchk_msg,"Bugcheck Message = \"!AC\"");    .   .   .4SDA$EXTEND_GET_BUGCHECK_MSG(bugchk_code,retbuf,80);  prm_lst = (int) retbuf;  +SDA$EXTEND_PRINT(bugchk_msg,&prm_lst);  


HIn this example, a bugcheck code is obtained from another source and is Aconverted into a user-readable text which is displayed on screen.


<

SDA$EXTEND_GET_CURRENT_PCB



/Returns the PCB address of the current process.



Format

+

SDA$EXTEND_GET_CURRENT_PCB pcbadr




RETURNS



0This callback does not return a condition value.




ARGUMENTS



pcbadr


                
 VMS usage: address
type:  longword (unsigned)
access:  write only
 mechanism:  by reference

9Address of a longword wherein the PCB address is written.



DESCRIPTION

EThis callback returns the PCB (process control block) address of the Hcurrent process. This may be useful if you want to provide the Fcurrent process as default process in your commands (like SDA does in Dsome of its commands). Since the current process may change between Fcalls of your extension, you should always use this callback when you qwant to reference data in current process' PCB (see Section 3.3).

HThis callback exists on Alpha V7 only. On previous versions, as well as Con OpenVMS VAX, the following routine obtains the same information:

SYM: .ascid   /PCB/  4     .entry   SDA_EXTEND_GET_CURRENT_PCB,^m<>      pushab   SYMNAM +     calls    #1,g^SDA$EXTEND_SYMBOL_VALUE      movl     r1,@4(ap) 	     ret 


yThis code invokes SDA$EXTEND_SYMBOL_VALUE to obtain the value of SDA's GPCB symbol. This symbol contain always the address of Ethe current process' PCB. This value is written back to the longword Bspecified by the caller. The routine is called in the same way as SDA$EXTEND_GET_CURRENT_PCB.


/

Condition values returned

2



Example


int pcbadr;  )SDA$EXTEND_GET_CURRENT_PCB(&pcbadr);  


AThis code will copy the current PCB address into pcbadr;


9

SDA$EXTEND_GET_DYN_INFO



7Returns pointers to SDA's internal dynamic data tables.



Format

0

SDA$EXTEND_GET_DYN_INFO offtab, strtab




RETURNS



0This callback does not return a condition value.




ARGUMENTS



offtab


                
 VMS usage: address
type:  longword (unsigned)
access:  write only
 mechanism:  by reference

AAddress of a longword which receives the base address of a table @containing word-sized offsets to the strings in strtab.

strtab


                
 VMS usage: address
type:  longword (unsigned)
access:  write only
 mechanism:  by reference

AAddress of a longword which receives the base address of a table Hcontaining ASCIC strings with the names of all dynamic data structures. DThese strings are addressed by the offsets given in offtab.



DESCRIPTION

CIn order to translate type codes stored in dynamic data structures F(these structures are mostly located in paged or non-paged pool), SDA Fcontains two tables: the first table contains word-sized byte offsets Fto ASCIC (Counter ASCII) strings stored in the second table. GThis callback returns the base addresses of these tables, allowing you Dto translate a dynamic structure's type code into the corresponding name string.

EThe contents of the tables whose addresses are returned are readable Hfrom user mode. Note that subtype codes cannot be translated with these tables.

BAll type codes and the related names are stored in module $DYNDEF.

CThe 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.

EThis callback is available on Alpha only, there is no replacement on VAX.


/

Condition values returned

2



Example


OFFTAB:  .long    0 STRTAB:  .long    0  3         .entry   GET_TYPSTR,^m<r2,r3,r4,r5>          pushal   STRTAB          pushal   OFFTAB /         calls    #2,g^SDA$EXTEND_GET_DYN_INFO :         movzbl   4(ap),r1        ; r1 = type code (byte) A         movzwl   OFFTAB[r1],r2   ; r2 = word-offset into STRTAB A         movab    STRTAB[r2],r3   ; r3 = address of ASCIC string :         movzbl   (r3)+,r4        ; r4 = length of string A         movc3    r4,(r3),@8(ap)  ; copy string into user buffer 9         clrb     (r3)            ; make an ASCIZ string 
         ret 


;Given a type code as first argument, this routine uses the ESDA$EXTEND_GET_DYN_INFO callback to obtain the base addresses of the Btables described above and to locate the appropriate string. This Dstring is copied into the user buffer whose address is given in the Gsecond argument. In order to make processing from C easier, the string Fis converted from ASCIC to ASCIZ. If you do not use C, you can remove Cthe clrb (r3) instruction and return the resultant string 1length as additional argument or as ASCIC string.


7

SDA$EXTEND_GET_HEADER



AReturns pointers to the dump header and to the error log buffers.



Format

D

SDA$EXTEND_GET_HEADER hdrbuf, hdrlen, errlogbuf, errloglen




RETURNS



0This callback does not return a condition value.




ARGUMENTS



hdrbuf


                
 VMS usage: address
type:  longword (unsigned)
access:  write only
 mechanism:  by reference

>Address of a longword to receive the dump header base address.

hdrsiz


                
 VMS usage: address
type:  longword (unsigned)
access:  write only
 mechanism:  by reference

6Address of a longword to receive the dump header size.

errlogbuf


                
 VMS usage: address
type:  longword (unsigned)
access:  write only
 mechanism:  by reference

BAddress of a longword to receive the errorlog buffer base address.

errloglen


                
 VMS usage: address
type:  longword (unsigned)
access:  write only
 mechanism:  by reference

:Address of a longword to receive the errorlog buffer size.



DESCRIPTION

FThis callback returns pointers to the dump header and to the errorlog Ebuffers. For both data structures, their base address and length (in bytes) is returned.




9Previous- | Next6 | Contents