A picture specification is a sequence of picture characters. A picture specification can be either a character picture specification or a numeric character picture specification. The picture specification is enclosed in single or double quotation marks.
The sequence of picture characters describe the contents of each position of either a character data item or numeric character data item, as well as the contents of the output. An A or X character in the picture specification defines it as a character picture specification. A picture specification without an A or X character is a numeric character picture specification.
A character pictured item consists of alphabetic characters, decimal digits, blanks, currency symbols, and punctuation characters.
A character picture specification includes:
The character picture characters are:
A character picture specification describes a nonvarying character data item. You can specify that any position in the data item contain characters only from certain subsets of the available character set. Data consists of alphabetic characters, decimal digits, and blanks. The only valid characters in a character picture specification are X, A, and 9.
When a character value is assigned or transferred to a picture character data item, the particular character in each position is validated according to the corresponding picture specification character. If the character data does not match the specification at a given position, the CONVERSION condition is raised for the invalid character.
In the following example, valid values for PartNum include:
'BF123M'
'KL092/'
'BT013'
declare PartNum picture'AA999X'; put skip edit(PartNum)(P'AA999X');
A numeric character pictured item consists only of decimal digits, an optional decimal point, and optional plus or minus signs. While other arithmetic characters such as currency symbols can also be specified, they are not part of the variable's numeric character value. Other arithmetic characters however are stored with the digits and are part of the variable's character value.
A numeric character picture specification includes:
| Category | Character | Description |
|---|---|---|
| decimal place character | V | Affects the numeric interpretation of the value only. The decimal point character is not actually stored. |
| digit characters | 9, Z, *, Y | Mark the positions occupied by decimal digits and affect both the numeric interpretation and character representation of the value. |
| encoded sign characters | T, I, R | Represent a digit that has the sign of the value encoded in the same position with the digit, thereby affecting both the numeric interpretation and character representation of the value. These characters can be used wherever the digit specifier '9' is valid. |
| drifting characters | $, +, –, S | Indicates digits or symbols to be inserted in the internal representation of a character. (See the section Drifting Characters and Strings.) |
| insertion characters | Decimal point (.), comma (,), slash (/), and space (B) | Inserted between digits to indicate that characters are inserted in the internal representation of the pictured value. Drifting characters also function as insertion characters when they are used singly. |
| credit and debit | CR, DB | Always specified as two-character symbols. (See the section Credit and Debit Characters.) |
The following describes the numeric picture characters.
| Character | Description |
|---|---|
| V | Indicates the position of the "assumed" decimal point. All digit positions to the right of the 'V' are fractional digits.
Any value assigned to a pictured value is first scaled so that its decimal point is aligned with the 'V'. Only one 'V' character can appear in a picture. If a picture does not contain the 'V' character, it is assumed to be at the right end of the picture, implying an integer value. |
| B, ./ | Indicate the positions at which a space (B), comma, decimal point, or slash, respectively, are inserted. These picture characters are inserted into the pictured value only if they are preceded by a nonzero digit or if they are preceded by a '9' or 'V' picture character. If they are not inserted, a zero suppression character (a blank) or an asterisk (*) is inserted instead.
If an asterisk or drifting string occupies the position preceding the insertion character and that position corresponds to a leading zero, the asterisk or drifting string character also suppresses the insertion character. The 'V' and decimal point (.) must be adjacent to one another to ensure that the decimal point is in the same position in both the numeric and character interpretations. The period should follow the 'V' to ensure that it will be in the correct location and will appear whenever any fractional digit is significant. |
| Z | Indicates a decimal digit with leading zero suppression.
The 'Z' causes zero suppression using a blank as the suppression character. A 'Z' must not be preceded by a '9' or a drifting string. A picture containing a 'Z' must also not contain an asterisk (*). If 'Z' picture characters appear to the left of 'V', all leading zeros in positions corresponding to those 'Z' characters are suppressed. Nonzero digits and significant zeros are never suppressed. Suppressed zeros are represented by spaces. If a 'Z' appears to the right of 'V', all digits in the value must be indicated by 'Z' characters. Fractional zeros are then suppressed only if all fractional digits are zero and all integer digits are suppressed. In this case, the internal representation contains only spaces in the digit positions. |
| * | Indicates a decimal digit with leading zero suppression. The '*' causes zero suppression using an asterisk as the suppression character. An '*' must not be preceded by a '9' or a drifting string. A picture containing an '*' must also not contain a 'Z'.
The rules for '*' are otherwise the same as those for 'Z'. |
| S | Indicates the position of the plus sign (+) or minus sign (-), which may or may not be drifting. The 'S' causes the plus sign to be inserted if the numeric value is greater than or equal to zero, and causes the minus sign to be inserted if the value is less than zero.
If an 'S' occurs more than once in a picture, the entire field of 'S's is a drifting string and can only contain a 'V' and one or more 'B' , '.' or '/' picture characters. Such a field cannot be preceded by a '9', 'Z', or '*', and if it contains a 'V' followed by one or more 'S's, it cannot be followed by a '9'. The total number of digits represented by a drifting string is one less than the number of 'S's in the field. The digits are zero suppressed and a sign of '+' or '-' is inserted immediately preceding the most significant digit of the value. A single 'S' causes a sign of '+' or '-' to be inserted into the pictured value, at the location implied by the position of 'S' in the picture. |
| + | Indicates the position of the plus sign (+) to be inserted if the numeric value is greater than or equal to zero. Operates exactly like 'S', except that the sign of negative values is indicated by a blank. |
| – | Indicates the position of the minus sign (–) to be inserted if the numeric value is less than zero. Operates exactly like 'S', except that the sign of positive values is indicated by a blank. |
| $ | Indicates the position of the dollar sign ($) to be inserted. Operates like 'S', except that a '$' is inserted instead of either sign. |
| 9 | Indicates a decimal digit, including leading zeros. The position occupied by '9' always contains a decimal digit, regardless of whether the digit is, or is not, significant in the numeric interpretation of the pictured value. |
| Y | Indicates the position of a decimal digit in which the zero digit is always suppressed by a blank, regardless of the position of 'Y' relative to other picture characters. |
| CR | Indicates the position at which 'CR' is inserted if the number is less than zero. These two characters must appear as a pair on the rightmost end of the picture. They are replaced by two blanks in internal representation if the value is not negative. |
| DB | Indicates the position at which 'DB' is inserted if the number is less than zero. Like 'CR,' these two characters must appear as a pair, may only appear on the rightmost end of the picture, and are replaced by two blanks in internal representation if the value is not negative. |
| T | Indicates the position of a decimal digit with an encoded plus or minus sign. The digit contains an encoded plus sign if the numeric value is greater than or equal to zero and an encoded minus sign if the value is less than zero. (See table below for representations of encoded sign digits.) |
| I | Indicates the position of a decimal digit with an encoded plus sign if the numeric value is greater than or equal to zero. If the value is less than zero, the position contains an ordinary digit. |
| R | Indicates the position of a decimal digit with, possibly, an encoded minus sign if the numeric value is less than zero. If the value is greater than or equal to zero, the position contains an ordinary digit. |