SFLROLVAL (Subfile Roll Value) keyword for display files

You use this field-level keyword in the subfile-control record format to specify that the workstation user can type a value in this field. The value tells the IBM® i operating system how many records to page up or down when the appropriate paging key is pressed.

This field must have the keyboard shift attribute of signed numeric with zero decimal positions. It can be up to 4 digits in length, and it must be defined as an input/output or input-only field.

This keyword has no parameters.

The workstation user can page through the data being displayed up or down by first typing in the number of records to page through and then pressing the Page Up or the Page Down key. (On subsequent pages, the SFLROLVAL value stays the same unless a new number is typed in before paging.) If a negative number or zero is typed into this field and a Page key is pressed, an error message is displayed at the workstation.

This keyword is valid only for the subfile-control record format. You must specify it if the IBM i operating system is to support the page-by-record function.

If this keyword is not specified, the IBM i operating system pages through the display by the SFLPAG value except for subfiles using the SFLDROP keyword. If using the SFLDROP keyword, more records are displayed than the SFLPAG value when records are displayed in the truncated format. For truncated records, the IBM i operating system pages through the display by the number of records displayed in the truncated format.

If subfile size equals subfile page, SFLROLVAL is ignored. When several display sizes are used (DSPSIZ keyword specified), SFLROLVAL is ignored only for display sizes for which subfile size equals subfile page. If the subfile record format contains field selection, SFLROLVAL is not valid.

This field is returned to your program as part of the input for this subfile control record.

If pressing the Page Up key pages beyond the first page of records of the subfile, one of the following conditions occurs:

If the first page of records is not currently displayed, paging up will display it.
If the first page of records is currently displayed, paging up will cause a message to be displayed.

If pressing the Page Down key pages beyond the last active record of the subfile, one of the following conditions occurs:

If the last full page of records is not already displayed, typing Page Down will display it.
If the last full page of records is already displayed, typing Page Down will cause a message to be displayed. One exception to this rule is that when the SFLROLVAL value is less than the SFLPAG value, the IBM i operating system pages through the subfile again and no message is displayed.

Certain keywords are helpful when specified with SFLROLVAL:

The SFLEND keyword notifies the workstation user when the last subfile record is displayed.
The PAGEUP or PAGEDOWN keywords cause control to return to the program when pressing a Page Up or a Page Down key can page beyond the end of the subfile. Without PAGEUP(ROLLDOWN) or PAGEDOWN(ROLLUP), a message is displayed (as described previously).

Note: The ROLLUP keyword is the same as the PAGEDOWN keyword and the ROLLDOWN keyword is the same as the PAGEUP keyword.

The following examples illustrate the use of SFLROLVAL:

Paging Up. Assume that the value specified for SFLPAG is 3, and there are 11 active records in the subfile. If records 8 through 10 are currently being displayed, and the user types a page value greater than 7, pressing the Page Up key displays records 1 through 3.
If records 1 through 3 are currently displayed, and a Page Up key is entered with a SFLROLVAL value greater than 0, either a message is sent to the workstation user (PAGEUP not specified) or control is returned to the user program (PAGEUP specified; the program has responsibility for paging down).
Paging Down. Assume that the value specified for SFLPAG is 3, and there are 11 active records in the subfile. If records 8 through 10 are currently being displayed, and the user enters a 3 into the SFLROLVAL field, pressing the Page Down key displays record 11 in the uppermost page area of the display. Any lines not occupied by that record are blank. If the Page Down key is pressed again, the last full page of subfile records (records 9 through 11) are displayed. Finally, if the Page Down key is pressed a third time, either a message is sent to the workstation user (PAGEDOWN not specified) or control is returned to the user program (PAGEDOWN specified; the program has responsibility for paging down).

The following shows the conditions that occur when paging beyond the ends of the subfile (when the SFLROLVAL value is greater than the SFLPAG value).

On pressing the Page Down key:
- If the last full page of records is not already displayed, then it is displayed.
- If the last full page of records is already displayed, then a message is displayed.
On pressing the Page Down key a second time:
- If PAGEDOWN is specified, control returns to your program.
- If PAGEDOWN is not specified, a message is displayed.
On pressing the Page Up key:
- If the first page of the subfile is not already displayed, then it is displayed.
- If the first page of the subfile is already displayed, then:
  - If PAGEUP is specified, control returns to your program.
  - If PAGEUP is not specified, a message is displayed.

You cannot specify both the SFLROLVAL and the SFLRCDNBR keywords for the same field.

Option indicators are not valid for this keyword.

Example

The following example shows how to specify the SFLROLVAL keyword.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
00010A          R SFLR                      SFL
     A*
     A*           (at least one displayable field)
     A*
00040A          R SFLCTLR                   SFLCTL(SFLR)
00050A                                      SFLPAG(17)
00060A                                      SFLSIZ(17)
00070A                                      SFLDSP SFLDSPCTL
00080A            ROLVAL         4S 0B  1 47SFLROLVAL
     A