The TBDISPL service combines information from a panel definition with information stored in an ISPF table. It displays all or certain rows from the table, allowing the application user to scroll the information up and down.
When only certain rows from a table are to be displayed, the TBSARG service is used to define the selection criteria before issuing TBDISPL. Only search arguments established by TBSARG that specify a forward scan through the table (for example, TBSARG specifying the keyword NEXT, either explicitly or implicitly) should be used. In this case, ROWS(SCAN) must be specified on the )MODEL statement in the panel definition.
TBDISPL can produce a display of a table based on a search argument that specifies a backward scan; that is, PREVIOUS on the TBSARG request and ROWS(SCAN) specified on the )MODEL header statement. This would display the table from bottom to top. Top to bottom is the normal table display. However, because TBDISPL does not support scrolling for the bottom-to-top case, scrolling results are unpredictable.
The format of the display is specified by a panel definition, which TBDISPL reads from the panel library. The panel definition specifies the fixed (non-scrollable) portion and the scrollable portion of the display. The fixed portion contains the command field and commonly the scroll amount field. It can also include other input fields as well as text, output fields, dynamic areas and a graphic area.
The scrollable portion is defined by up to eight "model" lines. They indicate which table fields are to be displayed.
Each line of scrollable data can have one or more input (unprotected) fields, as well as text and output (protected) fields. The user can modify the input fields in the scrollable or fixed portions.
Before TBDISPL is invoked, the table to be displayed must be open, such as TBOPEN, and the current row pointer (CRP) positioned to the row at which the display is to begin, such as TBTOP (automatic following TBOPEN), TBBOTTOM, or TBSKIP. When CRP is pointing to the top of the table, it has a value of 0. It is treated as though the CRP were pointing to the first row. Do not attempt to use TBDISPL to display a command table currently in use. This might produce unpredictable results.
The scrollable portion of the display is formed by replicating the model lines from the panel definition enough times to fill the screen. Each of these replications is known as a model set. Table rows are then read to fill in the appropriate fields in the model set replications. Each table row corresponds to a model set.
The table that is displayed in a panel's scrollable area can be built dynamically by the application. This is useful for applications involving large amounts of data that users might wish to access to varying extents. The application can provide a relatively small table as a starter, then expand the table as users scroll beyond the top or bottom table row.
When the user enters data into a model set, the corresponding table row is said to be selected for processing. The user can select several rows. The data must be modified to select the model set. If you simply overtype the existing model set with the same data, the model set is not considered to be selected.
TBDISPL itself does not modify the table. The dialog function can use the information entered by the user to determine what processing is to be performed, and can modify the table accordingly.