Symbols used in the PICTURE clause

Any punctuation character that appears within the PICTURE character-string is not considered a punctuation character, but rather is a PICTURE character-string symbol.

When specified in the SPECIAL-NAMES paragraph, DECIMAL-POINT IS COMMA exchanges the functions of the period and the comma in PICTURE character-strings and in numeric literals.

The lowercase letters that correspond to the uppercase letters that represent the following PICTURE symbols are equivalent to their uppercase representations in a PICTURE character-string:


A, B, E, G, N, P, S,  V, X, Z, CR, DB

All other lowercase letters are not equivalent to their corresponding uppercase representations.

The meaning of each PICTURE clause symbol is defined in the following tables:
  • If the LOCALE phrase is not specified, see Table 1.
  • If the LOCALE phrase is specified, see Table 2.
The heading Size indicates how the item is counted in determining the number of character positions in the item. The type of the character positions depends on the USAGE clause specified for the item.

Usage Type of character positions Number of bytes per character
DISPLAY Alphanumeric 1
DISPLAY-1 DBCS 2
NATIONAL National 2
All others Conceptual Not applicable

Table 1. PICTURE clause symbol meanings when the LOCALE phrase is not specified
Symbol Meaning Size
A A character position that can contain only a letter of the Latin alphabet or a space. Each 'A' is counted as one character position in the size of the data item.
B For usage DISPLAY, a character position into which an alphanumeric space is inserted.

For usage DISPLAY-1, a character position into which a DBCS space is inserted.

For usage NATIONAL, a character position into which a national space is inserted.

Each 'B' is counted as one character position in the size of the data item.
E Marks the start of the exponent in an external floating-point item. For additional details of external floating-point items, see Data categories and PICTURE rules. Each 'E' is counted as one character position in the size of the data item.
G A DBCS character position. Each 'G' is counted as one character position in the size of the data item.
N A DBCS character position when specified with usage DISPLAY-1 or when usage is unspecified and the NSYMBOL(DBCS) compiler option is in effect.

For category national, a national character position when specified with usage NATIONAL or when usage is unspecified and the NSYMBOL(NATIONAL) compiler option is in effect.

For category national-edited, a national character position.

Each 'N' is counted as one character position in the size of the data item.
P An assumed decimal scaling position. Used to specify the location of an assumed decimal point when the point is not within the number that appears in the data item. See P symbol for further details. Not counted in the size of the data item. Scaling position characters are counted in determining the maximum number of digit positions in numeric-edited items or in items that are used as arithmetic operands.

The size of the value is the number of digit positions represented by the PICTURE character-string.

S An indicator of the presence (but not the representation, and not necessarily the position) of an operational sign. An operational sign indicates whether the value of an item involved in an operation is positive or negative. Not counted in the size of the elementary item, unless an associated SIGN clause specifies the SEPARATE CHARACTER phrase (which would be counted as one character position).
V An indicator of the location of the assumed decimal point. Does not represent a character position.

When the assumed decimal point is to the right of the rightmost symbol in the string, the V is redundant.

Not counted in the size of the elementary item.
X A character position that can contain any allowable character from the alphanumeric character set of the computer. Each 'X' is counted as one character position in the size of the data item.
Z A leading numeric character position. When that position contains a zero, a space character replaces the zero. Each 'Z' is counted as one character position in the size of the data item.
9 A character position that contains a numeral. Each nine specifies one decimal digit in the value of the item. For usages DISPLAY and NATIONAL, each nine is counted as one character position in the size of the data item.
0 A character position into which the numeral zero is inserted. Each zero is counted as one character position in the size of the data item.
1 A character position that contains a boolean value of B"1" or B"0". Usage must be explicitly or implicitly defined as DISPLAY. Each boolean value is counted as one character position in the size of the data item.
/ A character position into which the slash character is inserted. Each slash character is counted as one character position in the size of the data item.
, A character position into which a comma is inserted. Each comma is counted as one character position in the size of the data item.
.
An editing symbol that represents the decimal point for alignment purposes. If the period insertion character is the last symbol in the PICTURE character string, the PICTURE clause must be the last clause of that data description entry and must be immediately followed by the separator period. The decimal point character used at runtime is taken from the locale.
Note: For a given program, the functions of the period and comma are exchanged if the clause DECIMAL-POINT IS COMMA is specified in the SPECIAL-NAMES paragraph. In this exchange, the rules for the period apply to the comma and the rules for the comma apply to the period wherever they appear in a PICTURE clause.
Each period is counted as one character position in the size of the data item.
+
-
CR
DB

Editing sign control symbols. Each represents the character position into which the editing sign control symbol is placed. Each character used in the editing sign symbol is counted as one character position in the size of the data item.
* A check protect symbol: a leading numeric character position into which an asterisk is placed when that position contains a zero. Each asterisk is counted as one character position in the size of the item.
cs cs can be any valid currency symbol. A currency symbol represents a character position into which a currency sign value is placed. The default currency symbol is the character assigned the value X'24' in the code page in effect at compile time. In this document, the default currency symbol is represented by the dollar sign ($) and cs stands for any valid currency symbol. For details, see Currency symbol. The first occurrence of a currency symbol adds the number of characters in the currency sign value to the size of the data item. Each subsequent occurrence adds one character position to the size of the data item.
Table 2. PICTURE clause symbol meanings when the LOCALE phrase is specified
Symbol Meaning Size
9 A character position that contains a numeral and is counted in the number of numerals that may appear in the edited item. Each nine specifies one decimal digit in the value of the item. For usages DISPLAY and NATIONAL, each nine is counted as one character position in the size of the data item.
. An editing symbol that represents the decimal point for alignment purposes. If the period insertion character is the last symbol in the PICTURE character string, the PICTURE clause must be the last clause of that data description entry and must be immediately followed by the separator period. The decimal point character used at runtime is taken from the locale.
Note: For a given program, the functions of the period and comma are exchanged if the clause DECIMAL-POINT IS COMMA is specified in the SPECIAL-NAMES paragraph. In this exchange, the rules for the period apply to the comma and the rules for the comma apply to the period wherever they appear in a PICTURE clause.
Each period is counted as one character position in the size of the data item.
+ Editing sign control symbol. The + indicates that the edited item is to be signed in accordance with the specified locale. If + is not specified, the edited item will be unsigned. Each + is counted as one character position in the size of the data item.
cs The currency symbol in the character string indicates that the edited item is to include the currency string associated with the specified locale. The first occurrence of a currency symbol adds the number of characters in the currency sign value to the size of the data item. Each subsequent occurrence adds one character position to the size of the data item.

Figure 1 shows the sequence in which PICTURE clause symbols must be specified if the LOCALE phrase is not specified. See the notes at the end of the figure. Figure 2 shows the sequence in which PICTURE clause symbols must be specified if the LOCALE phrase is specified.

Figure 1. PICTURE clause symbol sequence when the LOCALE phrase is not specified
This image shows valid picture symbol sequences if the LOCALE phrase is not specified.
Notes to Figure 1:
  1. An X at an intersection indicates that the symbol(s) at the top of the column may, in a given character-string, appear anywhere to the left of the symbol(s) at the left of the row.
  2. The $ character, however it is represented in the appropriate character set, is the default value for the currency symbol.
  3. At least one of the symbols A, X, Z, 9, or *, or at least two of the symbols +, -, or $ must be present in a PICTURE string.
  4. The symbols G or N can appear alone in the PICTURE character-string.
  5. Nonfloating insertion symbols + and -, floating insertion symbols Z, *, +, -, and $, and the symbol P appear twice in the above PICTURE character precedence table. The leftmost column and uppermost row for each symbol represents its use to the left of the decimal point position. The second appearance of the symbol in the table represents its use to the right of the decimal point position. ({ }) indicate items that are mutually exclusive.
  6. Braces ({}) indicate items that are mutually exclusive.
Figure 2. PICTURE clause symbol sequence when the LOCALE phrase is specified
This figure illustrates the PICTURE CLAUSE symbol sequence when the LOCALE phrase is specified: LOCPCSS
 

P symbol

The symbol P specifies a scaling position and implies an assumed decimal point (to the left of the Ps if the Ps are leftmost PICTURE characters; to the right of the Ps if the Ps are rightmost PICTURE characters).

The assumed decimal point symbol V is redundant as either the leftmost or rightmost character within such a PICTURE description.

The symbol P can be specified only as a continuous string of Ps in the leftmost or rightmost digit positions within a PICTURE character-string.

In certain operations that reference a data item whose PICTURE character-string contains the symbol P, the algebraic value of the data item is used rather than the actual character representation of the data item. This algebraic value assumes the decimal point in the prescribed location and zero in place of the digit position specified by the symbol P. The size of the value is the number of digit positions represented by the PICTURE character-string. These operations are any of the following ones:

  • Any operation that requires a numeric sending operand
  • A MOVE statement where the sending operand is numeric and its PICTURE character-string contains the symbol P
  • A MOVE statement where the sending operand is numeric-edited and its PICTURE character-string contains the symbol P, and the receiving operand is numeric or numeric-edited
  • A comparison operation where both operands are numeric

In all other operations, the digit positions specified with the symbol P are ignored and are not counted in the size of the operand.

Currency symbol

The currency symbol in a picture character-string is represented by the default currency symbol $ or by a single character specified either in the CURRENCY compiler option or in the CURRENCY SIGN clause in the SPECIAL-NAMES paragraph of the ENVIRONMENT DIVISION.

If the CURRENCY SIGN clause is specified, the CURRENCY and NOCURRENCY compiler options are ignored. If the CURRENCY SIGN clause is not specified and the NOCURRENCY compiler option is in effect, the dollar sign ($) is used as the default currency sign value and currency symbol. For more information about the CURRENCY SIGN clause, see CURRENCY SIGN clause. For more information about the CURRENCY and NOCURRENCY compiler options, see CURRENCY in the COBOL for Linux® on x86 Programming Guide.

A currency symbol can be repeated within the PICTURE character-string to specify floating insertion. Different currency symbols must not be used in the same PICTURE character-string.

Unlike all other picture symbols, currency symbols are case sensitive. For example, 'D' and 'd' specify different currency symbols.

A currency symbol can be used only to define a numeric-edited item with USAGE DISPLAY.