HP OpenVMS Systems Documentation

HP COBOL
DBMS Database Programming Manual

Format 3

5. Prior to the execution of a database USE procedure, the DBCS places appropriate values in the DB-CONDITION, DB-CURRENT-RECORD-NAME, and DB-CURRENT-RECORD-ID special registers.
6. A database USE procedure executes automatically:
   • After standard database exception condition processing ends
   • When an on error condition or an at end condition results from a COBOL DML (data manipulation language) statement that has no applicable ON ERROR or AT END clause
7. Use of a DML verb in a USE FOR DB-EXCEPTION is not supported.
8. If there is an applicable USE FOR DB-EXCEPTION procedure, it executes whenever a database exception condition occurs. However, it does not execute if: (a) the condition is at end and there is an AT END phrase or (b) the condition is any database exception and there is an ON ERROR phrase.
9. If the DBCS (Database Control System) detects more than one database exception condition during the execution of a COBOL DML statement, the database USE procedure to which control transfers is determined by the contents of DB-CONDITION.
10. One COBOL DML error cannot cause more than one USE FOR DB-EXCEPTION procedure to execute.
11. A database USE procedure executes for a COBOL DML statement's exception condition: (a) if the OTHER phrase is the only phrase specified in the program, and (b) if these conditions are also true:
    • The COBOL DML statement has no ON ERROR phrase
    • The COBOL DML statement has no AT END phrase
    • The program does not specify an ON phrase for that exception condition
    
    After the USE procedure executes, control returns to the next executable statement in the invoking routine, if one is defined. Otherwise, control transfers according to the rules for Explicit and Implicit Transfers of Control.
12. If the ON DBM$_exception-condition phrase is specified and a COBOL DML statement results in a database exception condition, execution continues as follows:
    • If the value of DB-CONDITION is equal to a DBM$_exception-condition, the procedures associated with that DBM$_exception-condition execute.
    • If the value of DB-CONDITION is not equal to any DBM$_exception-condition, the procedures associated with the OTHER phrase execute.
13. If a database exception condition occurs and there is no applicable USE FOR DB-EXCEPTION procedure, uncommitted transactions roll back and the image terminates abnormally.

Additional Reference

• Section 4.3, Scope of Names

Example

(The Technical Notes following this example explain execution of the USE procedures shown.)

PROCEDURE DIVISION.
DECLARATIVES.
200-DATABASE-EXCEPTIONS SECTION.
    USE FOR DB-EXCEPTION ON OTHER.
201-PROCEDURE.
    DISPLAY "DATABASE EXCEPTION CONDITION".
    PERFORM 250-DISPLAY-MNEMONIC.
210-DATABASE-EXCEPTIONS SECTION.
    USE FOR DB-EXCEPTION ON DBM$_NOTIP.
211-PROCEDURE.
    DISPLAY "DATABASE EXCEPTION CONDITION ON READY STATEMENT"
    PERFORM 250-DISPLAY-MNEMONIC.
250-DISPLAY-MNEMONIC.

*
*   DBM$SIGNAL displays a diagnostic message based on the
*   status code in DB-CONDITION.
*
*
    CALL "DBM$SIGNAL".

    STOP RUN.

END DECLARATIVES.

Technical Notes

• If this program has an exception condition when executing a READY statement, or if the program does not ready the database before executing a DML statement, 210-DATABASE-EXCEPTIONS executes.
• If any other database exception condition occurs during program execution, 200-DATABASE-EXCEPTIONS executes.

4.9.1 RETAINING Clause

set-name

is a set name which is available in the program's subschema.

You can prevent currency indicator updates for REALM, RECORD, or SET. Specifying REALM retains all realm currency indicators; specifying RECORD retains all record currency indicators.

If SET is used without the set-name list option, the Database Control System (DBCS) retains the currency indicators for all sets in the subschema. If you specify the set-name list option, only the currency indicators for the specified sets are retained. The same set-name cannot be listed more than once in a given set-name list.

If you specify the RETAINING clause and do not select an option, the DBCS retains all REALM, RECORD, and SET currency indicators.

With HP COBOL database programming you can access data without designing separate files for specific applications. You accomplish this with the database management system (Oracle CODASYL DBMS) and the COBOL data manipulation language (DML). This chapter is a resource for information on:

• HP COBOL database program development
• HP COBOL database concepts
• HP COBOL programming tips and techniques
• Debugging and testing HP COBOL database programs

Database programmers and readers unfamiliar with Oracle CODASYL DBMS concepts and definitions should run the online self-paced demonstration package (see Section 5.1) as a prerequisite to this chapter. The demonstration package lets you test Oracle CODASYL DBMS features and concepts as you learn them. Additional useful information can be found in:

• Introduction to Oracle CODASYL DBMS
• Oracle CODASYL DBMS Database Administration Reference Manual

To help you learn how to use a database, Oracle has provided you with a database called PARTS. PARTS is an online self-paced demonstration database configured to show some of the features of Oracle CODASYL DBMS. You create the PARTS database as part of the demonstration package. Examples in this chapter refer to either the PARTSS1 or PARTSS3 subschema in the PARTS database. A complete listing of the PARTS schema, including the PARTSS1 and PARTSS3 subschemas, can be found in the Oracle CODASYL DBMS documentation on data manipulation.

Before beginning the demonstration, you should do the following:

1. Create your own node in Oracle CDD/Repository using the Dictionary Management Utility (DMU). (Refer to the Oracle CDD/Repository documentation for more information.)

   $ RUN SYS$SYSTEM:DMU[RET] DMU> CREATE nodename[RET] DMU> SHOW DEFAULT[RET] defaultname DMU> EXIT[RET] $

   
   where:

   nodename	names the new node in the CDD to contain your personal PARTS database.
   defaultname	is your CDD default.

   
   For example:

   $ RUN SYS$SYSTEM:DMU[RET] DMU> CREATE DEMONODE[RET] DMU> SHOW DEFAULT[RET] CDD$TOP DMU> EXIT[RET] $

2. Define CDD$DEFAULT using the defaultname, a period, and the nodename from step 1. For example:

   ---

   

As of Version 7.0, DBMS ships a kit that allows you to choose either a standard or multi-version DBMS environment.

The multi-version environment is the same as the standard environment, except that it allows multiple versions of DBMS to exist concurrently on the same system. This is implemented by adding the major and minor version number to the image file names, the command procedures that exist in common locations, and the [.DBM] subdirectory located in SYS$COMMON:[SYSTEST].

To run the demonstration package after a standard installation, (of any version of DBMS) issue the following command:

$ @SYS$COMMON:[SYSTEST.DBM]DBMDEMO [RET]

To run the demonstration package after a multi-version installation, issue the following command:

$ @SYS$COMMON:[SYSTEST.DBMnn]DBMDEMO [RET]

where nn is the DBMS major and minor version.

For example, to run the demonstration package on OpenVMS I64 with DBMS Version 7.2, issue the following command:

$ @SYS$COMMON:[SYSTEST.DBM72]DBMDEMO [RET]

You must run the entire demonstration to create and load the PARTS database. If you have already created the PARTS database but are unsure of or have changed its contents, you can reload it by running option 11 of the self-paced demonstration package. The demonstration package creates the NEW.ROO database instance. If you have any problems with the demonstration package, see your system manager or database administrator.