7.26.3 DEF_LIST Comments / Warnings

 

• There are two types of working list. The first list is one that specifies *MAX for the ENTRYS parameter. This kind of list dynamically allocates memory and is referred to as a Dynamic Working List. The second specifies any other value for the ENTRYS parameter. These are static working lists.

• Warnings

• Keep in mind when defining static working lists that the amount of storage allocated to each working list will be equal to the entry length multiplied by the number of entries on the list, so the amount of storage space allocated to a function using many working lists can increase quite substantially.

• If you intend to improve the memory management and performance of your lists by performing storage space manipulation, a document: Memory Management in LANSA that covers this topic and is available from your LANSA distributor.
  Under normal circumstances you should not need to change a list's storage space. Changing it without understanding the implications could affect your application's performance or stability. Contact your local LANSA distributor before continuing.

• When a static working list will exceed typical available Windows 32-bit process memory, messages 870, 871, 872, 873 and 874 may be displayed. An example of message 871 is: "Maximum 32-bit windows server process memory of 3 GB will be exceeded." These messages should be considered as near fatal errors. They are indicating that the memory requirement is beyond the capability of particular windows configurations. The capabilities of other platforms is generally larger, like the IBM i, but to raise these warnings still indicates a design that should be re-considered.

• Message 874 contains the dimensions of the list. An example of message 874 is "List page size = 1098000000 bytes Entry length = 549 bytes."

• On the other hand a dynamic working list only pre-allocates a small amount of memory to hold pointers to the list entrys. Then, as more space is required it is allocated with one page of operating system memory or the size of one entry, which ever is the larger. On Microsoft Windows the size of a page is 32 KB. Memory is also released as entrys are deleted from the list. If you were to keep adding entries indefinitely, memory would eventually run out on windows.

• Whilst the IBM i has a greater total amount of memory available, it is limited to a maximum of 16 MB in any single memory allocation. This means that on an IBM i, each STATIC working list is limited to a TOTAL size of 16 MB and each DYNAMIC working lists is limited to a maximum ENTRY width of 16 MB. Thus a dynamic working list has a far greater total capacity - only limited by the total amount of memory that the operating system has available for the process to use. This is strictly an IBM i limitation. All other platforms have the same limit for each list as for the total memory used by all lists.

• Large working lists may not perform satisfactorily, especially if LOC_ENTRY is used because they are only accessed sequentially - there are no indexes. For lists that allow fast look-up see the SPACE BIFs.

Note: Once defined, an RDML working list has an aggregate length limit of 256 bytes in the primary list. To overcome this limit Appendage Lists may be specified by invoking the Transform_LIST Built-In Function. Another solution is to use an RDMLX Function with a dynamic working list.

Working lists are not an infinite resource - use a realistic and sensible size for the number of entries.

• Where the fields defined in a browse list will not fit onto one screen line they will automatically wrap around onto the next screen line. For example, the command:

DEF_LIST   NAME(#ORDERLINE) FIELDS(#ORDLIN  #PRODUCT #QUANTITY #PRICE)

May cause a list to be displayed that looks like this on the screen:

No       Product              Quantity              Price       99       9999999               99999               99999.99       99       9999999               99999               99999.99       99       9999999               99999               99999.99

If more fields were added to the DEF_LIST command like this:

DEF_LIST   NAME(#ORDERLINE) FIELDS(#ORDLIN #PRODUCT #PDESC #QUANTITY #PRICE #TAXRTE)

then when the list was displayed it might now look like this:

No     Product          Description       99      9999999           XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX       Quantity 99999      Price 99999.99     Tax rate 99.99       99      9999999           XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX       Quantity 99999      Price 99999.99      Tax rate 99.99       99     9999999          XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX       Quantity 99999      Price 99999.99     Tax rate 99.99

Field attributes and/or the screen design facility can be used to modify the automatically designed screen layout in any way.

For information refer to: 

In this guide, for details of:

• field attributes, refer to  Field Attributes.

• the screen design facility, refer to The Screen Design Facility in the Visual LANSA User Guide. Note that row/line attributes are ignored when specified for fields in a browselist.

In the LANSA for i User Guide, for details of:

• field attributes, refer to New Field Attribute Concepts Create a New Field Definition .

• the screen design facility, refer to The Screen Design Facility. Note that row/line attributes are ignored when specified for fields in a browselist.