FIND/OBTAIN WITHIN SET USING SORT KEY

Database Access Commands › Navigational DML › FIND/OBTAIN WITHIN SET USING SORT KEY

FIND/OBTAIN WITHIN SET USING SORT KEY

Purpose

Accesses a member record in a sorted set.

Sets are sorted in ascending or descending order based on the value of a sort-control element in each member record. The search begins with the current of set or the owner of the current of set and always proceeds through the set in the next direction.

Syntax

►►──┬─ FIND ───┬───┬──────────────────────────┬── record-name ────────────────►
    └─ OBTAIN ─┘   └─ KEEP ───┬─────────────┬─┘
                              └─ EXCLUSIVE ─┘

 ►──── WITHIN set-name ──────┬───────────┬────────────────────────────────────►
                             └─ CURRENT ─┘

 ►──── USING sort-field-name-variable ──────┬────────────────────┬─── . ──────►◄
                                            └─ error-expression ─┘

Parameters

KEEP

Places a shared lock on the object record.

EXCLUSIVE

Places an exclusive lock on the object record.

record-name

Specifies the record to be accessed.

Record-name must be known to the dialog's subschema and must participate in the set specified by set-name.

WITHIN set-name

Specifies the set in which the object record participates.

Set-name must be known to the dialog's subschema.

CURRENT

Specifies that the search begins with the current record of the named set.

If the set is sorted in ascending order and the sort key value of the record that is current of set is higher than the sort key value specified by sort-field-name-variable, an error condition results. If the set is sorted in descending order and the sort key value of the record that is current of set is lower than the sort key value specified by sort-field-name-variable, an error condition results.

If CURRENT is not specified, the search begins with the owner of the current record of the named set.

USING sort-field-name-variable

Specifies the sort-control element to be used in searching the sorted set.

Sort-field-name-variable is either the name of the sort-control element in the record specified by record-name or the name of a variable data field that contains the sort key value.

Note: The value specified for the sort-field-name variable may only be the name of a single field. If the sort key is comprised of multiple individual fields, the value specified must be that of a group-level element. If the name of a variable data field is coded and represents a group-level element, the associated elementary elements must be in the same sequence as the corresponding fields within the set's schema definition. The data formats for the elementary elements must also match the formats of the corresponding fields within the database record.

error-expression

Specifies the status codes that are returned to the dialog.

Usage

Considerations

If autostatus is not in use, a dialog's error-status field indicates the outcome of a FIND/OBTAIN WITHIN SET USING SORT KEY command:

Status code	Meaning
0000	The request was executed successfully
0306	Currency was not established for the named set
0308	The named record or set is not in the dialog's subschema
0310	The dialog's subschema specifies an access restriction that prohibits retrieval of the object record
0326	The specified record cannot be found
0329	A run-unit deadlock condition occurred. DBMS aborted and rolled back the run unit. All resources associated with the task are released.
0331	No sort-control element is defined for the object record in the dialog's subschema

Further Considerations

Before issuing a FIND/OBTAIN WITHIN SET USING SORT KEY command, the application developer must place the sort key value of the object record in the applicable field of the dialog's record buffer. If more than one record occurrence has a sort key value equal to the value in the record buffer, the first such record is accessed.
After successful execution of a FIND/OBTAIN WITHIN SET USING SORT KEY command, the accessed record is current of:
- The run unit
- Its record type
- Its area
- All sets in which it currently participates as member or owner
If the object record is not found, next of set and prior of set are maintained, but current of set is nullified.
Next of set points to the next higher (for ascending sets) or next lower (for descending sets) sort key value.

Example

The statements in the following example establish a current PRODUCT-ITEM set and then retrieve an ITEM record based on the lot number:

MOVE 'P8' TO PROD-NUMBER.
FIND CALC PRODUCT.
MOVE 1230427 TO ITEM-LOT-NUMBER.
FIND ITEM WITHIN PRODUCT-ITEM USING ITEM-LOT-NUMBER.

More information:

Error Handling