Compaq BASIC for OpenVMS
Alpha and VAX Systems
User Manual


Previous Contents Index

21.4.2 Accessing Shareable Images at DCL Level

To access a shareable image at DCL level, 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 at the DCL level 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.

    VAX BASIC


    !Program name - ADDSUB.OPT 
    UNIVERSAL = ADD 
    

    Alpha BASIC


    ! 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 a more thorough understanding of shareable images, see the OpenVMS Linker Utility Manual and the Guide to Creating Modular Procedures.

Note

On OpenVMS VAX, using the linker option UNIVERSAL = to export routines is not recommended.


Chapter 22
Using CDD/Repository with BASIC

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.

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

22.2 CDD/Repository Concepts

This section introduces CDD/Repository concepts.

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

Note

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

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

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

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.

22.2.3 Dictionary Entities

Several types of entities can exist in a dictionary. For example, DMU-format and CDO-format dictionaries each contain record entities, database entities, and form entities.

BASIC creates a compiled module entity (and relationships in CDD/Repository dictionaries that depend on compiled module entities) only if the compilation generates an object file. Therefore, compiled module entities are not generated if you specify the /NOOBJECT qualifier on the command line or if the program has compilation errors.

22.2.4 Dictionary Relationships

Relationships occur in a CDO-format dictionary when two or more CDO entity definitions are connected in any of several possible ways. For example, you can relate a set of field definitions to a record definition by including the field names in the record definition.

See the CDD/Repository documentation for detailed information about relationships in a CDO-format dictionary.

22.2.5 Extracting CDD/Repository Data Definitions

A data definition is one type of a CDD/Repository object. In BASIC, you can extract only data definition objects into your program.

To extract a CDD/Repository data definition in BASIC, specify the %INCLUDE %FROM %CDD compiler directive and a CDD/Repository path name. You can use this to extract a data definition from either a DMU-format or CDO-format dictionary. For example:


%INCLUDE %FROM %CDD "CDD$TOP.BASIC.BASICDEF" 

The %INCLUDE %FROM %CDD directive extracts the CDD/Repository data definition you specify and translates it into BASIC syntax. In BASIC, the syntax for data definitions or data structures is defined by the RECORD statement.

After a CDD/Repository data definition is translated into RECORD statement syntax, you can reference the name of the RECORD statement in your BASIC programs. After compilation, the translated RECORD statement is included as a part of your program's listing.

The following is an example of a CDD/Repository data definition and the translated BASIC RECORD statement. The examples in this chapter are CDD/Repository data definitions in DMU-format that were written in the Common Data Definition Language (CDDL). In all examples, a CDDL data definition is displayed in lowercase letters, and the translated RECORD statement is displayed in uppercase letters.

CDDL Definition


define record 
CDD$top.basic.basicdef 
        description is 
 
           /* This is an example record containing 
           only data types supported by BASIC */. 
        employee structure. 
                street          datatype is text 
                                size is 30 characters. 
                city            datatype is text 
                                size is 30 characters. 
                state           datatype is text 
                                size is 2 characters. 
                zip_code structure. 
                    new         datatype is packed decimal 
                                size is 4 digits. 
                    old         datatype is packed decimal 
                                size is 5 digits. 
                end zip_code structure. 
                emp_number      datatype is signed word. 
                wage_class      datatype is text 
                                size is 2 characters. 
                salary_ytd      datatype is d_floating. 
        end employee structure. 
end basicdef. 

Translated RECORD Statement


 
     1          %INCLUDE %FROM %CDD "CDD$TOP.BASIC.BASICDEF" 
        C1              !   This is an example record containing 
        C1              !   only data types supported by BASIC
        C1              RECORD  EMPLOYEE                   ! UNSPECIFIED 
        C1                STRING  STREET  = 30             ! TEXT 
        C1                STRING  CITY  = 30               ! TEXT 
        C1                STRING  STATE  = 2               ! TEXT 
        C1                GROUP   ZIP_CODE                 ! UNSPECIFIED 
        C1                  DECIMAL(4 ,0 ) NEW             ! PACKED DECIMAL 
        C1                  DECIMAL(5 ,0 ) OLD             ! PACKED DECIMAL 
        C1                END GROUP 
        C1                WORD    EMP_NUMBER               ! SIGNED WORD 
        C1                STRING  WAGE_CLASS  = 2          ! TEXT 
        C1                DOUBLE  SALARY_YTD               ! D_FLOATING 
        C1              END RECORD 

When BASIC translates a CDD/Repository data definition, it does the following:

If you specify the /LIST qualifier when BASIC translates a CDD/Repository data definition, it does the following:

BASIC requires that a CDD/Repository data definition include a minimum of one structure to be translated into a RECORD statement. If a CDD/Repository data definition contains only a single subordinate field (without a structure), BASIC signals an error because it cannot give a name to the RECORD statement. You cannot include a CDO FIELD definition in a BASIC program. You can, however, include CDO RECORD definitions that contain that field.

For more information about how BASIC translates CDD/Repository data types, see Section 22.9.

22.3 Using CDD/Repository with BASIC

When dependency recording is in effect, the compiler updates the CDO-format dictionary to show what dictionary data entities are used by the program (the data dependencies created by the compilation).

To take advantage of dependency recording, do the following:

22.3.1 /DEPENDENCY_DATA Qualifier

When you compile a program that references CDO-format data definitions, you can include the qualifier in the BASIC command line. The /DEPENDENCY_DATA qualifier instructs the compiler to create dependency relationships (as defined in the program by %INCLUDE and %REPORT directives) and update the dictionary to show those relationships.

To prevent update of the dictionary, specify the default, /NODEPENDENCY_DATA. The compiler can extract record definitions from the dictionary (as specified by %INCLUDE %FROM %CDD directives in the program) but not update the dictionary. The compilation does not add compiled module entities and file entities to the dictionary, nor does it create dependency relationships in the dictionary, unless you specify the /DEPENDENCY_DATA qualifier.

22.3.2 Creating Relationships with Included Record Definitions

In Section 22.2.4 a record description is defined as a set of fields (thus establishing a simple relationship in CDD/Repository between the record and its fields). With that record description defined, you can include it in a BASIC program.

With either a DMU-format or CDO-format dictionary, the compiler can extract a record description into a program. Use the %INCLUDE lexical directive in the source program. The format is as follows:


%INCLUDE %FROM %CDD "pathname" 

For example, the following BASIC source code extracts a record description named ADDRESS_REC from CDD/Repository:


   PROGRAM EXAMPLE1 
   %INCLUDE %FROM %CDD "CDD$TOP.SMITH.ADDRESS_REC" 
   DECLARE ADDRESS_REC TEST_RECORD 
   INPUT "First name";TEST_RECORD::FIRST_NAME 
   INPUT "Last name";TEST_RECORD::LAST_NAME 
   INPUT "Address";TEST_RECORD::ADDRESS 
   INPUT "City";TEST_RECORD::CITY 
   INPUT "State";TEST_RECORD::STATE 
   INPUT "Zip code";TEST_RECORD::ZIP_CODE 
 
   PRINT TEST_RECORD::FIRST_NAME; TEST_RECORD::LAST_NAME 
   PRINT TEST_RECORD::ADDRESS 
   PRINT TEST_RECORD::CITY; TEST_RECORD::STATE; TEST_RECORD::ZIP_CODE 

The following shows the content of the record:


     1             PROGRAM EXAMPLE1 
     2             %INCLUDE %FROM %CDD "CDD$TOP.SMITH.ADDRESS_REC" 
        C1              RECORD  ADDRESS_REC                ! UNSPECIFIED 
        C1                STRING  FIRST_NAME  = 20         ! TEXT 
        C1                STRING  LAST_NAME  = 30          ! TEXT 
        C1                STRING  ADDRESS  = 40            ! TEXT 
        C1                STRING  CITY  = 20               ! TEXT 
        C1                STRING  STATE  = 2               ! TEXT 
        C1                DECIMAL(5 ,0 ) ZIP_CODE          ! PACKED DECIMAL 
        C1              END RECORD 
     3             DECLARE ADDRESS_REC TEST_RECORD 
     4             INPUT "First name";TEST_RECORD::FIRST_NAME 
     5             INPUT "Last name";TEST_RECORD::LAST_NAME 
     6             INPUT "Address";TEST_RECORD::ADDRESS 
     7             INPUT "City";TEST_RECORD::CITY 
     8             INPUT "State";TEST_RECORD::STATE 
     9             INPUT "Zip code";TEST_RECORD::ZIP_CODE 
    10          
    11             PRINT TEST_RECORD::FIRST_NAME; TEST_RECORD::LAST_NAME 
    12             PRINT TEST_RECORD::ADDRESS 
    13             PRINT TEST_RECORD::CITY; TEST_RECORD::STATE; TEST_RECORD::ZIP_CODE 

With a CDO-format dictionary, you can also instruct the dictionary to create and maintain a formal relationship between the record description and the compiled module entity that represents your program in the dictionary.

This is known as a CDD$COMPILED_DEPENDS_ON relationship. Specify the /DEPENDENCY_DATA qualifier when compiling a program as follows:


$ BASIC/DEPENDENCY_DATA EX1.BAS 

If you specify the /DEPENDENCY_DATA qualifier, the compiled module entity is created and updated to reflect that your program uses that record. If you want to change the data definition, CDO allows you to find out what programs depend on it before doing so. For example:


CDO> DIRECTORY 
 Directory SYS$COMMON:[CDDPLUS]SMITH 
ADDRESS;1                                        FIELD 
ADDRESS_REC;1                                    RECORD 
CITY;1                                           FIELD 
EXAMPLE1;1                                       CDD$COMPILED_MODULE 
FIRST_NAME;1                                     FIELD 
LAST_NAME;1                                      FIELD 
STATE;1                                          FIELD 
ZIP_CODE;1                                       FIELD 
   .
   .
   .

You can use the CDO SHOW USES command to find out what programs use a dictionary definition. For example:


CDO> SHOW USES ADDRESS_REC 
Owners of SYS$COMMON:[CDDPLUS]SMITH.ADDRESS_REC;1 
|   SYS$COMMON:[CDDPLUS]SMITH.EXAMPLE1;1  (Type : CDD$COMPILED_MODULE) 
|   |   via CDD$COMPILED_DEPENDS_ON 

You can also use CDO to find out what dictionary definitions a program uses. For example:


CDO> SHOW USED_BY EXAMPLE1 
Members of SYS$COMMON:[CDDPLUS]SMITH.EXAMPLE1;1 
|   EX1                             (Type : CDD$FILE) 
|   |   via CDD$IN_FILE 
|   SYS$COMMON:[CDDPLUS]SMITH.ADDRESS_REC;1  (Type : RECORD) 
|   |   via CDD$COMPILED_DEPENDS_ON 


Previous Next Contents Index