Variable binding in INPUT

The INPUT instruction binds program variables (typically, members of a RECORD) to the fields of a screen record of the current form, and synchronizes the data between field input buffers and program variables.

Binding variables and fields by name

The INPUT BY NAME variable-list instruction implicitly binds the fields to the program variables that have the same identifiers as the form field names. The program variables are typically defined within a record declared with a LIKE table.* based on a database schema, so as to get the same names as the form fields defined with the database column references. The runtime system ignores any record name prefix when making the match, only record member names matter. The unqualified names of the variables and of the fields must be unique and unambiguous within their respective domains. If they are not, the runtime system generates an exception.

SCHEMA stock
DEFINE custrec RECORD LIKE customer.*
...
INPUT BY NAME custrec.*
  ...
END INPUT

Binding variables and fields by position

The INPUT variable-list FROM field-list clause explicitly binds the variables to form fields by position. The form can include other fields that are not part of the specified variable list, but the number of variables or record members must equal the number of form fields listed in the FROM clause. Each variable must be of the same (or a compatible) data type as the corresponding form field. 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 form field.

SCHEMA stock
DEFINE custrec RECORD LIKE customer.*,
       comment VARCHAR(100)
...
INPUT custrec.*, comment FROM sr_cust.*, cmt
  ...
END INPUT

When using the FROM clause with a screen record followed by a .* (dot star), keep in mind that program variables are bound to screen record fields by position, so you must make sure that the program variables are defined (or listed) in the same order as the screen array fields.

Serial column support

The program variables can be of any data type. The runtime system will adapt input and display rules to the variable type. If a variable is declared with the LIKE clause 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 UNBUFFERED mode

The variables act as data model to display data or to get user input through the INPUT 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 execution, just assign the values to the program variables; the runtime system will automatically display the values to the screen:

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

Handling default field values

When the INPUT instruction executes, any column default values are displayed in the screen fields, unless you specify the WITHOUT DEFAULTS keywords. The column default values are specified in the form specification file with the DEFAULT attribute, or in the database schema files.

If you specify the WITHOUT DEFAULTS option. However, the form fields display the current values of the variables when the INPUT statement begins. This option is available with both the BY NAME and the FROM binding clauses.

LET p_items.code = "A34"
INPUT p_items.* FROM s_items.* WITHOUT DEFAULTS
  BEFORE INPUT
    MESSAGE "it is recommended that you see A34 in field 'code'..."
END INPUT

Using PHANTOM fields

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