Database Access Commands › Navigational DML › FIND/OBTAIN WITHIN SET/AREA

FIND/OBTAIN WITHIN SET/AREA

Purpose

Accesses records logically, based on set relationships, or physically, based on database location.

Records can be accessed serially in a specified set or area, or accessed by selected specific occurrences of a given record type within the set or area.

Syntax

►►───┬─ FIND ───┬───┬──────────────────────────┬──────────────────────────────►
     └─ OBTAIN ─┘   └─ KEEP ───┬─────────────┬─┘
                               └─ EXCLUSIVE ─┘

 ►───┬─ NEXT ────────────┬──┬───────────────┬── WITHIN ─┬─ set-name ──┬───────►
     ├─ PRIOR ───────────┤  └─ record-name ─┘           └─ area-name ─┘
     ├─ FIRST ───────────┤
     ├─ LAST ────────────┤
     └─ sequence-number ─┘

 ►───┬────────────────────┬── . ──────────────────────────────────────────────►◄
     └─ error-expression ─┘

Parameters

KEEP

Places a shared lock on the object record.

EXCLUSIVE

Places an exclusive lock on the object record.

NEXT

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

PRIOR

Specifies the prior record in the specified set or area relative to the current record.

FIRST

Specifies the first record in the set or area.

LAST

Specifies the last record in the set or area.

sequence-number

Either the name of a variable data field that contains the sequence number of a record in a set or area or the sequence number itself expressed as a positive or negative integer. The actual sequence number, expressed as a positive or negative integer.

If sequence-number is negative, the specified set must have prior pointers.

record-name

Specifies only occurrences of the named record type.

Record-name must be defined as a member of the object set or be contained in the object area.

Record-name must be specified if set-name or area-name is specified, unless the record or one of the record's elements is named explicitly somewhere in the dialog's process code, or if the record is associated with the dialog as a map record.

WITHIN

Introduces the named set or area to be searched.

set-name

Specifies the set to be searched.

area-name

Specifies the area to be searched.

The named set or area must be known to the dialog's subschema.

error-expression

Specifies the status codes that are returned to the dialog.

Usage

Considerations

If autostatus is not in use, a dialog's error-status field indicates the outcome of a FIND/OBTAIN WITHIN SET/AREA command:

Further Considerations

• After successful execution of a FIND/OBTAIN WITHIN SET/AREA command, the accessed record is current of:
  • The run unit
  • Its record type
  • Its area
  • All sets in which it currently participates as member or owner
• When accessing records within a set, the following considerations apply:
  • The current record of the specified set determines the set occurrence to be accessed. Set currency must be established before a FIND/OBTAIN WITHIN SET command is executed.
  • The next or prior record within a set is the subsequent or previous record, 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 prior pointers.
  • The first or last record within a set is the first or last member occurrence, respectively, in terms of the logical order of the set. The record accessed is the same record accessed when the current of set is the owner record and the next or prior record is requested. The last record in a set can be retrieved only if the set has prior pointers.
  • The nth occurrence of a record within a set can be accessed by specifying a sequence number that identifies the position of the record in the set. The search begins with the owner of the current of set for the specified set and continues until the nth record is located or an end-of-set condition is encountered. If the specified sequence number is negative, the search proceeds in the prior direction in the set. A negative number can be specified only if the set has prior pointers.
  • When an end-of-set condition occurs, the owner record occurrence of the set becomes current of:
    • The run unit
    • Its record type
    • Its area

    The owner record also becomes current of the set named in the FIND/OBTAIN command. Currency of other sets in which the record participates as member or owner is not changed.

  • If OBTAIN is specified and an end-of-set condition occurs, the contents of the owner record are not moved to the dialog's record buffer (that is, OBTAIN is treated as FIND).
• When accessing records within an area, the following considerations apply:
  • The first record occurrence within an area is the one with the lowest database key. The last record occurrence is the one with the highest database key.
  • The next record within an area is the one with the next higher database key relative to the current record of the object area. The prior record is the one with the next lower database key relative to the current of area.
  • The first or last record or the nth occurrence of a record in an area must be accessed to establish correct starting position before next or prior records are requested.
• When using a native VSAM set, the following considerations apply:
  • When an end-of-set or end-of-area condition (0307) occurs for a native VSAM set, all currencies remain unchanged.
  • The FIRST, LAST, and sequence-number WITHIN area-name options cannot be used to access spanned data records in a native VSAM data set.

Example

The statements in the following example illustrate the use of the FIND/OBTAIN WITHIN SET command to retrieve records in an occurrence of the ORDER-ITEM set:

MOVE 'BB' TO ORD-NUM.
FIND CALC ORDOR.
OBTAIN FIRST ITEM WITHIN ORDER-ITEM.
OBTAIN NEXT WITHIN ORDER-ITEM.
OBTAIN 5 WITHIN ORDER-ITEM.
OBTAIN NEXT WITHIN ORDER-ITEM.

If the fifth ITEM record is the last record in the ORDER-ITEM set, the fourth OBTAIN statement finds the owner ORDOR record.

More information:

Error Handling