HP OpenVMS Systems

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.

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:

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

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.

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

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:

• For DMU-format definitions, BASIC takes the field name specified in the first CDDL STRUCTURE statement and assigns that name to BASIC RECORD. For CDO-format definitions, BASIC takes the record name from the CDO DEFINE RECORD statement and assigns that name to a BASIC RECORD. In the previous example, the first CDD/Repository structure statement is employee structure. When BASIC translates this line of a CDD/Repository data definition, it names the record EMPLOYEE. If this first structure is unnamed, BASIC signals the error "Record from CDD/Repository does not have a record name."
• Translates the field name in any subsequent CDD/Repository STRUCTURE statement to be the name of a group. In the previous example, the second STRUCTURE statement, zip_code structure, is translated to GROUP ZIP_CODE.
• Translates subordinate field names in CDD/Repository STRUCTURE statements to elementary components in the RECORD statement. In the previous example, the subordinate field name street is translated to STRING STREET.

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

• Begins each line of the RECORD statement with the letter "C" followed by a number. The letter "C" tells you that the RECORD statement is translated from a CDD/Repository data definition. The number tells you the nesting level of the %INCLUDE %FROM %CDD directive within the source program. For example, if your source program directly extracts a CDD/Repository record definition, then each line is preceded by "C1." If the CDD/Repository extraction came from a file included in the source program, then each line of the record definition is preceded by "C2," and so on.
• Includes the explanatory text in the CDDL DESCRIPTION clause as comment fields.
• Translates the data type text in the subordinate field to a comment field that tells you the data type of each elementary RECORD component. For example, the comment ! TEXT tells you that STRING STREET is a text data type.

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:

• Use either or both of the BASIC lexical directives, %INCLUDE %FROM %CDD and %REPORT %DEPENDENCY, in the source program to define the dependency relationships you want to create between your program and definitions in the CDO-format dictionary.
• Establish a CDO-format dictionary called CDD$DEFAULT.
• Include the /DEPENDENCY_DATA qualifier in the BASIC command that compiles the module.

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