[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

HP BASIC for OpenVMS
User Manual


Previous Contents Index

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

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

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

21.2.5 Extracting CDD/Repository Data Definitions

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

To extract a CDD/Repository data definition in HP 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 HP BASIC syntax. In HP 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 HP 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 HP 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 HP 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


        C1              !   This is an example record containing
        C1              !   only data types supported by HP 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 HP 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 HP BASIC RECORD. For CDO-format definitions, BASIC takes the record name from the CDO DEFINE RECORD statement and assigns that name to a HP BASIC RECORD. In the previous example, the first CDD/Repository structure statement is employee structure. When HP BASIC translates this line of a CDD/Repository data definition, it names the record EMPLOYEE. If this first structure is unnamed, HP 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 HP 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.

HP 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), HP BASIC signals an error because it cannot give a name to the RECORD statement. You cannot include a CDO FIELD definition in a HP BASIC program. You can, however, include CDO RECORD definitions that contain that field.

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

21.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 HP 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.

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

21.3.2 Creating Relationships with Included Record Definitions

In Section 21.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 HP 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

21.4 Creating Relationships for Referenced Dictionary Entities

The compiler can create a relationship between a compiled module entity and any dictionary entity that a program references (such as a VAX Rdb/VMS database or a form definition). The referenced dictionary entity is not copied to the program. Instead, the compiled program references the dictionary entity at run time or with the help of a preprocessor.

To create relationships for referenced dictionary entities in a BASIC program, use the %REPORT %DEPENDENCY lexical directive in the source program and specify the /DEPENDENCY_DATA qualifier when you compile the program. The format is as follows:


%REPORT %DEPENDENCY "pathname" ["relationship-type"]

The "pathname" parameter identifies the dictionary item that the compiled object module references. The path name can specify a CDO-format dictionary item (with an anchor as the first element), or it can specify a CDO-format item in the compatibility dictionary (which can be specified either as a CDD$TOP path name or as an anchor path name). See Section 21.2.2 for a full description of the path name options.

The optional "relationship-type" parameter determines the type of relationship by specifying a CDD/Repository protocol. There are many valid values; refer to the CDD/Repository documentation for full information. The most commonly used relationship for HP BASIC users is as follows:


CDD$COMPILED_DEPENDS_ON

This specifies a relationship that links a compiled object module to the element that goes into the compilation. This is the default.

The %REPORT %DEPENDENCY directive is meaningful only when the following conditions are true:

  • The /DEPENDENCY_DATA qualifier is specified in the BASIC command line. (If it is not specified, the compiler checks syntax but does not update the dictionary to reflect this usage of the item.)
  • The current CDD$DEFAULT dictionary points to a directory in a CDO dictionary.
  • The dictionary item specified by pathname is in a CDO-format dictionary. (No relationship can be created in a DMU-format dictionary.)

Suppose the HP BASIC program DOG_REPORT.BAS contains the following directive:


%REPORT %DEPENDENCY "DISK1$:[CDDPLUS.BASIC]SMITH.DOG_DATABASE"

Use the /DEPENDENCY_DATA qualifier when you compile the program:


$ BASIC/DEPENDENCY_DATA DOG_REPORT

After the compilation, the dictionary contains the following:


CDO> DIR

 Directory DISK1$:[CDDPLUS.BASIC]SMITH

BREED;1                                          FIELD
CALL_NAME;1                                      FIELD
DOG_REPORT$MAIN;1                                CDD$COMPILED_MODULE
DOG_DATABASE;1                                   CDD$DATABASE
DOG_INFORMATION;1                                CDD$RMS_DATABASE
DOG_REC;1                                        RECORD
OWNER_NUMBER;1                                   FIELD
REG_DOG_NAME;1                                   FIELD

CDO> SHOW USES DOG_DATABASE

Owners of DISK1$:[CDDPLUS.BASIC]SMITH.DOG_DATABASE;1
|   DISK1$:[CDDPLUS.BASIC]SMITH.DOG_REPORT$MAIN;1  (Type : CDD$COMPILED_MODULE)
|   |   via CDD$COMPILED_DEPENDS_ON

CDO> SHOW USED_BY DOG_REPORT$MAIN
Members of DISK1$:[CDDPLUS.BASIC]SMITH.DOG_REPORT$MAIN;1
|   DOG_REPORT                      (Type : CDD$FILE)
|   |   via CDD$IN_FILE
|   DISK1$:[CDDPLUS.BASIC]SMITH.DOG_DATABASE;1  (Type : CDD$DATABASE)
|   |   via CDD$COMPILED_DEPENDS_ON

21.5 Specifying a CDD History List Entry

When your HP BASIC program accesses CDD/Repository, you have the option of entering a history list entry in the database. The history list entry provides a history of users that access CDD/Repository.

You create a history list entry by specifying the DCL command qualifier /AUDIT. For example:


$ BASIC/DEPENDENCY_DATA/AUDIT="History text goes here" EX1.BAS

Note that instead of typing the text directly on the command line, you can also specify a file specification that contains the history entry.

When you specify /AUDIT, a history list entry is created for each compiled module entity that the compilation creates. In addition, the compilation will add a history list entry to each data definition that your program extracts with the %INCLUDE %FROM %CDD directive.

You can display history list information using the CDO utility. For example:


CDO> SHOW GENERIC CDD$COMPILED_MODULE EXAMPLE1 /AUDIT
Definition of EXAMPLE1   (Type : CDD$COMPILED_MODULE)
|   History entered by SMITH ([SMITH])
|       using BASIC Vn.n
|       to CREATE definition on 25-APR-1989 13:04:01.48
|       Explanation:
|               "History text goes here"

21.6 CDD/Repository Arrays

CDD/Repository supports the following arrays:

  • Multidimensional arrays (the ARRAY clause)
  • One-dimensional, fixed length arrays (the OCCURS clause or ARRAY clause)
  • One-dimensional, variable length arrays (the OCCURS DEPENDING ON clause---note that HP BASIC does not support this clause)

Arrays are valid for any CDD/Repository field. HP BASIC does not support dimensions on a RECORD statement; therefore, you cannot declare an entire RECORD statement as an array. However, you can dimension an instance of the record.

The following is an example of a CDDL data definition containing arrays and the corresponding HP BASIC RECORD statement:

CDDL Definition


define record CDD$top.basic.array1
    description is

        /* test arrays */.

    array_1 structure.
        my_byte         array 0:2            datatype        signed byte.
        my_string       array 0:10           datatype        text size 10.
        my_s_real       array 0:2 0:4        datatype        f_floating.
        my_d_real       array 1:3            datatype        d_floating.
        my_g_real       occurs 4 times       datatype        g_floating.
        my_h_real       occurs 4 times       datatype        h_floating.
    end array_1 structure.
end array1.

Translated RECORD Statement


     1          %INCLUDE %FROM %CDD "CDD$TOP.BASIC.ARRAY1"
        C1              !   test arrays
        C1              RECORD  ARRAY_1                    ! UNSPECIFIED
        C1                BYTE    MY_BYTE(0 TO 2)          ! SIGNED BYTE
        C1                STRING  MY_STRING(0 TO 10) = 10  ! TEXT
        C1                SINGLE  MY_S_REAL(0 TO 2,0 TO 4) ! F_FLOATING
        C1                DOUBLE  MY_D_REAL(1 TO 3)        ! D_FLOATING
        C1                GFLOAT  MY_G_REAL(1 TO 4)        ! G_FLOATING
        C1                HFLOAT  MY_H_REAL(1 TO 4)        ! H_FLOATING
        C1              END RECORD

By default, arrays in CDD/Repository are row-major. This means that when storage is allocated for the array, the rightmost subscript varies fastest. All HP BASIC arrays are row-major. HP BASIC does not support column-major arrays. If a CDD/Repository definition containing a column-major array is extracted, HP BASIC signals the error "<array-name> from CDD/Repository is a column major array."

By default, HP BASIC extracts an array field from CDD/Repository with the bounds specified in the data definition. However, if you use the qualifier /OLD_VERSION[=CDD_ARRAYS] when you extract a data definition, HP BASIC translates the data definition with lower bounds as zero and adjusts the upper bounds. This means that an array with dimensions of (2,5) in CDD/Repository is translated by HP BASIC to be an array with a lower bound of 0 and an upper bound of 3. HP BASIC issues an informational message to confirm the array bounds when you use this qualifier.

The following CDD/Repository data definition and corresponding RECORD statement are extracted with the /OLD_VERSION[=CDD_ARRAYS] qualifier:

CDDL Definition


define record CDD$top.basic.array2
    description is

        /* test arrays with /old_version[=CDD_ARRAYS] qualifier */.

    array_2 structure.
        my_byte         array 0:2            datatype        signed byte.
        my_string       array 0:10           datatype        text size 10.
        my_s_real       array 0:2 0:4        datatype        f_floating.
        my_d_real       array 1:3            datatype        d_floating.
        my_g_real       occurs 4 times       datatype        g_floating.
        dep_item                             datatype        signed longword.
        my_h_real       occurs 4 times
                                             datatype        h_floating.
    end array_2 structure.
end array2.

Translated RECORD Statement


1          %INCLUDE %FROM %CDD "CDD$TOP.BASIC.ARRAY2"
   C1              !   test arrays with /old_version[=CDD_ARRAYS] qualifier
   C1              RECORD  ARRAY_2                    ! UNSPECIFIED
   C1                BYTE    MY_BYTE(0 TO 2)          ! SIGNED BYTE
   C1                STRING  MY_STRING(0 TO 10) = 10  ! TEXT
   C1                SINGLE  MY_S_REAL(0 TO 2,0 TO 4) ! F_FLOATING
   C1                DOUBLE  MY_D_REAL(0 TO 2)        ! D_FLOATING
   C1                GFLOAT  MY_G_REAL(0 TO 3)        ! G_FLOATING
   C1                LONG    DEP_ITEM                 ! SIGNED LONGWORD
   C1                HFLOAT  MY_H_REAL(0 TO 3)        ! H_FLOATING
   C1              END RECORD


Previous Next Contents Index