HP OpenVMS Systems Documentation
HP BASIC for OpenVMS
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:
|Example 19-3 Calling System Services|
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.
|Example 19-4 Program Displaying the$QIOW System Service Routine|
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
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
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.
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:
|IMAGELIB.OLB||Contains symbol tables for all Run-Time Library (RTL) shareable images that are part of the OpenVMS operating system---for example, an OpenVMS RTL routine is called Lib$FAO.|
|STARLET.OLB||An object module library containing the object files used to create the shareable image version of the OpenVMS RTL, and other less frequently used procedures. If program symbols remain unresolved after the OpenVMS Linker searches IMAGELIB.OLB, the linker then searches this library.|
The linker searches modules in the following order:
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
$ 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.
$ 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
20.4 Shareable Images
Some of these benefits can only be realized if the shareable image is installed with the OpenVMS Install utility (Install).
$ 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
The following example shows how to access a shareable image by performing these steps:
!Program name - ADD.BAS FUNCTION REAL ADD (LONG A, LONG B) ADD = A + B FUNCTIONEND
! Program name - ADDSUB.OPT SYMBOL_ADDER = (ADD=PROCEDURE)
$ LINK/SHAREABLE ADD, ADDSUB/OPTION
$ Define ADD Sys$Login:Add.exe
!Program name - CALLADD.BAS EXTERNAL REAL FUNCTION ADD (LONG, LONG) DECLARE LONG X,Y X = 1 Y = 2 PRINT ADD(X,Y) END
$ 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:
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.
The compatibility dictionary is an installation option for CDD/Repository. If there is no compatibility dictionary, an application program can refer to both types of dictionaries. In this case, refer to the CDO-format dictionary with an anchor origin path name and to the DMU-format dictionary with a CDD$TOP path name. Anchor origin path names are described in Section 21.2.2.
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.
$ DEFINE CDD$DEFAULT CDD$TOP.BASIC