PICTURE attribute
The PICTURE
attribute specifies a character pattern for data entry
in a text field, and prevents entry of values that conflict with the specified pattern.
Syntax
PICTURE = "format-string"
- format-string defines the data input pattern of the field.
Usage
format-string can be any combination of characters, where the characters
"A
", "#
" and "X
" have a special meaning.
- The placeholder "
X
" specifies any character at the given position, for a character width of 1. - The placeholder "
#
" specifies a digit character (1,2,3,…) at the given position. - The placeholder "
A
" specifies any alphabetic character (A, B, é, É), for a character width of 1, at the given position.
The "X"
and "A"
placeholders represent characters in the
current application locale, for a character width of
1. When using a locale charset allowing fullwidth
characters like Chinese ideographs using a width of 2, two placeholders "XX"
or "AA"
need to be specified to allow fullwidth character input.
Any character in the PICTURE
specification different from "A
",
"X
" and "#
" is treated as a literal. Such characters automatically
appear in the field and do not have to be entered by the user.
The PICTURE
attribute does not require data entry into the
entire field. It only requires that whatever characters are entered conform to
format-string.
Combine the PICTURE
attribute with the UPSHIFT
attribute, to allow only
uppercase letters (A,B,C,...)
When PICTURE
specifies input formats for DATETIME
or INTERVAL
fields, the form compiler does not check the syntax of
format-string. Any error in format-string
such as an incorrect field separator, produces a runtime error.
The typical usage for the PICTURE
attribute is for (fixed-length)
CHAR
fields. It is not recommended to use PICTURE
for other data
types, especially numeric or date/time fields: The current value of the field must always match the
PICTURE
attribute.
Understand that the PICTURE
attribute defines a mask for data entry. In order
to format fields when data is displayed to the field, use the FORMAT
attribute
instead. FORMAT
is typically used for numeric and date fields, while
PICTURE
is typically used for formatted character string fields requiring
input control.
The PICTURE
attribute is ignored in CONSTRUCT
and
DISPLAY
/ DISPLAY ARRAY
instructions. It only effects
INPUT
and INPUT ARRAY
dialogs.
Example
EDIT f001 = carinfo.ident, PICTURE = "AA####-AA(X)";