Variable binding in INPUT ARRAY

The INPUT ARRAY statement binds the members of the array of record to the screen array fields specified with the FROM keyword. Array members and screen array fields are bound by position (i.e. not by name). The number of members in the program array must match the number of fields in the screen record (that is, in a single row of the screen array).

SCHEMA stock
DEFINE cust_arr DYNAMIC ARRAY OF customer.*
...
INPUT ARRAY cust_arr FROM sr.*
        ATTRIBUTES(UNBUFFERED)
   ...
END INPUT

Keep in mind that array members are bound to screen array fields by position, so you must make sure that the members of the array are defined in the same order as the screen array fields.

Note that the array is usually defined with a flat list of members with ARRAY OF RECORD / END RECORD. However, the array can be structured with sub-records and still be used with an INPUT ARRAY dialog. This is especially useful when you need to define arrays from database tables, and additional information needs to be managed at runtime (for example to hold image resource for each row, to be displayed with the IMAGECOLUMN attribute):

SCHEMA shop
DEFINE a_items DYNAMIC ARRAY OF RECORD
                   item_data RECORD LIKE items.*,
                   it_image STRING,
                   it_count INTEGER
               END RECORD
...
INPUT ARRAY a_items FROM sr.*
   ...

When using a static array, the initial number of rows is defined by the COUNT attribute and the size of the array determines how many rows can be inserted. When using a dynamic array, the initial number of rows is defined by the number of elements in the dynamic array (the COUNT attribute is ignored), and the maximum rows is unlimited. For both static and dynamic arrays, the maximum number of rows the user can enter can be defined with the MAXCOUNT attribute.

The FROM clause binds the screen records in the screen array to the program records of the program array. The form can include other fields that are not part of the specified screen array, but the number of member variables in each record of the program array must equal the number of fields in each row of the screen array. When the user enters data, the runtime system checks the entered value against the data type of the variable, not the data type of the screen field.

The variables of the record array are the interface to display data or to get the user input through the INPUT ARRAY instruction. Always use the variables if you want to change some field values by program. When using the UNBUFFERED attribute, the instruction is sensitive to program variable changes. If you need to display new data during the INPUT ARRAY execution, use the UNBUFFERED attribute and assign the values to the program array row; the runtime system will automatically display the values to the screen:

INPUT ARRAY p_items FROM s_items.*
      ATTRIBUTES(UNBUFFERED)
  ON CHANGE code 
    IF p_items[arr_curr()].code = "A34" THEN
      LET p_items[arr_curr()].desc = "Item A34"
    END IF
END INPUT

The runtime system adapts input and display rules to the data type of the array record members. If a member is declared with the DEFINE LIKE instruction and uses a column defined as SERIAL / SERIAL8 / BIGSERIAL, the runtime system will treat the field as if it was defined with the NOENTRY attribute in the form file. Since values of serial columns are automatically generated by the database server, no user input is required for such fields.

The default order in which the focus moves from field to field in the screen array is determined by the declared order of the corresponding member variables, in the array of the record definition. The program OPTIONS instruction can also change the behavior of the INPUT ARRAY instruction, with the INPUT WRAP or FIELD ORDER FORM options.

By default the INPUT ARRAY instruction clears the program array when starting, unless you specify the WITHOUT DEFAULTS keywords or option. With this option, the dialog displays the program array rows in the screen fields. Unlike the INPUT dialog, the column default values defined in the form specification file with the DEFAULT attribute or in the database schema files are always used when a new row is inserted in the list.

If the program array has the same structure as a database table (this is the case when the array is defined with a DEFINE LIKE clause), you may not want to display/use some of the columns. You can achieve this by using PHANTOM fields in the screen array definition. Phantom fields will only be used to bind program variables, and will not be transmitted to the front-end for display.