The Common Data Dictionary

The CDD supports some data types that are not native to PL/I. If a data definition contains an unsupported data type, PL/I makes the unsupported data type accessible by declaring it as data type BIT_FIELD or BYTE_FIELD. PL/I does not attempt to approximate a data type that is not supported by PL/I. For example, an F_FLOATING_COMPLEX number is declared BYTE_FIELD(8), not (2)FLOAT(24).

However, the use of the BIT_FIELD and BYTE_FIELD types is limited. Data declared with these data types can be manipulated only with the PL/I built-in functions ADDR, INT, POSINT, SIZE, and UNSPEC. Variables declared with BIT_FIELD or BYTE_FIELD can also be passed as parameters provided the parameter is declared as ANY. This limits references to data declared with BIT_FIELD or BYTE_FIELD to contexts in which the interpretation of a data type is not applied to the reference.

For example:

/* Declaration supplied by programmer */

DCL     1 A BASED(P),
          2 B FLOAT BINARY(24),
          2 C FLOAT BINARY(24);

/* Data definition supplied by CDD */

DCL     1 Q BASED,
          2 X BYTE_FIELD(8);
             .
             .
             .
P = ADDR(Q.X);

In this example, the ADDR built-in function gives the address of Q.X, which is assigned to P. Therefore, A can be used to reference X.

The following table summarizes the CDDL data types and corresponding PL/I data types. For further information on CDDL data types see the CDD documentation.

PL/I ignores CDD features that are not supported by PL/I, but issues error messages when the features conflict with PL/I.

CDD source files must be written in the Common Data Dictionary Language (CDDL). You enter them into your file directory using a VMS editor utility, just as you would enter any other file into your directory. CDD source files should have a file type of DDL, which is the file type recognized by CDD compiler.

Once you have created a CDD source file, you can invoke the CDDL compiler to insert your record definitions in the CDD. First, however, you can define CDDL as a global symbol by issuing the following command line or including it in your login command procedure:

$ CDDL:==$SYS$SYSTEM:CDDL

After you have done so, you need only enter CDDL to invoke CDD compiler. For example, to compile your FILE.DDL and insert it into the CDD, enter the following:

$ CDDL FILE.DDL

The CDD compiler compiles the structure declaration and issues messages, if necessary. To correct errors in your structure declaration, invoke an editor and change the data definition text as needed, and then recompile. The CDD enters only the highest version of a file; if you attempt to compile another file with the same name, CDD compiler issues an error message. However, the Dictionary Management Utility (DMU) permits updates. For further information see your CDD documentation.

The %DICTIONARY statement incorporates CDD data definitions into the current PL/I source file during compilation. The %DICTIONARY statement can occur anywhere in a PL/I source file. It has the following format:

%DICTIONARY cdd-path;

There are two types of CDD path name: full and relative. A full path name begins with CDD$TOP and specifies the given names of all its descendants; it is a complete path to the record definition. Descendant names are separated from each other by a period.

A relative path name begins with any generation name other than CDD$TOP, and specifies the given names of the descendants after that point. You can create a relative path by establishing a default directory with a logical name. For example:

$ DEFINE CDD$DEFAULT CDD$TOP.PLI

This logical name definition specifies the beginning of the CDD path name; thus, a relative path name specifies the remainder of the path to the record definition. Note also that a CDD path name beginning with CDD$TOP overrides the default CDD path name. For example, if you have a record with the following path name:

CDD$TOP.SALES.JONES.SALARY

You can specify a relative path name as follows:

%DICTIONARY 'SALARY';

Or you can specify an absolute path name as follows:

%DICTIONARY '_CDD$TOP.SALES.JONES.SALARY';

The compiler extracts the record definition from CDD and inserts the PL/I structure declaration corresponding to the record description in the PL/I program.

A %DICTIONARY statement can appear as a statement by itself, or it can appear within a regular PL/I structure declaration. However, the resulting structures appear somewhat different, depending on the way %DICTIONARY is included.

If the %DICTIONARY statement is not embedded in a PL/I language statement (that is, if %DICTIONARY immediately follows a nonpreprocessor semicolon or is the first statement in the program), then the resulting structure is declared with the logical level 1, and the BASED storage attribute is furnished. The logical member levels increment from 2. For example:

DECLARE PRICE FIXED BINARY(31);
%DICTIONARY 'ACCOUNTS';

would result in a declaration of the form:

DECLARE PRICE FIXED BINARY(31);
DECLARE 1 ACCOUNTS BASED,
          2 NUMBER,
            3 LEDGER CHARACTER(3),
            3 SUBACCOUNT CHARACTER(5),
          2 DATE CHARACTER(12),
           ⋮

Notice that in the previous example, ACCOUNTS is a relative dictionary path name.

If the %DICTIONARY statement is embedded in a PL/I language statement, as in a structure declaration, then the resulting structure is declared with no logical level and no storage attribute. Logical member numbers are supplied and incremented from 100. For example:

DECLARE 1 COMMON_INTERFACES STATIC EXTERNAL,
          %DICTIONARY 'ACCOUNTS';   ,
          %DICTIONARY 'ADDRESSES';  ;

Notice the syntax in this example: the %DICTIONARY statement is terminated with the usual preprocessor terminator semicolon before the normal PL/I punctuation. The normal PL/I punctuation must also be included so that the final structure declaration will contain proper PL/I punctuation. At compile time, this declaration would result in a declaration of the following form:

DECLARE 1 COMMON_INTERFACES STATIC EXTERNAL,
          100 ACCOUNTS,
            101 NUMBER,
               102 LEDGER CHARACTER(3),
               102 SUBACCOUNT CHARACTER (5),
            101 DATE CHARACTER(12),
            ⋮
          100 ADDRESSES,
           ⋮

When you extract a record definition from the CDD, you can choose to include this translated record in the program's listing by using the /LIST/SHOW=DICTIONARY qualifiers on the PLI command line.

CDD data definitions can contain explanatory text in the CDDL DESCRIPTION IS clause. If you specify /SHOW=DICTIONARY, this text is included in the PL/I listing comments. You can use these comments to indicate the data type of each structure and member. The punctuation for CDDL comments is the same as for other PL/I programs.

Even if you choose not to list the extracted record, the names, data types, and offsets of CDD record definition are displayed in the program listing's allocation map.