Map Commands › Pageable Maps › Map Paging Session

Map Paging Session

A map page refers to the header and footer map fields and to a page of detail occurrences.

When a pageable map is displayed, the page of occurrences that appears in the detail area is determined by the current value of the $PAGE system-supplied data field. For example, given a screen that can hold ten occurrences, if $PAGE equals 1, occurrences 1 through 10 are displayed; if $PAGE equals 2, occurrences 11 through 20 are displayed; and so forth. Actions taken by the user and commands issued by premap and response processes can modify the value of $PAGE.

Beginning a Map Paging Session

A map paging session begins when a dialog associated with a pageable map begins execution. A map paging session ends when the application terminates or when a dialog passes control to another dialog under any of the following conditions:

• The dialog receiving control is associated with a different pageable map than the dialog that initiated the map paging session
• The dialog receiving control has different map paging dialog options than the dialog that initiated the map paging session
• The dialog that initiated the map paging session issues a TRANSFER command
• The dialog receiving control is at a level higher than the dialog that initiated the map paging session

Note: The first two conditions do not apply when the receiving dialog is not associated with a pageable map. In such cases, the map paging session continues, provided that the third or fourth condition is not met.

If none of the above conditions is met, the map paging session continues. Detail occurrences created during the session can be added to, displayed, and modified by dialogs associated with the pageable map. If the map paging session terminates, the runtime system deletes all detail occurrences created during the session.

One or more dialogs can be associated with the same pageable map in a given map paging session. During a map paging session, premap and response process commands can create, display, retrieve, and modify detail occurrences.

Considerations

The following considerations apply:

• Detail occurrences are created by PUT NEW DETAIL process commands. Detail occurrences are built from the values stored in the variable data fields to which the detail occurrence fields map.

  The runtime system stores detail occurrences in the order in which they are created and divides them into pages, based on the number of detail occurrences that can fit on the screen at one time. A detail occurrence is displayed on the screen only when the map page to which the occurrence belongs is displayed.

• A dialog process displays a map page to the terminal as a result of either of the following actions:
  • A PUT NEW DETAIL command is issued that creates the first detail occurrence of the second map page. The runtime system automatically displays the first map page, allowing the user to enter information.

    The process that issues the PUT NEW DETAIL command continues to execute and can create additional detail occurrences. The process must issue a DISPLAY command to terminate processing. The runtime system does not process information entered during a pseudo-converse until the DISPLAY command is issued.

    Note: In this case, the DISPLAY command does not send information to the terminal. Header and footer variable data fields should be primed before the first map page is displayed. If the map contains a message field in the header or footer area, any text for the message field should be specified once by issuing a PUT NEW DETAIL command before the first map page is displayed.

  • A DISPLAY command is issued, except when the map has already been displayed as a result of a PUT NEW DETAIL command. The map page displayed is determined by the current value of $PAGE.
• The user can modify map data fields on the screen, including header and footer data fields and detail occurrence fields of the current map page. Restrictions that apply include those specified in the map definition (such as the PROTECT specification), in the dialog definition (that is, the paging mode dialog option, UPDATE/BROWSE), and by process commands (such as the MODIFY MAP command).
• The user can make a paging request to specify the next map to be displayed by performing one of the following actions:
  • Pressing the control key associated with paging forward one page. The system generation default paging-forward key is PF8.
  • Pressing the control key associated with paging backward one page. The system generation default paging-backward key is PF7.
  • Changing the $PAGE map field (if one is defined for the map) and pressing a control key other than the paging-forward key, paging-backward key, [Clear], [PA1], [PA2], or [PA3]
• The user presses a control key, including the paging-forward or paging-backward key, and the runtime system performs the following processing:
  • Updates map data fields— The runtime system updates its internal representation of the header and footer map data fields and updates detail occurrence fields to reflect changes made by the user. No updates are performed if [Clear], [PA1], [PA2], or [PA3] are pressed; these control keys do not transmit data.

    Map field attributes set temporarily by the user or by map modification commands are reset. Attributes set permanently in the map definition or by map modification commands remain set.

  • Updates $PAGE— If a paging request was made, the runtime system updates $PAGE as follows:
    • Adds 1 to $PAGE if the paging forward key was pressed and the current map page is not the last map page.
    • Subtracts 1 from $PAGE if the paging backward key was pressed and the current map page is not the first map page.
    • Moves the value entered in the $PAGE map field to $PAGE if the $PAGE map field was changed and the control key pressed was not the paging forward key, the paging backward key, [Clear], [PA1], [PA2], or [PA3]. If the value entered in the $PAGE field is less than the first map page or greater than the last map page, $PAGE is set to the first or last page number.

    $PAGE determines the next map page to be displayed.

  • Determines the flow of control— In a session that is not a map-paging session, the runtime system always attempts to initiate a function or response process when the user presses a control key. In a map paging session, the runtime system either attempts to initiate a function or response process, or instead displays the same or another map page. The action taken by the runtime system depends on the paging-type dialog option (NOWAIT/WAIT/RETURN), on whether a paging request was made, and whether any map field's modified data tag was set, as shown in the following table.

Flow of Control in a Map Paging Session

Notes:

¹ A paging request occurs when the user presses a control key associated with paging forward or backward or modifies the $PAGE field, if one is defined for the map. If [Clear], [PA1], [PA2], or [PA3] is pressed, any modification to $PAGE is ignored and is not considered as a paging request. If a paging request is not made, refer to the Nonpaging request columns.

² If the control key pressed is [Clear], [PA1], [PA2], or [PA3], refer to the No MDT set column under the applicable Paging/Nonpaging request column.

³ The function or response is selected as described in Runtime flow of control.

If the same or another map page is displayed, the user can modify map fields, make a paging request, and press a control key, as described above.

If a function or response process is initiated, the internal representations of the header and footer fields are mapped into their associated variable data fields.

• Detail occurrences are retrieved by GET DETAIL process commands. A GET DETAIL command locates the occurrence to be retrieved, then moves the occurrence's fields into the variable data fields to which the fields map.
• Only modified detail occurrences can be retrieved. A detail occurrence is considered to be modified if it has the following two characteristics:
  • Contains one or more map fields whose modified data tags (MDTs) are set at the time of the most recent pseudo-converse.
  • Has yet to be retrieved since the most recent pseudo-converse. Once a modified detail occurrence has been retrieved, it is no longer considered to be modified.

    Note that if a modified detail occurrence is not retrieved following a pseudo-converse, it is not automatically considered to be modified following a subsequent pseudo-converse. The detail occurrence must once again have the two characteristics listed above.

  A detail occurrence that is not a modified detail occurrence cannot be retrieved by dialog process code.

• Detail occurrence fields are modified in dialog processes by PUT CURRENT DETAIL commands. A PUT CURRENT DETAIL command modifies the detail occurrence referenced by the most recent GET DETAIL or PUT DETAIL command.
• Additional detail occurrences can be created by PUT NEW DETAIL commands. New occurrences are stored at the end of the set of detail occurrences.
• Detail occurrences cannot be deleted by process commands. Detail occurrences are deleted as follows:
  • If the backpage dialog option (described below) is NO, detail occurrences of previous map pages are deleted when a new map page is displayed.
  • At the end of a map paging session, all detail occurrences are deleted.

More information:

Variable Data Fields