7.23.1 DEF_LIST Parameters
Specifies the name that is to be assigned to the list. The name specified must not be the same as any other list defined in this function, any group name defined in this function (see the GROUP_BY command), or any field defined in this function or in the LANSA data dictionary.
Specifies the names of the field(s) which are to form one entry in the list. Field control attributes can be included with the field(s) specified. Alternatively, an expandable group expression can be entered in this parameter.
All fields nominated in this parameter must be defined within this function or in the LANSA data dictionary.
Fields of type Binary, VarBinary, Float and Boolean cannot be used.
Refer to the 7.52.1 GROUP_BY Parameters for more details of specifying field lists and field control attributes.
Specifies a field which is to be automatically maintained with a count of the number of entries currently in the list.
The default value is *NONE which indicates no automatic counter is required.
If a field is nominated as the automatic counter it must be defined in this function or in the LANSA data dictionary and be of numeric type.
Identifies the list as either a browse list (*BROWSE) which can be displayed at a workstation, or as a working list (*WORKING) that can be used within the program. The default value for this parameter is *BROWSE.
This parameter is used for TYPE(*WORKING) lists or for TYPE(*BROWSE) lists when the application will be run on Visual LANSA It specifies the maximum number of entries that can be contained in the list at any time. If this parameter is omitted a value of 50 is assumed. Otherwise specify an integer value in the range 1 to 2,147,483,647. If the Function or Component is not enabled for RDMLX, the limit is 9999.
The special value *MAX is provided to represent 2,147,483,647. Using this value on some operating systems, like 32-bit Microsoft Windows versions, will overflow available memory in a process if an attempt is made to add the maximum number of entries. So, the use of a large number of entries needs to be seen as allowing for an unknown number that may never be practically attained. It is up to the application designer to make appropriate use of this feature. The full function checker issues warnings when the maximum size of the list would overflow the practical available memory on various MS Windows versions. Refer to 7.23.3 DEF_LIST Comments / Warnings for information on how to use the FFC warnings to calculate memory use.
Note that an RDML list pre-allocates all the required memory for the list. An RDMLX list pre-allocates only the number of entries that will fit into one memory page or the width of one entry, whichever is the larger. RDMLX lists allocate more memory at runtime as the need arises.
This parameter is only used for TYPE(*BROWSE) lists. If used, it specifies the name of a numeric field that is to contain the size (number of entries) of the browse list that fits on one "page" of the display device being used.
The default value is *NONE which indicates that page size is not required.
If a field is nominated to contain the "page" size it must be defined in this function or in the LANSA data dictionary and be of numeric type.
Note: The use of this parameter does not control the page size, it merely allows you to nominate a numeric field that is to have the LANSA assigned page size placed into it at the start of the RDML program.
This parameter is normally only used when creating browse lists that are displayed using "page at a time" techniques. It saves the programmer from having to find out what the LANSA assigned page size is, and then having to "hard code" it into the RDML program.
This parameter is only used for TYPE(*BROWSE) lists. It specifies a numeric field which can be used to:
- Specify that the "page" of the browse list that is to be displayed initially is the "page" that contains this entry number.
- Receive back (after a DISPLAY, REQUEST or POP_UP command) the browse list entry number of the browse list line that was at the top of the "page" when the enter key or a function key was used.
The default value is *CURRENT which indicates that the "page" to be displayed should be the current one. This means the first page if this is the first time the list is being displayed, or the one that was last displayed if the list has been previously displayed.
If a field is nominated to contain the top entry it must be defined in this function or in the LANSA data dictionary and be of numeric type.
This parameter is only used for TYPE(*BROWSE) lists. It specifies a numeric field which is to contain the entry number of a browse list entry that was selected by the user placing the cursor on the entry and pressing enter or a function key. If the cursor is not validly positioned the value will be returned as zero.
The default value is *NONE which indicates that cursor selected entry number is not required.
If a field is nominated to contain the selected entry number it must be defined in this function or in the LANSA data dictionary and be of numeric type.
This parameter is only used for TYPE(*BROWSE) lists. Additionally it should only be used when you are coding your RDML program to use "page at a time" browse list displays.
Under the current releases of LANSA, IBM i and CPF this parameter is used to control the appearance (or non-appearance) of the high intensity "+" (plus) sign at the bottom of a list displayed on the screen.
Traditionally, this appearance of the "+" sign indicates to the user that more details exist on the next "page" of the list, and that they can be viewed by using the roll up key.
When your RDML program is not using "page at a time" techniques to build and display a list (ie: you build the whole list before displaying it) you should not use this parameter.
If your RDML program is using "page at a time" techniques, you should use this parameter to control when the "+" scrolling sign appears.
The default value is *NONE, which indicates that no specific program control of the "+" sign is required. It will be handled automatically by LANSA, IBM i or CPF with no program intervention. Use this value when you are not using "page at a time" techniques.
Otherwise nominate an alphanumeric field name for this parameter. When any page from the browse list is displayed on the screen, either by the RDML program or by the user pressing one of the scroll keys to move backwards or forwards through the list, the following occurs:
- If more entries exist in the browse list beyond the page that is being displayed, the "+" sign will appear, regardless of what value is contained in the field you nominate in this parameter.
- If no more entries exist in the browse list beyond the page that is being displayed, the appearance of the "+" sign is controlled by the content of the field you nominate in this parameter. If the contents of the field nominated start with an "M" or an "m", the "+" sign will appear. Otherwise it will not appear.
Refer to the end of this section for an example of a "page at a time" browse list program and the use of this parameter.
|
Portability Considerations |
If used with Visual LANSA, this feature is ignored. |