Terminal Management › Using Pageable Maps › Conducting a Map Paging Session

Conducting a Map Paging Session

A map paging session involves interaction among the user, the run-time mapping system, and your map paging application program. You should understand this interaction and the sequence of events that occurs during a map paging session before planning the logic of your application program.

Typical Map Paging Sequence

This sequence of events typically occurs during a map paging session:

1. Your program begins the session and defines map paging parameters
2. The program creates detail occurrences
3. A map page is displayed on the terminal
4. The user pages forward and backward through the pageable map
5. The user optionally modifies map data fields
6. The program receives control and updates the database
7. The user ends the map paging session

The following discussion describes each step in detail.

Beginning the Paging Session

A map paging session begins when your program issues a STARTPAGE statement. Options included in this statement specify the following:

• The runtime flow of control. The paging type (NOWAIT/WAIT/RETURN) determines whether the run-time mapping system or your program receives control when the user presses a control key, as detailed in the table below.

  The paging type affects the frequency with which your program will receive control and the processing logic you must provide. For example, in NOWAIT, run-time mapping performs all paging operations for you; in WAIT and RETURN, you must provide coding logic that performs the paging operations specified by the user.

  NOWAIT is best for applications in which the user can display but not update; WAIT and RETURN are best for update applications.

• Whether the user can display a previous map page. If backpaging is allowed, the run-time system must maintain the resources that describe the detail occurrences of previous pages. If backpaging is not allowed, the run-time system deletes all previous pages of detail occurrences when a new map page is displayed.

  Note: Always allow backpaging for pageable map applications that perform database updates.

• Whether the user can update map data fields. A paging mode of UPDATE specifies that the user can modify map data fields, subject to restrictions specified in the map and by previous MODIFY MAP statements. BROWSE specifies that the user can modify only the system-supplied $PAGE field (if present).

The tables below summarize flow of control in a map paging session.

• Paging request*:

* If the user presses Clear, PA1, PA2, or PA3, and that key is not associated with backward or forward paging, refer instead to "Nonpaging request" below.

** If the user presses Clear, PA1, PA2, or PA3, refer to the "No data fields modified" column.

• Nonpaging request:

** If the user presses Clear, PA1, PA2, or PA3, refer to the "No data fields modified" column.

Creating Detail Occurrences Your program retrieves data, moves it to map data fields, and creates detail occurrences by issuing MAP OUT DETAIL commands.

Displaying the First Page

The first page is displayed on the terminal screen in one of the following ways:

• Run-time mapping automatically displays the first map page when the first detail occurrence of the second page of occurrences is created. The program continues to execute and create additional detail occurrences.

  When the first page is displayed by run-time mapping, DC returns a status of 4676 (DC-FIRST-PAGE-SENT). Your program must check for this status after every MAP OUT DETAIL statement.

• Your program displays the first map page. When all detail occurrences are created, your program should check to determine if the first page was written to the terminal. You do this by setting a switch when DC returns a status of 4676 (DC-FIRST-PAGE-SENT). If 4676 was never returned, your program explicitly displays the first map page by issuing a MAP OUT RESUME statement.

Paging Forward and Backward

To specify the next map page to be displayed, the user does one of the following:

• Presses the control key associated with paging forward one page
• Presses the control key associated with paging backward one page
• Changes the $PAGE map field, if defined on the map, and presses a control key other than Clear, PA1, PA2, or PA3.

Modifying Map Fields

The user can change map data fields, including header and footer data fields, subject to restrictions specified by the STARTPAGE command (UPDATE/BROWSE) or by a previously specified MODIFY MAP command.

Updating the Database

If the user has modified any map data fields or if the paging type is RETURN, the program reads modified detail occurrences and updates the database.

A modified detail occurrence contains one or more map fields whose modified data tags (MDTs) are set on.

To retrieve a modified detail occurrence, issue a MAP IN DETAIL statement. MAP IN DETAIL can retrieve a modified detail occurrence sequentially, by the order of detail occurrences, or randomly by a key value that can be associated with an occurrence. If sequential or random retrieval cannot retrieve a modified detail occurrence, DC returns a status of 4668 (DC-NO-MORE-UPD-DETAILS).

If you need to modify the current detail occurrence (for example, to send an error message), issue a MAP OUT DETAIL CURRENT statement. This statement modifies the detail occurrence most recently referenced by a MAP IN DETAIL or MAP OUT DETAIL statement.

After processing all modified detail occurrences, write the map to the terminal screen by issuing a MAP OUT RESUME statement. If WAIT or RESUME has been specified, your program is responsible for displaying the next page specified by the user.

If you need to create additional detail occurrences, you can do so at any time by issuing further MAP OUT DETAIL statements. The new occurrences are stored at the end of the set of detail occurrences.

Ending the Paging Session

When a map paging session ends, the system deletes all the detail occurrences created during the session. To end a session, issue an ENDPAGE SESSION command.