Creates a frame field and variable with the data type you specify. This is useful for defining display positions in a frame for use with DISPLAY @ field.

LIKE field

Creates a frame field and variable with the same definition as field.

The LIKE option in a DEFINE VARIABLE statement, DEFINE WORK-TABLE statement, or Format phrase requires that a particular database is connected. Since you can start up an ABL application session without connecting to a database, use the LIKE option with caution.

ATTR-SPACE | NO-ATTR-SPACE

Has no effect; supported only for backward compatibility.

AUTO-RETURN

Causes the AVM to automatically move out of a field as if you pressed RETURN. When you enter the last character in the field, the AVM automatically moves out of the field. If this happens on the last field of a data entry statement, the AVM functions as if you pressed GO.

For the purposes of AUTO-RETURN, entering leading zeros in a numeric field does not count as filling the field. For example, suppose you define a numeric field as follows:

DEFINE VARIABLE x AS INTEGER NO-UNDO FORMAT "99".

SET x AUTO-RETURN.

If you enter a 09 into the field, the AVM does not AUTO-RETURN. To get the AUTO-RETURN behavior in this situation, define the field as CHARACTER with a format of "99".

BGCOLOR expression

Specifies the background color of the widget in graphical interfaces. This option is ignored in character interfaces.

BLANK

Displays blanks for the field you are displaying or entering. This is useful for entering passwords.

COLON n

The number (n) of the column in which you want the colon of the label to appear. Use this option with SIDE-LABEL frames where the labels are placed to the left of the data and are separated from the data with a colon. For code compiled with the -nocolon startup parameter in effect, the last character in the label appears in the specified column. See the OpenEdge Deployment: Startup Command and Parameter Reference for more information on -nocolon .

TO n

The number (n) of the column in which you want to end the display. The TO option does not right justify the data; it indicates the placement of the data area.

COLUMN-LABEL label

Names the label you want to display above the field. If you want the label to use more than one line (stacked labels), use an exclamation point (!) in the label to indicate where to break the line. For example:

Specifies the foreground color of the widget in graphical interfaces. This option is ignored in character interfaces.

FONT expression

Specifies the font of the widget.

FORMAT string

Represents the format in which you want to display the expression. You must enclose string in quotation marks (""). If you do not use the FORMAT option, ABL uses the defaults shown in the following table.

Table 39. Default display formats

Type of expression

Default format

Field

Format from Dictionary

Variable

Format from variable definition

Constant character

Length of character string

Other

Default format for the data type of the expression

The following table lists the default formats for the Other expression.

2 To display a HANDLE, you must first convert it using either the INT64 or INTEGER function and display the result.

3 You can only display a LONGCHAR using the VIEW-AS EDITOR LARGE phrase.

4 You can only display a LONGCHAR using the VIEW-AS EDITOR LARGE phrase.

5 You cannot display a MEMPTR, RAW, or ROWID value directly. However, you can convert it to a character string representation using the STRING function and display the result. A ROWID value converts to a hexadecimal string, "0xhexdigits", where hexdigits is any number of characters "0" through "9" and "A" through "F". A MEMPTR or RAW value converts to decimal integer string.

6 You cannot display a MEMPTR, RAW, or ROWID value directly. However, you can convert it to a character string representation using the STRING function and display the result. A ROWID value converts to a hexadecimal string, "0xhexdigits", where hexdigits is any number of characters "0" through "9" and "A" through "F". A MEMPTR or RAW value converts to decimal integer string.

7 You cannot display a MEMPTR, RAW, or ROWID value directly. However, you can convert it to a character string representation using the STRING function and display the result. A ROWID value converts to a hexadecimal string, "0xhexdigits", where hexdigits is any number of characters "0" through "9" and "A" through "F". A MEMPTR or RAW value converts to decimal integer string.

8 You cannot display a MEMPTR, RAW, or ROWID value directly. However, you can convert it to a character string representation using the STRING function and display the result. A ROWID value converts to a hexadecimal string, "0xhexdigits", where hexdigits is any number of characters "0" through "9" and "A" through "F". A MEMPTR or RAW value converts to decimal integer string.

9 You cannot display a MEMPTR, RAW, or ROWID value directly. However, you can convert it to a character string representation using the STRING function and display the result. A ROWID value converts to a hexadecimal string, "0xhexdigits", where hexdigits is any number of characters "0" through "9" and "A" through "F". A MEMPTR or RAW value converts to decimal integer string.

10 You cannot display a MEMPTR, RAW, or ROWID value directly. However, you can convert it to a character string representation using the STRING function and display the result. A ROWID value converts to a hexadecimal string, "0xhexdigits", where hexdigits is any number of characters "0" through "9" and "A" through "F". A MEMPTR or RAW value converts to decimal integer string.

You can use the FORMAT option with the UPDATE and SET statements to store a character string that is longer than the field length you define in the Data Dictionary or in a DEFINE VARIABLE statement. This is possible because ABL stores data in variable-length fields.

DEFINE VARIABLE mychar AS CHARACTER NO-UNDO FORMAT "x(3)".

UPDATE mychar FORMAT "x(8)".

You can also use the ASSIGN statement to store data in a field or variable that is longer than the predefined format of that field or variable.

mychar = "abcdefgh".

However, the Data Dictionary load program only loads character data that is no longer than the format you defined in the Dictionary. For more information on data formats, see OpenEdge Getting Started: ABL Essentials.

HELP string

Represents a character string that you want to display whenever the user enters the frame field for the field or variable. When the user leaves the frame field, the AVM removes the help string from the message area. You must enclose the string in quotation marks ("").

If the input source is not the terminal, the AVM disregards any HELP options.

LABEL label[ , label] . . .

Represents a character string that you want to use as a label for a field, variable, or expression. You must enclose the string in quotation marks (""). The following table shows the order ABL uses to determine the label for a field, variable, or expression.

Table 41. Determining labels

LABEL string

Dictionary label

Field name

LIKE field

Variable name

Field

1

2

3

N/A

N/A

Variable

1

N/A

N/A

2

3

Expression

1

N/A

N/A

N/A

N/A

Note: If you use side labels, Windows allows a user to transfer focus to field-level widgets by pressing ALT and one of the letters in the widget's label. This is called a mnemonic. Specify the letter by preceding it with an ampersand (&) when specifying the LABEL option. Ending a label with an ampersand might produce undesired behavior. If you want a literal ampersand within a label, enter two ampersands (&&) in label. If you specify more than one widget with the same mnemonic, the AVM transfers focus to each of these in tab order when you make a selection.

NO-LABELS

Prevents the AVM from displaying a label for a field, variable, or expression.

NO-TAB-STOP

Specifies that the widget is not in its parent frame's tab order.

The following example shows defining a frame with two fill-ins, both of which have the NO-TAB-STOP option specified:

Specifies the prompt color of the widget in character interfaces. This attribute is ignored in graphical interfaces.

VALIDATE ( condition, msg-expression )

Specifies a value that you want to validate against the data entered into a screen field or variable. The condition is a Boolean expression (a constant, field name, variable name, or expression) whose value is TRUE or FALSE.

When you use the VALIDATE option to validate a specific field, any reference to that field in condition is assumed to be an input field. For example, in the following statement, the AVM assumes the PromiseDate field is an input field:

SET Order.OrderDate Order.PromiseDate VALIDATE(Order.PromiseDate > Order.OrderDate, "Promise date must be later than order date").

The previous statement is equivalent to the following statement:

SET Order.OrderDate Order.PromiseDate VALIDATE(INPUT Order.PromiseDate > Order.OrderDate, "Promise date must be later than order date").

The validation is based on the value of OrderDate prior to the SET statement. If you want to validate the value of PromiseDate against the input value of OrderDate, use this statement:

SET Order.OrderDate Order.PromiseDate VALIDATE(Order.PromiseDate > INPUT Order.OrderDate, "Promise date must be later than order date").

If you try to validate a field whose reference is ambiguous, the AVM tries to resolve the ambiguity by referencing the table that contains the record being updated. In the following example, the SalesRep field is ambiguous because it exists in both the Order table and the Customer table. The AVM resolves the ambiguity by validating the SalesRep field in the Order table, since the Order table is being updated.

If the reference is to an array field and has no subscript, the AVM assumes you want to use the subscript of the field that is being prompted.

If the value of condition is FALSE, use msg-expression to display a specific message. You must enclose msg-expression in quotation marks (" ").

The AVM processes validation criteria whenever the user attempts to leave the frame field. If the frame field value is not valid, the AVM displays msg-expression in the message area, causes the terminal to beep, and does not advance out of the frame field.

If you tab a frame field, make no changes, and leave the field, the AVM does not process the validation criteria specified with the VALIDATE option until the you press GO (F1). If you press ENDKEY or END-ERROR, or an error occurs, the AVM does not test the validation criteria specified with the VALIDATE option.

If the input source for the procedure is a table, the AVM validates each input field (except those with a value of "-"). If the result of the validation is FALSE, msg-expression is displayed and the AVM treats the validation as an error.

To suppress the Data Dictionary validation criteria for a field, use this VALIDATE option:

VALIDATE(TRUE,"")

When you use the VALIDATE option in a procedure to specify validation criteria for a field, that validation criteria applies to all other references to that field in the same frame:

FOR EACH Order: UPDATE Order.OrderDate. UPDATE Order.OrderDate VALIDATE(Order.OrderDate LE TODAY, "Can't be later than today").END.

In this example, the AVM applies the validation criteria on the second UPDATE statement. The AVM also applies the validation criteria to the first UPDATE statement because both UPDATE statements use the same frame. Scope references to the same field to different frames if you do not want a VALIDATE option to affect all references to that field.

For more information on view-as-phrase, see the VIEW-AS phrase reference entry.

WIDGET-ID id-number

Specifies a widget ID for a field or variable widget to display in a frame. The value of id-number must be an expression that evaluates to an even integer value between 2 and 65534, inclusive, and must be unique across all widget IDs in the window or dialog box.

If you specify an invalid ID, the compiler displays an error message. This option is supported in graphical interfaces only, and only in Windows.

Example

This procedure lets the user update Customer records after entering the password "secret." The format phrase on the Phone field describes the display format of that field.

Notes

The ATTR-SPACE/NO-ATTR-SPACE designation in a Frame phrase takes precedence over an ATTR-SPACE/NO-ATTR-SPACE designation in a Format phrase. The ATTR-SPACE/NO-ATTR-SPACE designation in a Format phrase takes precedence over an ATTR-SPACE/NO-ATTR-SPACE designation in a COMPILE statement.

If you have enabled application-defined widget IDs in your ABL GUI application, by specifying the Use Widget ID (-usewidgetid) startup parameter, then the AVM uses the value specified in the WIDGET-ID option to set the WIDGET-ID attribute for this widget when it creates the widget at run time, instead of using the widget ID it normally generates by default. If you have not enabled application-defined widget IDs, then the AVM ignores this option setting at run time.

For more information about the WIDGET-ID attribute, see its reference entry in the Handle Attributes and Methods Reference. For more information about the Use Widget ID (-usewidgetid) startup parameter, see OpenEdge Deployment: Startup Command and Parameter Reference.

With respect to internationalization, some double-byte and UTF-8 multi-byte characters display and print in one or two columns. Each unit in the format string represents one physical column. To display or print a character that requires two columns, the FORMAT phrase must specify two columns. For more information, see OpenEdge Development: Internationalizing Applications.