Identifying fields in ui.Dialog methods

In ui.Dialog methods such as setFieldActive(), the first parameter identifies the form field (or, for some methods, a list of fields) to be modified. The form field names can be fully-qualified or partly-qualified.

Fields are identified by the form field name specification (in the .per form), not the program variable name used by the dialog. Form fields are bound to program variables with the binding clause of the dialog instruction (INPUT variable-list FROM field-list, INPUT BY NAME variable-list, CONSTRUCT BY NAME sql ON column-list,CONSTRUCT sql ON column-list FROM field-list, INPUT ARRAY array-name FROM screen-array.*).

The field name specification can be any of the following:

  • field-name
  • table-name.field-name
  • screen-record-name.field-name
  • FORMONLY.field-name

Here are some examples:

  • "cust_name",
  • "customer.cust_name",
  • "cust_screen_record.cust_name",
  • "item_screen_array.item_label",
  • "formonly.total",
  • "customer.*" (only some methods accept the "dot asterisk" notation)

When no field name prefix is used, the first form field matching that field name will be used. If the field specification is invalid (no field in the current dialog matches the field specification), the method will throw the error -1373.

When using a prefix in the field name specification, it must be equal to the field prefix used in the field binding clause of the dialog.
  • When no screen-record was specified in the field binding clause (for example, when using INPUT BY NAME variable-list), the field prefix must be the database table name (or FORMONLY) used in the form file, or any valid screen-record using that field.

  • When the FROM or TO clause of the dialog specifies an explicit screen-record (for example, in INPUT variable-list FROM screen-record.* / field-list-with-screen-record-prefix, INPUT ARRAY array-name FROM screen-array.*) or DISPLAY ARRAY array-name TO screen-array.*, the field prefix must be the screen-record name used in the FROM/TO clause.

The name of the field passed as parameter can use the same letter case as the field definition in the form file: The lookup is case-insensitive:
-- In the form file:
EDIT f01 = Customer.CustAddr, ... ;
-- In the program code:
CALL DIALOG.setFieldActive("Customer.CustAddr", FALSE)
The methods validate(), setFieldActive(), setFieldTouched(), getFieldTouched() can take a list of fields as parameter, by using the "dot-asterisk " notation (screen-record.*). This way you can check, query or change a complete list of fields in one method call:
ON ACTION save 
  CALL save_cust_record()
  CALL DIALOG.setFieldTouched("customer.*", FALSE)
    ...