The FIND/OBTAIN WITHIN SET USING SORT KEY statement locates a member record in a sorted set. Sorted sets are ordered in ascending or descending sequence based on the value of a sort-control element in each member record. The search begins with either the current of set or the owner of the current of set and always proceeds through the set in the next direction.
Before issuing this statement, you must initialize the sort-control element in program variable storage. The record occurrence selected will have a key value equal to the value of the sort-control element. If more than one record occurrence contains a sort key equal to the key value in variable storage, the first such record will be selected.
You can use FIND/OBTAIN WITHIN SET USING SORT KEY to access both sorted chained sets and sorted index sets.
Note: In a batch environment, sorted sets can be processed more efficiently by sorting the input transactions.
Currency
Following successful execution of a FIND/OBTAIN WITHIN SET USING SORT KEY statement, the accessed record becomes current of run unit, its record type, its area, and all sets in which it currently participates as member or owner. If a member record with the requested sort-key value is not found, the current of set is nullified but the next of set and prior of set are maintained. The next of set is the member record with the next higher sort-key value (or next lower for descending sets) than the requested value; the prior of set is the member record with the next lower value (or higher for descending sets) than requested. Because these currencies are maintained, the program can walk the set to do a generic search on the sort-key value.
►►─┬─ FIND ───┬─┬────────────────────────┬─ RECORD (record-name) ─────────────► └─ OBTAIN ─┘ └─ KEEP ─┬─────────────┬─┘ └─ EXCLUSIVE ─┘ ►── SET (set-name) ─┬───────────┬─ USING (sort-field-name); ─────────────────►◄ └─ CURRENT ─┘
Specifies the record type and sorted set name. The search begins with the owner of the current record of the specified set.
Places a shared (KEEP) or exclusive (KEEP EXCLUSIVE) lock on the accessed record.
Indicates that the search begins with the currencies already established for the specified set.
If the key value for the record that is current of set is higher than the key value of the requested record (assuming ascending set order), a NOT FOUND condition results. In a descending set order, if the key value for the record that is current of set is lower than the key value of the requested record, a NOT FOUND condition results.
Specifies the sort-control element to be used in searching the sorted set. Sort-field-name is either the name of the sort-control element in the record or the symbolic name of a field in variable storage that contains the value of the sort-control element.
Note: The value coded for sort-field-name can only specify a single field name. If the sort key is comprised of multiple fields, the value coded should represent a group-level field. The elementary elements must be in the same sequence as the corresponding fields within the set's schema definition. The data formats for the elementary fields must also match the formats of the corresponding fields in the database record's definition.
The following example illustrates the use of a FIND/OBTAIN WITHIN SET USING SORT KEY statement. Assume that the SKILL_NAME_NDX set is ordered in ascending sequence based on the value stored in SKILL_NAME_0455 in each SKILL record occurrence. Retrieval of a SKILL record with a skill name equal to PL/I is accomplished by coding the following statements:
SKILL_NAME_0455 = 'PL/I';
FIND RECORD (SKILL) SET (SKILL_NAME_NDX)
USING (SKILL_NAME_0455);
Upon completion of the FIND/OBTAIN WITHIN SET USING SORT KEY function, the ERROR_STATUS field in the IDMS DB communications block indicates the outcome of the operation:
The request has been serviced successfully.
A retrieval-only run unit has detected an inconsistency in an index that should cause an 1143 abend, but optional APAR bit 216 has been turned on.
The area in which the named record participates has not been readied.
Currency has not been established for the named set.
Either the named record or set is not in the subschema or the named record is not a member of the named set. The program has probably invoked the wrong subschema.
The subschema specifies an access restriction that prohibits retrieval of the named record.
The record cannot be found.
The retrieval statement format conflicts with the record's location mode.
A record occurrence has been encountered whose record type is not a member or owner of the set as it is defined in the subschema.
A database file will not open properly.
If the KEEP parameter is specified in a FIND/OBTAIN statement, and an error occurs during KEEP processing, the major code 06 is returned.
Note: For more information, see KEEP CURRENT, later in this chapter. The major code 03 is returned if an error occurs during FIND/OBTAIN processing.
|
Copyright © 2014 CA.
All rights reserved.
|
|