|
HP OpenVMS Systems Documentation |
|
HP BASIC for OpenVMS
|
| Previous | Contents | Index |
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.
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.
|
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:
If you specify the /LIST qualifier when HP BASIC translates a CDD/Repository data definition, it does the following:
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:
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 |
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:
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 |
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" |
CDD/Repository supports the following arrays:
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:
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.
|
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:
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.
|
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 |