7.20.2 DEF_ARRAY Comments / Warnings

To use the array facility properly you must understand the IBM i data storage formats of character, packed decimal and signed / zoned decimal.

When you define an array various fields are automatically defined into the function, just as if you had defined them yourself using the DEFINE command.

RDMLX fields may not be overlaid, nor overlay another field.

The following example assumes that #VAL01, #VAL02 and #VAL03 are all packed decimal fields of length 7, with 2 decimals:

DEF_ARRAY NAME(#VAL) INDEXES(#II #JJ) OF_FIELDS(#VAL01 #VAL02 #VAL03)

will define the following "fields" into your function:

• #VAL#II as a packed 7,2 field. This field allows you to make indexed references to array #VAL using index #II.

• #VAL#JJ as a packed 7,2 field. This field allows you to make indexed references to array #VAL using index #JJ.
  
  Additionally, references to #VAL#II or #VAL#JJ by data validation commands like RANGECHECK and SET_ERROR will cause an error to be set in the associated OF_FIELD field.
  
  For example:

         CHANGE FIELD(#II) TO(3)

         SET_ERROR FOR_FIELD(#VAL#II)

         CHANGE FIELD(#JJ) TO(1)

         SET_ERROR FOR_FIELD(#VAL#JJ)

         DISPLAY FIELDS(#VAL01 #VAL02 #VAL03)

   will cause fields #VAL01 and #VAL03 to be displayed in reverse video because they have had their error flags turned on by the SET_ERROR commands.

• These element fields #VAL#II and #VAL#JJ can be referenced as individual fields in almost all commands. Specific places where they cannot be used include:

• On any screen panel. DISPLAY FIELDS(#VAL#II) in any form is invalid and will cause a compile failure. Likewise they cannot be placed in browse lists. However, they can be placed into working lists.

• In EXEC_OS400 or EXEC_CPF commands, use an intermediate work field instead. See the following examples for details.

• In debug mode .... #VAL#II cannot be shown directly by the debug facility.

• In database operations. The following code sections are not equivalent. The second operation will yield no result.

             FETCH FIELDS(#VAL01) FROM_FILE(.....)

             and   CHANGE #II 1

             FETCH FIELDS(#VAL#II) FROM_FILE(.....)

#VAL#ARRAY as a character field of length 12. This field is the full representation of array #VAL in character format. In this case 3 * P(7,2) uses 12 bytes of storage. This field is only automatically defined when the aggregate array length is less than or equal to 256 bytes.

This full array field #VAL#ARRAY is very useful because it can be used to:

• Pass an entire array to another function via the exchange list or to a 3GL program via a parameter. Of course the array in the other function will have to have the same name and be identical in all other respects. Also remember that the complete exchange list area is only 2K bytes.

• Display the contents of the entire array while in debug mode.

• Allow alphanumeric arrays to be initialized in one command.

• Display on screen panels or reports. However, if the actual array content is packed decimal data it may cause a workstation device failure.

• Placed into a working list, thus facilitating 2 dimensional array processing. One "index" is the working list entry number, the other is the actual array entry index.

• Since fields like #VAL#II, #VAL#JJ and #VAL#ARRAY are real fields in the program, it is possible to override their attributes with an OVERRIDE command. Do not override their lengths or number of decimal positions.

• When an RDML function is translated into RPG code, up to 40 arrays may be defined by LANSA to facilitate program processing. The number and type vary with the complexity of, and facilities used by, the RDML function.

• Additionally, every group, list, database operation or screen panel interaction will cause additional arrays to be defined.

• An RPG program is limited to having 200 arrays.

• So while the actual number that any RDML program will consume automatically is impossible to predict until compile time, you should plan on not ever defining more than 50 to 100 arrays in any individual function. In a single RDML function, number of arrays multiplied by the number of indexes must be less or equal to 100.