# Compaq COBOL
DBMS Database Programming Manual

Previous | Contents | Index

## 4.8.4 Translating DB-CONDITION Values to Exception Messages

Oracle CODASYL DBMS includes the following procedure for exception condition handling:

         CALL "DBM$SIGNAL".

Use this procedure when it is necessary to output an exception message rather than, or in addition to, displaying the numeric value of DB-CONDITION. For more information on the Oracle CODASYL DBMS database special register DB-CONDITION, see Section 2.2.1, DB-CONDITION.

# 4.9 Database Programming Statements in the COBOL Procedure Division

The Compaq COBOL Oracle CODASYL DBMS DML statements are:

- COMMIT
- CONNECT
- DISCONNECT
- ERASE
- FETCH
- FIND
- FREE
- GET
- KEEP
- MODIFY
- READY
- RECONNECT
- ROLLBACK
- STORE
- USE (Format 3)
- The RETAINING clause

# COMMIT

Function

The COMMIT statement ends your database transaction, makes permanent all changes made to the database since the 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 COMMIT statement ends the database transaction.
2. If you do not specify the STREAM clause, the COMMIT statement makes all changes made to the database since the last quiet point for this run unit; a new quiet point is established for the run unit.
3. If you specify the STREAM clause, the COMMIT statement makes all changes made to the database since the last quiet point permanent for the specified stream; a new quiet point is then established for the stream.
4. If you do not use the RETAINING clause (see Section 4.9.1, RETAINING Clause), COMMIT:
   - Empties all keeplists
   - Resets all your currency indicators to null
   - Releases all realm and record locks
   - Makes visible any changes you made to the database
   - Terminates the READY mode for each target realm
5. If you do use the RETAINING clause, COMMIT:
   - Does not empty keeplists
   - Retains all currency indicators
   - Does not release realm locks
   - Demotes no-read record locks to read-only record locks, then releases locks for all records except those in currency indicators or keeplists

   - Makes visible any changes you made to the database
   - Maintains READY modes for each target realm
6. If a database exception condition occurs during the execution of a COMMIT statement, the DBCS places a database exception condition code in the special register DB-CONDITION. This code identifies the condition.

Additional References

- Section 2.2 on reserved words (database special registers)
- Compaq COBOL Reference Manual, Chapter 6, section on scope of statements
- Section 4.8.1, on database On Error condition
- USE statement (Format 3)
- Section 5.2.4, on subschema description (DB)

Example

    COMMIT ON ERROR PERFORM 200-DISPLAY-ERROR-ON-COMMIT
                   END-COMMIT.

# CONNECT

Function

The CONNECT statement inserts the current record of the run unit as a member record into one or more sets. The set occurrence for each insertion is determined by the currency indicator for the corresponding set type.

> ### 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. Record-name must reference a subschema record type.
2. Set-name must reference a subschema set type.
3. For each set-name in the TO set-name clause, the record type of record-name must be a member record type of the set type.
4. The same set-name cannot be specified more than once in the TO set-name clause.
5. The same set-name cannot be specified more than once in the RETAINING clause.

General Rules

1. The current record of the run unit must be in a realm in ready update mode and all records required by the Database Control System (DBCS) to execute the CONNECT statement must be in a realm in available mode. The CONNECT statement uses the current record of the run unit.
2. Use record-name to check that the current record of the run unit is a record type identical to the record-name record type.
3. The current record of the run unit must not already be a member of set-name.
4. For each set-name in the TO clause:
   1. The DBCS inserts the current record of the run unit into each set-name as determined by the set currency indicator associated with each set-name.
   2. The position where the DBCS inserts the record into the set is determined according to the criteria for ordering the set defined in the schema for set-name.
5. When specifying the ALL option:
   1. The DBCS considers only those set types specified in your subschema for which:
      - The current record is not presently a member of any occurrence of the set type.
      - The record type of the current record is defined in the schema as a member record type of the set type.
   2. For each such selected set type:
      - The DBCS inserts the current record into the set determined by the set currency indicator associated with the selected set type.
      - The position where the DBCS inserts the current record into the set is determined according to the set-ordering criteria in the schema for the selected set type.
6. Unless otherwise specified by the RETAINING clause (see Section 4.9.1, RETAINING Clause), set type currency indicators for the connected sets point to the connected record. All other currency indicators are not affected.
7. If a database exception condition occurs during the execution of a CONNECT statement, the DBCS places a database exception condition code in the special register DB-CONDITION (see Technical Notes). This code identifies the condition.
8. If the execution of a CONNECT statement results in a database exception condition, no changes are made to the membership of the current record in the database.

Technical Notes

CONNECT 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 as the current record's type.
DBM$_NOT_MTYP | The current record is not a member record type of a set in the TO set-name phrase.
DBM$_NOW_MBR | The current record is already a member of the set specified in the TO set-name phrase.
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 | The program attempts to connect a record to a set and its sort key value is identical to another record's sort key value already in the set.
DBM$_NOT_UPDATE | A realm is not in update usage mode.
DBM$_CHKMEMBER | The Oracle CODASYL DBMS CHECK (member) condition was evaluated to be false. The database remains unchanged.

Additional References

- Section 2.2 on reserved words (database special registers)
- Compaq 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. Connecting EMPLOYEE record to the CONSISTS_OF set:

       CONNECT EMPLOYEE TO CONSISTS_OF.

2. Connecting EMPLOYEE record to all sets:

       CONNECT EMPLOYEE TO ALL.

3. Connecting EMPLOYEE record to the CONSISTS_OF set without changing the currency indicator of the CONSISTS_OF set:

       CONNECT EMPLOYEE TO CONSISTS_OF
               RETAINING SET CONSISTS_OF CURRENCY.

# DISCONNECT

Function

The DISCONNECT statement logically removes the current record of the run unit from one or more sets.

> ### 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. The same set-name cannot be specified more than once in the same DISCONNECT statement.

General Rules

1. The DISCONNECT statement references the current record of the run unit.
2. The current record of the run unit must be in a realm in ready mode and all records required by the DBCS to execute the DISCONNECT statement must be in a realm in available mode.
3. Use record-name to check that the current record of the run unit has the same record type as record-name.
4. The current record of the run unit must be an OPTIONAL member of each set-name.
5. The record type of the current record of the run unit must be a member record type of the set type for each set-name.
6. The DBCS removes the current record of the run unit from each set-name.
7. Use the ALL clause to remove the current record of the run unit from as many sets as possible. The DBCS considers only those set types defined in the subschema for which the record is an OPTIONAL member. Set types not included in your subschema and set types of which the record is not a member are ignored. The current record of the run unit is removed from each remaining set type.
8. If the set type currency indicator for a disconnected set pointed to the current record, that currency indicator now points to the position in the set vacated by the record. All other currency indicators are not affected.
9. If the execution of a DISCONNECT statement results in a database exception condition, no changes are made to the membership of the current record in the database.
10. If a database exception condition occurs during the execution of a DISCONNECT 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

DISCONNECT statement execution can result in these DB-CONDITION database exception condition codes:

DBM$_NOT_OPTNL | The current record of the run unit is not an OPTIONAL member of set-name.
DBM$_CRUN_NULL | The currency indicator for the current record of the run unit is null.
DBM$_CRUN_POS | The currency indicator for the current record of 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 as the current record's type.
DBM$_NOT_MTYP | The current record is not a member record type of set-name.
DBM$_NOT_MBR | The current record is not a member of set-name.
DBM$_NOT_UPDATE | A realm is not in ready update usage mode.

Additional References

- Section 2.2 on reserved words (database special registers)
- Compaq COBOL Reference Manual, Chapter 6, section on scope of statements
- Section 4.8.1, on database On Error condition
- USE statement

Examples

    DISCONNECT EMPLOYEE FROM CONSISTS_OF.

    DISCONNECT EMPLOYEE FROM ALL.

    DISCONNECT FROM ALL.

    DISCONNECT FROM CONSISTS_OF.

# ERASE

Function

The ERASE statement deletes the current record of the run unit from the database. Additional records owned by the current record may also be deleted and/or disconnected.

> ### record-name

> names a subschema record type.

> ### stment

> is an imperative statement executed for an on error condition.

> ### stment2

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

General Rules

1. The ERASE statement references the current record of the run unit.
2. Use record-name to check that the current record of the run unit has the same record type as record-name.
3. The current record of the run unit must be in a realm in update ready mode, and all records required by the Database Control System (DBCS) to execute the ERASE statement must be in a realm in available mode.
4. The current record of the run unit is called the object record for the remaining General Rules.
5. The object record is erased from all sets in which it is a member and deleted from the database.
6. If you use the ALL phrase, the object record and all sets owned by the object record are erased (independent of set membership retention class).
7. If you do not use the ALL phrase, these rules apply to the members of the sets owned by the erased object record:
   - Each member with FIXED membership is erased.
   - Each member with OPTIONAL membership is disconnected from the set but not deleted from the database.
   - An exception occurs if any members have MANDATORY membership.
8. The database key value corresponding to the erased object record is removed from all keeplists.
9. General Rules 5 to 8 apply to each erased record as if it were the object record.
10. The successful ERASE statement changes currency indicators as follows:
    - The currency indicator for the current record of the run unit points to the position in the database vacated by the current record of the run unit. However, you no longer have a current record.
    - If an erased record is the current record of a disconnected set type, that set type currency indicator now points to the position in the set vacated by that record.
    - If an erased record is the owner of the current set of any set type, that set type's currency indicator becomes null.
    - If an erased record is the current record of a record type, that record type currency indicator becomes null.
    - If the erased record is the current record of the realm, that realm currency indicator now points to the position in the realm vacated by that record.
11. If the execution of an ERASE statement results in a database exception condition, no changes are made to the database.
12. If a database exception condition occurs during the execution of an ERASE 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

ERASE 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 the record collection.
DBM$_WRONGRTYP | The record type of record-name is not the same as the current record's type.
DBM$_ERASEMANDT | You attempted to erase a record that is the owner of a set occurrence with a MANDATORY member record occurrence, but you did not use the ALL option.
DBM$_NOT_UPDATE | A realm is not in update usage mode.

Additional References

- Section 2.2, on reserved words (database special registers)
- Compaq COBOL Reference Manual, Chapter 6, section on scope of statements
- Section 4.8.1, on database On Error condition
- USE statement

Examples

1. This example erases PART record, all records owned by PART in the PART_USES, PART_INFO, and PART_USED_ON sets. It also erases all SUPPLY and PR_QUOTE records that it owns through the PART_INFO set. It disconnects PART from the RESPONSIBLE_FOR set.

       ERASE PART.

2. This example has the same effect as in example 1 for each PART record that the CLASS1 record owns; however, it also erases the CLASS1 record.

       ERASE ALL CLASS1.

   Note Because CLASS1 has MANDATORY members, you cannot erase only CLASS1.

# FETCH

Function

The FETCH statement is a combined FIND and GET that establishes a specific record in the database as the current record of the run unit and makes the record available to the run unit in the user work area.

> ### database-record

> represents a record selection expression. References are made to a record in the database according to the rules for Record Selection Expressions (see Section 4.6).

> ### set-name

> names a subschema set type.

> ### stment

> is an imperative statement executed for an AT END or ON ERROR condition.

> ### stment2

> is an imperative statement executed for a NOT AT END or NOT ON ERROR condition.

General Rules

1. database-record must reference a record stored in a realm that is in ready mode.
2. The FETCH statement is equivalent to the following sequence of statements:
   FIND database-record...
   GET...
3. Execution of the FETCH statement causes database-record to become the current record of the run unit.
4. The FOR UPDATE option puts a no-read lock on the specified record.
5. The DBCS makes a copy of the selected database record available to the program in the user work area. Any change made to the user work area does not affect the record in the database. You must execute a MODIFY and COMMIT statement to make permanent changes to the database.
6. Unless otherwise specified by the RETAINING clause (see Section 4.9.1, RETAINING Clause), the successful FETCH statement causes the DBCS to update these currency indicators to point to the selected record:
   - Run unit.
   - Realm.
   - Record type.
   - Set type. If it is an owner record type of the set type, this currency indicator points to the selected record even if the set is empty. If it is a member record type of the set type, this currency indicator points to the selected record only if it is currently a member of some set of that record type.
7. The DBCS places the database key of the fetched record in the special register DB-KEY.
8. If a database exception condition occurs during the execution of a FETCH statement, the DBCS places a database exception condition code in the special register DB-CONDITION (see Technical Note). This code identifies the condition.
9. [NOT]ON ERROR and [NOT]AT END cannot be used concurrently in a Fetch statement.
10. If either AT END or ON ERROR is used, it must precede USE.
11. If ON ERROR and NOT ON ERROR are used concurrently in a Fetch statement, USE procedures will not be activated.

Technical Note

FETCH statement execution can result in these database exception conditions and those associated with the evaluation of the record selection expression:

DBM$_CONVERR | A data conversion error occurred in the FETCH 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 FETCH operation.
DBM$_TRUNCATION | A data truncation error occurred in the FETCH operation.
DBM$_UNDERFLOW | A data underflow error occurred in the FETCH operation.

Additional References

- Section 2.2, on reserved words (database special registers)
- Compaq COBOL Reference Manual, Chapter 6, section on scope of statements
- Section 4.6, on record selection expressions
- Compaq COBOL Reference Manual, Chapter 6, section on AT END phrase
- Section 4.8.1, on database On Error condition
- Section 5.14.1, on RETAINING clause
- USE statement

Examples

1. Currency indicator access. To retrieve the:
   - Current record of the run unit

         FETCH CURRENT.

   - Current record of the MAKE realm

         FETCH CURRENT WITHIN MAKE.

   - Current record of the CLASS_PART set

         FETCH CURRENT WITHIN CLASS_PART.

   - Current PART record

         FETCH CURRENT WITHIN PART.

2. Keeplist access. To retrieve the:
   - First entry in the keeplist

         FETCH FIRST WITHIN KEEPLIST-A.

   - Last entry in the keeplist

         FETCH LAST WITHIN KEEPLIST-B.

   - N(th) entry in the keeplist

         FETCH OFFSET RECORD-COUNT WITHIN KEEPLIST-C.

3. Set owner access. To retrieve the owner (PART) of the PART_USES set:

       FETCH OWNER WITHIN PART_USES.

4. Record search access. To retrieve the:
   - First member within the PART_USES set

         FETCH FIRST WITHIN PART_USES.

   - First part whose PART-COST is greater than 300 dollars

         FETCH FIRST PART WHERE PARTCOST GREATER THAN 300

   - Last member within the BUY realm

         FETCH LAST WITHIN BUY.

   - Next COMPONENT record in the PART_USED_ON set

         FETCH NEXT COMPONENT WITHIN PART_USED_ON.

   - Prior COMPONENT record in the PART_USES set using COMP_SUB_PART and COMP_OWNER_PART as record keys

         FETCH PRIOR COMPONENT WITHIN PART_USES
               USING COMP_SUB_PART, COMP_OWNER_PART.

   - Record relative to the current record, this statement starts from the current position to the position defined by this offset

         FETCH RELATIVE SEARCH-NUMBER
               ON ERROR PERFORM 300-FETCH-IN-ERROR-ROUTINE
               END-FETCH.

   - PART record with PART_STATUS equal to "G" from the CLASS_PART set

         MOVE "G" TO PART_STATUS.
         FETCH NEXT CLASS WITHIN ALL_CLASS.
         FETCH NEXT PART WITHIN CLASS_PART USING PART_STATUS
                          AT END ...

   - DB-KEY access. To retrieve the item referred to by the DB-KEY special register:

         FETCH DBKEY.

Previous | Next | Contents | Index