Test268 Section 2
<< Previous Section | Home | Next Section >>
Contents
- 1 Section 2 - Subfiles (8%)
- 1.1 Code and use subfiles
- 1.2 Create and maintain subfiles and programs that use those subfiles (DDS and RPG)
- 1.3 Determine the relationship between page size and subfile size
- 1.4 Determine performance issues dealing with loading subfiles
- 1.5 Interpret the use of SFLNXTCHG
- 1.6 Interpret subfile keywords (e.g., SFLCSRRRN, SFLDSP, SFLDSPCTL, SFLDROP, SFLPAG, SFLFOLD, SFLRCDNBR, SFLEND)
- 1.7 Apply appropriate methods for accessing and updating subfile records
Section 2 - Subfiles (8%)
Code and use subfiles
Create and maintain subfiles and programs that use those subfiles (DDS and RPG)
Determine the relationship between page size and subfile size
When you specify the same parameter values for SFLPAG and SFLSIZ, the maximum number of records that can be contained in the subfile equals the maximum number of subfile records that can appear on the display at one time. For this condition, the OS/400 program does not automatically page through the subfile when the Page Up or the Page Down key is pressed. If the ROLLUP and ROLLDOWN keywords are specified and one of the Page keys is pressed, the OS/400 program returns control to your program instead. If ROLLUP and ROLLDOWN are not specified, a message is sent to the workstation user, indicating that a key is not supported on the display.
If subfile size equals subfile page, the following keywords are not allowed: SFLDROP SFLFOLD SFLROLVAL
Determine performance issues dealing with loading subfiles
Load All:
- You might have to change the SFLSIZ keyword if the amount of data increases - User might have to page thru several pgaes to get the data he wants which is time consuming
Self-Extending:
- Allows users to add records to subfile only when they are needed (normally, one page at a time)
- Subfile performance will be more consistent
- more likely to perform to expected results:
-A load-all subfile may load 50 records one time & 500 records the next.
- navigation within the subfile more flexible, thus saving time
Interpret the use of SFLNXTCHG
A typical use of SFLNXTCHG could be as follows:
A work station user changes some records in a displayed subfile (this could be for a data-entry application or a data-update application). After changing some records, the work station user presses the Enter key, and the program reads only the changed records with get-next-changed operations. (READC)
If the program detects keying errors in the changed records, it can send update operations (UPDATE) to the subfile records in error, setting indicators so that SFLNXTCHG is in effect during the update operations. These update operations are sent to the subfile record format.
After all the records in error have been updated, the program sends an output/input operation to the subfile control record format to display the subfile again.
With the subfile displayed again, the work station user types the data again and presses the Enter key. If the data is correct, the program does not display the subfile again.
The records in error (and any other records changed by the work station user) are returned to the program on the next get-next-changed operation. This is because SFLNXTCHG caused the subfile records to be considered changed even though the work station user did not change them. This allows the program to prohibit the work station user from ignoring program-detected keying errors in subfile records.
Interpret subfile keywords (e.g., SFLCSRRRN, SFLDSP, SFLDSPCTL, SFLDROP, SFLPAG, SFLFOLD, SFLRCDNBR, SFLEND)
SFLCSRRRN (Subfile Cursor Relative Record Number)
Use this record-level keyword on the subfile control record format to return the relative record number of the record on which the cursor is located within a subfile. If the subfile records occupy more than one line, use this keyword in conjunction with the SFLMODE keyword to determine the location of the cursor.
The format of the keyword is:
SFLCSRRRN(&relative-record);
The relative-record parameter is required. It specifies the name of a hidden field that, on input, will contain the relative record number of the subfile record on which the cursor is located. The field must be defined in the subfile control record format as a signed numeric (S in position 35) field of length 5, with 0 decimal positions and usage H (hidden).
The relative-record field will contain the value 0 if the cursor is not located in the subfile associated with this subfile control record, or if the cursor is located within the subfile, but is not in an active record within the subfile. If the SFLMODE keyword is specified, the mode of the subfile will be returned in either case.
This keyword can be used on subfiles with field selection or subfiles with the SFLLIN keyword. If the cursor is located between two horizontal subfile records, the relative record number returned is 0.
Following is an example:
A R SFL01 SFL
A FLD2A 2A I 3 2
A FLD2B 30A O 3 5
A FLD2C 6A O 4 18
A R CTL01 SFLCTL(SFL01)
A SFLSIZ(25)
A SFLPAG(4)
A SFLDSP
A SFLEND
A SFLCSRRRN(&RELRCD);
A SFLMODE(&MODE);
A 10 SFLDROP(CF03)
A 11 SFLFOLD(CF03)
A RTNCSRLOC(&CSRRCD &CSRFLD);
A RELRCD 5S 0H
A MODE 1A H
A CSRFLD 10A H
A CSRRCD 10A H
SFLDSP (Subfile Display)
Use this record-level keyword on the subfile control record format so that the OS/400 program displays the subfile when your program sends an output operation to the subfile control record format. If you do not use an option indicator with this keyword, a page of subfile records is displayed on every output operation to the subfile control record format.
This keyword has no parameters.
This keyword is required and is valid only for the subfile control record format. Display size condition names are not valid for this keyword.
Option indicators are valid for this keyword.
Example:
The following example shows how to specify the SFLDSP keyword.
A R SFLR SFL
A*
A* (at least one displayable field)
A*
A R SFLCTLR SFLCTL(SFLR)
A SFLPAG(17)
A SFLSIZ(17)
A 01 SFLDSP
A SFLDSPCTL
A
The subfile is displayed when option indicator 01 is set on for an output operation to SFLCTLR.
SFLDSP (Subfile Display)
Use this record-level keyword on the subfile control record format so that the OS/400 program displays the subfile when your program sends an output operation to the subfile control record format. If you do not use an option indicator with this keyword, a page of subfile records is displayed on every output operation to the subfile control record format.
This keyword has no parameters.
See SFLRCDNBR (Subfile Record Number) keyword for display files to determine which page of subfile records is displayed when the subfile is displayed.
If your program sends an output operation to the subfile control record format when the SFLDSP keyword is in effect and the subfile is not activated (by adding records to it or by using SFLINZ), an error message is sent to your program.
This keyword is required and is valid only for the subfile control record format. Display size condition names are not valid for this keyword.
Option indicators are valid for this keyword.
Example:
The following example shows how to specify the SFLDSP keyword.
A R SFLR SFL
A*
A* (at least one displayable field)
A*
A R SFLCTLR SFLCTL(SFLR)
A SFLPAG(17)
A SFLSIZ(17)
A 01 SFLDSP
A SFLDSPCTL
A
The subfile is displayed when option indicator 01 is set on for an output operation to SFLCTLR.
SFLPAG (Subfile Page)
Use this record-level keyword on the subfile control record format to specify the number of records in the subfile to be displayed at the same time.
The format of the keyword is:
SFLPAG(number-of-records-to-be-displayed)
The SFLPAG parameter value and the number of lines required by each subfile record determine the number of actual lines required to display the page of records. Not all records within a subfile must be displayed at the same time, and not all lines of the display are required to display a page of subfile records.
This keyword is required for the subfile control record format.
Subfile page equals subfile size:
When you specify the same parameter values for SFLPAG and SFLSIZ, the maximum number of records that can be contained in the subfile equals the maximum number of subfile records that can appear on the display at one time. For this condition, the OS/400 program does not automatically page through the subfile when the Page Up or the Page Down key is pressed. If the ROLLUP and ROLLDOWN keywords are specified and one of the Page keys is pressed, the OS/400 program returns control to your program instead. If ROLLUP and ROLLDOWN are not specified, a message is sent to the workstation user, indicating that a key is not supported on the display.
If subfile size equals subfile page, the following keywords are not allowed: SFLDROP SFLFOLD SFLROLVAL
When several display sizes are used (DSPSIZ keyword specified), these keywords are ignored only for display sizes for which subfile size equals subfile page.
Field selection:
When subfile page equals subfile size, you can specify option indicators for fields in the subfile record format. This is called field selection. When field selection is used in the subfile record, SFLPAG(value) specifies the number of display lines available to display the records of this subfile. (Without field selection, SFLPAG(value) specifies the number of subfile records that can be displayed at one time.) This specification must be considered when a subfile record occupies more than one display line. The value of SFLPAG must be greater than or equal to the number of display lines occupied by the subfile.
If the subfile record format contains field selection, the following keywords are not valid on the subfile control record format: SFLDROP SFLFOLD SFLINZ SFLLIN SFLRCDNBR SFLRNA (because SFLINZ is not valid) SFLROLVAL
Subfile page does not equal subfile size:
When you specify different parameter values for SFLPAG and SFLSIZ, the OS/400 program recognizes the Page Up and Page Down keys and automatically pages through the subfile according to the value specified in the field for which the SFLROLVAL keyword is specified. If you do not specify the SFLROLVAL keyword, the OS/400 program pages through the subfile by the parameter value specified for the SFLPAG keyword except for subfiles using SFLDROP. 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 OS/400 program pages through the display by the number of records displayed in the truncated format.
Option indicators are not valid for this keyword. Display size condition names are valid. Display size condition names are required if you want the number of records that can be displayed at one time to change, based on the size of the display.
Example:
The following example shows how to specify the SFLPAG keyword.
A R SFLR SFL
A*
A* (at least one displayable field)
A*
A R SFLCTLR SFLCTL(SFLR)
A SFLPAG(17)
A SFLSIZ(17)
A SFLDSP SFLDSPCTL
A
Because the value specified for the SFLPAG keyword equals the value specified for SFLSIZ(17), subfile page equals subfile size.
SFLFOLD (Subfile Fold)
Use this record-level keyword on the subfile control record format to assign a command attention (CA) or a command function (CF) key that the workstation user can press to truncate or to fold subfile records that require more than one display line.
The format of the keyword is:
SFLFOLD(CAnn | CFnn)
When the SFLFOLD keyword is specified, the subfile is first displayed in folded form. When the workstation user presses the specified key, the OS/400 program displays the records again in truncated form. By pressing the specified key, the form of the displayed subfile changes from one state to the other. When truncated, subfile records fit on one display line.
Without SFLFOLD, the OS/400 program displays the entire subfile record folded where needed but the workstation user is not given the option to display the subfile record in truncated form.
In the folded form, as many records are displayed as are specified on the SFLPAG keyword. In the truncated form, more records are displayed than are specified on the SFLPAG keyword.
The OS/400 program truncates subfile records in the middle of output-only fields. However, if the truncation is in the middle of an input-capable field, the whole field is omitted from the display. If this results in omitting the entire record from the display, an error message is sent to the display and the record is not truncated. Instead, it is displayed in folded form.
Option indicators are valid for this keyword.
Example:
The following example shows how to specify the SFLFOLD keyword.
A R SFLR SFL A* A* (subfile records should not fit on one screen line) A R SFLCTLR SFLCTL(SFLR) A SFLPAG(17) A SFLSIZ(34) A SFLDSP SFLDSPCTL A SFLFOLD(CF03) A
When the subfile is displayed, the workstation user can press the CF03 key to change the subfile from folded to truncated form and from truncated to folded form.
SFLRCDNBR (Subfile Record Number)
Use this field-level keyword on the subfile control record format to specify that the page of the subfile to be displayed is the page containing the record whose relative record number is in this field. If you do not specify this keyword, the OS/400 program displays the first page of the subfile by default.
The format of the keyword is:
SFLRCDNBR[([CURSOR] [*TOP])]
If CURSOR is specified, the cursor is placed in the subfile record whose relative record number is identified by the contents of this field. The cursor is positioned at the first input-capable field in the subfile record. If there is no input-capable field, the cursor is positioned at the first output-only or constant field. For example, if a page can contain three records, and nine records are contained in the subfile, a SFLRCDNBR field value of 8 causes records 7, 8, and 9 to be displayed. If CURSOR is specified, the cursor appears in record 8.
If *TOP is specified, the subfile record whose relative record number is identified by the contents of this field will display as the first record of the page of the subfile records being displayed.
This field must be a zoned decimal field with zero decimal positions. It must have the keyboard shift attribute of signed numeric (S in position 35), and it can be up to 4 digits in length. It must be defined as an output-only, an output/input, or a hidden field. If a value less than 1 or a value greater than the number of records in the subfile is contained in this field on an output operation to the subfile control record format, an error is returned to your program.
This optional keyword is valid only for the subfile control record format.
You cannot specify both SFLRCDNBR and SFLROLVAL for the same field.
If the subfile record format contains field selection, this keyword is not allowed.
Option indicators are not valid for this keyword.
Example:
The following example shows how to specify the SFLRCDNBR keyword.
A R SFLR SFL
A*
A* (at least one displayable field)
A*
A R SFLCTLR SFLCTL(SFLR)
A SFLPAG(17)
A SFLSIZ(17)
A SFLDSP SFLDSPCTL
A DSPREC 4S 0B 4 12SFLRCDNBR(CURSOR)
A
In this example, either the program or the workstation user can set the value of the field before displaying the subfile.
SFLEND (Subfile End)
Use this record-level keyword on the subfile control record format to permit the display of a plus sign (+) or text (More... or Bottom) in the lower right display location occupied by the subfile or a scroll bar. The plus sign or More... text indicates that the workstation user can move the text lines on the subfile to display more records by pressing the Page Up key.
The format of the keyword is:
SFLEND[(*PLUS | *MORE | {*SCRBAR [*SCRBAR | *PLUS |*MORE ]})]
The scroll bar indicates different types of information about the subfile:
* Where the user is at in the subfile * How big the subfile is * What proportion of the subfile the user is viewing
If the device configuration that is being used supports a pointer device, the scroll bar can also navigate through the subfile. For more information on how to support different device configurations, see the Application Display Programming Link to PDF book.
The parameter values *PLUS, *SCRBAR, and *MORE are optional. If no parameter is specified, *PLUS is used. The second set of *PLUS, *MORE, and *SCRBAR can only be specified if *SCRBAR is specified as the first parameter. *SCRBAR is the default for the second parameter.
- PLUS tells the system to use the plus sign to indicate that you can use the Page Down key to see more records.
- MORE tells the system to use the More... text to indicate that you can use the Page Down key to see more records. *MORE also tells the system to use the Bottom text to indicate that the last subfile record is displayed.
When *MORE is specified, the subfile takes up one more line on the screen (SFLPAG + 1). This line is needed for the text, More... and Bottom. If there is not room for the extra line on the display or in a window, a message is issued at file creation time and the file is not created.
- SCRBAR tells the system to use a graphical scroll bar for a graphical display. When *SCRBAR is specified, the last 3 columns of the lines that the subfile is using is reserved for the scroll bar. When *SCRBAR is used, a second parameter can be specified. The second parameter tells the system what scrolling indicator should be used for nongraphical displays. *SCRBAR is the default for those displays. *MORE and *PLUS can be used for the second parameter. When *SCRBAR is used the subfile must occupy at least 3 lines. SFLFOLD or SFLDROP will work with scroll bars. Both versions of the subfile (folded or truncated) must occupy three lines.
An option indicator must be specified for this keyword.
Paging through your program (SFLPAG equals SFLSIZ)
Your program controls the display of the plus sign or the More... or Bottom text through the use of the indicators on SFLEND. Set the indicators off to display the plus sign or the More text. Set the indicators on to remove the plus sign from the display or to display the Bottom text. When the Page Up key is pressed, your program handles processing. For instance, it reads the subfile, clears it, then rewrites the subfile with new records and displays it again. If your program does this, show the plus sign or the More text. If not, remove the plus sign from the display or show the Bottom text.
Paging through the OS/400 program (SFLPAG does not equal SFLSIZ)
The OS/400 program displays the plus sign as long as there are more records in the subfile to be displayed, no matter how the option indicator is set. The scroll bar will display with the scroll box placed on the scroll shaft that best represents where the user is in the subfile. When the last page of the subfile is displayed, the OS/400 program displays the plus sign, More text, or the scroll bar with the scroll box one page size above the scroll button if the indicator is off. It does not display the plus sign, displays the Bottom text, or displays the scroll bar with the scroll box on top of the bottom scroll button if the indicator is on.
Your program must set the indicator on or off when displaying the subfile. (Your program cannot find out, when the OS/400 program is paging through the subfile, which page of the subfile is displayed.)
If your program sets off the indicator for SFLEND when displaying the subfile, either the plus sign, the More text, or the scroll bar with the scroll box one page size above the scroll button is displayed with the last page of the subfile. Because the plus sign is displayed but the OS/400 program cannot page the subfile any further, your program must provide for any further paging. Specify the PAGEDOWN keyword on the subfile control record format so that control is passed to your program when the Page Down key is pressed again. When your program receives control, it can add more records to the end of the subfile and use the SFLRCDNBR keyword to display a new page.
Position of plus sign with *PLUS option
For the 24 x 80 display size, positions 78 through 80 of the last line occupied by the subfile are used for the beginning attribute character, plus sign, and ending attribute character. For the 27 x 132 display size, positions 130 through 132 of the last line occupied by the subfile are used for the beginning attribute character, plus sign, and ending attribute character. Note: If an input field occupies the location of the plus sign and the field is changed, the plus sign and its attribute characters are returned to the program as data in the field. For selection lists, the plus will be positioned to the right of the choices for the list.
Position of More... and Bottom text with *MORE option
For the 24 x 80 display size, positions 67 through 80 of the line immediately following the last line occupied by the subfile are used for the beginning attribute character, right justified More... or Bottom text, and ending attribute character. For the 27 x 132 display size, positions 119 through 132 of the line immediately following the last line occupied by the subfile are used for the beginning attribute character, right justified More... or Bottom text, and ending attribute character. For selection lists, the more and bottom text will be positioned to the right of the choices for the list.
Position of the scroll bar with *SCRBAR option
For the 24 x 80 display size, positions 77 through 80 of every line of the subfile will be reserved for the scroll bar. No fields of the subfile can use those columns. Thus no fields can occupy more than one line of the subfile. Multiple line subfiles can be used. For the 27 x 132 display size, positions 129 through 132 of every line of the subfile will be reserved for the scroll bar. For selection lists, the scroll bar will be positioned to the right of the choices for the list. For other subfiles, the scroll bar will be positioned on column 79.
Example 1:
The following example shows how to specify the SFLEND keyword without parameters.
A R SETSFL1 SFL
A 50 SFLNXTCHG
A SETSEL 1Y 0B 6 2VALUES(1 2 9) CHECK(AB)
A SETNAME 10A O 6 4
A R SETCTL1 SFLCTL(SETSFL1)
A SFLSIZ(34)
A SFLPAG(17)
A 40 SFLDSP
A 41 SFLDSPCTL
A 42 SFLDLT
A 43 SFLCLR
A 49 SFLEND
A N49 ROLLUP(26)
A SETRRN 4S 0H SFLRCDNBR(CURSOR)
A
Paging is provided by the OS/400 program and the plus sign (+) appears in the lower right corner of the display. When the last record is written to the subfile, indicator 49 is set on, which disables the Page Down key and omits the plus sign from the display.
Example 2:
The following example shows how to specify the SFLEND keyword with *MORE as a parameter.
A R SETSFL2 SFL
A 50 SFLNXTCHG
A SETSEL 1Y 0B 6 2VALUES(1 2 9) CHECK(AB)
A SETNAM 10A O 6 4
A R SETCTL2 SFLCTL(SETSFL2)
A SFLSIZ(34)
A SFLPAG(17)
A 40 SFLDSP
A 41 SFLDSPCTL
A 42 SFLDLT
A 43 SFLCLR
A 49 SFLEND(*MORE)
A N49 ROLLUP(26)
A SETRRN 4S 0H SFLRCDNBR(CURSOR)
A
Paging is provided by the OS/400 program. The More... text appears at the lower right corner of the display on the line immediately following the subfile if there are more records to see in the subfile. When the last record is written to the subfile, indicator 49 is set on, which disables the Page Down key and causes the Bottom text to appear instead of More....
Example 3:
The following example shows how to specify the SFLEND keyword with *SCRBAR as a parameter.
A R SETSFL2 SFL
A 50 SFLNXTCHG
A SETSEL 1Y 0B 6 2VALUES(1 2 9) CHECK(AB)
A SETNAM 10A O 6 4
A R SETCTL2 SFLCTL(SETSFL2)
A SFLSIZ(34)
A SFLPAG(17)
A 40 SFLDSP
A 41 SFLDSPCTL
A 42 SFLDLT
A 43 SFLCLR
A 49 SFLEND(*SCRBAR *MORE)
A N49 ROLLUP(26)
A SETRRN 4S 0H SFLRCDNBR(CURSOR)
A
Paging is provided by the OS/400 program. The scroll bar will be displayed for graphical displays. If a graphical display is not used, then the More.... text appears at the lower right corner of the display on the line immediately following the subfile if there are more records to see in the subfile. When the last record is written to the subfile, indicator 49 is set on, which disables the Page Down key and causes the Bottom text to appear instead of the More.... text. The scroll bar will be displayed with the scroll box just above the bottom scroll button.
SFLDROP (Subfile Drop)
Use this record-level keyword on the subfile control record format to assign a command attention (CA) or a command function (CF) key that the workstation user can press to fold or to truncate subfile records that require more than one display line. The format of the keyword is:
SFLDROP(CAnn | CFnn)
The following example shows how to specify the SFLDROP keyword.
A R SFLR SFL
A*
A* (subfile records should not fit on one screen line)
A*
A R SFLCTLR SFLCTL(SFLR)
A SFLPAG(17)
A SFLSIZ(34)
A SFLDSP SFLDSPCTL
A SFLDROP(CF03)
When the subfile is displayed, the workstation user can press the CF03 key to change the subfile from truncated to folded form and from folded to truncated form.
