@FIND/@OBTAIN WITHIN SET/AREA

Data Manipulation Language Statements › @FIND/@OBTAIN Statements—accesses database records › @FIND/@OBTAIN WITHIN SET/AREA

@FIND/@OBTAIN WITHIN SET/AREA

The @FIND/@OBTAIN WITHIN SET/AREA statement accesses records logically based on set relationships or physically based on database location. The formats of this statement allow you serial access to each record in a set or area, or selection of specific occurrences of a given record type in a set or area.

Set currency

The following rules apply to currency and the selection of member records in a set:

The set occurrence used as the basis for the operation is determined by the current record of the specified set. Set currency must be established before attempting to access records in a set.
The next or prior record in a set is the subsequent or previous record, respectively, relative to the current record of the named set in the logical order of the set. The prior record in a set can be retrieved only if the set has been assigned prior pointers.
The first or last record in a set is the first or last member occurrence in terms of the logical order of the set. The record selected is the same as would be selected if the current of set were the owner record and the next or prior record had been requested. The last record in a set can be retrieved only if the set has prior pointers.
The nth occurrence of a record in a set can be retrieved by specifying a sequence number that identifies the position of the record in the set. CA IDMS/DB begins its search with the owner of the current of set for the specified set and continues until it locates the nth record or encounters an end-of-set condition. If the specified sequence number is negative, the search proceeds in the prior direction in the set. Note, however, that prior pointers are required to exercise this option.
When an end-of-set condition occurs, the owner record occurrence of the set becomes the current record of run unit, current of its record type, current of its area, and current of only the set involved in this operation. Currency of other sets in which the specified record participates as owner or member remains unaffected.

Note: Note 1If @OBTAIN has been specified, the contents of the owner record are not moved to program variable storage (@OBTAIN under these circumstances is treated as an @FIND).

Note: Note 2(Native VSAM users): When an end-of-set condition occurs, all currencies remain the same.

Area currency

The following rules apply to currency and the selection of records in an area:

The first record occurrence in an area is the one with the lowest db-key; the last record is the one with the highest db-key.
The next record in an area is the one with the next higher db-key relative to the current record of the named area; the prior record is the one with the next lower db-key relative to the current of area.
The first, last, or nth occurrence of a record in an area must be retrieved to establish correct starting position before next or prior records are requested.

Following successful execution of an @FIND/@OBTAIN WITHIN SET/AREA statement, the accessed record becomes the current record of run unit, its area, its record type, and all sets in which it currently participates as member or owner.

Syntax

►►─┬─ @FIND ───┬─┬─ NEXT ──┬──────────────────────────────────────────────────►
   └─ @OBTAIN ─┘ ├─ PRIOR ─┤
                 ├─ FIRST ─┤
                 ├─ LAST ──┤
                 └─ NTH ───┘

 ►─┬─ ,SET=set-name ───┬──────────────────────────────────────────────────────►
   └─ ,AREA=area-name ─┘

 ►─┬────────────────────┬─────────────────────────────────────────────────────►
   └─ ,REC=record-name ─┘

 ►─┬───────────────────┬──────────────────────────────────────────────────────►
   └─ ,OCCUR=sequence ─┘

 ►─┬───────────────────────────┬──────────────────────────────────────────────►◄
   └─ ,KEEP= ─┬─ SHARED ──────┬┘
              └─ EXCLUSIVE ───┘

Parameters

NEXT/PRIOR/FIRST/LAST/NTH

Accesses a record based on its location in a set or area.

NEXT

Accesses the next record in the specified set or area relative to the current record of the set or area.

PRIOR

Accesses the prior record in the specified set or area relative to the current record of the set or area. The specified set must have prior pointers.

FIRST

Accesses the first record in the specified set or area.

LAST

Accesses the last record in the specified set or area. The specified set must have prior pointers.

NTH

Accesses the nth record in the specified set or area. NTH requires the use of the OCCUR parameter (see below) to specify which record is to be accessed.

Note: Native VSAM users—FIRST, LAST, and NTH options are not allowed for a native VSAM KSDS with spanned records.

SET=set-name/AREA=area-name

Specifies the set or area to be searched.

SET=set-name

Specifies the name of the set that contains the record to be accessed. Set-name must identify an set included in the subschema.

AREA=area-name

Specifies the name of the area that contains the record to be accessed. Area-name must identify an area included in the subschema.

REC=

Specifies that in 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 in the specified area.

OCCUR=

Identifies the position of the record in the set (that is, the numeric occurrence that is associated with the keyword NTH).

sequence

Must specify a positive or negative number that is stored in a numerical field used by CA IDMS/DB in searching for the nth record occurrence. If sequence specifies a negative number, the specified set must have prior pointers.

KEEP=

Places a shared or exclusive lock on the accessed record.

SHARED

Places a shared lock on the specified record.

EXCLUSIVE

Places an exclusive lock on the specified record.

Example

The following example 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. Note that when EMPLOYEE 106 is retrieved, the end of the set is reached and the next OBTAIN statement positions the program on 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. In this example, the user wishes to sweep the EMP-DEMO-REGION area, retrieving sequentially each EMPLOYEE record and all records in the associated EMP-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 DBKEY statement is used to reestablish the proper position before retrieving EMPLOYEE 48. Note that if @FIND DBKEY for the employee record is not specified, an attempt to retrieve the next EMPLOYEE record in the area would return EMPLOYEE 23.

Status codes

After completion of the @FIND/@OBTAIN WITHIN SET/AREA 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:

0000: This request has been serviced successfully.
0301: The area in which the named record participates has not been readied.
0304: A sequence number of zero or a variable field that contains a value of zero was specified for the named record.
0306: Currency has not been established for the named record, set, or area.
0307: The end of the set or area has been reached, or the set is empty.
0308: Either the named record or the named 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, or has misspelled the record or set name.
0310: The subschema specifies an access restriction that prohibits retrieval of the named record.
0323: The area name specified has not been included in the subschema invoked, the record name specified has not been defined in the named area, or the area name has been misspelled.
0326: The record cannot be found.
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.
0361: The record cannot be stored because of broken chains in the database.
0370: A database file will not open properly.

When the KEEP parameter is specified as part of the @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.