HP OpenVMS Systems Documentation

HP COBOL
DBMS Database Programming Manual

All Formats

12. If a database exception condition occurs during the execution of a FIND statement, the DBCS places a database exception condition code in the special register DB-CONDITION (see Technical Note). This code identifies the condition.
13. The DBCS places the database key of the record found in the special register DB-KEY.
14. [NOT]ON ERROR and [NOT]AT END cannot be used concurrently in a Find statement.
15. If either AT END or ON ERROR is used, it must precede USE.
16. If ON ERROR and NOT ON ERROR are used concurrently in a Find statement, USE procedures will not be activated.

Technical Note

FIND statement execution can result in the database exception conditions associated with the evaluation of the record selection expression.

Additional References

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

Examples

1. Currency indicator access. To locate the following items, use the statement listed with each item:
   • Current record of the run unit

     FIND CURRENT.

   • Current record of the MAKE realm

     FIND CURRENT WITHIN MAKE.

   • Current record of the CLASS_PART set

     FIND CURRENT WITHIN CLASS_PART.

   • Current PART record

     FIND CURRENT WITHIN PART.

2. Keeplist access. To locate the following items, use the statement listed with each item:
   • (ALL) PART records with a PARTSTATUS OF H and put their dbkey values in keeplist THREE

     FIND ALL THREE PART USING PARTSTATUS PARTSTATUS [X(1)] = H

   • First entry in the keeplist

     FIND FIRST WITHIN KEEPLIST-A.

   • Last entry in the keeplist

     FIND LAST WITHIN KEEPLIST-B.

   • N(th) entry in the keeplist

     FIND OFFSET RECORD-COUNT WITHIN KEEPLIST-C.

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

   FIND OWNER WITHIN PART_USES.

4. Record search access. To locate the following items, use the statement listed with each item:
   • NEXT DEALER record whose DEAL-PHONE item begins with the area code numbers 617

     FIND NEXT DEALER WHERE DEAL-PHONE MATCHES "617"

   • First member within the PART_USES set

     FIND FIRST WITHIN PART_USES.

   • Last member within the BUY realm

     FIND LAST WITHIN BUY.

   • Next COMPONENT record in the PART_USED_ON set

     FIND NEXT COMPONENT WITHIN PART_USED_ON.

   • Prior COMPONENT record in the PART_USES set (uses COMP_SUB_PART and COMP_OWNER_PART as record keys)

     FIND PRIOR COMPONENT WITHIN PART_USES USING COMP_SUB_PART, COMP_OWNER_PART.

   • A record relative to the current record (this statement starts from the current position to the position defined by this offset)

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

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

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

   • All PART records with PART_STATUS OF G (this statement puts their dbkey values in KEEPLIST-4)

     FIND ALL KEEPLIST-4 PART USING PART_STATUS

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

     FIND DBKEY.

Function

The FREE statement empties selected keeplists or removes a database key value from a keeplist or currency indicator.

database-key-id

represents a database key identifier. References are made to a keeplist entry or a currency indicator according to the rules for Database Key Identifiers.

keeplist-name

names a keeplist in the Subschema Section.

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

Keeplist-name cannot be specified more than once in a given FREE statement.

General Rules

1. If database-key-id references a keeplist entry, the DBCS deletes that keeplist entry from the keeplist containing it. Removing an entry from a keeplist changes the position of all subsequent entries in the keeplist.
2. If database-key-id references a currency indicator, the DBCS sets that currency indicator to null.
3. If ALL is specified and the FROM phrase is omitted, the DBCS empties all keeplists in the program.
4. If ALL CURRENT is specified, the DBCS nulls all of your currencies. It does not free entries in a keeplist.
5. If the FROM phrase is specified, the DBCS empties each keeplist-name.
6. The FREE statement releases retrieval update locks on the target record.
7. If a database exception condition occurs during the execution of a FREE statement, the DBCS places a database exception condition code in the special register DB-CONDITION (see Technical Note). This code identifies the condition.

Technical Note

FREE statement execution can result in these database exception conditions and those associated with a Database Key Identifier:

Additional References

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

Examples

1. Currency indicator access
   • To free the current record of the run unit:

     FREE CURRENT.

   • To free the currency indicator for the PART record:

     FREE CURRENT WITHIN PART.

   • To free all currencies:

     FREE ALL CURRENT.

2. Keeplist access
   • To free the first keeplist entry in KEEPLIST-A:

     FREE FIRST WITHIN KEEPLIST-A.

   • To free the last keeplist entry in KEEPLIST-A:

     FREE LAST WITHIN KEEPLIST-A.

   • To free the second keeplist entry relative to the current position in the keeplist:

     FREE OFFSET 2 WITHIN KEEPLIST-B.

   • To empty a keeplist:

     FREE ALL FROM KEEPLIST-B

   • To empty all keeplists:

     FREE ALL