The @FIND/@OBTAIN USING SORT KEY statement accesses 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 issuing this statement, you must initialize the sort-control element in program variable storage. The selected record occurrence 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.
Currency
Before execution of an @FIND/@OBTAIN USING SORT KEY statement you have to establish currency for the specified set.
Following successful execution of an @FIND/@OBTAIN USING SORT KEY statement, the accessed record becomes current of run unit, its area, its record type, and all sets in which it currently participates as owner or member. 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 ───┬────┬───────────┬─ ,REC=record-name ──────────────────────────► └─ @OBTAIN ─┘ └─ CURRENT ─┘ ►─── ,SET=set-name ──────────────────────────────────────────────────────────► ►─── USING=sort-field-name ──────────────────────────────────────────────────► ►─┬───────────────────────────┬──────────────────────────────────────────────►◄ └─ ,KEEP= ─┬─ SHARED ──────┬┘ └─ EXCLUSIVE ───┘
Parameters
Accesses the named record in a sorted set. The search begins with the owner of the current record of the specified set. Record-name must be a record that is defined in the subschema and that participates in the specified set.
Current 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 specified record (assuming ascending set order), an error condition results.
Specifies the sort-control element to be used in searching the sorted set.
The name of the sort-control element in the record or the name of a field in program 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 composed of multiple fields, the value coded must point to an area of contiguous storage that contains the values of the various key components. These field values must be in the same sequence as the corresponding fields within the set's schema definition and their data formats must match the formats of the fields within the database record's definition.
Places a shared or exclusive lock on the accessed record.
Places a shared lock on the specified record.
Places an exclusive lock on the specified record.
Example
The following example illustrates the use of an @FIND/@OBTAIN USING SORT KEY statement. Assume that the DEPT-EMPLOYEE set is ordered in ascending sequence, based on the value stored in EMPNAME in each EMPLOYEE record occurrence. The @FIND statement assumes that the user has previously selected an occurrence of a DEPARTMENT record to establish the set currency. Retrieval of an EMPLOYEE record with a name (last name, first name) equal to IANDOLI, LUIGI is accomplished by the following statements:
MVC EMPNAME,=CL25'IANDOLI, LUIGI' @FIND REC='EMPLOYEE',SET='DEPT-EMPLOYEE',USING=EMPNAME
Status codes
After completion of the @FIND/@OBTAIN USING SORT KEY function, the ERRSTAT field in the IDMS communications block indicates the outcome of the operation. The following is a list of the acceptable status codes for this function and their corresponding meaning:
The request has been serviced successfully.
The area in which the named record participates has not been readied.
Currency has not been established for the named set.
The named record or the named 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 record cannot be found because of a broken chain in the database.
A database file will not open properly.
When the KEEP parameter is specified as part of an @FIND/@OBTAIN statement, a major code of 06 will be returned if an error occurs during the KEEP processing (see @KEEP in this chapter). The major code of 03 states that an error has occurred in the @FIND/@OBTAIN processing.
|
Copyright © 2014 CA.
All rights reserved.
|
|