OpenVMS Notes: Hacking the Starlet Library

OpenVMS documentation is some of the best I've ever seen but no one produces 100% accurate documentation which is why you need other options. If you write programs requiring OpenVMS system calls, then doing a simple hack of the Starlet library is one such option. The whole purpose of the next example is to produce a searchable text file of the BASIC definition for the Starlet system library (known as BASIC$STARLET.TLB) in order to "double check" passing mechanisms, variable types and variable sizes described in the OpenVMS documentation.

BTW, the following procedure requires ~ 6700 blocks so be careful.

Legend : <ur> = user response
         <sr> = system response

<sr> $
<ur> set def sys$library
<sr> $
<ur> dir *.tlb
<sr> Directory SYS$COMMON:[SYSLIB]

 BASIC$STARLET.TLB;1 DECC$RTLDEF.TLB;1 EPC$FACILITY.TLB;1 ERFLIB.TLB;1
 LIB_ADA_SUBSET.TLB;1 NTA.TLB;1 STARLETSD.TLB;1
 STARLET_RECENT_ADA_SUBSET.TLB;1 SYS$LIB_C.TLB;1 SYS$STARLET_C.TLB;1
 TCPIP$TEMPLATES.TLB;1

 Total of 11 files.
<sr> $
<ur> lib BASIC$STARLET.TLB/text/extract=*
<sr> $
<ur> dir BASIC$STARLET.TXT
<sr> Directory SYS$COMMON:[SYSLIB]

 BASIC$STARLET.TXT;1

 Total of 1 file.

<sr> $
<ur> edit/read BASIC$STARLET.TXT

Notes:

1. DCL command "$lib BASIC$STARLET.TLB/text/extract=*" will extract the whole library to a text file and requires ~ 6700 disk blocks
2. DCL command "$lib/list BASIC$STARLET.TLB/text" can be used to get a library module listing. BTW, the "TLB" file extension stands for "Text Library"
3. DCL command "$lib BASIC$STARLET.TLB/text/extract=STARLET" can be used to extract only one module (STARLET in this case) which contains every routine with a prefix of SYS$. (eg. SYS$QIO)
4. DCL command "$lib BASIC$STARLET.TLB/text/extract=$LIBROUTINES" can be used to extract only one module ($LIBROUTINES in this case) which includes every routine with a prefix LIB$. If you want just a listing of LIB$ constants then you must extract module $LIBDEF.
5. Don't waste your time attempting to modify the contents of "BASIC$STARLET.TLB". These are just declaration statements that tell the compiler what the system call expects.  (in the "C" world they would be external header (.h) references)

Now search for "sys$qio" and you'll see the following:

   $QIO
 
     Queue I/O Request
 
      $QIO     [efn] ,chan ,func ,[iosb] ,[astadr] ,[astprm]
      ($QIOW)  ,[p1] ,[p2] ,[p3] ,[p4] ,[p5] ,[p6]
 
      efn    = number of event flag to set on completion
 
      chan   = number of channel on which I/O is directed
 
      func   = function code specifying action to be performed
 
      iosb   = address of quadword I/O status block to receive final
               completion status
 
      astadr = address of entry mask of AST routine
 
      astprm = value to be passed to AST routine as argument
 
      p1...  = optional device- and function-specific parameters
 
      EXTERNAL LONG FUNCTION  SYS$QIO &
               ( &
                   LONG  BY VALUE, &
                   WORD  BY VALUE, &
                   WORD  BY VALUE, &
                   BASIC$QUADWORD  BY REF, &
                   LONG  BY REF, &
                   LONG  BY VALUE, &
                   ANY  BY REF, &
                   LONG  BY VALUE, &
                   LONG  BY VALUE, &
                   LONG  BY VALUE, &
                   LONG  BY VALUE, &
                   LONG  BY VALUE &
               )

Note: this info is required when chasing strange compile-time bugs but only the OpenVMS CD-ROM documentation can be used to write and support a program requiring system calls.

Some Documentation Anomalies:

To reference BASIC$STARLET text library declarations from within a Compaq-BASIC (soon to be HP-BASIC?) program you'll need to have something that looks similar to this code fragment:

    !
    !       <<< system declarations >>>
    !
    %include "starlet"      %from %library "sys$library:basic$starlet"  ! system services (sys$qio)
    %include "$ssdef"       %from %library "sys$library:basic$starlet"  ! ss$
    %include "$libroutines" %from %library "sys$library:basic$starlet"  ! lib$
    %include "$uaidef"      %from %library "sys$library:basic$starlet"  ! uai$

Note: Make sure to include every module that your program requires. For more information just click here to check out a list of my fully-functional free demo programs.

Back to Home
Neil Rieck
Kitchener - Waterloo - Cambridge, Ontario, Canada.