3.10 Paged Grids

A grid is a matrix of data fields. Each element of this matrix, called a "cell," can hold either text or a bitmap, or both. Grids are organized into rows, columns, and records. In a grid, a "row" is a grouping of cells that appear on one line in the control. A "record" is one or more rows that are treated as a logical unit. By default, a record occupies one row in a grid, but a record may also "wrap around" to the next row when it passes the right edge of the grid. A "column" identifies a particular cell in a record.

A grid's capacity is limited by available memory. Sometimes, however, you may want to view many records via a grid control. This could pose a problem when you are using normal grids. Just loading all the records into the grid could take an excessive amount of time. To remedy this problem, you may want to use a "paged" grid.

When you are using the PAGED style in a grid, the grid holds only as many records as can be viewed on the screen. This is called a "page" of data. The vertical scroll bar found in a normal grid is replaced by four buttons. These buttons respond to requests to get the next record, the previous record, the next page, or the previous page. When the user clicks one of these buttons, the grid sends a message to the program asking for the appropriate data depending on which button was clicked. This data typically comes from an indexed file. The expected program logic is to do one or more READ NEXT or READ PREVIOUS statements to retrieve the data.

Paged grids are conceptually similar to paged list boxes. Programmers familiar with paged list boxes, however, may notice some differences in programming paged grids. These differences were designed to make programming the grid's paging logic easier. The noticeable differences are:

The program's structure is simplified because event procedures, instead of responses to various exception values, are coded into the paging logic.
Less coding is required, because there is no need to write any code for Next Page and Previous Page actions. You may still opt to write additional code if you want to define actions other than the response normally expected from Next Page and Previous Page operations.
Coding the response to the First Page and Last Page requests are simpler.
Satisfying Next Record and Previous Record requests are easier because the grid control can tell you how many records will have to be read (in the proper direction) in response to these requests.

Furthermore, paged grids communicate requests for more data through events such as MSG-PAGED-NEXT, MSG-PAGED-PREV, MSG-PAGED-NEXTPAGE, MSG-PAGED-PREVPAGE, MSG-PAGED-FIRST and MSG-PAGED-LAST.

Paged grids never hold more data than they can display on the screen. When you are adding a record at the end of a full page, the control deletes the topmost non-heading record. This causes the grid's contents to scroll upward. When you are adding a record to any other position, the last record in the grid is deleted. This causes all records after the one being added to scroll downward.

Note that the current cell is not changed when the grid is paged. In other words, if the grid's cursor is at row 2, column 3, it will be at row 2, column 3 after the user clicks the "next record" button. This will effectively move the cursor to a new record, even though its physical location has not changed. Unlike other forms of cursor movement, this does not generate any additional events. If you are performing special actions when the cursor enters a new cell (for example, displaying related information outside of the grid), then you should perform the appropriate actions in response to paging events as well as cursor-movement events.

Example

 IDENTIFICATION              DIVISION.
 PROGRAM-ID. PagedGrid.
 AUTHOR. Bob Cavanagh.
 ENVIRONMENT                 DIVISION.
 INPUT-OUTPUT                SECTION.
 FILE-CONTROL.
 SELECT Samplegrid
     ASSIGN       TO DISK "samplegrid.dat"
     ORGANIZATION IS INDEXED
     ACCESS MODE  IS DYNAMIC
     FILE STATUS  IS samplegrid-status
     RECORD KEY   IS samplegridkey
     ALTERNATE RECORD KEY IS samplealtkey = last-name,  first-name.

 DATA                        DIVISION.
 FILE                        SECTION.
 FD  Samplegrid.
 01  samplegrid-record.
     05 samplegridkey.
         10 first-name       PIC  X(20).
         10 last-name        PIC  X(20).
     05 samplegrid-extension         PIC  X(4).
     05 samplegrid-department        PIC  X(15).
     05 manager-flag     PIC  9.
     05 samplegrid-email PIC  X(15).
     05 samplegrid-home-phone        PIC  X(15).
*
 WORKING-STORAGE             SECTION.
 78  EVENT-ACTION-FAIL                   VALUE 4.
 78  MSG-CLOSE                           VALUE 16415.
 78  MSG-PAGED-NEXT                      VALUE 16419.
 78  MSG-PAGED-PREV                      VALUE 16420.
 78  MSG-PAGED-FIRST                     VALUE 16423.
 78  MSG-PAGED-LAST                      VALUE 16424.
 78  ACTION-FIRST-PAGE                   VALUE 10.
*
 01  EVENT-STATUS
     IS SPECIAL-NAMES EVENT STATUS.
   03  EVENT-TYPE                      PIC X(4) COMP-X.
   03  EVENT-WINDOW-HANDLE             HANDLE OF WINDOW.
   03  EVENT-CONTROL-HANDLE            HANDLE.
   03  EVENT-CONTROL-ID                PIC XX COMP-X.
   03  EVENT-DATA-1                    SIGNED-SHORT.
   03  EVENT-DATA-2                    SIGNED-LONG.
   03  EVENT-ACTION                    PIC X COMP-X.

*
01 SCREEN-CONTROL IS SPECIAL-NAMES SCREEN CONTROL. 03 ACCEPT-CONTROL PIC 9. 03 CONTROL-VALUE PIC 999. 03 CONTROL-HANDLE HANDLE. 03 CONTROL-ID PIC XX COMP-X. * 77 Key-Status IS SPECIAL-NAMES CRT STATUS PIC 9(4) VALUE 0. 88 Exit-Pushed VALUE 27. 88 Message-Received VALUE 95. 88 Event-Occurred VALUE 96. 88 Screen-No-Input-Field VALUE 97. * 77 samplegrid-status PIC X(2). 88 Valid-Samplegrid VALUE "00" THRU "09". 77 Form1-Handle HANDLE OF WINDOW. 77 Arial24B HANDLE OF FONT. * 01 GRID-COLUMN-HEADINGS. 05 FILLER PIC X(20) VALUE "FIRST NAME". 05 FILLER PIC X(20) VALUE "LAST NAME". 05 FILLER PIC X(4) VALUE "EXT". 05 FILLER PIC X(15) VALUE "DEPT.". 05 FILLER PIC X(15) VALUE "E-MAIL". 05 FILLER PIC X(15) VALUE "HOME PHONE". * 01 GRID-DATA. 03 GRID-KEY. 05 GRID-FIRST-NAME PIC X(20). 05 GRID-LAST-NAME PIC X(20). 03 GRID-EXTENSION PIC X(4). 03 GRID-DEPARTMENT PIC X(15). 03 GRID-EMAIL PIC X(15). 03 GRID-HOME-PHONE PIC X(15).

* SCREEN SECTION. 01 PgGridSample. 03 Scr-Grid, Grid, COL 4.70, LINE 6.00, LINES 26.00 CELLS, SIZE 55.30 CELLS, ADJUSTABLE-COLUMNS, 3-D, COLOR IS 258, COLUMN-HEADINGS, DATA-COLUMNS (1, 21, 41, 45, 60, 75), DISPLAY-COLUMNS (1, 25, 49, 57, 76, 95), ALIGNMENT ("C", "C", "C", "C", "C", "C"), DATA-TYPES ("X(20)", "X(20)", "X(4)", "X(15)", "X(15)", "X(15)"), SEPARATION (5, 5, 5, 5, 5, 5), COLUMN-DIVIDERS (1, 1, 1, 1, 1, 1), CURSOR-COLOR 2, CURSOR-FRAME-WIDTH 3, DIVIDER-COLOR 1, HEADING-COLOR 257, HEADING-DIVIDER-COLOR 1, HSCROLL, ID IS 1, NUM-ROWS 20, PAGED, RECORD-DATA Grid-Data, RECORD-TO-ADD Grid-Data, ROW-DIVIDERS 1, TILED-HEADINGS, USE-TAB, VPADDING 80, VIRTUAL-WIDTH 112, EVENT PROCEDURE Grid-Events. * PROCEDURE DIVISION. DECLARATIVES. I-O-ERROR SECTION. USE AFTER STANDARD ERROR PROCEDURE ON I-O. 0200-DECL. EXIT. END DECLARATIVES. * Acu-Main-Logic. OPEN I-O SAMPLEGRID. PERFORM Acu-PgGridSample-Scrn. PERFORM Load-Grid. PERFORM Acu-PgGridSample-Proc. CLOSE SAMPLEGRID. STOP RUN. . Load-Grid. MOVE GRID-COLUMN-HEADINGS TO GRID-DATA. MODIFY SCR-GRID INSERTION-INDEX = 1 RECORD-TO-ADD=GRID-DATA. MOVE SPACES TO SAMPLEGRIDKEY. START SAMPLEGRID KEY NOT < SAMPLEGRIDKEY INVALID KEY EXIT PARAGRAPH END-START. MODIFY SCR-GRID ACTION = ACTION-FIRST-PAGE. * Move-Data-To-Grid. MOVE FIRST-NAME TO GRID-FIRST-NAME. MOVE LAST-NAME TO GRID-LAST-NAME. MOVE SAMPLEGRID-EXTENSION TO GRID-EXTENSION. MOVE SAMPLEGRID-DEPARTMENT TO GRID-DEPARTMENT. MOVE SAMPLEGRID-EMAIL TO GRID-EMAIL. MOVE SAMPLEGRID-HOME-PHONE TO GRID-HOME-PHONE. * Move-Grid-To-Data. MOVE GRID-FIRST-NAME TO FIRST-NAME. MOVE GRID-LAST-NAME TO LAST-NAME. MOVE GRID-EXTENSION TO SAMPLEGRID-EXTENSION. MOVE GRID-DEPARTMENT TO SAMPLEGRID-DEPARTMENT. MOVE GRID-EMAIL TO SAMPLEGRID-EMAIL. MOVE GRID-HOME-PHONE TO SAMPLEGRID-HOME-PHONE. * Acu-Exit-Rtn. EXIT PROGRAM STOP RUN . * Acu-PgGridSample-Routine. PERFORM Acu-PgGridSample-Scrn. PERFORM Acu-PgGridSample-Proc . Acu-PgGridSample-Scrn. PERFORM Acu-PgGridSample-Create-Win. DISPLAY PgGridSample UPON Form1-Handle . Acu-PgGridSample-Create-Win. * display screen DISPLAY Standard GRAPHICAL WINDOW LINES 38.00, SIZE 64.00, CELL HEIGHT 10, CELL WIDTH 10, AUTO-RESIZE, COLOR IS 65793, ERASE, LABEL-OFFSET 0, LINK TO THREAD, MODELESS, NO SCROLL, WITH SYSTEM MENU, TITLE "Paged Grid Sample", TITLE-BAR, NO WRAP, EVENT PROCEDURE Form1-Event-Proc, HANDLE IS Form1-Handle. * DISPLAY PgGridSample UPON Form1-Handle . * PgGridSample Acu-PgGridSample-Proc. PERFORM UNTIL Exit-Pushed ACCEPT PgGridSample ON EXCEPTION PERFORM Acu-PgGridSample-Evaluate-Func END-ACCEPT END-PERFORM DESTROY Form1-Handle INITIALIZE Key-Status . * PgGridSample Acu-PgGridSample-Evaluate-Func. * avoid changing focus MOVE 1 TO Accept-Control . Form1-Event-Proc. * EVALUATE Event-Type WHEN Msg-Close PERFORM Acu-Exit-Rtn END-EVALUATE . Grid-Events. * EVALUATE Event-Type WHEN Msg-Paged-First PERFORM Scr-Grid-Ev-Msg-Paged-First WHEN Msg-Paged-Last PERFORM Scr-Grid-Ev-Msg-Paged-Last WHEN Msg-Paged-Next PERFORM Scr-Grid-Ev-Msg-Paged-Next WHEN Msg-Paged-Prev PERFORM Scr-Grid-Ev-Msg-Paged-Prev END-EVALUATE . * Scr-Grid-Ev-Msg-Paged-Next. PERFORM EVENT-DATA-2 TIMES READ SAMPLEGRID NEXT RECORD AT END MOVE EVENT-ACTION-FAIL TO EVENT-ACTION EXIT PARAGRAPH END-READ END-PERFORM PERFORM MOVE-DATA-TO-GRID MODIFY SCR-GRID, RECORD-TO-ADD = GRID-DATA .

* Scr-Grid-Ev-Msg-Paged-Prev. PERFORM EVENT-DATA-2 TIMES READ SAMPLEGRID PREVIOUS RECORD AT END MOVE EVENT-ACTION-FAIL TO EVENT-ACTION EXIT PARAGRAPH END-READ END-PERFORM. PERFORM MOVE-DATA-TO-GRID. MODIFY SCR-GRID, INSERTION-INDEX = 2, RECORD-TO-ADD = GRID-DATA . * Scr-Grid-Ev-Msg-Paged-First. MOVE LOW-VALUES TO SAMPLEGRIDKEY. START SAMPLEGRID KEY >= SAMPLEGRIDKEY INVALID KEY MOVE EVENT-ACTION-FAIL TO EVENT-ACTION END-START . * Scr-Grid-Ev-Msg-Paged-Last. MOVE HIGH-VALUES TO SAMPLEGRIDKEY START SAMPLEGRID KEY <= SAMPLEGRIDKEY INVALID KEY MOVE EVENT-ACTION-FAIL TO EVENT-ACTION END-START . *