HP OpenVMS Systems Documentation

HP COBOL
DBMS Database Programming Manual

A separately compiled HP 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 HP 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 I64 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

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

You use the DCL command RUN to execute your HP COBOL DML program. At run time, the Database Control System (DBCS) fills a variety of roles in HP COBOL. Its major functions are to monitor database usage, act as an intermediary between HP 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 Hewlett-Packard.

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 HP COBOL Reference Manual. The same chapter defines user-defined names.)

Table 2-1 provides brief descriptions of the COBOL database-related user-defined 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.