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"
  1. 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)";