Specifies one or more attributes for a widget.
[ at-phrase ] [ AS datatype | LIKE field ] [ ATTR-SPACE | NO-ATTR-SPACE ] [ AUTO-RETURN ] [ BGCOLOR expression ] [ BLANK ] [ COLON n| TO n ] [ COLUMN-LABEL label ] [ DEBLANK ] [ DCOLOR expression ] [ DISABLE-AUTO-ZAP ] [ FGCOLOR expression ] [ FONT expression ] [ FORMAT string ] [ HELP string ] [ LABEL label [ , label]...| NO-LABELS ] [ NO-TAB-STOP ] [ PFCOLOR expression ] [ VALIDATE ( condition , msg-expression ) ] [ view-as-phrase ] [ WIDGET-ID id-number ] |
The column, row and column, or x and y pixel location you want the display to start. The AT option does not left justify the data; it simply indicates the placement of the data area.
AT { n
|{ COLUMN column | COLUMN-OF relative-position }
{ ROW row | ROW-OF relative-position }
[ COLON-ALIGNED | LEFT-ALIGNED | RIGHT-ALIGNED ]
|{ X x | X-OF relative-position }
{ Y y | Y-OF relative-position }
[ COLON-ALIGNED | LEFT-ALIGNED | RIGHT-ALIGNED ]
}
|
See the AT phrase reference entry for more information.
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.
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:
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".
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 .
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:
r-colbl.p
FOR EACH Customer NO-LOCK:
DISPLAY Customer.Name COLUMN-LABEL "Customer!Name"
Customer.SalesRep COLUMN-LABEL "Name of!Sales!Representative".
END.
|
The AVM does not display column labels if you use the SIDE-LABELS or the NO-LABELS option with the Frame phrase.
You must enclose the label string in quotation marks. If you want to use the exclamation point (!) as one of the characters in a column label, use two exclamation points (!!).
Specifies whether the value of the AUTO-ZAP attribute will be ignored. See the AUTO-ZAP attribute reference entry. This option only applies to fill-ins.
The following example defines a frame with two fill-ins, both of which specify the DISABLE-AUTO-ZAP option:
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.
| 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.
| Data type | Default display format |
|---|---|
| CHARACTER | x(8) |
| CLASS1 | N/A |
| DATE | 99/99/99 |
| DATETIME | 99/99/9999 HH:MM:SS.SSS |
| DATETIME-TZ | 99/99/9999 HH:MM:SS.SSS+HH:MM |
| DECIMAL | ->>,>>9.99 |
| HANDLE2 | >>>>>>9 |
| INT64 |
->,>>>,>>9 |
| INTEGER | ->,>>>,>>9 |
| LOGICAL | yes/no |
| LONGCHAR3 | See footnote.3 |
| MEMPTR4 | See footnote 4. |
| RAW4 | See footnote 4. |
| RECID | >>>>>>9 |
| ROWID4 | See footnote 4. |
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.
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.
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.
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.
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.
| 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 |
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:
See the TAB-STOP attribute reference entry for related information.
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.
FIND FIRST Customer. FIND FIRST Order. UPDATE Order.CustNum Order.SalesRep VALIDATE(LENGTH(Order.SalesRep) > 1, "Invalid sales rep value."). |
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:
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.
Specifies the type of widget. This is the syntax for view-as-phrase:
VIEW-AS { editor-phrase
| FILL-IN [ NATIVE ] [ size-phrase ]
| radio-set-phrase
| selection-list-phrase
| slider-phrase
| TEXT [ size-phrase]
| TOGGLE-BOX [ size-phrase ]
}
|
For more information on view-as-phrase, see the VIEW-AS phrase reference entry.
If you specify an invalid ID, the compiler displays an error message. This option is supported in graphical interfaces only, and only in Windows.
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.
r-frmat.p
DEFINE VARIABLE password AS CHARACTER NO-UNDO.
UPDATE password FORMAT "x(6)" BLANK
VALIDATE(password = "secret", "Sorry, wrong password")
HELP "Maybe the password is 'secret' !"
WITH FRAME passw CENTERED SIDE-LABELS.
HIDE FRAME passw.
REPEAT:
PROMPT-FOR Customer.CustNum COLON 20. FIND Customer USING Customer.CustNum.
UPDATE
Customer.Name LABEL "Customer Name" COLON 20
VALIDATE(Customer.Name NE "", "Please enter a name")
Customer.Address HELP "Please enter two lines of address"
COLON 20 LABEL "Address"
Customer.Address2 NO-LABEL COLON 20
Customer.City COLON 20
Customer.State COLON 20
Customer.PostalCode COLON 20 SKIP(3)
Customer.Phone AT 5 FORMAT "(999) 999-9999"
Customer.Contact TO 60
WITH CENTERED SIDE-LABELS.
END.
|
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.