Map Commands › Pageable Maps › GET DETAIL

GET DETAIL

Purpose

Retrieves a modified detail occurrence of a pageable map.

A GET DETAIL command can retrieve all the fields of a modified detail occurrence or only those fields whose MDTs are turned on.

Syntax

►►── GET DETail─┬───────────────────────────────────────────────────────────┬─►
                ├┬─ NEXt ◄ ─┬─┬────────────────────────────────────────────┬┤
                │└─ FIRst  ─┘ └─ RETurn KEY into data-field-name-variable ─┘│
                └─ KEY ────┬──────┬──── key-number ─────────────────────────┘
                           ├─ IS ─┤
                           └─ =  ─┘

 ►────────┬─────────────────────────┬─── . ───────────────────────────────────►◄
          ├─ ALL ◄ ────┬── FIElds ──┘
          └─ MODified ─┘

Parameters

NEXt

Retrieves the first modified detail occurrence that follows the detail occurrence referenced by the preceding pageable map command.

The preceding pageable map command must follow the most recent pseudo-converse.

FIRst

Retrieves the first modified detail occurrence of the pageable map.

Note that the GET DETAIL FIRST command can be used repeatedly to retrieve all the modified detail occurrences of a pageable map. The first GET DETAIL FIRST command retrieves the first modified detail occurrence. Once retrieved, the occurrence is no longer considered as modified, and the second modified detail occurrence becomes the first modified detail occurrence. This modified detail occurrence can be retrieved by a subsequent GET DETAIL FIRST command, and so forth.

An end-of-data condition results if no pageable map command precedes the GET DETAIL command, if the preceding pageable map command resulted in an end-of-data or detail-not-found (see the KEY IS parameter below) condition or if the GET DETAIL command cannot find a modified detail occurrence before reaching the end of the set of detail occurrences.

RETurn KEY into data-field-name-variable

Specifies the numeric variable field into which the runtime system moves the binary fullword value (if any) associated with the detail occurrence being retrieved. A value is associated with a detail occurrence by specifying the KEY IS parameter in a PUT DETAIL command.

If no value is associated with the detail occurrence, data-field-name-variable is set to zero. Data-field-name-variable does not have to be a binary fullword.

KEY is key-number

Specifies the modified detail occurrence to be retrieved based on the numeric key value associated with the detail occurrence. A key value is associated with a detail occurrence by specifying the KEY IS parameter in a PUT DETAIL command.

Key-number is either the numeric variable data field or the numeric literal itself.

The runtime system finds the first detail occurrence associated with the key value specified by key-number. If the detail occurrence is a modified detail occurrence, it is retrieved. If the occurrence is not a modified detail occurrence, or if no detail occurrence with the specified key value is found, a detail-not-found condition is set.

ALL

Specifies all the fields of the modified detail occurrence to be retrieved.

ALL is the default when neither ALL or MODIFIED is specified.

MODified

Specifies only those fields whose MDTs are turned on to be retrieved.

If MODIFIED is specified, variable data fields that map to nonretrieved fields retain their previous values.

Usage

Considerations:

• The GET DETAIL command causes the runtime system to move the following:
  • The retrieved fields into the variable data fields to which they map
  • The page number of the retrieved detail occurrence into the $PAGE system-supplied data field
  • The numeric key value (if any) associated with the occurrence into a specified field (optional)
• A GET DETAIL command can retrieve only a modified detail occurrence. A detail occurrence is considered modified if it has the following characteristics:
  • Contains one or more map fields whose modified data tags (MDTs) are turned on at the time of the most recent pseudo-converse.
  • Has yet to be retrieved. Once a modified detail occurrence has been retrieved, it is no longer considered modified.
• A detail occurrence that is not a modified detail occurrence cannot be retrieved by dialog process code.