Back to Contents

Displaying Data to Forms

Summary:

• How to display data to form fields
• Displaying data to specific form fields (DISPLAY TO)
• Displaying data to form fields by name (DISPLAY BY NAME)
• Clearing all form fields (CLEAR FORM)
• Clearing specific form fields (CLEAR field)

See also: Variables, Records, Windows, Forms, Record Input, Display Array

How to display data to form fields

Programs retrieve data from the database into variables with a cursor or a static SELECT statement, and display the variable values to the current form with the DISPLAY instruction:

DISPLAY TO

Purpose:

The DISPLAY TO instruction displays data to form fields explicitly.

Syntax:

where field-list is :

{ field-name
| table-name.*
| table-name.field-name
| screen-array[line].*
| screen-array[line].field-name
| screen-record.*
| screen-record.field-name
} [,...]

Notes:

1. expression is any expression supported by the language.
   This is typically a list of variables or a record with the .* notation.
2. field-name is the identifier of a field of the current form.
3. table-name is the identifier of a database table of the current form.
4. screen-record is the identifier of a screen record of the current form.
5. screen-array is the screen array that will be used in the form.
6. display-attribute is one of the display attributes supported in this instruction. See below for more details.

Warnings:

1. The DISPLAY TO statement changes the 'touched' status of the target fields. When you modify a field value with this instruction, the FIELD_TOUCHED() operator returns TRUE and the ON CHANGE trigger may be fired if the current field value was changed with a DISPLAY TO. During an INPUT or INPUT ARRAY, we recommend you to use the UNBUFFERED attribute to display data automatically to fields without changing the 'touched' status of fields.

Usage:

If the variables do not have the same names as the form fields, you must use the TO clause to map variables to fields explicitly. You can list the fields individually, or you can use the screen-record.* or screen-record[n].* notation, where screen-record[n].* specifies all the fields in line n of a screen array.

In a DISPLAY TO statement, any screen attributes specified in the ATTRIBUTE clause apply to all the fields that you specify after the TO keyword.

In the following example, the values in the p_items program record are displayed in the first row of the s_items screen array:

01 DISPLAY p_items.* TO s_items[1].*

The expanded list of screen fields must correspond in order and in number to the expanded list of identifiers after the DISPLAY keyword. Identifiers and their corresponding fields must have the same or compatible data types. For example, the next DISPLAY statement displays the values in the p_customer program record in fields of the s_customer screen record:

01 DISPLAY p_customer.* TO s_customer.*

For this example, the p_customer program record and the s_customer screen record require compatible declarations. The following DEFINE statement declares the p_customer program record:

01 DEFINE p_customer RECORD
02   customer_num LIKE customer.customer_num,
03   fname LIKE customer.fname,
04   lname LIKE customer.lname,
05   phone LIKE customer.phone
05 END RECORD

This fragment of a form specification declares the s_customer screen record:

01 ATTRIBUTES
02  f000 = customer.customer_num;
03  f001 = customer.fname;
04  f002 = customer.lname;
05  f003 = customer.phone;
06 END

The ATTRIBUTE clause temporarily overrides any default display attributes or any attributes specified in the OPTIONS or OPEN WINDOW statements for the fields. When the DISPLAY statement completes execution, the default display attributes are restored.

The following table shows the display-attributes supported by the DISPLAY TO statement:

The REVERSE, BLINK, INVISIBLE, and UNDERLINE attributes are not sensitive to the color or monochrome status of the terminal, if the terminal is capable of displaying these intensity modes. The ATTRIBUTE clause can include zero or more of the BLINK, REVERSE, and UNDERLINE attributes, and zero or one of the other attributes. That is, all of the attributes except BLINK, REVERSE, and UNDERLINE are mutually exclusive.

The DISPLAY statement ignores the INVISIBLE attribute, regardless of whether you specify it in the ATTRIBUTE clause.

DISPLAY BY NAME

Purpose:

The DISPLAY TO instruction displays data to form fields implicitly by name.

Syntax:

Notes:

1. expression is any expression supported by the language.
2. field-name is the identifier of a field of the current form.
3. table-name is the identifier of a database table of the current form.
4. screen-record is the identifier of a screen record of the current form.
5. screen-array is the screen array that will be used in the form.
6. display-attribute is one of the display attributes supported in this instruction. See below for more details.

Warnings:

1. The DISPLAY BY NAME statement changes the 'touched' status of the target fields. When you modify a field value with this instruction, the FIELD_TOUCHED() operator returns TRUE and the ON CHANGE trigger may be fired if the current field value was changed with a DISPLAY BY NAME. During an INPUT or INPUT ARRAY, we recommend you to use the UNBUFFERED attribute to display data automatically to fields without changing the 'touched' status of fields.

Usage:

If the variables to be displayed have the same name as form fields, you can use the BY NAME clause. The BY NAME clause implicitly binds the fields to variables. To use this clause, you must define variables with the same name as the form fields where they will be displayed. The language ignores any record name prefix when matching the names. The names must be unique and unambiguous;  if not, this option results in an error, and the runtime system sets STATUS to a negative value.

For example, the following statement displays the values for the specified variables in the form fields with corresponding names (company and address1):

01 DISPLAY BY NAME p_customer.company, p_customer.address1

This BY NAME clause displays data to the screen fields of the default screen records. The default screen records are those having the names of the tables defined in the TABLES section of the form specification file. To use a screen array, you define a screen array in addition to the default screen record. This default screen record holds only the first line of the screen array.

For example, the following DISPLAY statement displays the ordno variable only in the first line of the screen array (the default screen record):

01 DISPLAY BY NAME p_stock[1].ordno

To display ordno in all elements of the screen array, you can use the DISPLAY ARRAY statement, or DISPLAY TO, as in the next example:

01 FOR i=1 TO 10
02    DISPLAY p_stock[i].ordno TO sc.stock[i].ordno
03    ...
04 END FOR

The following table shows the display-attributes supported by the DISPLAY BY NAME statement:

CLEAR FORM

Purpose:

The CLEAR FORM instruction clears all fields in the current form.

Syntax:

Notes:

1. This instruction has no effect on any part of the screen display except the form fields.

Example:

01 MAIN
02    OPEN WINDOW w1 AT 1,1 WITH FORM "custlist"
03    CLEAR FORM
04    CLOSE WINDOW w1
05 END FOR

CLEAR field

Purpose:

The CLEAR field instruction clears specific fields in the current form.

Syntax:

where field-list is :

{ field-name
| table-name.*
| table-name.field-name
| screen-array[line].*
| screen-array[line].field-name
| screen-record.*
| screen-record.field-name
} [,...]

Notes:

1. field-name is the identifier of a field of the current form.
2. table-name is the identifier of a database table of the current form.
3. screen-record is the identifier of a screen record of the current form.
4. screen-array is the screen array that will be used in the form.

Example:

01 FOR i=1 TO 10
02    CLEAR s_items[i].*
03 END FOR