Test268 Section 2

From MidrangeWiki
Revision as of 15:41, 23 October 2006 by Kjburkhalter (talk | contribs) (Create and maintain subfiles and programs that use those subfiles (DDS and RPG))
Jump to: navigation, search

<< Previous Section | Home | Next Section >>

Section 2 - Subfiles (8%)

Code and use subfiles

Example of a subfile with SFLPAG value equal to SFLSIZ value

The following display is defined by the DDS in the following example. It is displayed by an output operation to the subfile control-record format SFLCTL1.

 +--------------------------------------------------------------------------------+
 |                                                                                |
 |         First Field     Second Field                                           |
 |                                                                                |
 |                         XXXXXXXXXXXXXXXXXXXX                                   |
 |                         XXXXXXXXXXXXXXXXXXXX                                   |
 |                         XXXXXXXXXXXXXXXXXXXX                                   |
 |                         XXXXXXXXXXXXXXXXXXXX                                   |
 |                         XXXXXXXXXXXXXXXXXXXX                                   |
 |                         XXXXXXXXXXXXXXXXXXXX                                   |
 |                         XXXXXXXXXXXXXXXXXXXX                                   |
 |                         XXXXXXXXXXXXXXXXXXXX                                   |
 |                         XXXXXXXXXXXXXXXXXXXX                                   |
 |                         XXXXXXXXXXXXXXXXXXXX                                   |
 |                         XXXXXXXXXXXXXXXXXXXX                                   |
 |                         XXXXXXXXXXXXXXXXXXXX                                   |
 |                         XXXXXXXXXXXXXXXXXXXX                                   |
 |                         XXXXXXXXXXXXXXXXXXXX                                   |
 |                         XXXXXXXXXXXXXXXXXXXX                                   |
 |                         XXXXXXXXXXXXXXXXXXXX                                   |
 |                         XXXXXXXXXXXXXXXXXXXX                                   |
 |                         XXXXXXXXXXXXXXXXXXXX                                   |
 |                                                                                |
 |                                                                                |
 +--------------------------------------------------------------------------------+

The following keywords are important in the example: ROLLDOWN ROLLUP SFLCLR SFLDSP SFLDSPCTL SFLPAG SFLSIZ

The file in Figure 8 has one column of subfile records. Constant fields in the subfile control-record format are used as headings for columns of fields in the subfile records.

 A* USE OF SUBFILE KEYWORDS
 A   (1)    R SFL1                      SFL
 A   (2)      FLD1          10  0I  3 11
 A   (2)      FLD2          16   O  3 26
 A
 A   (1)    R SFLCTL1                   SFLCTL(SFL1)
 A                                      SFLSIZ(18)     (3)
 A                                      SFLPAG(18)     (3)
 A  05                                  SFLDSP         (4)
 A  05                                  SFLDSPCTL      (4)
 A N05                                  SFLCLR         (5)
 A                                      ROLLUP(01) ROLLDOWN(02)(6)
 A                                  1 11'First Field'   (7)
 A                                  1 26'Second Field'  (7)
 A

Legend:

(1)The subfile record format SFL1 and the subfile control-record format SFLCTL1 together define one subfile. The parameter value for the SFLCTL keyword is the name of the subfile record format.

(2)Each subfile record is made up of two fields: FLD1 and FLD2. FLD1 is 10 bytes long (11 bytes display length because it defaults to signed numeric); FLD2 is 16 bytes long. FLD1 is an input-only field; FLD2 is an output-only field. Eighteen subfile records would appear on the display, with the first one on line 3 and the last one on line 20. For each subfile record on the display, two fields (FLD1 and FLD2) would appear, with four spaces between FLD1 and FLD2.

(3)SFLSIZ and SFLPAG (required keywords) have equal values (18). Therefore one page equals the whole subfile. For all subfiles, the value of the SFLPAG keyword is the number of subfile records displayed at any one time (unless the SFLDROP keyword or variable-length records are used).

(4)SFLDSP (a required keyword) and SFLDSPCTL (an optional keyword) are specified with indicator 05. Therefore, when indicator 05 is set on, the subfile and subfile control records can be displayed by an output operation to the subfile control-record format SFLCTL1.

(5)SFLCLR (an optional keyword) is specified with option indicator 05 preceded by an N. When indicator 05 is set off, the subfile can be cleared by an output operation to SFLCTL1.

(6)ROLLUP (an optional keyword) is specified with response indicator 01, and ROLLDOWN (an optional keyword) is specified with response indicator 02. Note also that the entire subfile equals one page, which means that the whole subfile is displayed at one time. Therefore, when the display station user presses the Page Up key, control passes to the program with indicator 01 on, and when the work station user presses the Page Down key, control passes to the program with indicator 02 on. The program must handle paging, by reading, clearing, rewriting, and redisplaying the subfile. Without ROLLUP and ROLLDOWN specified, the work station user would receive an error message when pressing the Page Up or Page Down key.

(7)Two constants ('First Field' and 'Second Field') are displayed when the subfile control-record is displayed (SFLDSPCTL in effect). As specified in this subfile, they act as column headings to the subfile records.


Example of a subfile with paging by OS/400 program and high-level language program

The following example describes a combined method of paging a subfile that uses system resources efficiently. In some applications, the number of records in the subfile could be quite large. However, the application user may want to view only the first page or two of these records. In this case, it may be faster and more efficient for the application program to build the subfile a page at a time as requested by the user. The OS/400 program handles the paging of records in the subfile. It also returns a Page Up key indicator to the high-level language program when another page should be added to the end of the subfile. The application user can detect no difference between a page up request handled by the OS/400 program and one handled by the high-level language program.

 +--------------------------------------------------------------------------------+
 |                                                                                |
 |NAME                               DEPARTMENT     PHONE                         |
 |                                                                                |
 |XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX     XXXXXXXXXX     NNNN                          |
 |XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX     XXXXXXXXXX     NNNN                          |
 |XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX     XXXXXXXXXX     NNNN                          |
 |XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX     XXXXXXXXXX     NNNN                          |
 |XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX     XXXXXXXXXX     NNNN                          |
 |XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX     XXXXXXXXXX     NNNN                          |
 |XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX     XXXXXXXXXX     NNNN                          |
 |XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX     XXXXXXXXXX     NNNN                          |
 |XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX     XXXXXXXXXX     NNNN                          |
 |XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX     XXXXXXXXXX     NNNN                          |
 |XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX     XXXXXXXXXX     NNNN                          |
 |XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX     XXXXXXXXXX     NNNN                          |
 |XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX     XXXXXXXXXX     NNNN                          |
 |XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX     XXXXXXXXXX     NNNN                          |
 |XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX     XXXXXXXXXX     NNNN                          |
 |XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX     XXXXXXXXXX     NNNN                          |
 |XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX     XXXXXXXXXX     NNNN                          |
 |                                                                                |
 |                                                                                |
 +--------------------------------------------------------------------------------+

The following keywords are important in the example: SFLPAG SFLSIZ

The SFLSIZ value is larger than the SFLPAG value. The subfile is paged by the SFLPAG value.

Figure 9. Subfile with Paging by OS/400 Program and High-Level Language Program in DDS

 A          R SETSFL                    SFL
 A  50                                  SFLNXTCHG
 A            NAME          30   0  5  2
 A            DEPT          10      5 40
 A            PHONE          4   0  5 58
 A          R SETCTL                    SFLCTL(SETSFL)
 A                                      SFLSIZ(0034)     (1)
 A                                      SFLPAG(0017)
 A  40                                  SFLDSP
 A  41                                  SFLDSPCTL
 A  42                                  SFLDLT
 A  43                                  SFLCLR
 A  49                                  SFLEND           (2)
 A N49                                  ROLLUP(26)
 A                                      LOCK
 A                                      OVERLAY
 A            SETRRN         4S 0H      SFLRCDNBR(CURSOR)(3)
 A                                  3  2'NAME'
 A                                  3 40'DEPARTMENT'
 A                                  3 58'PHONE'
 A

Legend:

(1)The SFLSIZ value must be greater than the SFLPAG value so that the OS/400 program will handle paging within the subfile. A maximum of 9 999 records can be stored in the subfile.

(2)The SFLEND keyword can be specified with the ROLLUP keyword. One indicator can be used to option both keywords. The application program turns on the indicator to disable the Page Up key and omit the plus sign (+) on the last subfile page when the last page of the subfile is displayed.

(3)The SFLRCDNBR keyword should be specified so the last subfile page can be displayed after it is built by the high-level language program.

Records in the subfile with changed input fields (modified data tags) will be changed after a new page is added to the subfile by the high-level language program.

Create and maintain subfiles and programs that use those subfiles (DDS and RPG)

DDS code example:

    A*
    A                                      DSPSIZ(24 80 *DS3)
    A                                      PRINT
    A                                      ERRSFL
    A                                      CA03
    A                                      CA12
    A*
    A          R SFL1                      SFL
    A*
    A            DBLNAM    R        O  5  2REFFLD(PFR/DBLNAM *LIBL/SFL001PF)
    A            DBFNAM    R        O  5 26REFFLD(PFR/DBFNAM *LIBL/SFL001PF)
    A            DBMINI    R        O  5 50REFFLD(PFR/DBMINI *LIBL/SFL001PF)
    A            DBNNAM    R        O  5 55REFFLD(PFR/DBNNAM *LIBL/SFL001PF)
    A*
    A          R SF1CTL                    SFLCTL(SFL1)
    A*
    A                                      SFLSIZ(0500)
    A                                      SFLPAG(0017)
    A                                      OVERLAY
    A N32                                  SFLDSP
    A N31                                  SFLDSPCTL
    A  31                                  SFLCLR
    A  90                                  SFLEND(*MORE)
    A            RRN1           4S 0H      
    A                                  4  2'Last Name'
    A                                      DSPATR(HI)
    A                                  4 26'First Name'
    A                                      DSPATR(HI)
    A                                  4 50'MI'
    A                                      DSPATR(HI)
    A                                  4 55'Nick Name'
    A                                      DSPATR(HI)
    A                                  1  2'SFL001RG'
    A                                  1 27'Simple Subfile Program'
    A                                      DSPATR(HI)
    A                                  1 71DATE
    A                                      EDTCDE(Y)
    A                                  2 71TIME
    A*
    A          R FKEY1
    A*
    A                                 23  2'F3=Exit'
    A                                      COLOR(BLU)
    A                                 23 12'F12=Cancel'
    A                                      COLOR(BLU)




RPG code example:

     *=======================================================================
    Fsfl001df  cf   e             workstn
    F                                     sfile(sfl1:rrn1)
    Fsfl001lf  if   e           k disk
     *
     *****************************************************************
     *  Main Routine
     *****************************************************************
     *
     * Build the subfile
     *
    C                   exsr      sflbld
     *
     * Do loop to process the subfile until F3 or F12 is pressed
     *
    C                   dou       *inkc or *inkl
     *
    C                   write     fkey1
    C                   exfmt     sf1ctl
     *
    C                   enddo
     *
    C                   eval      *inlr = *on
     *
     *****************************************************************
     *  SFLBLD - Build the List
     *****************************************************************
     *
    C     sflbld        begsr
     *
     *  Clear subfile
     *
    C                   eval      rrn1 = *zero
    C                   eval      *in31 = *on
    C                   write     sf1ctl
    C                   eval      *in31 = *off
     *
     * Load data to subfile
     *
    C     *loval        setll     sfl001lf
    C                   read      sfl001lf                               90
    C                   dow       (not *in90) and (rrn1 <= 500)
    C                   eval      rrn1 = rrn1 + 1
    C                   write     sfl1
    C                   read      sfl001lf                               90
    C                   enddo
     *
     * If no records were loaded, do not display the subfile
     *
    C                   if        rrn1 = *zero
    C                   eval      *in32 = *on
    C                   else
    C                   z-add     1             rrn1
    C                   endif
     *
    C                   endsr

Determine the relationship between page size and subfile size

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.

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.

Apply appropriate methods for accessing and updating subfile records

<< Previous Section | Home | Next Section >>