[an error occurred while processing this directive]

HP OpenVMS Systems Documentation
Content starts here

HP COBOL
DBMS Database Programming Manual

Previous Contents Index

Technical Notes

MODIFY 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 specifies the position of a vacated record in a record collection.
DBM$_WRONGRTYP The record type of record-name is not the same type as the current record of the run unit, or the record-item is not a group or elementary item of the current record type.
DBM$_DUPNOTALL A sort key data item is modified creating a duplicate value in a DUPLICATES NOT ALLOWED set.
DBM$_NOT_UPDATE A realm is not in ready update usage mode.
DBM$_CHKITEM A modified data item failed to pass the schema CHECK ITEM condition.
DBM$_CHKMEMBER A modified data item failed to pass the schema CHECK MEMBER condition.
DBM$_CHKRECORD A modified data item failed to pass the schema CHECK RECORD condition.
DBM$_CONVERR A data conversion error occurred in the MODIFY operation.
DBM$_ILLNCHAR An invalid character was found in a numeric field.
DBM$_NONDIGIT A nonnumeric character was found in a numeric field.
DBM$_OVERFLOW A data overflow error occurred in the MODIFY operation.
DBM$_TRUNCATION A data truncation error occurred in the MODIFY operation.
DBM$_UNDERFLOW A data underflow error occurred in the MODIFY operation.

Additional References

  • Section 2.2, on reserved words (database special registers)
  • HP COBOL Reference Manual, Chapter 6, section on scope of statements
  • Section 4.8.1, on database On Error condition
  • Section 5.14.1, on RETAINING clause
  • USE statement

Examples

  1. This example modifies an entire database record. It is a partial update routine. Except for the PART_ID number in PARTS, the set was originally created with empty parts records. As new information for a part is made available, it is included in the record. 


    150-UPDATE-PARTS-RECORD.

    DISPLAY "ENTER A PART-ID NUMBER - X(8): "
             WITHOUT ADVANCING.
    ACCEPT PART_ID.

    IF PART_ID NOT = "TERMINAL"
       FIND FIRST PART WITHIN ALL_PART USING PART_ID
            ON ERROR DISPLAY "ERROR IN FIND "
                     PERFORM 200-PARTS-RECORD-ERROR
                     GO TO 150-UPDATE-PARTS-RECORD
       END-FIND
       PERFORM VERIFY-PART-ROUTINE
    ELSE
       PERFORM TERMINAL-ROUTINE.

    DISPLAY "ENTER PART DESCRIPTION - X(50): "
            WITHOUT ADVANCING.
    ACCEPT PART_DESC.
       .
       .
       .
    MODIFY PART
       ON ERROR DISPLAY "ERROR MODIFYING PARTS_RECORD..."
                PERFORM 200-PARTS-RECORD-ERROR-ROUTINE.

    GO TO 150-UPDATE-PARTS-RECORD.
  2. In this example, PART_ID in the PART record is modified. PART_ID is a sort key for the CLASS_PART set. This routine will retain the current position in the CLASS_PART set after you modify the record. 


    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

  • HP COBOL Reference Manual, Chapter 6, section on scope of statements
  • Section 4.8.1, on database On Error condition

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.

Previous Next Contents Index