The PICTURE Clause

General Format

Syntax Rules

A PICTURE clause can be specified only at the elementary item level.
A character-string consists of certain allowable combinations of characters in the COBOL character set used as symbols. The allowable combinations determine the category of the elementary item.
The maximum number of characters allowed in the character-string is 30.
The maximum number of characters allowed in the character-string is 50.
The PICTURE clause must not be specified for the subject of a RENAMES clause.
PIC is an abbreviation for PICTURE.
The asterisk when used as the zero suppression symbol and the clause BLANK WHEN ZERO should not appear in the same entry.
This construct is, however, permitted, in which case zero suppression overrides the BLANK WHEN ZERO clause.
An integer in parentheses following a character indicates that the character is repeated the number of times shown by the integer.
BYTE-LENGTH must only be used for UTF-8 data items (that is, items defined as PICTURE U or PIC U). It indicates that the item is of fixed byte-length, and therefore must not also be used in conjunction with the DYNAMIC LENGTH clause. (Fixed byte-length items may hold a varying number of characters, depending on the size of each character.)
integer-1 indicates the length in bytes of the PICTURE clause.

General Rules

The categories of data that can be described with a PICTURE clause are: alphabetic, numeric, alphanumeric, alphanumeric edited, numeric edited,

national, national edited, UTF-8,

external floating-point,

and boolean.

Aside from numeric items, the number of character positions allocated to an item depends on the USAGE clause, as shown below:

Usage	Character type	Bytes per character
DISPLAY	Alphanumeric	1
DISPLAY-1	DBCS	2
NATIONAL	National	2
UTF-8	UTF-8	1 to 4 bytes

General rules within these categories are given below:

Alphabetic Data Rules

The PICTURE character-string can contain only the symbols "A" and "B".
The PICTURE character-string can contain only the symbol "A".
The contents when represented in standard data format must be one or more alphabetic characters.

Numeric Data Rules

The PICTURE character-string can contain only the symbols "9", "P", "S", and "V", and can contain up to 18 digit positions; or:
The PICTURE character-string can contain up to 31 digit positions; or:

The PICTURE character-string can contain up to 38 digit positions.
If unsigned, the data in standard data format must be a combination of the Arabic numerals "0", "1", "2", " 3", "4", "5", "6", "7", "8", and "9"; if signed, the item can also contain a "+", "-", or other representation of an operational sign. (See the topic The SIGN Clause.)

Alphanumeric Data Rules

The PICTURE character-string is restricted to certain combinations of the symbols " A", "X", "9", and the item is treated as if the character-string contained all X"s. A PICTURE character-string which contains all A"s or all 9"s does not define an alphanumeric item.
The contents when represented in standard data format can consist of any characters in the computer's character set.

Alphanumeric Edited Data Rules

The PICTURE character-string is restricted to certain combinations of the following symbols: "A", "X", " 9", "B", "0", and "/" as follows:
1. The character-string must contain at least one "B" and at least one "X" or at least one "0" (zero) and at least one "X" or at least one "/" (slash) and at least one "X", or:
2. The character-string must contain at least one "0" (zero) and at least one "A" or at least one "/" (slash) and at least one "A".
The contents when represented in standard data format can consist of any characters in the computer's character set.

Numeric Edited Data Rules

The PICTURE character-string is restricted to certain combinations of the symbols "B", "/", "P", "V" , "Z", "0", "9", ",", ".", "*", "+", "-", "CR", "DB", and the currency symbol. The allowable combinations are determined from the order of precedence of symbols and the editing rules as follows:
1. The PICTURE character-string can contain up to 18 digit positions; or:
  The PICTURE character-string can contain up to 31 digit positions; or:
  
  The PICTURE character-string can contain up to 38 digit positions.
2. The character-string must contain at least one "0" , "B", "/", "Z", "*", "+", ",", ".", "-", "CR" , "DB", or currency symbol.
The contents of the character positions that represent a digit must be one of the numerals.
If all character positions in the PICTURE character-string are represented by an insertion character, at least one of the insertion characters must be positioned to the left of the decimal point.

National Data Rules

The PICTURE character-string is restricted to the "N" symbol. Each "N" represents one national character position in the size of the data item.
The character-string represents a DBCS character when USAGE DISPLAY-1 is specified, or when no USAGE clause is specified and the NSYMBOL"DBCS" Compiler directive is in effect.
The character-string represents a national character when USAGE NATIONAL is specified, or when no USAGE clause is specified and the NSYMBOL"NATIONAL" Compiler directive is in effect.

National-edited Data Rules

The NATIONAL"2" Compiler directive must be in effect, and the PICTURE character-string must contain at least one "N" symbol, and at least one of the following symbols: B, 0 (zero), or / (slash). Each symbol represents one national character position in the size of the data item.

UTF-8 Data Rules

The PICTURE character-string is restricted to the "U" symbol. Each "U" represents one UTF-8 character position in the size of the data item.
If the BYTE-LENGTH clause is specified, only a single "U" symbol must be specified, and the number of character positions is determined by integer-1.
When BYTE-LENGTH is specified, the number of characters within the item may vary depending on the size of each character - the maximum being integer-1, when each character in the string is a single byte in length.
When required, items with BYTE-LENGTH specified are padded (with UTF-8 spaces) if the contents is not equal to the length of integer-1, or truncated when the contents exceeds integer-1.
Only UTF-8 data items specified with the BYTE-LENGTH clause may be defined within a group defined with the GROUP-USAGE UTF-8 clause.

External Floating-point Data Rules

The PICTURE string must have the following form:

A sign character must immediately precede both the significand and the exponent.

A "+" sign indicates that a positive sign will be used in the output to represent positive values and that a negative sign will represent negative values.

A "-"sign indicates that a blank will be used in the output to represent positive values and that a negative sign will represent negative values.

Each sign position occupies one byte of storage.

significand

The significand can contain the symbols:

9 . V

An actual decimal point can be represented with a period while an assumed decimal point is represented by a V. Either an actual or an assumed decimal point must be present in the significand; the decimal point can be leading, embedded or trailing. The significand can contain from 1 to 16 numeric characters.

E

Indicates the exponent.

exponent

The exponent must be a PIC "99".
The OCCURS, REDEFINES and RENAMES clauses can be associated with external floating-point items.
The SIGN clause is documentary only and has no effect on the representation of the sign.
The SYNCHRONIZED clause is documentary only.
The following clauses are invalid with external floating-point items:
BLANK WHEN ZERO JUSTIFIED VALUE

Boolean Data Rules

The PICTURE character-string can contain only the symbol "1".
The PICTURE character-string can contain up to 64 digit positions.
Values can be specified in literals with an opening separator B", for example B"1110", where the value is expressed as bits.

Comments:

The size of an elementary item, where size means the number of character positions occupied by the elementary item in standard data format, is determined by the number of allowable symbols that represent character positions. An integer which is enclosed in parentheses following the symbols "A", ",", "X" , "9", "N", "P", "U", "Z", "*", "B", "/", "0", "+", "-", or the currency symbol indicates the number of replications of the symbol. Note that the following symbols can appear only once in a given PICTURE: "S" , "V", ".", "CR", and "DB",

"E".

The functions of the symbols used to describe an elementary item are explained as follows:

A	Each "A" in the character-string represents a character position which can contain only a letter of the alphabet or a space.
B	Each "B" in the character-string represents a character position into which the space character will be inserted.
E	Marks the start of the exponent in an external floating-point item. The exponent occupies 1 byte of storage at run time.
N	Each "N" in the character-string represents one national character position in the size of the data item. If specified, an associated VALUE clause must contain either an alphanumeric literal, a national literal, or one of the following figurative constants: ZERO SPACE QUOTE HIGH-VALUE LOW-VALUE symbolic-character ALL alphanumeric-literal ALL national-literal NATIONAL is the only phrase permitted in the USAGE clause. When the NSYMBOL"NATIONAL" Compiler directive is in effect and the USAGE clause is omitted, USAGE NATIONAL is implied. The following additional clauses can also be specified: JUSTIFIED EXTERNAL GLOBAL OCCURS REDEFINES RENAMES SYNCHRONIZED VOLATILE Restriction: You cannot specify either the BLANK WHEN ZERO or the SIGN clause. If the NATIONAL"2" Compiler directive is in effect, you can specify a national-edited item by ensuring that the character-string includes at least one "N" symbol, and at least one of B, 0 (zero), or / (slash). The VALUE and additional clauses are the same as stated above for national characters. Literals are treated exactly as specified (no editing is done). Also, the USAGE NATIONAL clause must be specified or implied; however, NSYMBOL"NATIONAL" has no effect for national-edited items, and so cannot be used to imply USAGE.
P	Each "P" indicates an assumed decimal scaling position and is used to specify the location of an assumed decimal point when the point is not within the number that appears in the data item. The scaling position character "P" is 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 numeric items. The scaling position character "P" can appear only to the left or right as a continuous string of "P"s within a PICTURE description; since the scaling position character "P" implies an assumed decimal point (to the left of "P" s if "P"s are leftmost PICTURE characters and to the right if "P"s 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 character "P" and the insertion character "." (period) cannot both occur in the same PICTURE character-string. If, in any operation involving conversion of data from one form of internal representation to another, the data item being converted is described with the PICTURE character "P", each digit position described by a "P" is considered to contain the value zero, and the size of the data item is considered to include the digit positions so described. 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: Any operation requiring a numeric sending operand. An elementary 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.
S	The letter "S" is used in a character-string to indicate the presence, but neither the representation nor, necessarily, the position of an operational sign; it must be written as the leftmost character in the PICTURE. The "S" is not counted in determining the size (in terms of standard data format characters) of the elementary item unless the entry is subject to a SIGN clause which specifies the optional SEPARATE CHARACTER phrase. (See the topic The SIGN Clause.)
U	Each "U" in the character-string represents one UTF-8 character position in the size of the data item. If specified, an associated VALUE clause must contain either an alphanumeric literal, a UTF-8 literal, or one of the following figurative constants: ZERO SPACE QUOTE HIGH-VALUE LOW-VALUE symbolic-character ALL utf-8-literal UTF-8 is the only phrase permitted in the USAGE clause, and USAGE UTF-8 is implied if it is omitted. The following clauses can also be specified: JUSTIFIED EXTERNAL GLOBAL OCCURS REDEFINES RENAMES SYNCHRONIZED VOLATILE Restriction: You cannot specify either the BLANK WHEN ZERO or the SIGN clause.
V	The letter "V" is used in a character-string to indicate the location of the assumed decimal point and can only appear once in a character-string. The "V" does not represent a character position and therefore is not counted in the size of the elementary item. When the assumed decimal point is to the right of the rightmost symbol in the string the "V" is redundant.
X	Each "X" in the character-string is used to represent a character position which contains any allowable character from the computer's character set.
Z	Each "Z" in a character-string can only be used to represent the leftmost numeric character positions which will be replaced by a space character when the contents of that character position is zero. Each "Z" is counted in the size of the item.
9	Each "9" in the character-string represents a character position which contains a numeral and is counted in the size of the item.
0	Each "0" (zero) in the character-string represents a character position into which the numeral zero will be inserted. The "0" is counted in the size of the item.
/	Each "/" (slash) in the character-string represents a character position into which the slash character will be inserted. The "/" is counted in the size of the item.
,	Each "," (comma) in the character-string represents a character position into which the character "," will be inserted. This character position is counted in the size of the item. The insertion character "," must not be the last character in the PICTURE character-string. The insertion character "," can be the last character in the PICTURE character-string.
.	When the character "." (period) appears in the character-string it is an editing symbol which represents the decimal point for alignment purposes and, in addition, represents a character position into which the character "." will be inserted. The character "." is counted in the size of the item. For a given source unit the functions of the period and comma are exchanged if the clause DECIMAL-POINT IS COMMA is stated 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. The insertion character " ." must not be the last character in the PICTURE character-string. The insertion character "." can be the last character in the PICTURE character-string.
+, -, CR, DB	These symbols are used as editing sign control symbols. When used, they represent the character position into which the editing sign control symbol will be placed. The symbols are mutually exclusive in any one character-string and each character used in the symbol is counted in determining the size of the data item.
*	Each "" (asterisk) in the character-string represents a leading numeric character position into which an asterisk will be placed when the contents of that position is zero. Each "" is counted in the size of the item.
cs	A currency symbol represents character positions into which the currency string will be placed during editing. A currency symbol is represented in character-string-1 either by the currency sign or by the currency symbol specified in a CURRENCY SIGN clause in the Special-Names paragraph. The first occurrence of the currency symbol adds the number of characters in the currency string to the size of the item. Each subsequent occurrence of the currency symbol adds one to the size of the item. The CURRENCY-SIGN Compiler directive also affects the currency symbol used.

Two general methods of performing editing in the PICTURE clause are available: insertion editing, and suppression and replacement editing. There are four types of insertion editing available:

Simple insertion
Special insertion
Fixed insertion
Floating insertion

Two types of suppression and replacement editing are available:

Zero suppression and replacement with spaces
Zero suppression and replacement with asterisks

The type of editing which can be performed upon an item is dependent upon the category to which the item belongs. The table below specifies which type of editing can be performed upon a given category.

Table 1. Editing Types For Data Categories
Category	Type of Editing
Alphabetic	Simple insertion "B" only 1
Numeric	None
Alphanumeric	None
Alphanumeric edited	Simple insertion "0", "B" and "/"
Numeric edited	All 2
DBCS	Simple insertion
External floating-point	Special insertion
National	None
National-edited	Simple insertion "0", "B" and "/"
UTF-8	None

Note:

In the ANSI'74 standard, PICTURE clauses containing both "A" and "B" are treated as simple insertion in category Alphabetic. As the ANSI'85 standard does not support "B" in the Alphabetic category, the ANSI'85 standard considers this PICTURE as simple insertion in the Alphanumeric Edited category.
Floating insertion editing and editing by zero suppression and replacement are mutually exclusive in a PICTURE clause. Only one type of replacement can be used with zero suppression in a PICTURE clause.

The "," (comma), "B" (space), "0" (zero), and " /" (slash) are used as the insertion characters. The insertion characters are counted in the size of the item and represent the position in the item into which the character will be inserted.

This type of editing is valid for either numeric edited items or external floating-point items.

The "." (period) is used as the insertion character. In addition to being an insertion character it represents the decimal point for alignment purposes. The insertion character used for the actual decimal point is counted in the size of the item. The use of the assumed decimal point, represented by the symbol "V" and the actual decimal point, represented by the insertion character, in the same PICTURE character-string is disallowed. The result of special insertion editing is the appearance of the insertion character in the item in the same position as shown in the character-string.

The currency string and the editing sign control symbols "+" , "-", "CR", "DB" are the insertion characters. Only one currency symbol and only one of the editing sign control symbols can be used in a given PICTURE character-string. When the symbols "CR" or "DB" are used, they represent two character positions in determining the size of the item and they must represent the rightmost character positions that are counted in the size of the item. The symbol "+" or "-", when used, must be either the leftmost or rightmost character position to be counted in the size of the item. The currency symbol must be the leftmost character.

Table 2. Editing Symbols in PICTURE Character-Strings
Editing Symbol in Picture Character-string	Result
Editing Symbol in Picture Character-string	Data Item Positive or Zero	Data Item Negative
+	+	-
-	space	-
CR	2 spaces	CR
DB	2 spaces	DB

The currency symbol and the editing sign control symbols "+" and "-" are the floating insertion symbols and as such are mutually exclusive in a given PICTURE character-string.

Floating insertion editing is indicated in a PICTURE character-string by using a string of at least two of the floating insertion symbols. This string of floating insertion characters can contain any of the simple insertion characters or have simple insertion characters immediately to the right of this string. These simple insertion characters are part of the floating string.

When the floating insertion character is the currency symbol, this string of floating insertion characters can have one of the editing sign control symbols "+", "-", "CR" or " DB" immediately to the right of this string.

The leftmost character of the floating insertion string represents the leftmost limit of the floating symbol in the data item. The rightmost character of the floating string represents the rightmost limit of the floating symbols in the data item.

The second floating character from the left represents the leftmost limit of the numeric data that can be stored in the data item. Non-zero numeric data can replace all the characters at or to the right of this limit.

Floating insertion editing can be represented in a PICTURE character-string in only two ways. One way is to represent any or all of the leading numeric character positions on the left of the decimal point by the insertion character. The other way is to represent all of the numeric character positions in the PICTURE character-string by the insertion character.

If the insertion characters are only to the left of the decimal point in the PICTURE character-string, the result is that a single floating insertion character will be placed into the character position immediately preceding either the decimal point or the first non-zero digit in the data represented by the insertion symbol string, whichever is farther to the left in the PICTURE character-string. The character positions preceding the insertion character are replaced with spaces.

If all numeric character positions in the PICTURE character-string are represented by the insertion character, the result depends upon the value of the data. If the value is zero, the entire data item will contain spaces. If the value is not zero, the result is the same as when the insertion character is only to the left of the decimal point.

If all numeric positions in the PICTURE character string are represented by the insertion character, at least one numeric position must be to the left of the assumed or actual decimal point.

To avoid truncation, the minimum size of the PICTURE character-string for the receiving data item must be the number of characters in the sending data item, plus the number of non-floating insertion characters being edited into the receiving data item, plus one for the floating insertion character.

The suppression of leading zeros in numeric character positions is indicated by the use of the alphabetic character "Z" or the character "*" (asterisk) as suppression symbols in a PICTURE character-string. These symbols are mutually exclusive in a given PICTURE character-string. Each suppression symbol is counted in determining the size of the item. If "Z" is used, the replacement character will be the space and if the asterisk is used, the replacement character will be "*".

Zero suppression and replacement is indicated in a PICTURE character-string by using a string of one or more of the allowable symbols to represent leading numeric character positions which are to be replaced when the associated character position in the data contains a zero. Any of the simple insertion characters embedded in the string of symbols or to the immediate right of this string are part of the string.

Zero suppression can be represented in a PICTURE character-string in only two ways. One way is to represent any or all of the leading numeric character positions to the left of the decimal point by suppression symbols. The other way is to represent all of the numeric character positions in the PICTURE character-string by suppression symbols.

If the suppression symbols appear only to the left of the decimal point, any leading zero in the data which corresponds to a symbol in the string is replaced by the replacement character. Suppression terminates at the first non-zero digit in the data represented by the suppression symbol string or at the decimal point, whichever is encountered first.

If all numeric character positions in the PICTURE character-string are represented by suppression symbols and the value of the data is not zero, the result is the same as if the suppression characters were only to the left of the decimal point. If the value is zero and the suppression symbol is "Z", the entire data item will be spaces. If the value is zero and the suppression symbol is "*", the data item will be all "*" except for the actual decimal point.

The symbols "+", "-", "*", " Z" and the currency symbol, when used as floating replacement characters, are mutually exclusive within a given character-string.

The table below shows the order of precedence when using characters as symbols in a character-string. An "X" at an intersection indicates that the symbol(s) at the top of the column can precede, in a given character-string, the symbol(s) at the left of the row. Arguments appearing in braces indicate that the symbols are mutually exclusive. The currency symbol is indicated by the symbol "cs". At least one of the symbols "A " , "X", "Z", " 9" or "*", or at least two of the symbols "+" , "-" or "cs" must be present in a PICTURE string.

In this table, non-floating insertion symbols "+" and "-" , floating insertion symbols "Z", "*", " +", "-", and "cs", and other symbol "P" appear twice in the PICTURE character precedence chart. The leftmost column and uppermost row for each symbol represents its use to the left of the decimal point position. The second appearance of symbol in the row and column represents its use to the right of the decimal point position.

Table 3. PICTURE Character Precedence Chart
First Symbol		Non-Floating Insertion Symbols										Floating Insertion Symbols						Other Symbols
Second Symbol		B	0	/	,	.	+ -	+ -	CR DB	C S	E	Z *	Z *	+ -	+ -	C S	C S	9	A X	S	V	P	P	G	1
Non-Floating Insertion Symbols	B	X	X	X	X	X				X		X	X	X	X	X	X	X	X		X		X	X
	0	X	X	X	X	X				X		X	X	X	X	X	X	X	X		X		X
	/	X	X	X	X	X				X		X	X	X	X	X	X	X	X		X		X
	,	X	X	X	X	X				X		X	X	X	X	X	X	X			X		X
	.	X	X	X	X	X				X		X		X		X		X
	+ -
	+ -	X	X	X	X	X				X	X	X	X			X	X	X			X	X	X
	CR DB	X	X	X	X	X				X		X	X			X	X	X			X	X	X
	CC S						X
	E				X	X												X			X
Floating Insertion Symbols	Z *	X	X	X	X		X			X		X
	Z *	X	X	X	X	X	X			X		X	X								X		X
	+ -	X	X	X	X					X				X
	+ -	X	X	X	X	X				X				X	X						X
	C S	X	X	X	X		X									X
	C S	X	X	X	X	X	X									X	X				X
Other Symbols	9	X	X	X	X	X	X			X	X	X		X		X		X	X	X	X		X
	A X	X	X	X														X	X
	S
	V	X	X	X	X		X			X		X		X				X		X		X
	P	X	X	X	X		X			X		X		X				X		X		X
	P						X			X										X	X		X
	G	X																						X
	1																								X