7.27.1 DISPLAY Parameters
Specifies either the field(s) that are to be displayed at the workstation or the name of a group that specifies the field(s) to be displayed. Alternatively, an expandable group expression can be entered in this parameter.
|
Portability Considerations |
Visual LANSA has multi-page and field spanning line restrictions: Multi-page data (i.e. if the screen format is larger than one page) can be displayed in a Web browser window but NOT in a LANSA function. Field spanning (i.e. when the field is larger than one line on the screen) is not supported - only a single line will be displayed. No error or warning is issued. |
Specifies the design/positioning method which should be used for fields that do not have specific positioning attributes associated with them.
*IDENTIFY, which is the default value, indicates that the design method should be the default method associated with the IDENTIFY parameter. Refer to the table in the Comments section for more details.
*DOWN indicates that the fields should be designed "down" the screen in a column.
*ACROSS indicates that fields should be designed "across" the screen in a row.
Specifies the default identification method to be used for fields that do not have a specific identification attribute associated with them.
*DESIGN, which is the default value, indicates that the fields should be identified by the default method associated with the DESIGN parameter. See the table in the comments section for more details.
*LABEL indicates that fields should be identified by their associated labels on the screen.
*DESC indicates that fields should be identified by their associated descriptions on the screen.
*COLHDG indicates that fields should be identified by their associated column headings on the screen.
*NOID indicates that no identification of the field is required. Only the field itself should be included into the screen design.
Specifies display attributes that are to be associated with identification text (labels, descriptions, column headings, etc) that are displayed on the screen.
*DEFAULT, which is the default value, indicates that the system defaults for identification display attributes should be adopted. They are set up in the system definition block as overall system default values. Refer to The System Definition Data Areas in the and how to change it.
*NONE indicates that identification text should have no special display attributes associated with it.
Otherwise, specify one or more of the values: *HI (high intensity), *RI (reverse image) and *UL (underline).
This parameter is ignored in SAA/CUA processes in SAA/CUA compliant partitions. In such partitions the attributes are determined from the partition wide standards for labels and column headings.
Specifies the spacing between rows on the display that should be used when automatically designing a screen. The value specified must be *DESIGN or a number in the range 1 to 10. Refer to the table in the Comments section for details of what value *DESIGN is actually specifying.
Specifies the spacing between columns on the display that should be used when automatically designing a screen. The value specified must be *DESIGN or a number in the range 1 to 10. Refer to the table in the Comments section for details of what value *DESIGN is actually specifying.
Specifies the name of a browse list which is also to be included into the screen format, and optionally, the number of entries of the browse list that should appear in the screen panel.
*NONE indicates that no browse list is required. The screen designed will not have any browse component.
If a browse list is specified, then you may also specify the number of entries from the browse list that are to appear on the screen panel. This may leave space below the browse list for other details (which can be overlaid by a subsequent screen). The default of 999 entries indicates that the browse list should extend to the logical bottom of the screen panel.
If a browse list is specified it must be defined elsewhere in the RDML program with a DEF_LIST (define list) command.
Specifies the following things about the EXIT function key:
- Whether the EXIT function key is to be enabled.
- What is to happen when the EXIT function key is used.
- In SAA/CUA partitions, which EXIT function key is required.
- A condition to control when the EXIT function key is enabled.
By default the EXIT function key is enabled. To disable the EXIT function key specify *NO as the first value for this parameter.
If the EXIT function key is enabled, you may specify what happens when it is used. The allowable values for this second component of the EXIT_KEY parameter are as follows:
|
*EXIT |
The application should exit completely from LANSA (identical to executing an EXIT command). |
|
*MENU |
The process's main menu should be re-displayed (identical to executing a MENU command). |
|
*NEXT |
Indicates that control should be passed to the next command. |
|
*RETURN |
Specifies that in a program mainline control is to be returned to the caller and in a subroutine control is to be returned to the caller routine or the program mainline. |
If none of the previous values are used you must nominate a valid command label to which control should be passed.
The value *EXIT is the default for this parameter value.
The default value is *HIGH for this parameter value.
The final value that can be specified for this parameter allows a condition to be named to control when the function key should be enabled. The default value is *NONE that indicates no condition should apply. The function key will be enabled according to the normal rules.
If a condition name is specified it must be defined within the RDML program by a DEF_COND (define condition) command.
Note: In SAA/CUA applications it is recommended that only the following 2 variations of the EXIT_KEY parameter are used:
EXIT_KEY(*YES *EXIT *HIGH) in a "main program"
*
EXIT_KEY(*YES *RETURN *LOW) in "subroutines"
Specifies whether the MENU function key is to be enabled when this screen format is displayed at the workstation. In addition it also specifies what is to happen if the MENU key is used.
*NO indicates that the MENU function key should not be enabled when the screen is displayed.
*YES, which is the default value, indicates that the MENU key should be enabled when the screen is displayed. If *YES is used it is also possible to specify the action to be taken when the menu key is used.
*MENU, the default value, specifies that the process's main menu should be re-displayed. *EXIT specifies that the application should exit completely from LANSA.
*NEXT indicates that control should be passed to the next command.
*RETURN specifies that in a program mainline control is to be returned to the caller and in a subroutine control is to be returned to the caller routine or the program mainline.
If none of the previous values are used you must nominate a valid command label to which control should be passed.
The final value that can be specified for this parameter allows a condition to be named to control when the function key should be enabled. The default value is *NONE that indicates no condition should apply. The function key will be enabled according to the normal rules.
If a condition name is specified it must be defined within the RDML program by a DEF_COND (define condition) command.
Specifies whether the ADD function key is to be enabled when this screen format is displayed at the workstation. In addition it also specifies what is to happen if the ADD key is used.
*NO, which is the default value, indicates that the ADD function key should not be enabled when the screen is displayed.
*YES indicates that the ADD key should be enabled when the screen is displayed. If *YES is used it is also possible to nominate a command label to which control should be passed when the ADD key is used.
*NEXT indicates that control should be passed to the next command.
*RETURN specifies that in a program mainline control is to be returned to the caller and in a subroutine control is to be returned to the caller routine or the program mainline.
If none of the previous values are used you must nominate a valid command label to which control should be passed.
The final value that can be specified for this parameter allows a condition to be named to control when the function key should be enabled. The default value is *NONE that indicates no condition should apply. The function key will be enabled according to the normal rules.
If a condition name is specified it must be defined within the RDML program by a DEF_COND (define condition) command.
Specifies whether the CHANGE function key is to be enabled when this screen format is displayed at the workstation. In addition it also specifies what is to happen if the CHANGE key is used.
*NO, which is the default value, indicates that the CHANGE function key should not be enabled when the screen is displayed.
*YES indicates that the CHANGE key should be enabled when the screen is displayed. If *YES is used it is also possible to nominate a command label to which control should be passed when the CHANGE key is used.
*NEXT indicates that control should be passed to the next command.
*RETURN specifies that in a program mainline control is to be returned to the caller and in a subroutine control is to be returned to the caller routine or the program mainline.
If none of the previous values are used you must nominate a valid command label to which control should be passed.
The final value that can be specified for this parameter allows a condition to be named to control when the function key should be enabled. The default value is *NONE that indicates no condition should apply. The function key will be enabled according to the normal rules.
If a condition name is specified it must be defined within the RDML program by a DEF_COND (define condition) command.
Specifies whether the DELETE function key is to be enabled when this screen format is displayed at the workstation. In addition it also specifies what is to happen if the DELETE key is used.
*NO, which is the default value, indicates that the DELETE function key should not be enabled when the screen is displayed.
*YES indicates that the DELETE key should be enabled when the screen is displayed. If *YES is used it is also possible to nominate a command label to which control should be passed when the DELETE key is used.
*NEXT indicates that control should be passed to the next command.
*RETURN specifies that in a program mainline control is to be returned to the caller and in a subroutine control is to be returned to the caller routine or the program mainline.
If none of the previous values are used you must nominate a valid command label to which control should be passed.
The final value that can be specified for this parameter allows a condition to be named to control when the function key should be enabled. The default value is *NONE that indicates no condition should apply. The function key will be enabled according to the normal rules.
If a condition name is specified it must be defined within the RDML program by a DEF_COND (define condition) command.
Specifies whether the PROMPT function key is to be enabled when this screen format is displayed at the workstation. In addition it also specifies what is to happen if the PROMPT key is used.
*DFT, which is the default value, indicates that the PROMPT function key should be enabled or disabled automatically according to its default value defined in the system definition data area DC@A01. Refer System Definition Data Area DC@A01 in the for more information about this default value.
*YES indicates that the PROMPT key should be enabled when the screen is displayed.
*NO indicates that the PROMPT key should NOT be enabled when the screen is displayed.
In any case, when the PROMPT function key is enabled (either by specifying *DFT or *YES for the first part of this parameter), it is possible to also specify what is to happen if the function key is used. Allowable values for this part of the parameter are:
*AUTO indicates that the prompt key processing should be handled automatically by LANSA. Before attempting to use this option, refer to Prompt Key Processing.
*NEXT indicates that control should be passed to the next command.
*RETURN specifies that in a program mainline control is to be returned to the caller and in a subroutine control is to be returned to the caller routine or the program mainline.
If none of the previous values are used you must nominate a valid command label to which control should be passed.
The final value that can be specified for this parameter allows a condition to be named to control when the function key should be enabled. The default value is *NONE that indicates no condition should apply. The function key will be enabled according to the normal rules.
If a condition name is specified it must be defined within the RDML program by a DEF_COND (define condition) command.
Specifies up to 5 additional user function keys that can be enabled when the screen format is displayed at the workstation.
Any user function keys assigned must not conflict with function keys assigned to the standard LANSA functions of EXIT, MENU, MESSAGES, PROMPT, ADD, CHANGE or DELETE when they are enabled on a command (ie: a function key cannot be assigned to more than one function).
Additional user function keys are specified in the format:
|
'description' |
|||
|
|
|
||
|
|
|
|
where -
|
Fnc key number: |
Is the function key number in the range 1 to 24 or one of the special values *ROLLUP (roll up key) or *ROLLDOWN (roll down key). |
|
'description' |
Is a description of the function assigned to the function key. This description will be displayed on line 23 of the screen format. Maximum length is 8 characters. |
|
*NEXT |
Is the default and indicates that the next command (after this one) should receive control. |
|
*RETURN |
Indicates that in a program mainline control is to be returned to the caller and in a subroutine control is to be returned to the caller routine or the program mainline. |
|
Label |
Indicates the command label to which control should be passed if the command key is used. |
|
*NONE |
Indicates that no condition applies to control when the function key is to be enabled or disabled. |
|
Cond name |
Indicates that a condition defined by a DEF_COND command should be evaluated to determine whether to enable or disable the function key. |
Refer to the IF_KEY command for details of how the function key that was used can be tested in the RDML program.
As an example of use consider the following:
DISPLAY FIELDS(#PRODUCT) USER_KEYS((14 'Commit')(15 'Purge'))
IF_KEY WAS(*USERKEY1)
* << Commit logic >>
ENDIF
IF_KEY WAS(*USERKEY2)
* << Purge logic >>
ENDIF
Note: The IF_KEY command refers to the keys by symbolic names that indicate the order they are declared in the USER_KEYS parameter, not the actual function key numbers assigned to them. This makes changing function key assignments easier.
Specifies the identifier that is to be assigned to the panel or pop-up window created by this command.
*AUTO indicates that it should be automatically generated by LANSA from the function name and the source statement number of the RDML program.
*NONE indicates that no panel identifier is required for this panel or pop-up window.
Otherwise specify a panel identifier from 1 to 10 characters in length. The value specified is fixed and cannot be changed at execution time.
This parameter is valid for SAA/CUA applications only.
This parameter is ignored if the current partition definition indicates that panel identifiers are never required, no matter what value is specified.
Specifies the title that is to be assigned to the window panel.
*FUNCTION indicates that it should be derived from the RDML function's description.
Otherwise specify a panel title from 1 to 40 characters in length. The value specified is fixed and cannot be changed at execution time.
This parameter is valid for SAA/CUA applications only.
Specifies whether the "next function" field should be shown on line 22 of the screen. The next function field is a facility that allows transfer between the functions in a process without the need to return to the process menu each time. Refer to the section that describes the The Function Control Table in the for more details about "next function" processing.
*PRO, which is the default value, indicates that the "next function" field should appear only when the process to which this function belongs has a menu selection style of "FUNCTION". If the process menu selection style is "NUMBER" or "CURSOR" then the next function field should not appear.
*YES indicates that the next function field should appear regardless of what menu selection style is being used by the process to which this function belongs.
*NO indicates that the next function field should not appear regardless of what menu selection style is being used by the process to which this function belongs.
Note: The SHOW_NEXT parameter is ignored in SAA/CUA applications.
|
Portability Considerations |
Ignored in Visual LANSA applications with no known effect to the application. |
Allows the specification of up to 50 "text strings" that are to appear on the screen panel or report. Each text string specified is restricted to a maximum length of 20 characters.
When a text string is specified it should be followed by a row/line number and a column/position number that indicates where it should appear on the screen panel or report.
For example:
TEXT(('ACME' 6 2)('ENGINEERING' 7 2))
specifies 2 text strings to appear at line 6, position 2 and line 7, position 2 respectively.
|
Portability Considerations |
In Visual LANSA this parameter should only be edited using the screen or report painter which will replace any text with a text map. DO NOT enter text using the command prompt or free format editor as it will not pass the full function checker if checked in to LANSA for i. |
All Platforms
The text map is used by the screen or report design facilities to store the details of all the text strings associated with the screen panel or report lines.
Once a screen or report layout has been "painted" and saved, all text details from the layout are stored in a "text map". The text map is then subsequently changed by using the "painter" again.
The presence of a text map is indicated by a TEXT parameter that looks like this example:
TEXT((*TMAPnnn 1 1))
where "nnn" is a unique number (within this function) that identifies the stored text map.
Some very important things about "text maps" and *TMAPnnn identifiers that you must know are:
- Never specify *TMAPnnn identifiers of your own or change *TMAPnnn identifiers to other values. Leave the assignment and management of *TMAPnnn identifiers to the screen and report design facilities.
- When copying a command that has an *TMAPnnn identifier, remove the *TMAPnnn references (ie: the whole TEXT parameter) from the copied command. If you fail to do this, then the full function checker will detect the duplicated use of *TMAPnnn identifiers, and issue a fatal error message before any loss occurs.
- Never remove an *TMAPnnn identifier from a command. If this is done then the associated text map may be deleted, or reused in another command, during a full function check or compilation. Loss of text details is likely to result.
- Never "comment out" a command that contains a valid *TMAPnnn identifier. This is just another variation of the preceding warning and it runs the same risks of loss or reuse of text.
- Never specify *TMAPnnn values in an Application Template. In the template context *TMAPnnn values have no meaning. Use the "text string" format in commands used in, and initially generated by, Application Templates.
Specifies any user controlled cursor positioning that is required. The CURSOR_LOC parameter must always contain 2 values which may take any of the following forms:
*NONE / *NONE: which are the default values indicate that no user controlled cursor positioning is required. Normal LANSA cursor control is to be used. When a screen is displayed the cursor will be positioned to either the first input capable field or the first field in error.
*ATFIELD / Field name: specifies that the cursor should be positioned to the named field. If the named field is not on the display or a field error exists, normal LANSA cursor control will be used. Otherwise the cursor will be positioned to the nominated field.
Row value / Column value: specifies that the "values" nominated indicate the row and column number at which the cursor is to be positioned. The "values" nominated may be an alphanumeric literal (e.g.: 15) or the name of a field that contains the value (e.g.: #ROW). In all cases the value must be numeric. If the row or column values are invalid or a field error exists, normal LANSA cursor control will be used. Otherwise the cursor will be positioned at the row and column specified.
When the row and column option is used and the row and column values are specified as fields (rather than numeric literals), the row and column number that the cursor was at when the command completed execution will be returned in them.
Note: The CURSOR_LOC does not behave in the same way on Windows as on IBM i. On a Windows platform the value retrieved is the first position of the field the cursor is currently in.
The feature is a useful way of retrieving the location of the screen cursor at the time the command completed execution. In cases where you wish to retrieve the cursor location, but do not want to specify it before output to the screen, use coding like this:
CHANGE FIELD(#ROW #COL) TO(0)
DISPLAY FIELDS(#FIELD1 .. #FIELD10) CURSOR_LOC(#ROW #COL)
When the DISPLAY command is executed #ROW and #COL are both zero, which is an invalid cursor location. In such cases normal LANSA cursor control is resumed and the user positioning request is ignored. However, after completion of the command fields #ROW and #COL will contain the location of the cursor at the time the DISPLAY command completed execution.
Specifies whether or not the standard LANSA design for the screen heading lines (lines 1 and 2) should be used.
*DFT, which is the default value, indicates that the system default value for the STD_HEAD parameter should be used. The system default value is stored in the LANSA system definition block. Refer to The System Definition Data Areas in the for more details of the system definition block and how to change it.
This default value is affected when used with the OPTIONS(*OVERLAY) parameter. Refer to the OPTIONS parameter for more details.
*YES indicates that the standard LANSA screen heading lines should be used. When this option is used lines 1 and 2 of the display are not available for the positioning of user fields.
*NO indicates that the standard LANSA screen heading lines should not be used. In this case lines 1 and 2 of the display can be used to position user fields.
Specifies special display options for this screen panel.
*NONE, which is the default value, indicates that there are no special display options for this screen panel.
Otherwise, specify one or more of the following:
*NOREAD indicates that the details being displayed are not to be read back from the screen. Thus the details are presented to the user, but cannot ever be read back into the program. Additionally, the program does not stop at the command and wait for a user interaction. The stop and wait event will only occur when a subsequent DISPLAY or REQUEST command is executed that does not use the *NOREAD option.
*OVERLAY indicates that the screen panel should overlay whatever details are already on the screen. Details already on the screen will become protected and can no longer be read from the device, but they will be visible to the user.
When *OVERLAY is used, the default for the STD_HEAD parameter is *NO. Therefore, unless STD_HEAD(*YES) is coded, the screen heading lines will not be displayed when using OPTIONS(*OVERLAY). Note that when a "standard heading" (*YES) is sent to the screen it causes the entire screen to be cleared. If STD_HEAD(*NO) is used it has no effect upon standard headings already on the screen from previous commands.
If either the *NOREAD or *OVERLAY options are used, the complete screen details must fit on one screen panel.
Note: These display options have been provided to allow emulation of IBM i 3GL programs, and will not be portable to other platforms. They are not supported by the current GUI or by LANSA for the Web. use of these options is therefore not recommended.
|
Portability Considerations |
This parameter is not supported in Visual LANSA applications and should not be used. If used, a Full Function Check fatal error will be issued. |
Controls the appearance of the text "Fnn=XXXXXX" in the function key area, of the function key assigned to support IGC conversion.
This parameter is ignored if the language under which this function is being compiled does not have the "IGCCNV required" flag enabled, or if this function uses the *NOIGCCNV options keyword (refer to the FUNCTION command).
Also note that this parameter only controls the appearance of the text "Fnn=XXXXX" in the function key area. It does not control the enablement of the IGCCNV DDS keyword in the display file associated with this function. This is controlled by the setting of the "IGCCNV required" flag and the use of the *NOIGCCNV option.
*AUTO, which is the default value, indicates that appearance of the function key text should be determined automatically. The automatic rules used to determine whether or not to show the function key text are:
- If there are no fields with keyboard shift J, E or O involved, the text will not appear (ignore all following rules).
- For a REQUEST command the text will always appear.
- For DISPLAY or POP_UP commands, the current "mode" is tested. If the mode is "change" (ie: fields on the screen are input capable), the text will appear. For all other modes the text will not appear.
Other allowable values for this parameter are *YES, indicating that the text should always appear, or, *NO indicating that the text should never appear.
The final option allows the nomination of a condition previously defined by a DEF_COND command. If the condition is true the text should appear. If the condition is false, the text should not appear.
|
Portability Considerations |
The parameter is ignored in Visual LANSA applications with no known effect to the application. |