GUI ScreenIO for Windows

Loading a Listview

Loading a listview isn't difficult, but you need to observe a couple of rules to ensure that it works properly.  Failing to do do can cause one of the listview common problems:

Rules for loading a listview

Usual method

Reset the list (not usually necessary, but a good habit to get into).

Position the file to the record where you want to start loading the list (usually the first record in the file), then load the listview from this point in the file. 

If you want to force the listview to start at some point other than the first record in the file, move the record's key (the same stuff you moved to the record's invisible key field) to listview-SCROLL-TO-KEY.

Sample code

     SET listview-RESET TO TRUE.

     MOVE starting-key TO record-KEY.
     SET file-command-START-EQUAL TO TRUE.
     CALL file-I-O-routine USING file-commands
     IF valid-file-status

* ------------------------: (Optional) Scroll to specific record

     MOVE listview--KEY (1) TO listview--SCROLL-TO-KEY.

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).


         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

         WHEN valid-file-status

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



     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).


Invisible Record Keys

Listview controls will save your record keys for you so that you don't need to keep track of them; in fact, it's essential to provide the keys of your records to the listview when you load data to it so that the listview can pass you the keys of records the user selected and keys needed to process GET-NEXT and GET-PRIOR events.

However, the invisible key data can be any sort of data; the content is up to you, though it would be wise to have a unique primary key be part of the data. 

For example, you could define your invisible key field as 19 bytes, and then do this:

     05  IK-PRIMARY-KEY          PIC X(8).
     05  IK-PERCENT              PIC S9(3)V9(6).



     MOVE record-KEY     TO IK-PRIMARY-KEY.
     MOVE whatever       TO IK-WHATEVER.

     MOVE INVISIBLE-KEY-DATA TO listview--KEY (listview-IDX).

The code above shows how you can associate any kind of data - not just a key - with the records you load to a listview.  This can be extremely useful.

Selected records

If you want to have an item in the list appear to be selected when the listview is displayed, just set the selected byte for that item when you load the record to the listview buffer:

     SET listview-SDX TO listview-IDX
     SET listview-SELECTED (listview-SDX) TO TRUE

End-of-file logic

The end-of-file logic is worth a comment or two.

Some file systems, including the COBOL file systems, have the seemingly perverse convention of not telling you that you've read the last record in the file until you try to read beyond it!  Then it returns an end-of-file status.  This can make life difficult when you're loading a listview because you need to load 100 percent to the record you read before you encountered the end-of-file.

The logic illustrated does exactly what's needed.  It works because the way listviews work, you will always have read at least one record successfully and loaded it to the listview buffer.  Therefore, when you attempt to read another record and receive the end-of-file status, you can successfully load 100 percent to the record you previously loaded.

Overlap successive buffers by one record

When the listview comes back to your program with a GET-NEXT event, it also provides you with a GET-FROM-KEY.  Be sure to start your file system at this key, load it, and read forward.  You will note that this key is the same as the last record in the prior buffer.  THIS IS INTENTIONAL.  Pay attention to the GET-FROM-KEY.

Its purpose is to assure the listview that you are feeding it continuous data.  Failure to overlap buffers is a very common problem.  Its works fine if you just honor the GET-FROM-KEY without trying to out-smart the listview.

Common problems

Please review the list of common problems encountered when loading listviews.

Related topics:

2000-2019 Norcom, all rights reserved 


Send feedback to Norcom