When you create a Compaq COBOL DML program, you must include the SUB-SCHEMA SECTION entry as the first section in the Data Division. The SUB-SCHEMA SECTION is followed by a DB statement and any LD statements. The Procedure Division contains all occurrences of the DML verbs.

1.4 Compiling a Compaq COBOL DML Program

Your database administrator (DBA) creates schema and subschema definitions in Oracle CDD/Repository. These record definitions are defined in DMU format and are intended to serve all OpenVMS languages that might access them. In this format, the record definitions are not compatible with COBOL record definitions. Therefore, when the Compaq COBOL compiler retrieves the subschema definition from Oracle CDD/Repository, it translates the file into an internal form acceptable to the Compaq COBOL compiler.

If the translation results in compiler errors, they will probably be fatal.

You should alert your DBA to any errors resulting from a DB statement.

You can define the logical name CDD$DEFAULT as the starting schema node in Oracle CDD/Repository. There is only one logical name translation in the DB statement for schema-name. If you do not define it, CDD$TOP is the default.

A separately compiled Compaq COBOL database program must include the SUB-SCHEMA SECTION header and only one DB statement. The compiler copies and translates the record, set, and realm definitions in the subschema named by the DB statement into compatible Compaq COBOL record definitions. You will not see any database record definitions listed immediately following the DB statement. The translated record, set, and realm definitions are only in the compiler's subschema map listing. To list these definitions in your program listing, use the /MAP compiler command line qualifier.

1.4.2 Using the /MAP Compiler Qualifier

Use the /MAP compiler qualifier to generate a subschema map containing a translated subschema listing. Section 7.3 contains two subschema map listings on Alpha and two on VAX and explains how to read them. The following example compiles DBPROG and creates a listing that includes a subschema map:

$ COBOL/LIST/MAP DBPROG

1.5 Linking a Compaq COBOL DML Program

Compaq COBOL DML programs must be linked with the shareable Oracle CODASYL DBMS Library (SYS$LIBRARY:DBMDML/OPT). This library was created as part of the Oracle CODASYL DBMS installation procedure. Therefore, to link a Compaq COBOL DML object program named DMLPROG.OBJ with the shareable Oracle CODASYL DBMS Library, you use this DCL command:

$ LINK DMLPROG,SYS$LIBRARY:DBMDML/OPT

1.6 Running a Compaq COBOL DML Program

You use the DCL command RUN to execute your Compaq COBOL DML program. At run time, the Database Control System (DBCS) fills a variety of roles in Compaq COBOL. Its major functions are to monitor database usage, act as an intermediary between Compaq COBOL and the OpenVMS operating system, and manipulate database records on behalf of user programs. Upon execution of the first DML statement, the DBCS implicitly executes a BIND statement that links the run unit to the database. If the BIND statement is unsuccessful, a database exception occurs.

The DBCS also enforces the subschema view of the database. For example, a database schema record may contain 20 data items. However, a subschema record may only define 10 of those data items. If a FETCH statement references this record, the DBCS only retrieves those defined 10 data items and makes them available to the COBOL program in the user work area (UWA). The other 10 items are not available to the COBOL program. Figure 1-2 illustrates the run-time relationships between an application program requesting subschema data (a FETCH statement, for example), the DBCS, and the data the subschema describes.

Figure 1-2 Database and Application Program Relationship

In your database programming project you will need familiarity with:

• Database-related user-defined words
• Database-related reserved words

A user-defined word is a COBOL word that you must supply to satisfy the format of a clause or statement. This word consists of characters selected from the set A to Z, 0 to 9, the currency sign ($), underline (_), and hyphen (-). Throughout this manual, and except where specific rules apply, the hyphen (-) and the underline (_) are treated as the same character in a user-defined word. The underline (_), however, can begin or end a user-defined word, and the hyphen (-) cannot. By convention, names containing a currency sign ($) are reserved for Compaq.

Within a given source program, but excluding any contained program, each database-related user-defined word belongs to one of the following disjoint sets:

Keeplist-names
Realm-names
Schema-names
Set-names
Sub-schema-names
Record-names
Data-item-names

Each user-defined database-related word in a program can belong to only one of these sets. User-defined words in each set must be unique, except as described in the rules for uniqueness of reference. (Refer to the section on Uniqueness of Reference in the Procedure Division chapter of the Compaq COBOL Reference Manual. The same chapter defines user-defined names.)

Table 2-1 provides brief descriptions of the COBOL database-related user-defined words.

Table 2-1 COBOL Database-Related User-Defined Words

User-Defined Word Set	Purpose
Keeplist-name	Names a list of database keys used by the run unit to lock records for later use.
Realm-name	Names a database realm. (See the READY statement in the Procedure Division chapter.)
Schema-name	Names a database schema. (See the DB statement in the Data Division chapter.)
Set-name	Identifies a database set type.
Sub-schema-name	Names a database subschema. (See the DB statement in the Data Division chapter.)
Record-name	Names a database record type.
Data-item-name	Names a data-item that is defined for a record type.

2.2 Database-Related Reserved Words

A reserved word can be used only as specified in the general formats. It cannot be a user-defined word. (See the appendix that lists Reserved Words.) Among the COBOL reserved words are required words, optional words, and special-purpose words. One of the special-purpose words, DB-CONDITION, is of special interest to the database programmer.

2.2.1 DB-CONDITION

The reserved word DB-CONDITION names a database exception condition register. It is a longword COMP item represented by PIC S9(9) USAGE IS COMP. The execution of every COBOL data manipulation language (DML) statement causes the Database Control System (DBCS) to place a status code value in this register indicating either a successful condition or an exception condition.

Before the program executes the first DML statement, the value of DB-CONDITION is initialized to DBM$_NOT_BOUND. For an explanation of this and other Oracle CODASYL DBMS status codes, refer to the Oracle CODASYL DBMS documentation set.

If a DML statement causes an exception condition, the return status code in DB-CONDITION equals the condition value. If the execution of a DML statement does not result in a database exception condition, DB-CONDITION contains a successful return status. Procedure Division statements can access the values in this register; however, only the DBCS can change the value.

2.2.2 DB-CURRENT-RECORD-NAME

This reserved word names a database register. It consists of 31 alphanumeric characters represented by PIC X(31) USAGE IS DISPLAY. The execution of COBOL data manipulation language (DML) statements that alter currency indicators causes the Database Control System (DBCS) to place a value in this register.

If the currency indicator for the run unit is not null, the register contains the name of the record type of the current record of the run unit. If the currency indicator for the run unit is null, the register contains spaces. Procedure Division statements can access the values in this register; however, only the DBCS can change the value.

2.2.3 DB-CURRENT-RECORD-ID

The reserved word DB-CURRENT-RECORD-ID names a database register. It consists of a word COMP item represented by PIC S9(4) USAGE IS COMP. The execution of COBOL data manipulation language (DML) statements that alter currency indicators causes the Database Control System (DBCS) to place a value in this register.

If the currency indicator for the run unit is not null, the register contains the subschema User ID number (UID) of the record type of the current record of the run unit. If the currency indicator for the run unit is null, the register contains zero. Procedure Division statements can access the values in this register; however, only the DBCS can change the value.

2.2.4 DB-KEY

The reserved word DB-KEY names a database register. It consists of a quadword COMP item represented by PIC S9(18) USAGE IS COMP. The execution of the COBOL data manipulation language (DML) statements FETCH, FIND, and STORE causes the Database Control System (DBCS) to place a value in this register.

The DB-KEY special register contains three values. To access the individual values, move the DB-KEY register to a record as follows:

01 DATABASE-KEY 02 LINE-NUMBER PIC 9(4) USAGE IS COMP. 02 PAGE-NUMBER PIC 9(9) USAGE IS COMP. 02 AREA-NUMBER PIC 9(4) USAGE IS COMP.

2.2.5 DB-UWA

The reserved word DB-UWA names a database register. It consists of 108 alphanumeric characters represented by PIC X(108) USAGE IS DISPLAY. The Database Control System (DBCS) makes data items available to your program through the DB-UWA record delivery area. The DB-UWA register can be used with callable DBQ routines. Procedure Division statements can access the values in this register; however, only the DBCS can change the value. For more information, refer to the the discussion of the DBO/WORK_AREA command in the Oracle CODASYL DBMS documentation set.

The logical and physical concepts that apply to the Data Division in any COBOL program also apply to your database programs. The Compaq COBOL Reference Manual presents the general formats for Data Division entries and clauses, describes their basic elements, and lists rules of use. Information of special interest to the database programmer will be found here.

The Data Division defines the data processed by your COBOL program in both physical and logical terms. It also specifies whether the data is contained in files, a database, or Oracle CDD/Repository, or is developed only for local use in your program.

The Subschema Section specifies data contained in a database or Oracle CDD/Repository. The Working-Storage and Linkage Sections contain data description entries, which describe characteristics of data developed for use in your program.

3.1 DATA DIVISION General Format and Rules

The Data Division describes data the program creates, receives as input, manipulates, and produces as output.

Syntax Rules

1. The Data Division follows the Environment Division.
2. The reserved words DATA DIVISION, followed by a separator period, identify and begin the Data Division.

General Rules

1. The Data Division has six sections. These sections must be in the following order:

   SUB-SCHEMA SECTION.
   FILE SECTION.
   WORKING-STORAGE SECTION.
   LINKAGE SECTION.
   REPORT SECTION.
   SCREEN SECTION. (Alpha)

Subschema Section

2. The Subschema Section names the subschema you want to use. It describes a logical view of the database as it is to be accessed by the COBOL program. It begins with the Subschema Section header containing the reserved words SUB-SCHEMA SECTION followed by a period (.) separator character.
3. The Subschema entry follows the Subschema Section header.
4. The Subschema entry consists of a level indicator (DB), a sub-schema-name, the reserved word WITHIN, a schema-name, and an optional database clause.
5. A DB entry specifies the following:
   • Which subschema contains the descriptions of the data to be made available to the COBOL program
   • Which schema contains the subschema definition in Oracle CDD/Repository
   • The name of the database that the program is to be run against
   • The stream name
6. A run unit can declare only one Subschema (DB) entry.
7. Keeplist entries follow the Subschema (DB) entry. A keeplist is a table containing an ordered list of database key values.
8. Each database key value represents a record occurrence in the Oracle CODASYL DBMS database. A keeplist can contain the same database key value any number of times. Any number of keeplists can contain the same database key value any number of times.
9. A database key is added to the end of a keeplist by the KEEP or the FIND ALL statement and selectively removed by the FREE statement. One FIND ALL statement can add multiple database keys to a keeplist.
10. The number of entries in a keeplist is called the cardinality of the keeplist. A keeplist with zero entries is called an empty keeplist. The order of the entries in the keeplist reflects their sequence of insertion. As entries are added, the cardinality of the keeplist increases. As entries are removed, the cardinality decreases.
11. A COBOL program can reference a keeplist by using a database key identifier.
12. The Database Control System (DBCS) creates and maintains all keeplists.
13. No other run unit can update a record whose database key value is in a keeplist. The DBCS locks each record that is in a keeplist. The record remains locked until the program frees it or until the program executes a COMMIT (without the RETAINING option) or ROLLBACK statement, or until the program terminates.

File Section

Working-Storage Section

Linkage Section

Report Section

Screen Section (Alpha)

The last five COBOL sections are described and discussed in the Compaq COBOL Reference Manual chapter on Data Division.

Additional References

Refer to the Compaq COBOL Reference Manual for:

• REPORT clause
• VALUE IS clause
• CALL statement
• User-defined words

Function

The Subschema entry allows a program to access a subschema in Oracle CDD/Repository under the schema name.

sub-schema-name

references a subschema name in Oracle CDD/Repository under the schema name. See Technical Notes for more information.

schema-name

references a schema name in Oracle CDD/Repository. See Technical Notes for more information.

database-name

represents a complete or partial file specification defining the database occurrence. A database occurrence is a root file. At run time, database-name points the Database Control System (DBCS) to the root file. See Technical Notes for more information.

stream-name

represents the name of the stream. See Technical Notes for more information.

General Rules

1. The compiler finds the schema-name within Oracle CDD/Repository under your CDD$DEFAULT and includes these sub-schema-name definitions in your program: realm names, set names, record names, database data-names. These definitions are user-defined words. Other definitions include the database registers DB-CONDITION, DB-CURRENT-RECORD-NAME, DB-UWA, DB-CURRENT-RECORD-ID, and DB-KEY. Subschema definitions are also called database objects.
2. Database objects implicitly have the global attribute. Therefore, any program contained within a program declaring the DB statement can access any of the declaring program's database objects.
3. Only one DB statement is allowed for each separately compiled program; however, more than one DB statement is allowed in the run unit if its separately compiled programs define identical DB statements, or if each separately compiled program uses a stream.
4. Database objects either explicitly or implicitly defined in the subschema section are external objects by default. However, these objects can only be referenced by a program defining the DB statement or a program contained within that program.
5. When you compile a program containing a DB statement, the resulting .OBJ file includes the subschema date and time stamp assigned to the sub-schema-name when it was inserted in Oracle CDD/Repository. At run time, the DBCS finds the root file and binds the program to the subschema identified by sub-schema-name. If the program does not contain the same date and time as the subschema identified by sub-schema-name, then compile-time subschema definitions may not be the same as the run-time definitions; therefore, an exception condition occurs. This security check prevents your program from accessing the database with obsolete subschema definitions.
6. If you include the FOR database-name clause, the DBCS determines if database-name is a logical name or a file specification. If it is a partial file specification, the default file type is .ROO.
7. If you omit the FOR database-name clause, the DBCS creates a database-name from schema-name. The DBCS determines if schema-name is a logical name. If it is, a translation is done to determine the database-name. If schema-name is not a logical name, the DBCS creates a database-name by appending .ROO to the first nine characters of schema-name.
8. If a separately compiled program in the run unit uses a stream, then all separately compiled programs in the same run unit must use streams. Otherwise, a run-time error occurs.

Technical Notes

• Table 3-1 describes the representation of data types in the Oracle CODASYL DBMS data definition language (DDL) compiler and the Compaq COBOL for OpenVMS Alpha or VAX compiler. Additionally, this table lists all data types that can be specified using the DDL data definition language with the corresponding COBOL data item picture. Note that COBOL does not have an equivalent specification for some data types.

  Table 3-1 Compaq COBOL and DDL Utility Data Type Equivalences

  DDL	COBOL
  SIGNED BYTE	(a)
  UNSIGNED BYTE	(a)
  SIGNED WORD	S9(4) COMP
  UNSIGNED WORD	(b)
  SIGNED LONGWORD	S9(9) COMP
  UNSIGNED LONGWORD	(b)
  SIGNED QUADWORD	S9(18) COMP
  UNSIGNED QUADWORD	(b)
  SIGNED OCTAWORD	(a)
  UNSIGNED OCTAWORD	(a)
  FLOATING	COMP-1
  FLOATING COMPLEX	(a)
  D_FLOATING	COMP-2
  D_FLOATING COMPLEX	(a)
  G_FLOATING	COMP-2 (/FLOAT=G on Alpha)
  G_FLOATING COMPLEX	(a)
  H_FLOATING	(a)
  H_FLOATING COMPLEX	(a)
  CHARACTER l	X(l)
  UNSIGNED NUMERIC l s	9(m)V9(n)
  LEFT SEPARATE NUMERIC l s	S9(m)V9(n) LEADING SEPARATE
  LEFT OVERPUNCHED NUMERIC l s	S9(m)V9(n) LEADING
  RIGHT SEPARATE NUMERIC l s	S9(m)V9(n) TRAILING SEPARATE
  RIGHT OVERPUNCHED NUMERIC l s	S9(m)V9(n) TRAILING
  ZONED NUMERIC l s	(a)
  PACKED DECIMAL l s	S9(m)V9(n) COMP-3

  ---

  Legend:

  l---The total number of digits for the item.
  s---The decimal offset to 1.
  ( a ) ---COBOL has no equivalent for this data type. A fatal diagnostic is issued for such an item, which is part of a subschema record description. The compiler treats this item as if it had been specified as an alphanumeric data item that occupies the same number of bytes.
  ( b ) ---COBOL has no exact equivalent for this data type. A warning diagnostic is issued for such an item, which is part of a subschema record description. The compiler treats this item as if it had been specified as the equivalent unsigned COMP item.

  ---

  
  The method for describing the assumed decimal point is different in the two products. In a COBOL picture, the decimal position is directly indicated by the symbol V or implied by the symbol P. In DDL, scaled numbers are specified by two integers. The first integer represents the total number of decimal digits that the item represents. The second integer represents the decimal offset to the first integer.
  For example, the COBOL data item described by PIC 9(4)V99 is equivalent to the DDL entry TYPE IS UNSIGNED NUMERIC 6 -2. Similarly, the DDL entry TYPE IS LEFT SEPARATE NUMERIC 6 2 is equivalent to the COBOL description PIC S9(6)PP SIGN IS LEADING SEPARATE. The items described using the CDD INDEXED FOR COBOL BY clause become COBOL index-names.
• Schema-name, sub-schema-name, database-name, and stream-name can be a nonnumeric literal or a COBOL word formed according to the rules for user-defined names. Database-name represents a complete or partial file specification. If any of these names is not a literal, the compiler:
  • Translates hyphens in the COBOL word to underline characters
  • Translates lowercase alphabetic characters to uppercase
  • Treats the word as if it were enclosed in quotation marks
• Most of the information described in the remaining Technical Notes is included in the subschema map. See Chapter 1, Program Organization and Structure, for information on the /MAP qualifier.
• You can use this Database Operator (DBO) utility command to display date and time stamp information on schema-name and sub-schema-name:

  $ DBO/REPORT

  
  Additional information is available with the HELP DBO/REPORT command.

• You can use the DBO utility command to create a sub-schema-name output file from Oracle CDD/Repository:

  $ DBO/EXTRACT- $_ schema-name/SUB-SCHEMAS=sub-schema-name/OUTPUT=filename - $_ /OPTION=FULL $ PRINT filename

  
  Additional information is available with the HELP DBO/EXTRACT command.

• You can use the DBO utility command to create a sub-schema-name output file from the root file:

  $ DBO/DUMP database-name/SUB-SCHEMAS=sub-schema-name/OUTPUT=filename $ PRINT filename

  
  Additional information is available with the HELP DBO/DUMP command.

Additional Reference