The FIND/OBTAIN WITHIN SET/AREA statement locates records either logically, based on set relationships, or physically, based on database location. The formats of this statement allow you either to access serially each record in a set or area or to select specific occurrences of a given record type within the set or area.
Selecting from a Set
The following rules apply to the selection of member records within a set:
Note: If OBTAIN has been specified, the contents of the owner record are not moved to program variable storage (that is, OBTAIN under these circumstances is treated as a FIND).
Native VSAM users: When an end-of-set condition occurs, all currencies remain unchanged.
Selecting from an Area
The following rules apply to the selection of records within an area:
Currency
Following successful execution of a FIND/OBTAIN WITHIN SET/AREA statement, the accessed record becomes the current record of run unit, its record type, its area, and all sets in which it currently participates as member or owner.
When an end-of-set condition occurs selecting records within a set, the owner record occurrence of the set becomes the current record of run unit, its record type, its area, and only the set involved in this operation. Currency of other sets in which the specified record participates as owner or member remains unaffected.
►►─┬─ FIND ───┬─┬────────────────────────┬─┬─ NEXT ──────────────────┬────────► └─ OBTAIN ─┘ └─ KEEP ─┬─────────────┬─┘ ├─ FIRST ─────────────────┤ └─ EXCLUSIVE ─┘ ├─ LAST ──────────────────┤ ├─ PRIOR ─────────────────┤ └─ NTH (sequence-number) ─┘ ►─┬────────────────────────┬─┬─ SET (set-name) ───┬─ ; ──────────────────────►◄ └─ RECORD (record-name) ─┘ └─ AREA (area-name) ─┘
Locates a record based on its location within a set or area. Set-name/area-name specifies the set or area that will be searched and must identify a set or area included in the subschema.
Places a shared (KEEP) or exclusive (KEEP EXCLUSIVE) lock on the accessed record.
Accesses the next record in the specified set or area relative to the current record.
Accesses the first record in the specified set or area.
Accesses the last record in the specified set or area. The specified set must have prior pointers.
Accesses the prior record in the specified set or area relative to the current record. The specified set must have prior pointers.
Accesses the nth record in the specified set or area. Sequence-number must either be a positive or negative number or any numeric field that contains a nonzero value used by the DBMS in searching for the nth record occurrence. If sequence is negative, the specified set must have prior pointers.
Native VSAM users: FIRST, LAST, and NTH (sequence) options are not valid for a native VSAM KSDS with spanned records.
Specifies that within a set or area, only occurrences of the named record type will be accessed. Record-name must be defined as a member of the specified set or contained within the specified area.
The following figure illustrates the retrieval of records in an occurrence of the DEPT_EMPLOYEE set.
The FIND CALC statement establishes currency in the DEPT_EMPLOYEE set. Member EMPLOYEE records are then retrieved by a series of OBTAIN WITHIN SET statements. EMPLOYEE 106 is the last record in the set and the next OBTAIN statement returns an end-of-set condition, positioning run-unit currency at the owner of the set, DEPARTMENT 2000.
The following figure illustrates special considerations relating to the retrieval of records in an area that contains multiple record types.
A sweep of the EMP_DEMO_REGION is performed, retrieving sequentially each EMPLOYEE record and all records in the associated EMPLOYEE_EXPERTISE set. The first command retrieves EMPLOYEE 119. Subsequent OBTAIN WITHIN SET statements retrieve the associated EXPERTISE records and establish currency on EXPERTISE 03. The FIND CURRENT statement is used to reestablish the proper position before retrieving EMPLOYEE 48. If FIND CURRENT EMPLOYEE is not specified, an attempt to retrieve the next EMPLOYEE record in the area would return EMPLOYEE 23.
Upon completion of the FIND/OBTAIN WITHIN SET/AREA 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.
Either a sequence number of 0 or a variable field that contains a value of 0 was specified for the named record.
Currency has not been established for the named record, set, or area.
Either the end of the set or the area was reached or the set is empty.
Either the named record or set is not in the subschema or the named record is not defined as 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.
Either the area name specified has not been included in the subschema invoked or the record name specified has not been defined within the named area.
The record cannot be found.
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. 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.
|
|