GUI ScreenIO for Windows |
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.
In panel-3 area | Data |
listview-GET-FROM-KEY | The value of the invisible key column for the last record in the listview cache. |
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. |
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.
PERFORM WITH TEST AFTER
CALL 'GS' USING panel-1
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.
|
If a list has only one record, you load it with 100%.
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.
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.
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.
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 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 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.
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.
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.
© 2000-2019 Norcom, all rights reserved |