FIND/OBTAIN WITHIN SET USING SORT KEY (COBOL)

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 the current of set or the owner of the current of set and always proceeds through the set in the next direction.
idmscu
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 the current of set or the owner of the current of set and always proceeds through the set in the next direction.
Before you issue this statement, initialize the sort control element in program variable storage. The selected record occurrence will have a key value that is 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 one is selected.
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.
Syntax
►►─┬─ FIND ───┬─┬────────────────────────┬─ 
record-name
 WITHIN 
set-name
 ──────►    └─ OBTAIN ─┘ └─ KEEP ─┬─────────────┬─┘                          └─ EXCLUSIVE ─┘  ►─┬───────────┬─ USING 
sort-key
 ── . ────────────────────────────────────────►◄    └─ CURRENT ─┘                  └─;─┘
Parameters
  • KEEP
    Places a shared lock on the accessed record.
  • EXCLUSIVE
    Places an exclusive lock on the accessed record.
  • record-name
    Specifies the record type to locate.
  • WITHIN 
    set-name
    Specifies the set to search. The set must be included in the subschema.
    Unless you specify CURRENT, the search begins with the 
    owner
     of the specified set.
  • CURRENT
    Begins the search with the currencies that are 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 nonzero status condition results. In a descending set order, when the key value for the record that is current of set is lower than the key value of the requested record, a nonzero status condition results.
  • USING 
    sort-key
    Specifies the sort control element to use in searching the sorted set. Specify the symbolic name of a field that is defined in working storage and that contains the value of the sort control element. 
    • Due to the architecture of the client interface for CA IDMS, 256 bytes are moved regardless of the actual length of the working storage sort key. Account for this additional storage to avoid potential program exceptions that can occur. While these exceptions are rare, they are more probable when the sort key is defined in a FILE or LINKAGE SECTION definition. To avoid this problem, define the sort key in the WORKING STORAGE SECTION of the program, padded to a full 256 bytes; and moved in and out of the FILE or LINKAGE SECTION fields.
    • The value coded for 
      sort-key
       can specify only a single field name. If the sort key has of multiple elementary fields, the value that is coded should be a group-level name. The elementary fields that make up the group element must be in the same sequence as the corresponding fields in the schema definition for the database set. The data formats for the individual elementary fields must also match the formats of the corresponding fields within the database record.
    • A period or semicolon is required to terminate the statement unless an ON clause has been coded.
      Here is an example of OBTAIN RECA WITHIN RECA-SET USING RECA-KEY. The sort key of the record would be defined as follows in the WORKING-STORAGE SECTION:
      01 RECA-KEY. 02 RECA-FIELD1 PIC X(10). 02 RECA-FIELD2 PIC X(10).
      The definition should be changed to:
      01 RECA-KEY. 02 RECA-FIELD1 PIC X(10). 02 RECA-FIELD2 PIC X(10). 02 FILLER PIC X(236).
Example
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. The following statements retrieve a SKILL record with a skill name equal to PL/I:
MOVE 'PL/I' TO SKILL-NAME-0455. FIND SKILL WITHIN SKILL-NAME-NDX           USING SKILL-NAME-0455.
Status Codes
After completion of the FIND/OBTAIN WITHIN SET USING SORT KEY function, the ERROR-STATUS field in the IDMS communications block indicates the outcome:
Status code
Meaning
0000
The request has been serviced successfully.
0301
The area in which the named record participates has not been readied.
0303
Invalid currency for a record to be retrieved on a FIND. This code occurs only when a run unit shares a transaction with other database sessions. The 03 minor status is returned when the run unit tries to find a record using a currency that has been invalidated because of changes that were made by another database session that is sharing the same transaction.
0306
Currency has not been established for the named set.
0308
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.
0310
The subschema specifies an access restriction that prohibits retrieval of the named record.
0326
The record cannot be found.
0331
The retrieval statement format conflicts with the location mode of the record.
0360
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.
0370
A database file will not open properly.
If the FIND/OBTAIN statement includes an explicit KEEP, major code 03 is returned when an error occurs during FIND processing. Major code 06 is returned when the error occurs during KEEP processing.