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 = "picture-string"
- picture-string defines the data input pattern of the field.
Usage
The PICTURE
attribute defines an input mask for CHAR
,
VARCHAR
or STRING
fields. Do not use this attribute for numeric or
date/time fields.
picture-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 picture-string.
Combine the PICTURE
attribute with the UPSHIFT
attribute, to allow only
uppercase letters for X
and A
place holders.
When PICTURE
specifies input formats for DATETIME
or
INTERVAL
fields, the form compiler does not check the syntax of
picture-string. Any error in picture-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)";