Binding variables to form fields

Some dialogs need program variables to store form field values.

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 declaring a dialog handling form fields, you specify what program variables must be bound to the form fields:

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

There are different ways to bind program variables to screen record fields. Basically program variables can be bound to form fields by name or by position, according to the binding clause used in the dialog definition.

When binding program variables with a screen record followed by a .* (dotstar), 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. This is true for INPUT, DISPLAY ARRAY and INPUT ARRAY.

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 bound to that type of dialog, to hold the generated SQL condition. Note that 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 ensure 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.

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

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)

Some 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).

If the program record or array has the same structure as a database table (this is the case when the variable is defined with a DEFINE LIKE clause), you may not want to display / use some of the columns. You can achieve this by used 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.