GUI ScreenIO for Windows

 ScreenIO.com


The listview-GET-NEXT event

A listview-GET-NEXT event is returned when the listview needs records following those previously loaded. 

It usually occurs when the user scrolls the list beyond the end of the data in the listview's cache.

Data returned with this event

Required to process this event

In panel-3 area Data
listview-GET-FROM-KEY The value of the invisible key column for the last record in the listview cache.

Returned but not used to handle this event

In panel-3 area Data
listview-MAX Maximum number records that may be passed in the listview buffer, useful for PERFORMed loops when loading records to  your listview buffer.
listview-SCROLL-TO-KEY Set to HIGH-VALUES.
listview-SEL1-KEY The value of the invisible key column for the first selected record in the list.
listview-SEL2-KEY The value of the invisible key column for the last selected record record in the list. 

Note:  Since GUI ScreenIO does not presently support a selection range (multiple record selections), this field is always the same as listview-SEL1-KEY.

listview-TOP-OF-LIST-KEY The value of the invisible key column for the first (top) record that is visible in the listview control.
All other fields Set to LOW-VALUES.
In panel-4 area Data
listview Number of items in the list that are selected.

Required response

Position the file to the record having the key that was returned in listview-GET-FROM-KEY, then load the listview from this point in the file. 

The key and percentage of the first record in the listview buffer must match the key and percentage of the last record in the cache; that is, you must reload the record with the key that was returned to you in listview-GET-FROM-KEY. 

Sample code

     PERFORM WITH TEST AFTER
         UNTIL panel-EVENT-CLOSE-WINDOW
            OR panel-EVENT-CLOSE-AND-STOP

       CALL 'GS' USING panel-1
                       panel-2
                       panel-3
                       panel-4

       EVALUATE TRUE

-->      WHEN listview-GET-NEXT
-->        MOVE listview-GET-FROM-KEY TO record-KEY
-->        SET file-command-START-EQUAL TO TRUE
-->        CALL file-I-O-routine USING file-commands
-->                                    data-record
-->        IF valid-file-status
-->          PERFORM BROWSE-FORWARD
-->        END-IF

           .
           .
           .

       END-EVALUATE

     END-PERFORM.

Here's the general form of the performed routine that loads the listview buffer. 

Note that you must move 100 percent to the last record that was successfully loaded to indicate to the listview that you have loaded the last record in the list.  Once the listview has received a record with 100 in the percentage, it will no longer return listview-GET-NEXT events (unless this record has been discarded from the cache by GUI ScreenIO's caching algorithm).

 BROWSE-FORWARD.

     PERFORM WITH TEST AFTER
         VARYING listview-IDX FROM 1 BY 1
         UNTIL listview-IDX NOT < listview-MAX
            OR NOT valid-file-status

       SET file-command-READ-NEXT TO TRUE
       CALL file-I-O-routine USING file-commands
                                   data-record

       EVALUATE TRUE
 
         WHEN valid-file-status
           PERFORM LOAD-DATA-TO-LISTVIEW

         WHEN file-status-end-of-file
           IF listview-IDX > 1
             MOVE 100 TO listview--PERCENT (listview-IDX - 1)
           END-IF

       END-EVALUATE
     END-PERFORM.


 LOAD-DATA-TO-LISTVIEW.

     MOVE record-PERCENT TO listview--PERCENT (listview-IDX).
     MOVE record-KEY     TO listview--KEY     (listview-IDX).

     MOVE record-data    TO listview-column-1 (listview-IDX).
     MOVE record-data    TO listview-column-2 (listview-IDX).
     MOVE record-data    TO listview-column-n (listview-IDX).


Common problems

Lists of only one record

If a list has only one record, you load it with 100%.

Failing to reload (match) the last record in the cache

The first record that you load to your listview buffer, must match the last record in the listview cache.  That is, you must reload the record with the key returned in listview-GET-FROM-KEY when you respond to this event.

Failing to load 100 percent to the last record

If you do NOT load 100 percent to the last record in the list, the listview will continue to return listview-GET-NEXT events.  This results in a loop because your program will be unable to provide any more data.

Loading 100 percent prematurely to a record

More than one developer has made the simple mistake of loading 100 percent to a record when their PERFORMed loop reaches listview-MAX, instead of when they reach end-of-file.  If you do this, the listview will no longer return listview-GET-NEXT events because you told it you gave it the last record in the list!

This is a good example of when your interactive COBOL debugger would help you identify the problem in a hurry.

Remarks

The listview-GET-NEXT event is used to add data to GUI ScreenIO's listview cache when it is required.  This "just-in-time" strategy of loading data to a listview means that there is no particular delay when browsing a very large file with a listview, and also reduces memory utilization.

Preload Cache

Preload cache is primarily used to accommodate relatively small lists and file systems that do not supply record percentages. 

Specify preload caching in the panel editor using the listview properties.  Choose the Listview Behavior tab, then click the radiobutton for Preload Cache.

When you load the first buffer of records to a listview that uses preload cache, it will return a series of listview-GET-NEXT events until the last record (100% record) has been received.  After that, you will no longer receive any requests for data from the listview, because all of the data has been loaded to the listview's cache.

Listviews using preload caching will not return listview-START-AT or listview-GET-PRIOR events, because they're loaded sequentially (using listview-GET-NEXT events) until all of the records are loaded. 

You don't need to provide accurate percentages, either.  Simply provide 0 percent for the first record, and then 50% for all the rest of the records until you hit the last one, which is set to 100%.

Accumulate Cache

Accumulate caching works much like preload cache, except that it only returns listview-GET-NEXT events when needed, instead of loading the entire list at once.  Like preload caching, it's best when used for relatively small files.

Specify accumulate caching in the panel editor using the listview properties.  Choose the Listview Behavior tab, then click the radiobutton for Accumulate Cache.

If the user scrolls beyond what's in the cache, you'll receive a listview-GET-NEXT event. 

If the user drags the scrollbar thumb a long way along the list, you'll receive a series of listview-GET-NEXT events until the listview receives a record with a percentage that matches the scrollbar thumb position (which can be tricky if your file system doesn't support percentages).  If your list is very large, it may take a considerable time for the listview to load all of the data up to the scrollbar thumb position, since accumulate-caching listviews always load the data sequentially.

Therefore, if you have a file of a million records and the user drags the scrollbar thumb to the halfway point, you'll receive listview-GET-NEXT events until you've loaded 500,000 records!  Keep this in mind if you're thinking about using this caching mode.

Accumulate caching is sometimes useful when your file system doesn't handle percentages well, or when you want to keep all of the data you've loaded to the cache in memory. 

On the other hand, GUI ScreenIO's caching algorithm is so efficient that you'll probably have as good or better performance by using the default listview caching.

Percentages

The listview implementation requires that you be able to position the file to a percentage along the keypath, and that you be able to supply this percentage with each record loaded to the listview.

Go here for a complete discussion of percentages with respect to using listviews, and one technique of synthesizing percentages for file systems (like ISAM) which do not provide them.

Internal Listview Cache management

When you respond to a listview-GET-NEXT event, GUI ScreenIO appends the records that you supply in the listview buffer to the records already in its cache.  If the cache size exceeds the internal maximum, records will be deleted from the beginning in order to accommodate the records you're adding to the end of the cache.

Preload caching causes the cache to be expanded as required to hold the entire list. 

Accumulate caching causes the cache to be expanded on demand as records are loaded, until the entire list has been loaded.

Related topics:


© 2000-2019 Norcom, all rights reserved 

TOC

Send feedback to Norcom