MAP OUT

PL/I DML Statements for Pageable Maps › MAP OUT

MAP OUT

The MAP OUT statement is used to create or modify detail occurrences for a pageable map or to request that a map page be transmitted to the terminal screen. After completion of a MAP OUT function, the ERROR-STATUS field of the CA IDMS/DC communications block indicates the outcome of a pageable-map operation using the following error messages:

Message	Description
4664	There is no current detail occurrence to be updated (MAP OUT DETAIL CURRENT only). No action is taken.
4668	The amount of storage defined for pageable maps at system generation is insufficient. No action is taken. This and subsequent MAP OUT DETAIL commands are ignored.
4672	No detail occurrence, footer, or header fields exist to be mapped out by a MAPOUT RESUME command.
4676	The first screen page has been transmitted to the terminal.

Syntax

►►─── MAP OUT (map-name) ─┬──────────┬────────────────────────────────────────►
                          ├─ WAIT ◄ ─┤
                          └─ NOWAIT ─┘

 ►──┬───────────────────────┬─────────────────────────────────────────────────►
    ├─ io-specification ────┤
    └─ no-io-specification ─┘

 ►─┬──────────────────────────────────────────────┬─ ; ───────────────────────►◄
   └─┬─ DETAIL ──┬───────────┬─┬──────────────┬─┬─┘
     │           ├─ NEW ◄ ───┤ └─ KEY (key) ──┘ │
     │           └─ CURRENT ─┘                  │
     └─ RESUME ─┬────────────────────────────┬──┘
                └─ PAGE ─┬─ CURRENT ◄ ─────┬─┘
                         ├─ NEXT ──────────┤
                         ├─ PRIOR ─────────┤
                         ├─ LAST ──────────┤
                         ├─ FIRST ─────────┤
                         └─ (page-number) ─┘
►►─┬──────────────────────────────────────────────────────────────────────────►─
   └ IO ◄ ─┬────────────────────────────────────────────────────────────┬─────
           └ OUTPUT ─┬────────────────────────────────────────────────┬─┘
                     └ DATA ─┬─ YES ───────┬─┬─────────┬─┬──────────┬─┘
                             ├─ NO ────────┤ └ NEWPAGE ┘ └ LITERALS ┘
                             ├─ ERASE ─────┤
                             └─ ATTRibute ─┘

─►───────────────────────────────────────────────────────────────────┬────────►◄
  ─┬───────────────────────────────────────────────────────────────┬─┘
   └─ MESSAGE (message-text) ─┬─ TO (end-message-data-location) ─┬─┘
                              └─ LENGTH (message-data-length) ───┘
►►─┬──────────────────────────────────────────────────────────────────────────►─
   └─ NOIO DATASTREAM INTO (mapped-data-location) ────────────────────────────

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

─►───────────────────────────────────────────────┬────────────────────────────►◄
  ─┬───────────────────────────────────────────┬─┘
   └─ RETURN LENGTH INTO (data-actual-length) ─┘

DETAIL

Specifies that the MAP OUT command is to create or modify a detail occurrence for a pageable map, and optionally associates a numeric key value with the occurrence:

NEW/CURRENT

Specifies whether the detail is to be created or modified:

NEW (default) creates a detail occurrence of a pageable map. Detail occurrences are displayed in the order in which they are created.
CURRENT modifies the detail occurrence that was referenced by the most recent MAP IN DETAIL or MAP OUT DETAIL statement.

KEY IS key-v (optional)

Specifies a value associated with the created or modified detail occurrence. The value is not displayed on the terminal screen. Key-v is the name of a variable data field that contains the key of a database record associated with the detail occurrence.

The specified value is stored as a 4-byte value. When the KEY IS parameter is used with a MAP OUT DETAIL CURRENT command, the specified value replaces the value (if any) previously associated with the detail occurrence.

RESUME PAGE IS

Specifies that a page of detail occurrences is mapped out to the terminal from the session scratch record. Detail occurrences in the scratch record are divided into pages at runtime based on the number of detail occurrences that can fit on the screen at one time.

The page of occurrences displayed is determined by the PAGE IS clause:

CURRENT (default) specifies that the current page is redisplayed. If no page has been displayed, the first page of the pageable map is displayed.
NEXT specifies that the page that follows the current page is displayed. If no page follows the current page, the current page is redisplayed.
PRIOR specifies that the page that precedes the current page is displayed. If no page precedes the current page, the current page is redisplayed.
FIRST specifies that the first available page of detail occurrences is displayed.
LAST specifies that the page of detail occurrences with the highest available page number is displayed. field in which is stored the binary fullword number of the displayed page. A page number is stored in the variable field by a preceding MAP IN PAGE IS data-field-name-v statement that names the same numeric variable field.