Compaq COBOL
DBMS Database Programming Manual
Previous Contents Index

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:

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.

All Formats

  1. 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.
  2. The DBCS places the database key of the record found in the special register DB-KEY.
  3. [NOT]ON ERROR and [NOT]AT END cannot be used concurrently in a Find statement.
  4. If either AT END or ON ERROR is used, it must precede USE.
  5. 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

Examples

  1. Currency indicator access. To locate the following items, use the statement listed with each item:
  2. Keeplist access. To locate the following items, use the statement listed with each item:
  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:

FREE

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:
DBM$_BADZERO Integer-exp is zero.
DBM$_END You accessed a keeplist with fewer entries than you expected.

Additional References

Examples

  1. Currency indicator access
  2. Keeplist access

GET

Function

The GET statement moves the contents of the current database record of the run unit to your user work area.

record-name

names a subschema record type.

record-item

is a group or elementary data item in a subschema record type. Record-item may be qualified.

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. Each record-item must reference a data item in the same subschema record type.
  2. If record-item is a group item, its subordinate group and elementary items cannot be referenced in the same GET statement.

General Rules

  1. The GET statement references the current record of the run unit.
  2. If you use the record-name option, or if you do not specify either the record-item or the record-name option, the DBCS makes a copy of the entire current record of the run unit available to the program in the user work area.
  3. If you use the record-item option, only those items in the current record of the run unit are made available to the program in the user work area.
  4. Any change made to the user work area does not affect the record in the database. You must execute a MODIFY and a COMMIT statement to make permanent changes to the database.
  5. Use record-name to check that the record type of the current record is identical to the record type specified by record-name.
  6. The GET statement has no effect on currency indicators.
  7. If a database exception condition occurs during the execution of a GET 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

GET 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 for record-name is not identical to the current record type, or a record-item is not a group or elementary item in the current record.
DBM$_CONVERR A data conversion error occurred in the GET 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 GET operation.
DBM$_TRUNCATION A data truncation error occurred in the GET operation.
DBM$_UNDERFLOW A data underflow error occurred in the GET operation.

Additional References

Examples

  1. This example gets the current record of the run unit: 


    GET.

  2. This example gets a PART record only if it is the current record of the run unit: 


    GET PART.

  3. This example gets these items only if they are part of the current record of the run unit: 


    GET PART_ID, PART_DESC.

KEEP

Function

The KEEP statement inserts a database key value from a currency indicator or keeplist into a keeplist.

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.

destination-keeplist

names a keeplist in the Subschema Section to receive the database key value.

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. If database-key-id references a database key value in either a currency indicator or a keeplist, the DBCS:
  2. If the program does not specify database-key-id, the DBCS inserts the database key value of the current record of the run unit as the last entry of destination-keeplist.
  3. The KEEP statement has no effect on currency indicators.
  4. If a database exception condition occurs during the execution of a KEEP 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

KEEP statement execution can result in the database exception conditions associated with the evaluation of the database key identifier.

Additional References

Examples

  1. Currency indicator access
  2. Keeplist access

MODIFY

Function

The MODIFY statement changes the contents of specified data items in a database record.

record-name

names a subschema record type.

record-item

is a group or elementary data item in a subschema record type. Record-item can be qualified.

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. Each record-item must reference a data item in the same subschema record type.
  2. If record-item is a group item, its subordinate group and elementary data items cannot be referenced as a record-item in the same MODIFY statement.
  3. Use record-name to check that the current record of the run unit is a record type identical to the record-name record type.

General Rules

  1. Changes are made to a database record by:
  2. The DBCS changes the contents of the entire database record:
  3. Using record-item limits the changes to the database record to only those items you specify.
  4. If you modify any data item that is the sort key for that record's position in a sorted set, the DBCS automatically repositions the record in that set in accordance with the set-ordering criteria of the set type.
    If the value of the sort key is identical to another record of this type, and if duplicates are not allowed for this sorted set, the DBCS does not perform the MODIFY operation, and a database exception condition occurs.
  5. Currency indicator update rules for record insertion and removal are as follows:
  6. The current record of the run unit must be in a realm in ready update mode and all records required by the DBCS to execute the MODIFY statement must be in realms in one of the appropriate READY modes.
  7. The contents of the user work area (UWA) do not change after the successful or unsuccessful execution of a MODIFY statement.
  8. If the execution of a MODIFY statement results in an exception condition, the record is not changed.
  9. If a database exception condition occurs during the execution of a MODIFY 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

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

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.

    Previous Next Contents Index