k%Writing SDA Extensions.

Writing SDA Extensions


9Previous6 | Contents


HDepending on your programming language and the references in your code, Eother shareable libraries or object modules must be included as well.

FYou use the LINK/SHARE command to create a shareable Aimage. Since you must include universal symbols in the shareable nimage's symbol table (see Section 2.2), you must provide a linker Foption file (see the Linker Utility manual how to create and use linker options files).

GIt is recommended that you include all information in the option file. HOn the command line, you specify the option file name only. Here is the ioption file for the MYEXT extension presented in Section 2.3:

 <myext$cld (1)=myext$main (2)   .   .   .Vsys$system:sys.stb/selective_search (3)Tsys$share:sda_extend_vector/share (4)Guniversal=sda$extend (5)universal=sda$extend_version Sidentification="V1.0-002/BOL-96" (6)name="MYEXT$SDA_VAX"  




    
  1. 0This object module was created with SET GCOMMAND/OBJECT. It contains the binary CDL definitions of all %commands recognized by the extension.
  2. HThis is the extension's main module. It contains the definitions of the Auniversal symbols and the extension's initialization routine. In Daddition, it contains the dispatcher to all command routines. These =routines may or may not be in the same module. An example of uinitialization and command dispatching code is given in Section 2.3.1. E
    Other extension modules may follow, as indicated by the ellipsis.
  3. ESYS$SYSTEM:SYS.STB is the system symbol table. You must include this Etable when using names of executive cells or constants (examples are Gnames starting with CTL$, EXE$, IOC$, LCK$, MMG$, PIO$, SCH$ or SWP$). :If you do not use such names, you can omit this line. The C/SELECTIVE _SEARCH qualifier causes the linker to Gprocess only those symbols in the input file that have been referenced in the previous modules.
  4. EThis is the shareable image containing all SDA callbacks (since it's Fshareable, you must supply the /SHARE qualifier). As mdescribed in Section 2.2.2.1, the routines in this image are Fjackets to the internal routines in SDA.EXE. By initializing Hthe global location SDA$EXTEND_VECTOR_TABLE_ADDR within this image with Cthe first argument passed by SDA to your extension, you create the Grequired connection between your extension and SDA's internal routines F(see Section 2.2.2.1).
  5. HTo include a global symbol into the shareable image's symbol table, you 5must declare it as universal using the linker option ouniversal. As described in Section 2.2, these two symbols must exist in the symbol table.
  6. EThis line and the following line are optional. They place naming and ?version information into the image header. This information is Gdisplayed when analyzing the image with ANALYZE/IMAGE.


3To link your extension with this option file, enter

 $ LINK/SHARE=MYEXT MYEXT/OPTIONS


2assuming that the option file was named MYEXT.OPT.

DUnless you copy the resultant image to SYS$SHARE, you must define a logical name in this way:

*$ DEFINE MYEXT$SDA directory:MYEXT$SDA.EXE


>You can now invoke the extension by starting SDA and entering ,MYEXTat the SDA> prompt.





Note

GIf you have SDA.EXE installed, you must install the extension image as Fwell (/OPEN/HEADER/SHARE).

7

A.2 Linking on Alpha



FOn Alpha, your extension is built by linking the following components:



HDepending on your programming language and the references in your code, 3other shareable libraries must be included as well.

FYou use the LINK/SHARE command to create a shareable Fimage. Since you must include symbols in the shareable image's symbol rvector, (see Section 2.2), you must provide a linker option file (see Hthe Linker Utility manual how to create and use linker options files).

GIt is recommended that you include all information in the option file. HOn the command line, you specify the option file name only. Here is the ioption file for the MYEXT extension presented in Section 2.3:

 <myext$cld (1)=myext$main (2)   .   .   .Nsys$share:sda_extend_vector (3)Wsymbol_vector=(sda$extend=procedure) (4)(symbol_vector=(sda$extend_version=data) Sidentification="V1.0-002/BOL-96" (5)name="MYEXT$SDA_AXP"  




    
  1. 0This object module was created with SET GCOMMAND/OBJECT. It contains the binary CDL definitions of all %commands recognized by the extension.
  2. HThis is the extension's main module. It contains the definitions of the Auniversal symbols and the extension's initialization routine. In Daddition, it contains the dispatcher to all command routines. These :routines may or may not in the same module. An example of uinitialization and command dispatching code is given in Section 2.3.1. E
    Other extension modules may follow, as indicated by the ellipsis.
  3. HThis is the object module containing all SDA callbacks. As described in ySection 2.2.2.1, the routines in this module are jackets to the Binternal routines in SDA.EXE. By initializing the global location HSDA$EXTEND_VECTOR_TABLE_ADDR within this module with the first argument Dpassed by SDA to your extension, you create the required connection ybetween your extension and SDA's internal routines (see Section 2.2.2.1).
  4. HTo include a global symbol into the shareable image's symbol table, you Dmust declare it using the linker option symbol_vector. The Fextension's entry point SDA$EXTEND must be declared as procedure, the +global location SDA$EXTEND_VERSION as data.
  5. EThis line and the following line are optional. They place naming and ?version information into the image header. This information is Gdisplayed when analyzing the image with ANALYZE/IMAGE.


3To link your extension with this option file, enter

'$ LINK/SHARE=MYEXT/SYSEXE MYEXT/OPTIONS


7assuming that the option file was named MYEXT.OPT. The E/SYSEXE qualifier directs the linker to process the Gsystem shareable image ALPHA$LOADABLE_IMAGES:SYS$BASE_IMAGE.EXE in the Hlink operation. This image contains references to executive data cells. CThe names of these cells mostly start with CTL$, EXE$, IOC$, LCK$, EMMG$, PIO$, SCH$ or SWP$; if you do not use such names, you can omit this qualifier.

DUnless you copy the resultant image to SYS$SHARE, you must define a logical name in this way:

*$ DEFINE MYEXT$SDA directory:MYEXT$SDA.EXE


>You can now invoke the extension by starting SDA and entering ,MYEXTat the SDA> prompt.





Note

GIf you have SDA.EXE installed, you must install the extension image as Fwell (/OPEN/HEADER/SHARE).

?

A.3 Debugging your extension



CDebugging an extension isn't possible in the normal way. Since the Eextension runs under control of SDA and the SDA.EXE image was linked Hwith /NODEBUG/NOTRACEBACK, there is no way to run your Hextension under the control of the debugger. Instead, if your extension Ebehaves in an unexpected way, you should use checkpoints to watch its behaviour.

GA checkpoint is simply a point where you display some data or signal a Fparticular condition. For example, if you receive an access violation Cwhile accessing data via a pointer, you should display the pointer Avalue. If it contains a wrong value, you may look for the reason causing the wrong value.

EYou can use the statements or functions provided by your programming Elanguage to display data in your program. Since checkpoints are used Gtemporary only, there is no need to use callbacks (although you can do Gso as well). Assume that ptr is a pointer variable, the C call

printf("%08X",ptr); 


Gwill show the value of ptr - it's up to you to decide whether Dit is correct. Once you have recompiled and relinked your extension ;with the above statement, invoke SDA to load the new image.





Note

AYou cannot force SDA to use a new extension image during one SDA Fsession. Once loaded, the current version remains active for the rest Fof the session. You must terminate and restart SDA to work with a new +extension image.



CIf you're not sure whether a particular checkpoint is reached in a Hroutine, you may also call LIB$SIGNAL with particular condition values. @When LIB$SIGNAL generates an condition, SDA's condition handler Adisplays the condition value, telling you at which point in your Croutine the condition has occurred. Calls to LIB$SIGNAL at various Cpoints can help to find out the actual execution flow in your code.

EDebugging SDA extensions is primary a 'run-and-try' job. It may be a Ftime-consuming task, however, with checkpoints, it is always possible !to locate any error in your code.


H

Appendix B
SDA callback description



EThis appendix contains a detailed description of every callback. The description includes



GThe callbacks are described in alphabetical order. For every callback, Ga detailed description of all arguments is given as well as an example Cin C. Note that some callbacks have different arguments on VAX and Alpha.

rTable 3-1 contains an alphabetical listing of all callbacks. wTable 3-2 contains a short description of all callbacks, sorted by their purpose.

FThe following abbreviations for VMS versions are used throughout this appendix:



FAll versions include hardware-related subversions; for example VAX V5 8includes VAX/VMS V5.5-2, as well VAX/VMS V5.5-2H1 to H4.


6

SDA$EXTEND_ADD_SYMBOL



$Adds a symbol to SDA's symbol table.



Format

6

SDA$EXTEND_ADD_SYMBOL symlen, symnam, symval

 (VAX)>

SDA$EXTEND_ADD_SYMBOL symlen, symnam, symval, symflg

 (Alpha)



RETURNS

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


>Always SDA$_SUCCESS (0x00F48009). All conditions are signaled.




ARGUMENTS



symlen


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

HA longword containing the length of the symbol name. The maximum length are 31 characters.

symnam


                
 VMS usage:  char_string
type:  character string
access:  read only
 mechanism:  by reference

:The symbol name you want to assign to the new symbol. The Fsymnam argument is the address of a character string holding Ethe symbol name. The string must not exceed 31 characters. Note that Dthis argument is not passed by descriptor, only the string Haddress is supplied. The string length is passed in the symlen argument.

symval


                
 VMS usage: ( longword_signed or quadword_signed
type: 2 longword (VAX, Alpha V6)/quadword (Alpha V7)
access:  read only
 mechanism:  by value

EA longword (VAX, Alpha V6) or quadword (Alpha V7) holding the binary 'value you want to assign to the symbol.

symflg (Alpha only)


                
 VMS usage:  word_unsigned
type:  word (unsigned)
access:  read only
 mechanism:  by value

HOn Alpha only, if this argument is set to 1, symval is treated =as procedure descriptor address. This is equivalent to SDA's EDEFINE/PDcommand. SDA will create a symbol with the Dgiven name, and a second named symnam_C holding the actual Gprocedure entry address. In this case, symval must be a valid Evirtual address (mostly in S0 space) and symnam cannot have more than 29 characters.



DESCRIPTION

5This callback provides a callable interface to SDA's HDEFINE command. The specified symbol is added to SDA's Gsymbol table; if it already exists, the old value is replaced with the new value.

HOn Alpha only, procedures are addressed by their procedure descriptors. ?For a particular procedure, the procedure descriptor holds the Eprocedure entry address, as well as other information (register save Amask, how many arguments are passed in which registers, and some Fothers). It is equivalent to the callframe used and maintained by the HVAX CALLS, CALLG and RET instructions. If you set symflg to 1, Esymval must be the address of a valid procedure descriptor. HSDA uses the contents of this descriptor to obtain the actual procedure Eentry address and creates a symbol named symnam_C with that address.

FSee the description of SDA's DEFINE command for more information.


/

Condition values returned

1
AReturns always SDA$_SUCCESS (0x00F48009). Conditions returned by FLIB$GET_VM (which is used to create virtual memory for the SDA symbol Adescriptor) are catched by SDA's condition handler.



Example


char symnam[] = "MY_SYMBOL";  9SDA$EXTEND_ADD_SYMBOL(strlen(symnam),symnam,0x00FF00FF);  


GIn this example, a new symbol named MY_SYMBOL is added to SDA's symbol Dtable with the value 0x00FF00FF. Since this callback returns always <SDA$_SUCCESS, there is no need to check for a return status.


4

SDA$EXTEND_ALLOCATE



Allocates virtual memory.



Format

"

SDA$EXTEND_ALLOCATE size

 (VAX, Alpha V6),

SDA$EXTEND_ALLOCATE size, [retadr]

(Alpha V7)



RETURNS

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


&All conditions returned by LIB$GET_VM.




ARGUMENTS

size


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

%Number of bytes you want to allocate.

retadr (Alpha V7 only)


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

BAddress of a longword receiving the base address of the allocated ?virtual memory. This optional argument exists on Alpha V7 only.



DESCRIPTION

CThis callback allocates the specified amount of virtual memory. It Finvokes LIB$GET_VM for the allocation and signals all conditions. The memory is allocated in P0 space.

FThe callback returns the base address of the allocated virtual memory Fin register R1 and, on Alpha V7 only, in the retadr argument Bas well, if specified. Therefore, on other VMS versions, you must 4provide a jacket routine to obtain the base address:

,     .entry  SDA_EXTEND_ALLOCATE,^m<> =     clrl    @8(ap)                   ; Clear return address =     pushl   4(ap)                    ; Pass number of bytes >     calls   #1,g^SDA$EXTEND_ALLOCATE ; Invoke SDA's callback 6     blbc    r0,10$                   ; Exit on error ?     movl    r1,@8(ap)                ; Return VM base address 	10$: ret 


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

EYou might also consider to invoke LIB$GET_VM directly, if you do not Dwant conditions signaled. Note that SDA$EXTEND_ALLOCATE expects the Fbyte count to be passed by value, whereas LIB$GET_VM expects it to be passed by reference.





Note

CWhenever virtual memory is allocated by your extension, be sure to Hreturn it before the first line of output is displayed. Always Gkeep in mind that routines in your extension may be interrupted at any Htime when the screen becomes full, SDA displays its Press RETURN to 9continue prompt, and the user enters a new command. 


/

Condition values returned

1
CAll conditions given by LIB$GET_VM are returned and also signaled.



Example


int status; int retptr;  Nstatus = SDA_EXTEND_ALLOCATE(5000,&retptr);  /* VAX, Alpha V6 (jacket) */  @status = SDA$EXTEND_ALLOCATE(5000,&retptr);  /* Alpha V7 */  &if (!(status & 1)) return status;  


FThis example allocates 5000 bytes of virtual memory. On VAX and Alpha Cprior V7, the jacket described above is used. retptr is a 5longword receiving the virtual memory's base address.


6

SDA$EXTEND_DEALLOCATE



0Deallocates previously allocated virtual memory.



Format

+

SDA$EXTEND_DEALLOCATE inadr, size




RETURNS

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


'All conditions returned by LIB$FREE_VM.




ARGUMENTS



inadr


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

?Base address of the virtual memory area you want to deallocate.

size


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

@Size in bytes of the virtual memory area you want to deallocate.



DESCRIPTION

AThis callback deallocates virtual memory previously allocated by SDA$EXTEND_ALLOCATE or LIB$GET_VM. It invokes LIB$FREE_VM for the deallocation and signals all conditions.

HYou may also call LIB$FREE_VM directly. Note that the argument sequence is inverted for LIB$FREE_VM.





Note

CWhenever virtual memory is allocated by your extension, be sure to Hreturn it before the first line of output is displayed. Always Gkeep in mind that routines in your extension may be interrupted at any Htime when the screen becomes full, SDA displays its Press RETURN to 9continue prompt, and the user enters a new command. 


/

Condition values returned

1
DAll conditions given by LIB$FREE_VM are returned and also signaled.



Example


$SDA$EXTEND_DEALLOCATE(retptr,size);  


EThis example deallocates the virtual memory allocated in the example agiven in the description of SDA$EXTEND_ALLOCATE.


8

SDA$EXTEND_DISPLAY_HELP



)Displays online help from a help library.



Format

/

SDA$EXTEND_DISPLAY_HELP hlplib, topic




RETURNS

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


>Always SDA$_SUCCESS (0x00F48009). All conditions are signaled.




ARGUMENTS



hlplib


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

GName of the help library. The library argument is the address Bof a character string descriptor pointing to the extension's help Dlibrary or to a logical name which translates to the actual library name.

EUse the LIBRARY/HELP/CREATE command to create a new ?help library. Use the LIBRARY/HELP/INSERT and DLIBRARY/HELP/REPLACEcommands to insert and replace help topics into the library.

topic


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

BTopic or topics for which help is requested. This argument is the Haddress of a character string descriptor pointing to the requested help Btopic or to a blank-separated list of help topics in hierarchical Border. In most cases, this is the entire user command without the &leading HELP keyword.



DESCRIPTION

EThis callback provides a SDA-conform way to display online help. The Hdisplay occurs on the screen unless it was redirected to an output file Fwith SDA's SET OUTPUT command. Therefore, instead of Dcalling LBR$OUTPUT_HELP, you should better invoke this callback. It 5calls LBR$OUTPUT_HELP with the appropriate arguments.

HFor more information, please see the description of the LBR$OUTPUT_HELP 8routine in the OpenVMS Utility Routines Manual.


/

Condition values returned

1
AReturns always SDA$_SUCCESS (0x00F48009). Conditions returned by FLIBR$OUTPUT_HELP are catched by SDA's condition handler.



Example

WAn example can be found in Section 2.3.3.

2

SDA$EXTEND_ENSURE



-Ensures sufficient lines on the current page.



Format

"

SDA$EXTEND_ENSURE lincnt




RETURNS



0This callback does not return a condition value.




ARGUMENTS



lincnt


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

9A longword containing the requested number of free lines.



DESCRIPTION

FThis 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 Ato issue a page break. It may be useful if you want to display a *particular block of text on a single page.

/

Condition values returned

2



Example


SDA$EXTEND_ENSURE(8);  


DThis code ensures that 8 lines are available in the current display.


2

SDA$EXTEND_FORMAT



6Formats and displays the contents of a data structure.



Format

3

SDA$EXTEND_FORMAT options, typnam, basadr




RETURNS

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


>Always SDA$_SUCCESS (0x00F48009). All conditions are signaled.




ARGUMENTS



options


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

HLongword containing a bitmask with on ore more of the following options set: # . &            
Bit Name Bitmask value (hex) Description
 OPT$M_TYPE  00000001 M When set, indicates that the data structure's name was specified in the typnam argument.
 OPT$M_PHYSICAL  10000000 7 When set, indicates that the address given in theE basadr argument is a physical address (Alpha V7 only).


HNote that the bit names shown in the table are not defined anywhere; if Ayou want to use it in your code, you must define the appropriate literals yourself.

typnam


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

FData structure name. The typnam argument is the address of a Fcharacter string descriptor pointing to the data structure name. This Cargument 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 value

HA longword holding the virtual base address of the data structure whose Fcontents should be formatted. If the OPT$M_PHYSICAL bit is set in the Foptions argument, basadr is interpreted as physical address (Alpha V7 only).



DESCRIPTION

5This callback provides a callable interface to SDA's BFORMAT command. Given the base address of a data Fstructure, SDA determines the structure type and uses the appropriate Hsymbols from its symbol table to format and display the contents of all >elements of the structure. Most VMS data structures provide a 'xxx$B_TYPE byte which holds their type.




9Previous- | Next6 | Contents