| Previous | Contents | Index |
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 22.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 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 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 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. 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 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 BASIC arrays are row-major. BASIC does not support column-major arrays. If a CDD/Repository definition containing a column-major array is extracted, BASIC signals the error "<array-name> from CDD/Repository is a column major array."
By default, 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, 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 BASIC to be an array with a lower bound of 0 and an upper bound of 3. 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 |
A variant comprises two or more fields of a record that provide alternative descriptions for the same portion of a record.
The following is an example of a CDDL data definition containing variant fields and the corresponding BASIC RECORD statement:
define record CDD$top.basic.variant_example
description is
/* test simple variant */.
variant_example structure.
my_string datatype text size 9.
variants.
variant.
my_s_real datatype f_floating.
my_d_real datatype d_floating.
end variant.
variant.
my_g_real datatype g_floating.
my_h_real datatype h_floating.
end variant.
end variants.
my_byte datatype signed byte.
end variant_example structure.
end variant_example.
|
1 %INCLUDE %FROM %CDD "CDD$TOP.BASIC.VARIANT_EXAMPLE"
C1 ! test simple variant
C1 RECORD VARIANT_EXAMPLE ! UNSPECIFIED
C1 STRING MY_STRING = 9 ! TEXT
C1 VARIANT
C1 CASE
C1 SINGLE MY_S_REAL ! F_FLOATING
C1 DOUBLE MY_D_REAL ! D_FLOATING
C1 CASE
C1 GFLOAT MY_G_REAL ! G_FLOATING
C1 HFLOAT MY_H_REAL ! H_FLOATING
C1 END VARIANT
C1 BYTE MY_BYTE ! SIGNED BYTE
C1 END RECORD
|
<CDD/Repository data definitions sometimes contain VARIANTS OF field
description statements as well as simple variants. A CDDL or CDO
VARIANTS OF statement names a tag variable whose value at run time
determines which of the variant fields is the current variant.
BASIC does not support the VARIANTS OF statement. If a
CDD/Repository data definition containing a VARIANTS OF statement is
extracted, BASIC signals the informational message,
"<number> tag value from CDD/Repository ignored" and
treats the VARIANTS OF as an ordinary variant and ignores the tag value.
22.8 NAME FOR BASIC Clause
BASIC supports the CDDL and CDO field attribute clause NAME FOR BASIC.
The field attribute clause NAME FOR BASIC declares a facility-specific name for a field. For example:
name for basic is "subject_name$" |
When you assign a name using the NAME FOR BASIC clause in a CDDL or CDO data definition, BASIC recognizes only this name when you refer to the field. Note that when you use the NAME FOR BASIC clause, you can place dollar sign ($) and percent sign (%) suffixes in your RECORD statement field names.
The following example is a CDDL data definition containing the NAME FOR BASIC clause and the corresponding BASIC RECORD statement.
define record city_study
description is
/* This example formats data resulting from a
study on the relationship between place of birth
and earning potential */.
info structure.
subject_name datatype text size 10
name for basic is "subject_name$".
birth_city datatype text size 10
name for basic is "city_of_birth$".
salary datatype signed byte
name for basic is "salary%".
end info structure.
end city_study.
|
1 %INCLUDE %FROM %CDD "CDD$TOP.BASIC.CITY_STUDY" C1 ! This example formats data resulting from a C1 ! study on the relationship between place of birth C1 ! and earning potential C1 RECORD INFO ! UNSPECIFIED C1 STRING SUBJECT_NAME$ = 10 ! TEXT C1 STRING CITY_OF_BIRTH$ = 10 ! TEXT C1 BYTE SALARY% ! SIGNED BYTE C1 END RECORD |
The NAME FOR BASIC clause enables you to assign completely different names to the same field. |
For more information about the CDDL NAME FOR BASIC field attribute
clause, see the CDD/Repository documentation.
22.9 CDD/Repository Data Types
BASIC supports only a subset of CDD/Repository data types as described in Table 22-1. Alpha BASIC does not support the HFLOAT data type.
| Data Type | BASIC Translation |
|---|---|
| TEXT | STRING |
| SIGNED BYTE | BYTE |
| SIGNED WORD | WORD |
| SIGNED LONGWORD | LONG |
| F_FLOATING | SINGLE |
| D_FLOATING | DOUBLE |
| G_FLOATING | GFLOAT |
| H_FLOATING 1 | HFLOAT |
| PACKED DECIMAL | DECIMAL |
If a CDD/Repository data definition containing an unsupported data type is extracted, BASIC signals the informational message "Datatype in CDD/Repository not supported, substituted group for: <field-name>" and translates the data type by creating a group to contain the data type field. The group name is the name of the unsupported data type followed by the text "_VALUE". This allows you to access the field name within the group.
An example of how BASIC translates unsupported CDD/Repository data types is shown in the following CDDL data definition and corresponding BASIC RECORD statement:
define record CDD$top.basic.stock
description is
/* this is an example data definition that contains
data types not supported by BASIC */.
stock structure.
product_no datatype is text
size is 8 characters.
date_ordered datatype is date.
status_code datatype is unsigned byte.
quantity datatype is unsigned longword
aligned on longword.
location array 1:4
datatype is text
size is 30 characters.
unit_price datatype is longword.
end stock structure.
end stock.
|
1 %INCLUDE %FROM %CDD "CDD$TOP.BASIC.STOCK"
C1 ! This is an example data definition that contains
C1 ! data types not supported by BASIC
C1 RECORD STOCK ! UNSPECIFIED
C1 STRING PRODUCT_NO = 8 ! TEXT
C1 GROUP DATE_ORDERED ! DATE
C1 STRING STRING_VALUE = 8
C1 END GROUP
C1 GROUP STATUS_CODE ! UNSIGNED BYTE
C1 BYTE BYTE_VALUE
C1 END GROUP
C1 STRING FILL = 3
C1 GROUP QUANTITY ! UNSIGNED LONGWORD
C1 LONG LONG_VALUE
C1 END GROUP
C1 STRING LOCATION(1 TO 4) = 30 ! TEXT
C1 GROUP UNIT_PRICE ! UNSIGNED LONGWORD
C1 LONG LONG_VALUE
C1 END GROUP
C1 END RECORD
%BASIC-I-CDDSUBGRO, data type in CDD/Repository not supported,
substituted group for: STOCK::DATE_ORDERED.
%BASIC-I-CDDSUBGRO, data type in CDD/Repository not supported,
substituted group for: STOCK::STATUS_CODE.
%BASIC-I-CDDSUBGRO, data type in CDD/Repository not supported,
substituted group for: STOCK::QUANTITY.
%BASIC-I-CDDSUBGRO, data type in CDD/Repository not supported,
substituted group for: STOCK::UNIT_PRICE.
|
Table 22-2 describes CDD/Repository data types not supported by BASIC and their translation.
| Data Type | BASIC Translation |
|---|---|
| UNSIGNED BYTE |
GROUP CDD/Repository-field-name
BYTE BYTE_VALUE END GROUP |
| UNSIGNED WORD |
GROUP CDD/Repository-field-name
WORD WORD_VALUE END GROUP |
| UNSIGNED LONGWORD |
GROUP CDD/Repository-field-name
LONG LONG_VALUE END GROUP |
| SIGNED QUADWORD |
GROUP CDD/Repository-field-name
STRING STRING_VALUE = 8 END GROUP |
| UNSIGNED QUADWORD |
GROUPCDD/Repository-field-name
STRING STRING_VALUE = 8 END GROUP |
| SIGNED OCTAWORD |
GROUP CDD/Repository-field-name
STRING STRING_VALUE = 16 END GROUP |
| UNSIGNED OCTAWORD |
GROUP CDD/Repository-field-name
STRING STRING_VALUE = 16 END GROUP |
| F_FLOATING COMPLEX |
GROUP CDD/Repository-field-name
SINGLE SINGLE_R_VALUE SINGLE SINGLE_I_VALUE END GROUP |
| D_FLOATING COMPLEX |
GROUP CDD/Repository-field-name
DOUBLE DOUBLE_R_VALUE DOUBLE DOUBLE_I_VALUE END GROUP |
| G_FLOATING COMPLEX |
GROUP CDD/Repository-field-name
GFLOAT GFLOAT_R_VALUE GFLOAT GFLOAT_I_VALUE END GROUP |
| H_FLOATING COMPLEX |
GROUP CDD/Repository-field-name
HFLOAT HFLOAT_R_VALUE HFLOAT HFLOAT_I_VALUE END GROUP |
| ZONED NUMERIC |
GROUP CDD/Repository-field-name
STRING STRING_VALUE = length END GROUP |
| UNSIGNED NUMERIC |
GROUP CDD/Repository-field-name
STRING STRING_VALUE = length END GROUP |
| LEFT SEPARATE NUMERIC |
GROUP CDD/Repository-field-name
STRING STRING_VALUE = length + 1 END GROUP |
|
LEFT OVERPUNCHED
NUMERIC |
GROUP CDD/Repository-field-name
STRING STRING_VALUE = length END GROUP |
| RIGHT SEPARATE NUMERIC |
GROUP CDD/Repository-field-name
STRING STRING_VALUE = length + 1 END GROUP |
|
RIGHT OVERPUNCHED
NUMERIC |
GROUP CDD/Repository-field-name
STRING STRING_VALUE = length END GROUP |
| VARYING STRING |
GROUP CDD/Repository-field-name
WORD WORD_VALUE STRING STRING_VALUE = length END GROUP |
| BIT 1 |
GROUP CDD/Repository-field-name
STRING STRING_VALUE = length /8 END GROUP |
| DATE |
GROUP CDD/Repository-field-name
STRING STRING_VALUE = 8 END GROUP |
| POINTER |
GROUP CDD/Repository-field-name
LONG LONG_VALUE END GROUP |
| UNSPECIFIED |
GROUP CDD/Repository-field-name
STRING STRING_VALUE = length END GROUP |
| VIRTUAL FIELD | Ignored |
The following sections describe how BASIC translates CDD/Repository data types.
| Previous | Next | Contents | Index |