PL/I DML Statements for Pageable Maps › MAP OUT › STARTPAGE

STARTPAGE

A STARTPAGE statement initiates the paging session. It can be followed by any number of DML commands, including MAP IN and MAP OUT commands. The map-paging session is terminated by an ENDPAGE command (or by another STARTPAGE command, if one is encountered before an ENDPAGE command).

After completion of a STARTPAGE function, the ERROR-STATUS field of the IDMS-DC communications block indicates the outcome of a pageable-map operation:

Syntax

►►─── STARTPAGE session (map-name) ───────────────────────────────────────────►

 ►─┬────────────┬─┬──────────────┬─┬────────────┬─┬─────────────────┬─ ; ─────►◄
   ├─ WAIT ─────┤ ├─ BACKPAGE ◄ ─┤ ├─ UPDATE ◄ ─┤ ├─ AUTODISPLAY ◄ ─┤
   ├─ NOWAIT ◄ ─┤ └─ NOBACKPAGE ─┘ └─ BROWSE ───┘ └─ NOAUTODISPLAY ─┘
   └─ RETURN ───┘

STARTPAGE SESSION map-name

Specifies the beginning of a pageable map session, specifies the name of the pageable map used for the session, and specifies the map paging options in effect for the session. The STARTPAGE command must precede any commands (such as MAP IN) that specify operations performed using the map.

NOWAIT/WAIT/RETURN

Specifies the runtime flow of control when the operator presses a control key:

• NOWAIT (default) specifies that runtime mapping automatically handles all paging and update transactions. Control is passed to the program only when neither an update nor paging request is made when the operator presses a control key.
• WAIT specifies that runtime mapping automatically handles paging transactions that do not update data. Control is passed to the program when the operator presses a key that requests an update or a nonpaging operation.
• RETURN specifies that runtime mapping does not handle any terminal transactions in the paging session. Control is passed to the program when the operator presses a control key.

Runtime mapping does not update program variable storage unless the application program issues a MAP IN command. In cases where the operator can update data, it is recommended that WAIT or RETURN be specified for the paging session so that data can be retrieved as it is updated.

BACKPAGE/NOBACKPAGE

Specifies whether the terminal operator can display a previous map page:

• BACKPAGE (default) specifies that the operator can display previous pages of detail occurrences.
• NOBACKPAGE specifies that the operator cannot display any page of detail occurrences with a page number lower than the current page number. Modifications made on a given page of the map must be retrieved by a MAP IN statement in the application program prior to a MAP OUT RESUME statement. The previous page of detail occurrences is deleted from the session scratch record when a new map page is displayed.

UPDATE/BROWSE

Specifies whether the terminal operator can modify map data fields:

• UPDATE (default) specifies that the terminal operator can modify variable map fields, subject to restrictions specified for the map either at map-definition time or by statements in the program.
• BROWSE specifies that the terminal operator can modify only the page and response fields (if any) of the map. The MDTs for variable fields on the map can be set on only according to specifications made either in the map-definition or by statements in the program.

NOBACKPAGE cannot be assigned if UPDATE and NOWAIT are specified for the session.