HP OpenVMS Systems Documentation

HP COBOL
DBMS Database Programming Manual

FIND ALL KEEP-1 WHERE PARTDESC MATCHES '*DISK*'
FIND ALL KEEP-1 WHERE PARTDESC MATCHES '*F%%'

To match either the percent sign (%) or asterisk (*) in the pattern string, precede it with the caret (that is, to match percent sign (%) use caret and percent (^%), and to match asterisk (*) use caret and asterisk (^*)).

Collection Clause

The reserved word WITHIN with set-name or realm-name is called the collection clause. Use the collection clause to restrict a search to a specific collection of records in the database. If you do not use the collection clause, the DBCS searches through all the records in the database to which you have access.

The collection clause specifies the object collection. The following rules govern its use:

1. When you use WITHIN realm-name, realm records make up the object collection. The realm currency indicator is called the object currency indicator. The ordering of the object collection is unspecified.
2. When you use WITHIN set-name, the member records of the current set of the specified set type make up the object collection. The set type's currency indicator is called the object currency indicator. The ordering of the object collection is the ordering of the records in the current set of the specified set type.
3. If you use neither WITHIN realm-name nor WITHIN set-name, all records defined in the subschema make up the object collection. The object currency indicator defaults to the currency indicator for the run unit. The ordering of the object collection is unspecified.

Qualification Clause

Use record-name to restrict the search to records of a particular type. If you do not use record-name, the DBCS searches each record type in the subschema. You can further restrict the search to records with specific data item values. You do this by specifying the qualification clause. The qualification clause is either the reserved word USING followed by one or more rec-keys, or the reserved word WHERE followed by a Boolean expression. When USING is specified, the DBCS searches for only those database records whose key data items equal the corresponding data items in your user work area. When WHERE is specified, the DBCS searches for database records of the object record type whose item values cause the Boolean expression to evaluate to true.

The qualification clause optionally specifies the following additional rules for determining the object record type, the qualifying record, and the key data item:

1. If record-name is used, its record type is called the object record type.
2. Rec-key must be a data item defined in the subschema database record type, record-name.
3. If the key data item consists of one or more rec-keys, it describes additional criteria for selecting a record.
4. If the USING clause is used, a qualifying record is an occurrence of the object record whose corresponding variables in the user work area (UWA) equal the contents of the key data item.
5. If the WHERE clause is used, each occurrence of the object record type for which the bool-expression is true is called a qualifying record.
6. If you do not use the qualification clause, each occurrence of record-name, regardless of its contents, is called the qualifying record.
7. At least one operand in every relation condition of a WHERE Boolean expression must be an elementary item in the record being found or fetched.

Position Clause

The reserved words FIRST, LAST, NEXT, PRIOR, ANY, DUPLICATE, and RELATIVE make up the position clause. The position clause selects a specific qualifying record in the object collection. The position clause rules follow:

1. Int-exp refers to an embedded integer literal or to an integer variable. Int-exp can be either an integer or an arithmetic expression. Both result in a longword integer value. Int-exp cannot be zero.
2. ANY is equivalent to FIRST.
3. DUPLICATE is equivalent to NEXT.
4. Using the FIRST clause is equivalent to assigning +1 to int-exp. It refers to the first record in the object collection.
5. Using the LAST clause is equivalent to assigning --1 to int-exp. It refers to the last record in the object collection.
6. Using the NEXT clause is equivalent to using RELATIVE +1. It refers to the record in the object collection immediately after the current position.
7. Using the PRIOR clause is equivalent to using RELATIVE --1. It refers to the record in the object collection immediately before the current position.
8. If you use int-exp without the RELATIVE clause, the DBCS selects the record whose ordinal position in the object collection is equal to int-exp.
   • If int-exp is positive, the ordinal position is relative to the first record of the object collection.
   • If int-exp is negative, the ordinal position is relative to the last record of the object collection.
   • If int-exp is zero, a database exception condition occurs.
   • If int-exp is greater than the cardinality of the collection, a database exception condition occurs.
9. If you use the RELATIVE int-exp clause, the selected record is the one whose ordinal position in the object collection, relative to the position specified by the object currency indicator, is equal to int-exp.
   If the object currency indicator does not specify a position in the object collection, it is as though the RELATIVE clause did not appear.
   • If int-exp is positive, the search in the object collection proceeds in the next direction.
   • If int-exp is negative, the search in the object collection proceeds in the prior direction.
   • If int-exp is zero, a database exception condition occurs.
   • If the current position, modified by int-exp, is zero or is greater in magnitude than the cardinality of the collection, a database exception condition occurs.

All Formats

The record selection expression causes a database exception condition to occur if:

1. The selected set currency indicator does not identify a record (DB-CONDITION is set to DBM$_CSTYP_NULL).
2. Int-exp is zero (DB-CONDITION is set to DBM$_BADZERO).
3. The program attempts to find or fetch a record following the last record in the selected collection (DB-CONDITION is set to DBM$_END).
4. The program attempts to find or fetch a record preceding the first record in the selected collection (DB-CONDITION is set to DBM$_END).
5. A realm required to carry out the record selection is not in ready mode (DB-CONDITION is set to DBM$_NOTIP).
6. The bool-exp clause is used and any specified data item is not included in the Subschema Record Description entry for the object record type.

See Section 4.8.3, Exception Conditions and the USE Statement statement for an explanation of DBM$_symbolic constants.

4.7 Set Membership Options and DML Verbs

The HP COBOL data manipulation language (DML) verbs CONNECT, DISCONNECT, ERASE, MODIFY, RECONNECT, and STORE can affect a record's set membership. The effects of these verbs depend on the INSERTION and RETENTION clauses declared for the record's membership in each set in the schema.

The member's INSERTION clause determines whether the record is automatically inserted into a set when it is stored:

• If the INSERTION IS AUTOMATIC clause is used, the member is automatically inserted into the set.
• If the INSERTION IS MANUAL clause is used, the member must be manually inserted into the set with a CONNECT statement.

The member's RETENTION clause determines whether the record can be removed from a set with the verbs ERASE, DISCONNECT, and RECONNECT. If the RETENTION IS FIXED clause is used, you cannot remove the record from a set occurrence at all unless you erase the record at the same time. If the RETENTION IS MANDATORY clause is used, you cannot use DISCONNECT to remove the record from a set occurrence; you can use RECONNECT to move it from one occurrence of the set type to another. If the RETENTION IS OPTIONAL clause is used, you can use either DISCONNECT or RECONNECT to remove the record from a set occurrence.

The ERASE statement always removes the erased record from all sets of which it is a member. ERASE also affects sets owned by that record. If you use the ERASE ALL option, all members of sets owned by an erased record are erased in a recursive process. If you use ERASE without the ALL option, the effect on each set member depends on the member's RETENTION clause: FIXED members are erased; OPTIONAL members are not erased (but are removed from the set, since the set is about to vanish). If any members have a RETENTION MANDATORY clause, an exception occurs because they can exist in the database without being members of this set occurrence. However, the Database Control System does not know into which set occurrence the members should be inserted.

The MODIFY statement may reposition a record within the same set occurrence if its sort key for that set is one of the data items being modified.

See the Oracle CODASYL DBMS DML documentation that summarizes the effects of the various verbs on the record directly modified and on any members (ERASE only).