k%Writing SDA Extensions.

Writing SDA Extensions


9Previous6 | Contents


‚This callback is invoked by SDA$EXTEND_FORMAT_SUBHEADING when it has formatted a Hstring containing FAO directives. If you want to format a header string Hwith the tools and functions provided by your language, you can do this ?and invoke SDA$EXTEND_SET_HEADING yourself to store the string. 


/

Condition values returned

2



Example


<char fmtstr[] = "Summary of %s Pool Usage, %3.2f%% in use"; char outbuf[80];  $DESCRIPTOR(outdsc,outbuf);  float percent;    .   .   .,sprintf(outbuf,fmtstr,"Non-paged",percent);  &outdsc.dsc$w_length = strlen(outbuf);  %SDA$EXTEND_SET_HEADING(&outdsc);  


EUsing the sprintf() function, this example formats a header Bstring and invokes SDA$EXTEND_SET_HEADING to store it for further Gdisplays. Note that the SYS$FAO services do not provide directives for Gfloating point values; you must use language-specific tools to display &such values (as shown in the example).


@

SDA$EXTEND_SET_HEADING_ROUTINE



,Establishes a new subheader display routine.



Format

/

SDA$EXTEND_SET_HEADING_ROUTINE dsprtn




RETURNS



0This callback does not return a condition value.




ARGUMENTS



dsprtn


                
 VMS usage:  procedure
type:  procedure value
access: " call without stack unwinding
 mechanism:  by reference

@A longword holding the address of the subheader display routine.



DESCRIPTION

GThis callback establishes a subheader display routine. This routine is Dinvoked every time when a new page is displayed. Its output appears „immediately under the header text established with SDA$EXTEND_FORMAT_SUBHEADING or ISDA$EXTEND_SET_HEADING.

BIn most cases, you use this callback when displaying large tables Acontaining many rows and columns. The subheader ensures that the Fdescription of every column appears at the top of every new page. You @can see an example of a subheader in the output of CLUE 0MEMORY/LAYOUT. The line containing the AItem/Base/End/Length string is displayed by a subheader 'routine established with this callback.

>The subheader display routine is called as procedure, with no 'arguments. SDA expects no return value.

GTo delete a previously established subheader routine, specify 0 in the Gdsprtn argument. Note that it's your responsibility to delete Da subheading routine when it is not longer required; otherwise, SDA Dwill still continue to invoke it at the top of every new page (even Eoutside of your code), until a new routine is established by another command.

FOn VAX, there is no way to establish a subheader routine. If you want Gto display subheaders, you must obtain the terminal's page size (using ASYS$GETDVI with the DVI$_TT_PAGE item code), maintain a count of Aalready displayed lines and write a subheader whenever the count Hreaches the value of DVI$_TT_PAGE. In this case, reset the line counter Hto 2 (since the underscored heading line at the top of the new page was already displayed).




Example


void my_main_rtn(); { 1  SDA$EXTEND_SET_HEADING_ROUTINE(my_subhdr_rtn);   .  .  .E  SDA$EXTEND_SET_HEADING_ROUTINE(0);   /* Clear subheader routine */  
  return; }  void my_subhdr_rtn() { C char subhdr[] = "Start VA         End VA         Size       Use";   $DESCRIPTOR(subdsc,subhdr);    SDA$EXTEND_PRINT(&subdsc); }  


GThis example shows how to establish a subheader routine and what to do Fwithin this routine. It ensures that a subheader, showing the meaning @of the table columns, is displayed at the top of every new page.


;

SDA$EXTEND_SET_LINE_COUNT



Changes the current line count.



Format

*

SDA$EXTEND_SET_LINE_COUNT lincnt




RETURNS



0This callback does not return a condition value.




ARGUMENTS



lincnt


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

/A longword containing the new line count value.



DESCRIPTION

GThis callback changes the current line count (the number of lines that Fhave been printed on the current page). The line count is used by SDA Eto maintain a page-oriented display. Whenever the line count reaches uthe end of current page, SDA invoke SDA$EXTEND_NEW_PAGE to perform page-related operations.

HThis callback enables you to change the current line count, controlling DSDA's behaviour in page processing. For example, you can obtain the †current line with SDA$EXTEND_GET_LINE_COUNT, decrement this value and store the new Dvalue with this callback. This will result in the display of larger Epages which may be useful when output was redirected to a file (with SET OUTPUT).

HThis callback is available on Alpha V7 only, there is no replacement on &earlier Alpha VMS versions and on VAX.


/

Condition values returned

2



Example


int lines;  'SDA$EXTEND_GET_LINE_COUNT(&lines);  lines =- 4;  "SDA$EXTEND_SET_LINE_COUNT(lines);  


EThis example performs the task described in the Description Fsection. SDA will display four additional lines on the current output page.


7

SDA$EXTEND_SKIP_LINES



Inserts a number of empty lines.



Format

&

SDA$EXTEND_SKIP_LINES lincnt




RETURNS



0This callback does not return a condition value.




ARGUMENTS



lincnt


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

:A longword containing the number of empty lines to insert.



DESCRIPTION

GThis callback inserts the specified number of empty lines. The current line count is incremented and SDA$EXTEND_NEW_PAGE is invoked when the bottom Fof the current page is reached. You can use this callback to separate %different text blocks in your output.

/

Condition values returned

2



Example


SDA$EXTEND_SKIP_LINES(2);  


8This will insert two empty lines in the current display.


6

SDA$EXTEND_SYMBOLIZE



Symbolizes a numerical value.



Format

6

SDA$EXTEND_SYMBOLIZE value, retstr, [symblk]




RETURNS



0This callback does not return a condition value.




ARGUMENTS



value


                
 VMS usage: , longword_unsigned or quadword_unsigned
type: F longword (unsigned: VAX, Alpha V6)/quadword (unsigned: Alpha V7)
access:  read only
 mechanism:  by value

GA longword (VAX, Alpha V6) or quadword (Alpha V7) holding the value to symbolize.

retstr


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

GTranslated symbol name. The retstr argument is the address of Ba character string descriptor pointing to a buffer into which the Ftranslated symbol name is written. The buffer should provide at least 40 bytes of space.

symblk


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

HA longword holding the address of a symbol block. When you specify this Gargument, SDA does not look for a matching symbol in its symbol table; Einstead, it uses this argument in conjunction with value to Gbuild a symbolization string. This argument is optional; if you do not Cspecify it or specify it as 0, SDA looks in its symbol table for a matching symbol.



DESCRIPTION

GThis callback symbolizes a value. Symbolization occurs when a Enumerical value is substituted by a symbol name; either based on the Bsymbols stored in SDA's symbol table or on the symbol whose block $address is given in symadr.

GWhen a symbol is defined, SDA creates a symbol block to store Ait. The symbol block contains the symbol name, its value and its =attributes (if any). SDA inserts the symbol block in several Ctrees at different positions; this allows the creation of 3symbol listings in alphabetical or numerical order.

HGiven a symbol value, this callback traverses one tree (the 'numerical' Gtree which holds symbols sorted by value) to find a symbol whose value Gmatches the given value. If a symbol is found, its name is returned in Fretstr. If more symbols with the same value exist, the first Fmatching symbol from the numerical tree is returned; there is no rule &which symbol is returned in this case.

EIf no such symbol exist, SDA tries to find a symbol with a value not Hless than 0xFFF from the given value; if such symbol exist, its name is Greturned in the form name+offset where offset is the Fdifference between the symbol value and the given value. For example, Gif you specify 20004 as symbol value and there is a symbol named TEST1 <with a value of 20000, the callback would return the string HTEST1+00004. Note that the offset is returned as five-digit hexadecimal 2number (although it cannot be greater than 0xFFF).

>SDA always tries to find the symbol with the closest value to Fvalue. Consider the example above: if there would be another Gsymbol named TEST2 with a value of 20002, the string TEST2+00002 would Hbe returned since this difference (2) is lower than the difference 4 in the above example.

GSDA recognizes differences up to 0xFFF (decimal 4095) only as offsets. GIf the difference is greater than this value, the corresponding symbol is not further used.

GIf no matching symbol is found in the symbol table, SDA interprets the Cgiven value as virtual address and scans the base addresses of all Cloaded system images and device drivers. If a base address (and an Hadditional offset) matches, the name of the corresponding image and the Hoffset value is returned. For example, if the image SYSGETSYI starts at Aaddress 81922000 and you specify 81922C00 in value, the ,callback returns the string SYSGETSYI+00C00.

AOn Alpha only, if the specified address points to a sliced image Fsection, SDA returns the image name and appends an underscore and one of the following abbreviations:



DFor example, if you specify 8021C800 in value and 8021C000 Fwould be the base address of the non-paged read-only RMS execlet, SDA 'would return the string RMS_NPRO+00800.

EIf you specify the address of a symbol block in symadr, SDA Euses the information in this block for the symbolization. First, the Gvalue stored in the symbol block is compared with the given value; the Gdifference must not be greater than 0x0FFF. Then, if the difference is Glower (or 0), the name from the symbol block and an optional offset is returned.

GIf no matching symbol is found, SDA sets the descriptor's length field to 0.


/

Condition values returned

2



Example


char symbuf[40];  int my_val;  $DESCRIPTOR(symdsc,symbuf);    .   .   .*SDA$EXTEND_SYMBOLIZE(my_val,&symdsc);  "if (!symdsc.dsc$w_length) return;  


GThis example invokes SDA$EXTEND_SYMBOLIZE to translate the value given Cin my_val into a symbol name. If no symbol was found (the Elength field of the descriptor 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.


9

SDA$EXTEND_SYMBOL_VALUE



Obtains a symbol value.



Format

(

SDA$EXTEND_SYMBOL_VALUE symnam

 (VAX, Alpha V6)2

SDA$EXTEND_SYMBOL_VALUE symanm, [retval]

(Alpha V7)



RETURNS

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


CReturns 1, if the specified symbol exists; 0, if it does not exist.




ARGUMENTS



symnam


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

GName of the symbol whose value you want to obtain. The symnam Gargument 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 reference

CAddress of a quadword receiving the symbol value. This argument is optional.



DESCRIPTION

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

FThe callback returns the symbol value in register R1 and, on Alpha V7 Gonly, in the retval argument as well. Therefore, on other VMS @versions, you must provide a jacket routine to obtain the value:

0     .entry  SDA_EXTEND_SYMBOL_VALUE,^m<> >     clrl    @8(ap)                       ; Init return value =     pushl   4(ap)                        ; Push symbol name <     calls   #1,g^SDA$EXTEND_SYMBOL_VALUE ; Invoke callback :     blbc    r0,10$                       ; On error exit @     movl    r1,@8(ap)                    ; Return symbol value 710$: ret                                  ; That's all 


BThis jacket is invoked in the same way as the Alpha V7 version of SDA$EXTEND_SYMBOL_VALUE.


/

Condition values returned

1
BReturns 1, if the symbol exists; else, returns 0. No condition is signaled.



Examples

uExamples how to use this callback can be found in Section 3.1 and in `the description of SDA$EXTEND_GET_CURRENT_PCB.

>

SDA$EXTEND_TRANSLATE_ADDRESS



#Translates a value into an address.



Format

&

SDA$EXTEND_TRANSLATE_ADDRESS




RETURNS

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


EReturns the address associated with the matched value, or zero if no matching value was found.




ARGUMENTS

R2


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

HWhen 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 reference

HWhen invoking this callback, the processor register R3 must contain the Caddress of a table holding value/address pairs. The format of this table is described later.



DESCRIPTION

FThis callback translates a value into an address, based on a supplied Gtable. It returns the address 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 Dvalues to their corresponding names; the names strings are found by Etheir addresses which are coded in the table. See the description of aSDA$EXTEND_TRANSLATE_BITS for more information.

FThis callback does not conform the OpenVMS calling standard. HIt must be invoked as subroutine, with input arguments in CPU registers ?R2 and R3. If your programming language does not allow to call Hsubroutines or pass arguments in processor registers, you can provide a jacket routine:

:     .entry  SDA_EXTEND_TRANSLATE_ADDRESS,^m<r2,r3> -     movl    4(ap),r2                ; Value 5     movl    8(ap),r3                ; Table address ,     jsr     g^SDA$EXTEND_TRANSLATE_ADDRESS =     movl    r0,@12(ap)              ; Return address (or 0) >     beql    10$                     ; If 0, no value matches 9     movzbl  #1,r0                   ; Otherwise success 210$: ret                             ; That's all 


HThis jacket routine is invoked with three arguments: the first argument Eis the value you want to translate, the second is the address of the ?table and the third is the address of a longword receiving the Dcorresponding address. The routine returns 1 if the translation was successful, else it returns 0.

"The table is formatted as follows:

  value1, address1   value2, address2   .  .  .$  valuen, addressn	  -1, -1 


<where value is a value and address is its Fcorresponding address. value and address are stored <in longwords. The table is terminated with a quadword of -1.





Note

CMost HLL (high level languages) provide an easier way to translate Gvalues to addresses. This callback was intended primarily for MACRO-32 Gprogrammers. Unless you are programming in MACRO-32, it is recommended Ethat you use the features or functions provided by your language for Fthis purpose. For example, in C, a switch/case construct can /be used here easier.




Returns

1
HReturns the address whose value matches the specified value. Returns 0, "if no value matches.



Examples

GAn example showing the coding of a value/address table can be found in _the description of SDA$EXTEND_TRANSLATE_BITS.

;

SDA$EXTEND_TRANSLATE_BITS



'Translates a bitmask into a bit string.



Format

B

SDA$EXTEND_TRANSLATE_BITS tabadr, bitmsk, buflen, bufadr

 (VAX):

SDA$EXTEND_TRANSLATE_BITS tabadr, bitmsk, retdsc

 (Alpha)



RETURNS

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


!Always SDA$_SUCCESS (0x00F48009).




ARGUMENTS



tabadr


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

EAddress of a bit definition table. The tabadr argument is a Glongword holding the address of this table. The format of the table is described later.

bitmsk


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

3Longword holding the bitmask you want to translate.

buflen (VAX only)


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

FA longword holding the length of the buffer whose address is supplied in bufadr.

bufadr (VAX only)


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

HTranslated bit string. The bufadr argument is the address of a Gbuffer into which the translated bit string is written. Note that this Hargument is passed by reference, it's not a descriptor address.

retdsc (Alpha only)


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

HTranslated bit string. The retdsc argument is the address of a @character string descriptor pointing to a buffer into which the Gtranslated bit string is written. The length field of this descriptor, Hwhich initially contains the length of the string buffer, is updated by :the callback to contain the length of the returned string.



DESCRIPTION

BThis callback translates a bit mask into a comma-separated string Hconsisting of the names of the bits set in the mask. The bit values and Hbit names are supplied in a bit definition table whose address is given Ein tabadr. The bit definition table is formatted as follows:
  value1, address1   value2, address2   .  .  .$  valuen, addressn	  -1, -1 


Cwhere value is the bit number and address is the Faddress of the counted ASCII (ASCIC) name string associated with that Fbit. value and address are stored in longwords. The *table is terminated with a quadword of -1.

EOn VAX, the translated bit string is written into the buffer, but no Hinformation about its length is returned. Therefore, you should provide Aa mechanism to obtain this length. For example, in C, you should Gpre-initialize the buffer with binary null's; upon return, you can use Fthe strlen() function to obtain the actual string length. An 9example of this is given in the Example section.

COn VAX, if no matching bits are set in bitmsk, the return Fbuffer remains unchanged. On Alpha, in this case, the length field of the descriptor is set to 0.





Note

CMost HLL (high level languages) provide an easier way to translate Ebits. This callback was intended primarily for MACRO-32 programmers. GUnless you are programming in MACRO-32, it is recommended that you use Fthe features or functions provided by your language for this purpose. EFor example, in C, a switch/case construct may be used here "easier.



ˆThis callback invokes SDA$EXTEND_TRANSLATE_ADDRESS to perform the bitvalue-to-address translation.


/

Condition values returned

1
7Returns always SDA$_SUCCESS (0x00F48009).



Example


#include <psldef.h>  char retbuf[40];  int bitmsk, i;  #char bit_name[4][10] = {"Xinited", %                        "Xpagflful", %                        "Xswpflful", %                        "Xdinspen"};  $DESCRIPTOR(retdsc,retbuf);  struct {  int value; 
 char *name; .} bittab [5] = {PFL$V_INITED,    bit_name[0], .                PFL$V_PAGFILFUL, bit_name[1], .                PFL$V_SPWFILFUL, bit_name[2], .                PFL$V_DINSPEN,   bit_name[3],                 -1,-1};    .   .   . Sfor (i=0; i<5; i++)                                /* Convert ASCIZ to ASCIC */ { P bit_name[i][0] = (char) strlen(bit_name[i]) - 1;  /* The 'X' is overwritten */ P}                                                  /* with the string length */  Ememset(retbuf,0,sizeof(retbuf);)                           /* VAX */  ESDA$EXTEND_TRANSLATE_BITS(bittab,bitmsk,40,retbuf);        /* VAX */  Eif (retbuf[0]) SDA$EXTEND_PRINT(desc("Bits: !AZ"),retbuf); /* VAX */  KSDA$EXTEND_TRANSLATE_BITS(bittab,bitmsk,40,&retdsc);       /* Alpha */  Gif (retdsc.dsc$w_length)                                   /* Alpha */ { K SDA$EXTEND_PRINT(desc(Bits: "!AS"),&retdsc);              /* Alpha */ }  


HThis example shows the callback invocation on VAX and Alpha. It is used Hhere to obtain a list of all bits set in a page/swap file control block (PFL).

DFirst, since the bit strings in the table must be in ASCIC (counted EASCII) format, they are converted from ASCIZ (zero-terminated ASCII) Hformat used in C. ASCIC strings contain the length of the string in the Bfirst byte. In the declaration of the bit names, 'X's are used as Eplaceholder; they are overwritten at run-time with the actual string Flength. To accomplish this, you must declare the strings in RW (data) $area (not as 'const' or 'readonly').

FOn VAX, the output buffer is pre-initialized with 0; otherwise, there Gwould no way to retrieve the returned string length. Once the callback Eis invoked, the first byte in the output buffer is checked; if it is ?still 0, there was no string retured. Otherwise, the FAO "!AZ" Gdirective can be used to display the buffer contents; since the buffer Fwas initialized with 0, the string is still zero-terminated (assuming Ethat the buffer was large enough to hold a string even with all bits 0set - it is the programmers job to ensure this).

HOn Alpha, things are easier - if the descriptor length field contains a Dnon-zero value on callback return, the string is displayed directly with the FAO "!AS" directive.

@The desc() function can be found in the description of KSDA$EXTEND_PRINT_COLUMNS.


3

SDA$EXTEND_TRYMEM



Copies data from memory.



Format

6

SDA$EXTEND_TRYMEM inadr, [retadr, len] (VAX)

:

SDA$EXTEND_TRYMEM inadr, [retadr, len], [phyflg]

(Alpha V6)>

SDA$EXTEND_TRYMEM64 inadr64, [retadr, len], [phyflg]

(Alpha V7)



RETURNS

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



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_TRYMEM 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_TRYMEM64 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 Hargument is a longword holding the base address of the buffer receiving Bthe copied data. This must be a 32-bit address in either P0 or P1 Gspace. This argument is optional; if you do not supply it, an internal +buffer is used to retrieve the copied data.




9Previous- | Next6 | Contents