ASNA Wings™ Subfile Controls

A subfile is the view mechanism IBM i Display Files use to show one or more file records. A subfile appears as a rectangular area of the screen; their apperance and function is very similar to a .NET GridView. Each record is displayed on one or more rows in the subfile. Each Subfile in Wings is represented by both a DdsSubfile control and a DdsSubfileControl control.

• A subfile record format (DdsSubfile control).
  The subfile record format control serves as a container for the fields in one row of the subfile. The RPG program uses the subfile record format to read a subfile, write new records to a subfile, and update the subfile. Operations on the subfile record format are performed between the subfile and RPG program; the mobile device screen is not changed by operations on a subfile record format.
• A subfile control record format (DdsSubfileControl control).
  The subfile control record format is a container for the subfile. Additionally, it contains heading information and controls subfile functions such as size, initialization, and clearing. The RPG program performs operations on the subfile control record format to write the subfile to the mobile device screen and to read the subfile from the screen. Some of the most important properties of the subfile control are:
• SubfileSize — specifies the size of the subfile.
• SubfilePage — specifies the number of records in the subfile to be displayed simultaneously.
• DisplayRecords — specifies when to begin displaying records in a subfile.
• ClearRecords — specifies when the subfile will be clear of all records before new records are to be written.
• DisplayFields — specifies if the fields in the Subfile Control, not the actual subfile records are to be shown on the screen.

As rendered in a Wings Display File, Subfiles and Subfile Controllers resemble the following:

When a Subfile is displayed in a Terminal, a cursor is used to indicate the current on-screen position. This position (expressed as a {row,col} pair) is available to the application code to determine which record (or field within the record) the user wishes to change (or select) via the screen cursor. 5250 interfaces often let users call up further information or perform other processes based on this position.

Several characteristics of subfiles are controlled by another display file element called a "Subfile Controller". In addition to parameters that control the subfile, the Subfile Controller may have fields to be displayed on the screen above or below the subfile (to act as a header or footer).

When a Display File is modernized into a Wings web page, the subfile element becomes a division (<div>) of the HTML document. The Subfile <div> is sub-divided vertically into rows, each becoming another division (<div>) element.

Wings allows uses of subfiles that neatly parallel the ways they can be interacted with on a green-screen:

1. There are two visual indications to assist with record selection (regardless of input field usage):
   • As the mouse "hovers" on the subfile rows, a new style is applied to the row. By default the background color changes and the rectangle around the row is rounded. Even if the application does not require the user to select a record, the row highlight is helpful for reading related fields (much like the rulers used by accountants when working on ledgers).
   • If a row is clicked, a different style is applied and the "current record" is set. Even if the mouse is moved outside the subfile, the current record is remembered (as indicated by the unique style). The "current record" selection is only changed if there is a new mouse click in a different position. If the field clicked is outside the subfile, then the current subfile record status is lost (the subfile is no longer active).
2. When an Aid Key (or a button that pushes a Key with an Aid Key code) is pressed, if any of the subfiles had the "current record" set, the Workstation feedback information (regarding Cursor position) will be populated. The Cursor position will contain the Row, Col values corresponding to the mouse position when the selection happened (converted to virtual coordinates, which are character positions as defined by the DDS file).
3. Mouse double-click events on the subfile are also detected, allowing the user to:
   • Change a value on any field of the selected subfile record.
   • After the field's value has been changed, submit the Page with a specific Aid Key code.
4. Subfiles now support scrollbars to simulate the PgUp and PgDn keys.

These effects may be enabled, disabled, or customized on any subfile using new properties that have been added to support subfiles and the grids they appear on. An example of how to use these properties to change the look of a subfile is provided here. Wings (via properites of the Monarch Framework) allows the use of most of the subfile related DDS keywords available in RPG ILE, as detailed in the chart below.

Subfile Keywords

Supported	Supported in future release	Not applicable
SFL	SFLRNA	SFLCSRPRG
SFLCLR		SFLDLT
SFLCTL		SFLENTER
SFLCSRRRN		SFLROLVAL
SFLDROP		SFLSCROLL
SFLDSP
SFLDSPCTL
SFLEND
SFLFOLD
SFLINZ
SFLLIN
SFLMODE
SFLMSG
SFLMSGID
SFLMSGKEY
SFLRCDNBR
SFLSMGRCD
SFLNXTCHG
SFLPAG
SFLPGMQ
SFLSIZ