HP OpenVMS Systems Documentation

HP BASIC for OpenVMS
User Manual

This section provides complete examples of calling system routines from HP BASIC. In addition to the examples provided, the VMS Run-Time Library Routines Volume and the HP OpenVMS System Services Reference Manual also provide examples for selected routines. See these manuals for help about the use of a specific system routine.

Example 19-3 uses a function that invokes the SYS$TRNLNM system service. SYS$TRNLNM translates a logical name to an equivalence name. It places the equivalence name string into a string variable you supply in the parameter list.

System services never change a string variable's length. Therefore, if you use a system service that returns a string, be sure that the receiving string variable is long enough for the returned data. You can make sure of this in one of two ways:

• Define the string variable's length in a MAP, COMMON, or RECORD definition.
• Assign a long string to the variable (for example, A$ = SPACE$(80)). This pre-extends the variable so that it is long enough to receive all of the returned data.

10   !This function attempts to translate a logical name while searching
     !through all of the tables defined in LNM$DCL_LOGICAL.  If the translation
     !is successful, $TRNLNM returns the equivalence name string.


     FUNCTION STRING Translate(STRING Logical_name)
     EXTERNAL LONG FUNCTION SYS$TRNLNM (LONG, STRING, STRING, LONG, ITEM_LIST)
     EXTERNAL LONG CONSTANT LNM$M_CASE_BLIND, LNM$_STRING, SS$_NORMAL

     !Declare the parameters
     DECLARE LONG attributes,   &
                  trans_status
     DECLARE WORD equiv_len

     !Declare the value returned by the function.
     DECLARE LONG CONSTANT Buffer_length = 255
     RECORD item_list
     GROUP item (1)
             VARIANT
                  CASE
                     WORD Buf_len
                     WORD Code
                     LONG Buffer_address
                     LONG Length_address
                   CASE
                     LONG Terminator
              END VARIANT
      END GROUP item
      END RECORD item_list
      !Declare an instance of the record

      DECLARE ITEM_LIST TRNLNM_ITEMS

      !Define a common area for Translation_buffer

      COMMON (Trans_buffer) &
              STRING Translation_buffer = Buffer_length

      !Setting TRN$LNM to not distinguish between uppercase and lowercase
      !letters in the logical name to be translated.

      Attributes = LNM$M_CASE_BLIND
      !Assign values to each record item.

      TRNLNM_ITEMS::item(0)::Buf_len = Buffer_length
      TRNLNM_ITEMS::item(0)::Code = LNM$_STRING
      TRNLNM_ITEMS::item(0)::Buffer_address = LOC(Translation_buffer)
      TRNLNM_ITEMS::item(0)::Length_address = LOC(Equiv_len)
      TRNLNM_ITEMS::item(1)::Terminator = 0%

      !Invoke the function

      TRANS_STATUS = SYS$TRNLNM(attributes,"LNM$DCL_LOGICAL", logical_name, &
                                ,trnlnm_items)
      !Check the condition value

      IF trans_status AND SS$_NORMAL
      THEN
               Translate = LEFT(Translation_buffer, Equiv_len)
      ELSE
               Translate = ""
      END IF
      END FUNCTION

Example 19-4 is a program that demonstrates the use of the system service $QIOW. Unlike SYS$QIO, SYS$QIOW performs synchronously; SYS$QIOW returns a condition value to the caller after I/O operation is complete.

10  !Declare SYS$QIOW as an EXTERNAL FUNCTION

    EXTERNAL LONG FUNCTION SYS$QIOW(,WORD BY VALUE,LONG BY VALUE,WORD DIM() &
                                     BY REF,,,STRING BY REF,LONG BY VALUE,, &
                                     LONG BY VALUE,,)
    !Declare SYS$ASSIGN as an EXTERNAL FUNCTION

    EXTERNAL LONG FUNCTION SYS$ASSIGN(STRING,WORD,,)

    EXTERNAL LONG CONSTANT IO$_WRITEVBLK
    !Declare the parameters

    DECLARE STRING my_term, out_str, &
            WORD term_chan, counter, stat_block(3),&
            LONG ret_status, msg_len, car_cntrl

    out_str = "Successful $QIOW output!"
    my_term = "SYS$COMMAND"
    msg_len = LEN(out_str)
    car_cntrl = 32%
    !Assign a channel to the terminal
    ret_status = SYS$ASSIGN(my_term, term_chan, ,)
    CALL LIB$STOP(ret_status BY VALUE) IF (ret_status AND 1%) = 0%
    !Output the message four times
    FOR counter = 1% to 4%
        ret_status = SYS$QIOW(,term_chan BY VALUE, IO$_WRITEVBLK BY VALUE, &
                               stat_block() BY REF,,,out_str BY REF,       &
                               msg_len BY VALUE,,car_cntrl BY VALUE,,)
        CALL LIB$STOP(ret_status BY VALUE) IF (ret_status AND 1%) = 0%
        CALL LIB$STOP(stat_block(0%) BY VALUE) &
                      IF (stat_block(0%) and 1%) = 0%
    NEXT counter

    END

Output

Successful $QIOW output!
Successful $QIOW output!
Successful $QIOW output!
Successful $QIOW output!

In addition to invoking the function SYS$QIOW, the previous example also invokes the function SYS$ASSIGN. This function provides a process with an I/O channel so that input and output operations can be performed on a logical device name (my_term). As soon as SYS$ASSIGN is invoked and a path is established to the device, a counter is set up to invoke the $QIOW function four times. Once all I/O operations are complete, $QIOW returns to the caller.

19.6 OpenVMS Calling Standard

The primary purpose of the OpenVMS Calling Standard is to define the concepts for invoking routines and passing data between them. For more information, see the HP OpenVMS Calling Standard.

19.7 Additional Information

The information provided on system routines in this chapter is general to all system services and OpenVMS Run-Time Library routines. For specific information about these routines, see the VMS Run-Time Library Routines Volume and the HP OpenVMS System Services Reference Manual.

Libraries and shareable images allow you to access program symbols and incorporate commonly used routines into your source code. This chapter describes how to create and access libraries and shareable images in HP BASIC.

20.1 Overview of Libraries

Libraries are files that can contain object modules, text modules, and shareable images. There are two types of libraries: system-supplied and user-supplied. System-supplied libraries are provided by the OpenVMS system, and user-supplied libraries are libraries that you create.

Shareable images are similar to libraries; they contain code that can be shared by other programs. However, shareable images contain executable code rather than object code.

If you have routines that are used in many programs, placing the routines in object module libraries or shareable image libraries lets you access them at link time. You do not need to include the routines in the source code, thus shortening compilation time and conserving disk space.

If you have routines that are used simultaneously by many different programs, placing the routines in installed shareable images can improve performance at run time, conserve main physical memory, and reduce paging I/O because one copy of the executable code is shared by all users.

When you link programs, object module libraries, shareable image libraries, and shareable images can contain object code created by any native mode compiler or assembler.

For more understanding of libraries and shareable images, see the HP OpenVMS Linker Utility Manual and the Guide to Creating OpenVMS Modular Procedures. For more information about installing shareable images, see the HP OpenVMS System Manager's Manual. For information about text libraries, see Chapter 16.

20.2 System-Supplied Libraries

If symbols are unresolved after the OpenVMS Linker (linker) searches all user-supplied libraries, the linker goes on to search the files in the default system library. The OpenVMS system supplies the following libraries:

The linker searches modules in the following order:

1. Modules and libraries specified in the LINK command line, in the order given
2. User-supplied libraries (logicals of the form LNK$LIBRARY and LNK$LIBRARY_1 through LNK$LIBRARY_999)
3. Images contained in IMAGELIB.OLB
4. Modules contained in STARLET.OLB

The linker only includes references to needed shareable images in the image being created. You can use the /NOSYSSHR qualifier to the LINK command to suppress the linker's search of RTL shareable images. Similarly, you can use the /NOSYSLIB qualifier to suppress the linker's search of both RTL shareable images and STARLET.OLB.

The linker searches user-supplied libraries before searching the default system library. If one of your modules has the same name (program symbol) as an OpenVMS System Service or an RTL routine, the linker includes your module in the resulting image rather than the system service or RTL routine.

20.3 Creating User-Supplied Object Module Libraries

You create a user-supplied object module library with the DCL command LIBRARY. Specify a library file specification as well as a list of the program modules you want to insert into the library. For example:

$ BASIC MODULE1,MODULE2
$ LIBRARY/CREATE TESTLIB1.OLB MODULE1.OBJ,MODULE2.OBJ

In the previous example, the BASIC command creates object files from MODULE1.BAS and MODULE2.BAS. The LIBRARY command creates an object module library named TESTLIB1.OLB and inserts MODULE1.OBJ and MODULE2.OBJ into that library. See the HP OpenVMS DCL Dictionary for more information about the LIBRARY command.

20.3.1 Accessing User-Supplied Object Module Libraries

To access user-supplied object module libraries, specify the /LIBRARY qualifier to the DCL command LINK. For example:

$ LINK MAIN,TESTLIB/LIBRARY

This command instructs the linker to search the library TESTLIB.OLB for any unresolved symbols in the HP BASIC object module MAIN.OBJ.

Also, you can explicitly include a module from a library with the /INCLUDE qualifier. For example:

$ LINK MAIN,TESTLIB/LIBRARY/INCLUDE = (module1,module2)

This command instructs the linker to include module1 and module2 from the library TESTLIB.OLB, whether or not it needs these modules to resolve symbols.

You can access user-supplied object module libraries automatically. However, a program executing at DCL level does not automatically search libraries that are assigned to the logical name BASIC$LIB0. Instead, the linker searches libraries that are assigned to the logical name LNK$LIBRARY. If you have more than one library for the linker to search, you must number these libraries consecutively; otherwise, the linker does not search past the first missing logical name. The linker allows you to number libraries from 1 to 999.

For example:

$ DEFINE LNK$LIBRARY USER$$DEV:[KELLY]TESTLIB.OLB
$ DEFINE LNK$LIBRARY_1 USER$$DEV:[KELLY]TESTLIB1.OLB
$ DEFINE LNK$LIBRARY_2 USER$$DEV:[KELLY]TESTLIB2.OLB

After you issue these commands, a program executing at DCL level automatically accesses these three library files to resolve program symbols.

20.4 Shareable Images

Shareable images are not directly executable. They contain executable code that can be shared by other images and are intended to be included by the linker in other images.

The benefits of using shareable images include:

• Conserving disk storage space
• Conserving main physical memory
• Reducing paging I/O
• Allowing shared memory-resident databases
• Eliminating the need to relink programs that access a new version of a shared routine

To create a shareable image, use the /SHAREABLE qualifier with the DCL command LINK and specify at least one object module. For example:

$ LINK/SHAREABLE prog1

This command creates an image that can be linked to other programs. You cannot execute a shareable image with the DCL command RUN.

When a program is linked with a shareable image, the required shareable image code is not included in the created executable image on the disk. This code is included by the image activator at run time. Therefore, many programs can reside on disk and be bound with a particular shareable image, and only one physical copy of that shareable image file needs to exist on disk.

If a shareable image has been installed using the OpenVMS Install utility, you conserve physical memory and potentially reduce paging I/O. Many processes can include the physical memory pages of an installed shareable image in their address space. This reduces the requirements for physical memory.

Paging occurs when a process attempts to access a virtual address that is not in the process working set. When this page fault occurs, the page is either in a disk file, in which case paging I/O is required, or is already in physical memory. If a page fault occurs for a shared page, the shared page may already be resident in memory and no paging I/O is required.

20.4.1 Accessing Shareable Images

To access a shareable image, follow these steps:

1. Write and compile a program unit that is to be inserted into a shareable image.
2. Create an options file required for the link operation.
3. Link the program with the /SHAREABLE qualifier, and specify the options file with the /OPTION qualifier.
4. Write a main program that accesses the routine in the shareable image.
5. Compile the main program, and link it with the shareable image.

The following example shows how to access a shareable image by performing these steps:

1. Write and compile a program unit that is to be inserted into a shareable image.

   !Program name - ADD.BAS FUNCTION REAL ADD (LONG A, LONG B) ADD = A + B FUNCTIONEND

2. Create an options file that will export the function for the link operation.

   ! Program name - ADDSUB.OPT SYMBOL_ADDER = (ADD=PROCEDURE)

   
   
3. Link the program with the qualifiers /SHAREABLE and /OPTION.

   $ LINK/SHAREABLE ADD, ADDSUB/OPTION

   
   Copy the shareable image to SYS$SHARE:, or define a logical name to the full image file specification. For example,

   $ Define ADD Sys$Login:Add.exe

4. Write a main program that accesses the routine in the shareable image.

   !Program name - CALLADD.BAS EXTERNAL REAL FUNCTION ADD (LONG, LONG) DECLARE LONG X,Y X = 1 Y = 2 PRINT ADD(X,Y) END

   
   
5. Compile the main program, and link it with the shareable image.

$ LINK CALLADD,ADDMAIN/OPTION

To link CALLADD with the shareable image ADD, you must have a linker options file specifying that ADD is a shareable image. For example:

!Options file - ADDMAIN.OPT
ADD/SHAREABLE

Next, execute the program. Upon executing the program, the image activator attempts to locate the shareable image in the directory SYS$SHARE:. If you want the image activator to access a shareable image outside SYS$SHARE:, you must define a logical name to the shareable image before you execute the program. Define the full file specification of the shareable image to the name of the shareable image, as follows:

$ DEFINE MYSHR DISK$WORKDISK:[MYDIR]MYSHR.EXE

This is a simple example of using shareable images. For more information, see the HP OpenVMS Linker Utility Manual and the Guide to Creating OpenVMS Modular Procedures.

This chapter explains how you can take advantage of CDD/Repository capabilities. For more detailed information about CDD/Repository, see Using CDD/Repository on VMS Systems.

21.1 Overview of CDD/Repository

CDD/Repository is a common data dictionary tool that supports sharing of data definitions by OpenVMS programming languages and information architecture products. Each language or product translates the generic definitions stored in CDD/Repository language- or product-specific definitions that it can use.

BASIC supports CDD/Repository features including dependency recording. Dependency recording allows you to record (or track) which programs use CDD/Repository data definitions. Dependency recording helps evaluate the effort needed to change a record definition by identifying the modules that need to be modified, recompiled, or both.

To support dependency recording, CDD/Repository uses a dictionary structure known as CDO-format. (The type of dictionary used in CDD versions prior to Version 4.0 is known as DMU-format.) You can have many CDO-format dictionaries on an OpenVMS system (but only one DMU-format dictionary). The two types of dictionaries can coexist on a system, and a program can refer to data definitions in both types.

21.2 CDD/Repository Concepts

This section introduces CDD/Repository concepts.

21.2.1 Dictionary Formats

CDD/Repository allows the following types of dictionaries:

• DMU-format dictionary
• CDO-format dictionary

These dictionaries can coexist on a system to form one logical directory structure. CDD/Repository uses a special dictionary, known as the compatibility dictionary, that allows an application to refer to dictionary definitions without concern about which type of dictionary format the definitions are stored in.

The compatibility dictionary is a CDO-format dictionary whose directory hierarchy matches that of the DMU-format dictionary (if any) on the system.

Refer to the CDD/Repository documentation for detailed information about the CDO utility and the compatibility dictionary.

21.2.2 Dictionary Path Names

To access dictionary definitions, you must specify a path name in the %INCLUDE %FROM %CDD or %REPORT %DEPENDENCY directive. The path name tells CDD/Repository where to locate a particular data definition in its directory. A CDD/Repository path name consists of a string of names separated by periods and enclosed in quotation marks.

The origin is the top, or root, of a dictionary directory. This directory contains other dictionary directories, subdictionary directories, and objects.

HP BASIC allows the following types of valid path name parameters when referring to CDO dictionary definitions. They differ in the method of specifying the dictionary origin.

• Dictionary anchor path name
  An anchor path name begins with an anchor, which is an OpenVMS directory specification, as the dictionary origin. The anchor specifies the OpenVMS directory that contains the CDO dictionary. This is known as the CDO naming convention. In the following example, MYNODE::DISK$2:[MYDIRECTORY] is the anchor:

  MYNODE::DISK$2:[MYDIRECTORY]PERSONNEL.EMPLOYEES_REC

• CDD$TOP path name
  Use this to refer to either DMU-format dictionary definitions or CDO-format dictionary definitions in a compatibility dictionary. The path origin is always CDD$TOP. This is known as the DMU naming convention. For example:

  CDD$TOP.PERSONNEL.EMPLOYEES_REC

• Relative path name
  CDD/Repository always begins its search at CDD$TOP (or at the anchor you specify) unless you define another directory or object to be the start of your directory. You can do this by assigning the name of a dictionary directory to the logical name CDD$DEFAULT. For example:

  $ DEFINE CDD$DEFAULT CDD$TOP.BASIC

  
  Using this command defines the dictionary directory CDD$TOP.BASIC as the default start of your directory. You can override the defined default by specifying CDD$TOP in a path name.
  You can omit the origin of a path name and specify a relative path name. Any path name that does not begin with either CDD$TOP or an anchor is automatically appended to the current CDD$DEFAULT. For example, you can specify:

  PERSONNEL.EMPLOYEES_REC

  
  If CDD$DEFAULT is MYNODE::MY$DISK:[MYDIR], the relative path name is the same as:

  MYNODE::MY$DISK:[MYDIR]PERSONNEL.EMPLOYEES_REC.

  
  Similarly, if CDD$DEFAULT is CDD$TOP.MYDIR, the relative path name is the same as:

  CDD$TOP.MYDIR.PERSONNEL.EMPLOYEES_REC.