FILE-POS (numeric)

This special property is used only for paged grids. The value of FILE-POS is the grid's record number that matches the current file position in the corresponding data file. It is used to simplify the paging logic in your program. FILE-POS computes the number of records that need to be read in order to find the record needed by the grid. The grid uses this value when generating MSG-PAGED-NEXT or MSG-PAGED-PREV events.

The FILE-POS value will often be either the last visible record in the grid or the first non-heading record visible. To illustrate, suppose that you have a four-line grid with no headings. When you are moving forward through the file, FILE-POS will usually be 4, matching the last record added to the grid. If the user clicks the Next Record button, the MSG-PAGED-NEXT event will indicate that only one READ NEXT is needed to retrieve the appropriate record. However, if the user clicks the Previous Record button, the MSG-PAGED-PREV event will indicate that four READ PREVIOUS statements are needed to get the desired record. In this case, FILE-POS will change to 1, indicating that only one READ PREVIOUS is needed to get another previous record while four READ NEXT statements are needed to get the next record.

In addition, FILE-POS has three special values that are level 78 data names defined in acugui.def. These values are listed below:

The grid automatically manages FILE-POS, using the following rules:

• When a record is added to the grid in the topmost non-heading position, FILE-POS is set to that position.
• When a record is added to the grid or past the last grid record, FILE-POS is set to that position.
• If you set EVENT-ACTION-FAIL in response to a MSG-PAGED-NEXT event, FILE-POS is set to PAGED-AT-END.
• If you set EVENT-ACTION-FAIL in response to a MSG-PAGED-PREV event, FILE-POS is set to PAGED-AT-START.
• If you set EVENT-ACTION-FAIL in response to a MSG-PAGED-FIRST or MSG-PAGED-LAST event, FILE-POS is set to PAGED-EMPTY.
• If a MSG-PAGED-FIRST event sets EVENT-ACTION (this is the default), FILE-POS is set to PAGED-AT-START.
• If a MSG-PAGED-LAST event sets EVENT-ACTION, FILE-POS is set to PAGED-AT-END.
• If you reset the grid, FILE-POS is set to PAGED-EMPTY. Adding records to the grid will change this value.

The automatic handling provided here will correctly handle grids whose data is coming from an indexed data file if you move the file's record pointer only in response to grid events (and only as required by those events). In cases in which you move the file's record pointer independent of a grid request, you will need to do one of the following:

• Modify FILE-POS to reflect the actual record position. You may use FILE-POS numbers outside of the range of available grid records if needed. For example, if you position the file pointer one record before the first record in the grid, set FILE-POS to 0. Set FILE-POS to 1 to point to the first record in the grid, 0 to point to the record before that, -1 to point to two records before it, and so on. You can also use numbers larger than the last grid record to indicate a position beyond the end of the grid.
• Reposition the current file pointer to match the FILE-POS value. You can do this by reading the appropriate record from the data file again. Note that a START may not be good enough. START positions the file pointer so that the next READ NEXT or READ PREVIOUS returns the selected record; it may not return the record positioned at either side of that record.
• Ignore the positioning information passed into the MSG-PAGED-NEXT and MSG-PAGED-PREV events, and the positioning information supplied by the grid control. Supply your own positioning logic. In this case, FILE-POS may be incorrect, but FILE-POS is irrelevant at this point because you are not using it. If you ignore the value of FILE-POS, you must decide whether or not you will use the at-end or at-start feature of FILE-POS. If you don't wish to use this feature, don't set EVENT-ACTION-FAIL in MSG-PAGED-NEXT and MSG-PAGED-PREV events.

Any of the techniques mentioned above will work. Note, however, that FILE-POS may be difficult to compute with the first technique because it is often hard to tell how far apart two records are in an indexed file.