PL/I DML Statements for Pageable Maps › MAP IN

MAP IN

The MAP IN statement requests a transfer of data to program storage. After completion of a MAP IN function, the ERROR-STATUS field of the IDMS-DC communications block indicates the outcome of a pageable-map operation:

Syntax

►►─── MAP IN (map-name) ──────────────────────────────────────────────────────►

 ►─┬──────────────────────────────────────────────────────────────────────────►─
   └─┬─ IO ─┬────────────────────────┬────────────────────────────────────────
     │      └─ INPUT DATA ─┬─ YES ─┬─┘
     │                     └─ NO ──┘
     └─ NOIO DATASTREAM FROM (mapped-data-location) ──────────────────────────

─►───────────────────────────────────────┬────────────────────────────────────►─
  ─────────────────────────────────────┬─┘
                                       │
                                       │
  ─┬─ TO (end-mapped-data-location) ─┬─┘
   └─ MAX LENGTH (data-length) ──────┘

 ►─┬────────────────────────────────────┬─────────────────────────────────────►◄
   ├─ detail-specification ─────────────┤
   └─ HEADER ─┬──────────────────────┬──┘
              ├─ PAGE (page-number) ─┤
              └─ MODIFIED ───────────┘
►►─┬──────────────────────────────────────────────────────────────────────────
   └─ DETAIL ┬  NEXT ◄ ─────────────────────────────────────────────────────┬─
             ├─ FIRST ─┬──────────────────────────┬─────────────────────────┤
             │         └─ RETURNKEY (data-field) ─┘                         │
             ├─ KEY (key-name) ─────────────────────────────────────────────┤
             ├─ SEQUENCE_NUMBER (sequence-field) ─┬────────────────────────┬┤
             │                                    └ RETURNKEY (data-field)─┘│
             └─ RETURNKEY (data-field) ─────────────────────────────────────┘

─►─────────────────────────────────────────┬──────────────────────────────────►◄
  ─┬──────────────────────┬─┬────────────┬─┘
   └─ PAGE (page-number) ─┘ └─ MODIFIED ─┘

DETAIL

Specifies that the MAP IN operation is to retrieve data from a modified detail occurrence (MDT set on). The contents of all data fields in the detail occurrence are retrieved unless MODIFIED is specified for the MAP IN DETAIL statement; MODIFIED retrieves only modified fields.

The retrieved detail occurrence is specified by one of the following clauses:

NEXT (default)

Retrieves the next sequential modified detail occurrence. An end-of-data condition is returned in either of the following cases:

• No detail occurrences have been modified
• All modified detail occurrences have been mapped in already

FIRST RETURNKEY IS data-field-name-v

Retrieves the first available modified detail occurrence.

RETURNKEY IS data-field-name-v optionally specifies the name of a variable field in which to store the 4-byte key (if any) associated with the retrieved detail occurrence. If no value is associated with the detail occurrence, data-field-name-v is set to 0. Data-field-name-v must be a 4-byte value, but does not have to be a binary fullword.

Note: A value is associated with a detail occurrence by using the KEY IS parameter in a MAP OUT DETAIL command for that occurrence.

An end-of-data condition results if all modified detail occurrences have been retrieved already.

KEY IS key-v

Specifies the modified detail occurrence to retrieve based on the value associated with the detail occurrence. (A value is associated with a detail occurrence by using the KEY IS parameter in the MAP OUT DETAIL command for that occurrence.) Key-v is the name of a 4-byte field.

A detail-not-found condition is returned in either of the following cases:

• The specified occurrence is not a modified detail occurrence
• No detail occurrence with the specified value is found

SEQUENCE_NUMBER IS data-field-name-v RETURNKEY IS data-field-name

Specifies the sequence number of the retrieved data occurrence. Detail occurrences are built by the application program, and are stored in the sequence in which they are created. Data-field-name is a binary fullword.

RETURNKEY IS data-field-name-v optionally specifies the name of a variable field to store the 4-byte value (if any) associated with the retrieved detail occurrence. If no value is associated with the detail occurrence, data-field-name-v is set to zero. Data-field-name-v must be a 4-byte value, but does not have to be a binary fullword.

A detail-not-found condition is returned in either of the following cases:

• The specified occurrence is not a modified detail occurrence.
• No detail occurrence with the specified value is found.
• RETURNKEY IS data-field-name performs the same operation as the NEXT clause (described previously) and specifies the name of a variable field to store the 4-byte value (if any) associated with the retrieved detail occurrence. (A value is associated with a detail occurrence by using the KEY IS parameter in a MAP OUT DETAIL command for that occurrence.) If no value is associated with the detail occurrence, data-field-name-v is set to 0. Data-field-name-v must be a 4-byte value, but does not have to be a binary fullword.

HEADER

Specifies that the MAP IN operation is to retrieve the contents of data fields in the header and footer areas. The contents of all data fields in the header and footer areas are retrieved unless MODIFIED is specified for the MAP IN HEADER statement; MODIFIED retrieves only modified fields.

MODIFIED

Specifies that only modified fields (MDT set on) are retrieved in the MAP IN operation.