HP OpenVMS Systems Documentation
Content starts here

HP COBOL
DBMS Database Programming Manual

Previous Contents Index

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)
  • HP COBOL Reference Manual, Chapter 6, section on scope of statements
  • Section 4.6, on record selection expressions
  • HP 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.

FIND

Function

The FIND statement locates a specific record in the database and establishes it as the current record of the run unit. The FIND ALL statement locates zero or more records in the database and inserts them into the named keeplist.

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.

keeplist-name

names a list of database keys used by a run unit to lock records for later reference.

record-name

names a subschema record type.

realm-name

names a subschema realm.

rec-key

is a key data item within the subschema record occurrence.

bool-expres

is a conditional expression that involves data items of the object record.

General Rules

Format 1

  1. database-record must reference a record stored in a realm that is in ready mode.
  2. Execution of the FIND statement causes database-record to become the current record of the run unit.
  3. The Database Control System (DBCS) does not make a copy of the database record available to the program. To retrieve the record you must use a FETCH or GET statement.
  4. The FOR UPDATE option puts a no-read lock on the specified record.
  5. Unless otherwise specified by the RETAINING clause (see Section 4.9.1, RETAINING Clause), the successful FIND statement causes the DBCS to update these currency indicators to point to the selected record:
    • Run unit.
    • Realm.
    • Record type.
    • Set type. If the record is an owner record of the set type, this currency indicator points to the selected record even if the set is empty. If the record is a member record 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.

Format 2

  1. keeplist-name identifies the object keeplist for the statement.
  2. Using FIND ALL puts the database key values corresponding to each qualifying record at the end of the object keeplist.
  3. When FIND ALL keeplist-name is used, no currency indicators are affected.
  4. The same rec-key can appear only once in a given USING phrase.
  5. The bool-expres expression is used to specify additional requirements of a qualifying record.
  6. When FOR UPDATE is used, no-read locks may be placed on more than one record.

Previous Next Contents Index