DISPLAY BY NAME

The DISPLAY BY NAME instruction displays data to form fields explicitly by name.

Syntax

DISPLAY BY NAME { variable | record.* } [,...]
  [ ATTRIBUTES ( display-attribute [,...] ) ]

where display-attribute is:

{ BLACK | BLUE | CYAN | GREEN
| MAGENTA | RED | WHITE | YELLOW
| BOLD | DIM | NORMAL
| REVERSE | BLINK | UNDERLINE
}
  1. variable is a program variable that has the same name as a form field.
  2. record.* is a record variable that has members with the same names as form fields.

Usage

A DISPLAY BY NAME statement copies the data from program variables to the form fields associated to the variables by name. The program variables used in DISPLAY BY NAME must have the same name as the form fields where they have to be displayed. The language ignores any record structure name prefix when matching the names. The names must be unique and unambiguous; if not, the instruction raises an error.

For example, the following statement displays the values for the specified variables in the form fields with corresponding names (company and address1):
DISPLAY BY NAME p_customer.cust_company,
                p_customer.cust_address1

The DISPLAY BY NAME instruction is usually not needed if the program is always in the context of a dialog controlling the form fields.

DISPLAY BY NAME uses the default screen record

Unlike the DISPLAY TO instruction where you can explicitly specify a screen record or screen array, DISPLAY BY NAME 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. When the form fields define a record list in the layout, only the first row can be referenced with the default screen record. In the next example, the form contains a static record list definition in the layout.
SCHEMA mystock
SCREEN
{
[f01  |f02    |f03          ]
[f01  |f02    |f03          ]
[f01  |f02    |f03          ]
[f01  |f02    |f03          ]
}
END
TABLES
customer
END
ATTRIBUTES
f01 = customer.cust_key;
f02 = customer.cust_name;
f03 = customer.cust_address;
END

In the program, a DISPLAY BY NAME statement will display the data in the first line of the record list in the form:

DISPLAY BY NAME record_cust.*

DISPLAY BY NAME changes the touched flag

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 and ON ROW CHANGE triggers may be invoked if the current field value was changed with a DISPLAY BY NAME.

In dialogs controlling field input such as INPUT or INPUT ARRAY, use the UNBUFFERED attribute to display data to fields automatically without changing the 'touched' status of fields. The UNBUFFERED clause will perform automatic form field and program variable synchronization. When using the UNBUFFERED mode, the touched flag can be set with DIALOG.setFieldTouched() if you want to get the same effect as a DISPLAY BY NAME statement.

Specifying TTY attributes in the DISPLAY BY NAME statement

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

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 ATTRIBUTES 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 BY NAME statement ignores the INVISIBLE attribute, regardless of whether you specify it in the ATTRIBUTES clause.