Binding variables to form fields

Sub-dialogs handling data fields need program variables to store the information displayed in form fields during the dialog execution. The exception is the CONSTRUCT sub-dialogs, which needs only one string variable that hold the SQL condition produced.

When declaring a sub-dialog handling form fields, you specify what program variables must be bound to the form fields:

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

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 sub-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 data type; 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, not program variable is used for fields: Only one string variable is bound to that type of sub-dialog, to hold the generated SQL condition. The CONSTRUCT sub-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.

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 (with the ACCEPT DIALOG instruction).

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.