Compaq COBOL
DBMS Database Programming Manual
Previous Contents Index 


300-FIX-ID-ROUTINE. 
 
    DISPLAY "ENTER PART ID TO BE CHANGED - X(8): " 
            WITHOUT ADVANCING. 
    ACCEPT PART_ID. 
 
    FIND  FIRST PART WITHIN CLASS_PART USING PART_ID 
       ON ERROR DISPLAY "ERROR IN FIND PARTS_RECORD..." 
                PERFORM 200-PARTS-RECORD-ERROR-ROUTINE. 
 
    DISPLAY "ENTER NEW PART ID - X(8): " 
             WITHOUT ADVANCING. 
    ACCEPT PART_ID. 
 
    MODIFY PART_ID RETAINING CLASS_PART 
        ON ERROR DISPLAY "ERROR MODIFYING PARTS_RECORD..." 
                 PERFORM 200-PARTS-RECORD-ERROR-ROUTINE.

READY

Function

The READY statement begins a database transaction, prepares one or more database realms for processing, and places each specified realm in a ready mode.

realm-name

names a subschema realm.

stment

is an imperative statement executed for an on error condition.

stment2

is an imperative statement executed for a not on error condition.

Syntax Rule

The same realm-name cannot be specified more than once in a single READY statement.

General Rules

  1. The READY statement begins a database transaction.
  2. Execution of the READY statement is successful only when all specified realm-names are placed in the ready mode.
  3. If you do not specify a realm-name, the DBCS (Database Control System) readies all realms in your subschema except those already readied.
  4. The USAGE-MODE phrase establishes run-time privileges for this run unit. It also affects other run units running concurrently. It consists of two parts: (a) the allow mode, and (b) the access mode.
  5. If the program does not specify a usage mode, PROTECTED RETRIEVAL is the default.
  6. The allow mode specifies what you will allow other concurrent run units to do. It consists of the reserved words BATCH, CONCURRENT, EXCLUSIVE, and PROTECTED.
  7. The BATCH RETRIEVAL option allows concurrent run units to update the realm. You can retrieve data as though a copy of the database had been made at the time you readied the realm. This eliminates the possibility of deadlocks due to record lock conflicts. Any updates made by concurrent run units will not be available to your transaction.
    If you ready any realm in BATCH, you must ready all realms in BATCH.
  8. The BATCH UPDATE option allows you to access or update any data in the realm while preventing concurrent run units from accessing or updating the realm.
  9. The CONCURRENT clause permits other run units to update records in the same areas that map to the readied realm-name. Record-locking will be done for you by the DBCS to protect the integrity of your currency indicators, keeplists, and uncommitted changes. You will not be able to see any other user's uncommitted changes.
  10. The EXCLUSIVE clause prevents concurrent run units from accessing records in the same areas that map to the readied realm-name.
  11. The PROTECTED clause (the default) prohibits concurrent run units from updating records in the same areas that map to the readied realm-name. Concurrent run units will be able to ready the realm for retrieval only.
  12. The access mode indicates what your run unit will do. It consists of the reserved words RETRIEVAL and UPDATE.
  13. The RETRIEVAL clause (the default) allows your run unit read-only privileges. It prevents your unit from updating records in the readied realms.
  14. The UPDATE clause permits your run unit to update records in a readied realm. It allows the run unit to execute any DML statement against the specified realm.
  15. The WAIT option tells the DBCS to READY the specified realms as soon as possible. You will get a response only when the realms can be readied or when an error other than a lock conflict occurs.
  16. Currency indicators are not affected by the READY statement.
  17. If a database exception condition occurs during the execution of a READY statement, the DBCS places a database exception condition code in the special register DB-CONDITION (see Technical Notes). This code identifies the condition.
  18. Figure 4-1 summarizes the effects of the allow and access options on concurrent run units readying the same realm-name. A database exception condition will occur if a concurrent run unit has a realm-name readied in a conflicting or incompatible mode (see Technical Notes).
    The First Run Unit column refers to a READY statement that has already been executed in a concurrent run unit. The Second Run Unit column refers to a READY statement being attempted by the current run unit. The intersection indicates whether the attempted READY statement can be executed immediately or if there is a conflict.
    Because Figure 4-1 is symmetrical, the chronology of access (that is, did the First Run Unit ready the realm first) does not matter.
    The locking effects of the BATCH RETRIEVAL usage mode are equivalent to those of the CONCURRENT RETRIEVAL usage mode; however, BATCH RETRIEVAL performs no record locking.
    The locking effects of the BATCH UPDATE usage mode are equivalent to those of the EXCLUSIVE UPDATE usage mode.
    Note also that the two EXCLUSIVE usage modes have identical locking effects.

Figure 4-1 Usage Mode Conflicts

Technical Notes

READY statement execution can result in these DB-CONDITION database exception condition codes:
DBM$_ALLREADY All subschema realms are already readied.
DBM$_READY Realm-name is already readied.
DBM$_AREABUSY Your usage mode conflicts with another run unit's usage mode. See Figure 4-1.

Additional References

Example

Depending on the contents of PROCESS-MODE, this statement readies the BUY, MAKE, and PERSONNEL realms in either PROTECTED UPDATE mode or CONCURRENT RETRIEVAL mode (default for USAGE-MODE). 


    IF PROCESS-MODE = "UPDATE" 
       READY BUY, MAKE, PERSONNEL 
       USAGE-MODE IS PROTECTED UPDATE 
       ON ERROR DISPLAY "ERROR READYING ..." 
                DISPLAY "IN PROTECTED UPDATE MODE..." 
                PERFORM ERROR-ROUTINE 
       END-READY 
       PERFORM UPDATE-ROUTINE 
    ELSE 
       READY BUY, MAKE, PERSONNEL 
       ON ERROR DISPLAY "ERROR READYING ..." 
                DISPLAY "IN CONCURRENT RETRIEVAL MODE..." 
                PERFORM ERROR-ROUTINE 
       END-READY.

RECONNECT

Function

The RECONNECT statement moves the current database record of the run unit from one set to another (possibly the same) set.

record-name

names a subschema record type.

set-name

names a subschema set type.

stment

is an imperative statement executed for an on error condition.

stment2

is an imperative statement executed for a not on error condition.

Syntax Rules

  1. The record type of record-name must be a member record type of the set type for each set-name.
  2. Set-name cannot be specified more than once in the WITHIN clause.
  3. Set-name cannot be specified more than once in the RETAINING clause.

General Rules

  1. RECONNECT uses the current record of the run unit.
  2. The current run unit record must be in a realm in ready update mode and all records required by the Database Control System (DBCS) to execute the RECONNECT statement must be in realms in available mode.
  3. Use record-name to check that the record type of the current record of the run unit is identical to the record type specified by record-name.
  4. For each set-name you specify in the WITHIN clause:
    1. The DBCS disconnects the current record of the run unit from the set in which it is currently a member and inserts this record in the current set of the set-name set type.
    2. The position where the DBCS inserts the record into the set is determined by the set-ordering criteria defined in the schema for set-name.
  5. If the program specifies the ALL option:
    1. The DBCS considers only those set types that satisfy these requirements:
      • The set type is in your subschema.
      • The current run-unit record type is defined in the schema as an OPTIONAL or MANDATORY member record type of the set type.
      • The current run-unit record is presently a member of a set of the set type.
    2. For each selected set type:
      • The DBCS disconnects the current record of the run unit from the set in which it is currently a member and inserts this record in the current set of the selected set type.
      • The position where the DBCS inserts the record into the set is determined by the set-ordering criteria defined in the schema for set-name.
  6. Unless otherwise specified by the RETAINING clause (see Section 4.9.1, RETAINING Clause), the DBCS updates the set type currency indicators for the reconnected sets to point to the connected record.
  7. If a database exception condition occurs during the execution of a RECONNECT statement, the DBCS places a database exception condition code in the special register DB-CONDITION (see Technical Notes). This code identifies the condition.

Technical Notes

RECONNECT statement execution can result in these DB-CONDITION database exception condition codes:
DBM$_CRUN_NULL The currency indicator for the run unit is null.
DBM$_CRUN_POS The currency indicator for the run unit points to a vacated position in the database.
DBM$_WRONGRTYP The record type of record-name is not identical to the current record type.
DBM$_CSTYP_NULL There is no current of set type for the set specified in the TO set-name phrase. This occurs only if the set is not a singular set.
DBM$_DUPNOTALL A sort key data item in the record to be reconnected is the same as the sort key of a record already in the set.
DBM$_FIXED The program attempted to reconnect a FIXED member record from one set type to another set of a given set type.
DBM$_NOT_UPDATE The realm is not in ready update usage mode.
DBM$_NOT_MBR You attempted to reconnect a record to a set in which it is not a member.
DBM$_CHKMEMBER The Oracle CODASYL DBMS CHECK (member) condition was evaluated to be false. The database has not been changed.

Additional References

Example

This example shows how to change a record's set membership (terminal classifications) when the record (VT3) is a MANDATORY member. (OPTIONAL members must be DISCONNECTED from the old set occurrence and CONNECTED to the new set occurrence.) 


MOVE "TERMINALS NOT SUP" TO CLASS_DESC. 
FIND FIRST CLASS-REC WITHIN ALL_CLASS 
      USING CLASS_DESC. 
 
MOVE "VT3" TO PART_DESC. 
FIND FIRST PART WITHIN ALL_PARTS_ACTIVE. 
      USING PART_DESC 
      RETAINING CLASS_PART. 
 
    RECONNECT PART WITHIN CLASS_PART.

ROLLBACK

Function

The ROLLBACK statement ends your database transaction, nullifies all database changes made by this run unit since its last quiet point, and establishes a new quiet point for this run unit.

stment

is an imperative statement executed for an on error condition.

stment2

is an imperative statement executed for a not on error condition.

Syntax Rules

  1. The STREAM clause cannot be specified if the subschema entry (DB) does not name a stream.

General Rules

  1. The ROLLBACK statement ends your database transaction.
  2. All keeplists are emptied.
  3. If you do not use the STREAM clause, the ROLLBACK statement does the following:
  4. If you use the STREAM clause, the ROLLBACK statement does the following:
  5. All currency indicators are set to null.
  6. All realm and record locks are released. These records and realms are now available to concurrent run units.
  7. To begin another transaction, the program must execute another READY statement after it executes the ROLLBACK statement.
  8. If the run unit abnormally terminates, the DBCS executes an implicit ROLLBACK statement.
  9. If a database exception condition occurs during the execution of a ROLLBACK statement, the DBCS places a database exception condition code in the special register DB-CONDITION. This code identifies the condition.

Additional References

Example

This ROLLBACK example illustrates one way to end a database transaction and undo the changes made to the database during the transaction. 


010-BEGIN-UPDATE-TRANSACTION. 
 
* This transaction begins with the first READY statement in 
* the run unit, continues through a series of DML database 
* access statements, and ends with a COMMIT or ROLLBACK. 
    . 
    . 
    . 
 
100-END-UPDATE-TRANSACTION. 
 
    DISPLAY "DO YOU WANT TO COMMIT THIS TRANSACTION ? ". 
    ACCEPT ANSWER. 
    IF ANSWER = "YES" 
       COMMIT ...
     ELSE 
       ROLLBACK 
            ON ERROR 
               IF DB-CONDITION = DBM-NOT-BOUND 
                  DISPLAY " Database not bound" 
               ELSE 
                  CALL "DBM$SIGNAL". 
               END-IF 
            END-ROLLBACK.

STORE

Function

The STORE statement stores a new record in the database, establishes the record as an owner of an empty set of each set type for which the record is an owner record type, and connects the record as a member to the current set of each set type for which the record is an AUTOMATIC member record type.

record-name

names a subschema record type.

realm-name

names a subschema realm.

set-name

names a subschema set type.

stment

is an imperative statement executed for an on error condition.

stment2

is an imperative statement executed for a not on error condition.

Syntax Rules

  1. Realm-name cannot be specified more than once in the same STORE statement.
  2. Set-name cannot be specified more than once in the same STORE statement.

General Rules

  1. The STORE statement references the record-name in the user work area. You must move the data to be in record-name to the user work area before executing a STORE statement.
  2. If you specify the WITHIN option, the Database Control System (DBCS) stores a new record occurrence in one of the realms from the list of realm-names.
    If you do not specify the WITHIN option, the DBCS stores a new record occurrence in one valid subschema realm for that record type.
  3. If you specify the DBKEY option, the target area is determined by page size. If the page specified by the DB-KEY special register has space available, that page is the target area. Otherwise, the DBCS chooses the next page that has available space.
  4. After a successful STORE operation, the DB-KEY special register contains the database key for the record.
  5. The STORE statement stores a record occurrence of the record-name record type from your user work area to a single target area.
  6. If the DBCS can store record-name in more than one realm or area, the selected realm or area is unspecified.
  7. The successful STORE statement directs the DBCS to store these items in the target area:
  8. The DBCS establishes the newly stored record as the owner record of an empty set for each set type for which record-name is defined as the owner record type.
  9. The DBCS connects the newly stored record as a member record of the current set of each set type for which record-name is defined as an AUTOMATIC member record type. The set criteria defined in the schema for that set type determine the position where the DBCS inserts record-name.
  10. Unless otherwise specified by the RETAINING clause (see Section 4.9.1, RETAINING Clause), these currency indicators point to the stored record:
  11. The contents of the user work area do not change after the successful or unsuccessful execution of a STORE statement.
  12. If a database exception condition occurs during the processing of a STORE statement, the DBCS places a database exception condition code in the special register DB-CONDITION (see Technical Notes). This code identifies the condition.

Technical Notes

STORE statement execution can result in these DB-CONDITION database exception condition codes:
DBM$_NODEFVAL There is no schema DEFAULT clause for an omitted data item in record-name.
DBM$_CHKITEM A record-name item contains an invalid value as determined by a schema CHECK clause.
DBM$_CHKMEMBER A record-name item contains an invalid value as determined by a schema CHECK clause.
DBM$_CHKRECORD A record-name item contains an invalid value as determined by a schema CHECK clause.
DBM$_CSTYP_NULL The set currency indicator for an AUTOMATIC, nonsingular set type in which record-name is a member is null.
DBM$_CONVERR A data conversion error occurred in the STORE operation.
DBM$_ILLNCHAR Invalid character found in a numeric field.
DBM$_NONDIGIT Nonnumeric character found in a numeric field.
DBM$_OVERFLOW A data overflow error occurred in the STORE operation.
DBM$_TRUNCATION A data truncation error occurred in the STORE operation.
DBM$_UNDERFLOW A data underflow error occurred in the STORE operation.
DBM$_SETSELECT You cannot store this record using this subschema. Either add the specified set type to your subschema or use a different subschema.

Additional References

Example 


010-ADD-NEW-CLASS-RECORDS. 
 
    DISPLAY "ENTER CLASS CODE". 
    ACCEPT  CLASS_CODE. 
    DISPLAY "ENTER CLASS DESCRIPTION". 
    ACCEPT  CLASS_DESC. 
    DISPLAY "ENTER CLASS STATUS". 
    ACCEPT  CLASS_STATUS. 
 
    STORE CLASS_REC WITHIN MAKE 
          ON ERROR DISPLAY "ERROR STORING CLASS..." 
                   PERFORM 200-STORE-CLASS-ERROR 
          END-STORE.

USE

Function

The USE statement specifies Declaratives procedures to handle file input/output errors and database exception conditions. It can also specify procedures to be executed before the program processes a specific report group.

These procedures supplement the procedures in the COBOL Run-Time System and RMS.

USE is part of the COBOL ANSI standard.

Formats 1 and 2

Refer to the Compaq COBOL Reference Manual for Formats 1 and 2. Only Format 3 is applicable to DBMS DML.

DBM$_exception-condition

is a symbolic constant name beginning with the characters DBM$_. It identifies an Oracle CODASYL DBMS exception condition. Refer to the Oracle CODASYL DBMS documentation set for information on DML error and warning messages.

Syntax Rules

All Formats

  1. A USE statement can be used only in a sentence immediately after a section header in the Procedure Division Declaratives area. It must be the only statement in the sentence. The rest of the section can contain zero, one, or more paragraphs to define the particular USE procedures.
  2. The USE statement itself does not execute. It defines the conditions that cause execution of the associated USE procedure.
  3. Refer to Compaq COBOL Reference Manual for information on USE formats 1 and 2.

Format 3

  1. The DBM$_exception-condition argument must begin with these five characters: DBM$_.
  2. If the phrase USE [GLOBAL] FOR DB-EXCEPTION. occurs, it is the only USE procedure allowed in the program.
  3. Multiple occurrences of the USE statement can exist within a program only if the ON phrase is specified. DBM$_exception-condition in each USE statement must be unique. Multiple USE statements must not cause the simultaneous request for execution of more than one USE procedure. The OTHER phrase may be specified only once in a program.
  4. If a USE FOR DB-EXCEPTION statement does not specify the ON phrase, it must be the only occurrence of Format 3 of the USE statement in the program.

General Rules

All Formats

  1. At run time, two special precedence rules apply for the selection of a USE procedure when a program is contained within another program. In applying these rules, only the first qualifying USE procedure is selected for execution. The order of precedence for the selection of a USE procedure is as follows:
  2. A USE procedure cannot refer to a non-Declaratives procedure. However, only the PERFORM statement can transfer execution control from:
  3. After a 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.
  4. A program must not execute a statement in a USE procedure that would cause execution of a USE procedure that had been previously executed and had not yet returned control to the routine that invoked it.

Format 3

  1. 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.
  2. A database USE procedure executes automatically:
  3. Use of a DML verb in a USE FOR DB-EXCEPTION is not supported.
  4. 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.
  5. 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.
  6. One COBOL DML error cannot cause more than one USE FOR DB-EXCEPTION procedure to execute.
  7. 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:
    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.
  8. If the ON DBM$_exception-condition phrase is specified and a COBOL DML statement results in a database exception condition, execution continues as follows:
  9. 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.

Previous Next Contents Index