Binding variables to form fields

Some dialogs need program variables to store form field values.

Program variables are the data model for dialog instructions

Dialogs handling data fields input or display (INPUT, INPUT ARRAY, DISPLAY ARRAY) need program variables to store the information displayed in form fields during the dialog execution. The exception is CONSTRUCT, which needs only one string variable that holds the SQL condition produced.

When implementing a dialog controlling form fields, you specify what program variables must be bound to the form fields of the current displayed form:

   INPUT BY NAME custrec.* ...
      ...
   END INPUT

Program variables (simple records and arrays) used in dialogs can have a flat definition, or structured definition with sub-records.

Dialog variables binding methods

There are different ways to bind program variables to screen record fields.

Program variables can be bound to form fields by name or by position, depending on the binding clause used in the dialog definition.

Note: When binding program variables with a screen record followed by a .* (dot star), program variables are bound to screen record fields by position. Make sure that the program variables are defined (or listed) in the same order as the screen array fields. This is true for INPUT,

DISPLAY
                    ARRAY

and INPUT ARRAY.

For more details about binding methods, see dialog-specific syntax reference topics in Dialog instructions.

Variables and form fields data types

The program variables can be of any simple data type supported by the dialogs; the runtime system will adapt input and display rules to the variable type. When the user enters data for an INPUT or INPUT ARRAY instruction, the runtime system checks the entered value against the data type of the variable, not the data type of the form field. For example, if you want to use a DATE variable, the dialog will check for a valid date value when the user enters a value in the corresponding form field.

With CONSTRUCT, no program variable is used for fields: Only one string variable is required, to hold the generated SQL condition.

Note: The CONSTRUCT dialog uses the field data types defined in the form file.

Program variables are typically declared with a DEFINE LIKE clause to get the data type of a column as defined in the database schema file. When the form fields are also defined like a column of the database schema, this ensures that the program variable and form field data type matches the underlying database column type. If a variable is declared LIKE a SERIAL / SERIAL8 / BIGSERIAL column, the runtime system will treat the field as if it was defined as NOENTRY in the form file. Since values of serial columns are automatically generated by the database server, no user input is required for such fields.

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

Data formatting

Data format for input and display of numeric (DECIMAL, INTEGER) and DATE fields can be defined with the FORMAT attribute.

A default data format can be defined with environment variables (DBDATE, DBFORMAT, etc)

Data validation rules

Data validation rules can be defined at the form level, such as NOT NULL, REQUIRED and INCLUDE attributes.

Data validation constraints are checked when leaving a field, or when the dialog is validated (for example, with the ACCEPT DIALOG instruction inside a DIALOG multiple dialog block).

Note: Trailing blanks entered by the user will be removed when leaving the input field.