action.skip

Picture Clause

A PICTURE clause is used, as in basic COBOL, to indicate the size and format for each report field.

picture clause

Picture Clause: Coding Rules

  • All the available PICTURE symbols may be used, including a currency symbol defined by a CURRENCY SIGN phrase, provided they are consistent with a DISPLAY field, and the rules for combining them are exactly as for basic COBOL. Here are some examples:

    Picture symbols Description
    PIC ZZZZ9.99 reproduces the field with up to five integral places, of which four leading zeros can be changed to a space, followed by a decimal point and two fractional places.
    PIC -$(5)9 outputs a "-" sign if the field is negative, followed by from 1 to 6 digits, with leading zeros changed to a space, and a currency symbol placed immediately before the first digit.
    PIC XXBXXBXX outputs a six-character field, with spaces inserted between characters 2 and 3, and characters 4 and 5.

  • If the item is DBCS (Double-Byte Character Set), the PICTURE may contain only the symbols G and B (representing a DBCS space). However, a PICTURE clause is not required with a DBCS literal.

  • Report writer allows the additional left-shift PICTURE symbols "<" and ">" to indicate that all or part of your field is variable-length . These symbols may be used only in the REPORT SECTION. You may place the "<" symbol anywhere within the PICTURE, in any number of places, provided that it is followed by one of the following symbols: "X", "A", "9", "Z", or floating (that is, repeated) "-". (In other words, it must appear before a symbol that represents "data", as opposed to an "editing" symbol.) The ">" symbol may optionally be used to terminate its scope. The effect of these symbols is described below).

  • Report writer also allows general insertion characters, in the REPORT SECTION only. These are indicated by writing the characters to be inserted in "quotes" (or 'apostrophes') anywhere in the PICTURE, for example: PIC 99"."99"."99. These insertion characters do not take a repetition factor (so that PIC "."(5)X is invalid and must be written PIC "....."X).

  • You may omit the PICTURE clause in an entry that has a VALUE clause, whether nonnumeric (when a PICTURE X(n) is assumed) or (unsigned) numeric (when a PICTURE S9(n) DISPLAY is assumed.) (A SYMBOLIC CHARACTER is treated as a one byte nonnumeric.) A PICTURE is required if you use ALL "literal", or a figurative constant such as QUOTE. In the case of a multiple VALUE or multiple-choice entry, there may be several "literals" but still no PICTURE is required.

  • If you use a SOURCE, SUM/COUNT, or FUNCTION clause, the PICTURE is necessary, even if you want to display the field in exactly the same format in which it is stored.

  • If the OSVS precompiler option is in effect, PICTURE symbol "A" may be used even with a literal that is not entirely alphabetic.

  • In common with the rest of the DATA DIVISION, PICTURE is allowed only in an elementary entry.

Picture Clause: Operation

  • In the REPORT SECTION, the PICTURE clause plays the same role as it does in other SECTIONs. The rest of this section and the next describe the extensions which are unique to the REPORT SECTION.

  • General insertion characters may used to reduce the number of entries to be coded. For example:

    picture-general-insertion

    and

    picture-general-insertion

    Note that an insertion character specified in this way never has any semantic significance. Thus "." is never treated as a decimal point for alignment purposes.

Variable-length fields ("<" and ">" symbols)

  • If you code the "<" symbol somewhere in your PICTURE in the REPORT SECTION, report writer takes it as referring to the following symbol and repetitions of that symbol, until the end of the PICTURE or a change of symbol is found. (The use of parenthesis as a shorthand for repetition does not count as a change of symbol.) The "<" symbol itself does not contribute to the length of the field. In the following case: PIC 9<99,999.<99

    Report writer will divide the field into the following parts:

    Fields Description
    9 1 character fixed
    <99 0 to 2 characters variable
    ,999. all fixed

    The variable parts of your field are represented by those parts of your PICTURE that follow a "<" symbol, up to a change of symbol. To mark where each variable part ends, you may code a ">" symbol, resulting, in the above case, in: PIC 9<99>,999.<99>. By convention PIC <Z(n) is taken to mean the same as the more conventional PIC <9(n), and PIC <$(n) is understood to mean the same as PIC $<9(n-1).

  • When your field is output, report writer first stores the value to be output in a working area whose PICTURE is the same as the PICTURE you coded but without the "<" symbol(s) . It then examines each part of your field that corresponds to a variable part of the PICTURE. If the symbol after the "<" is "X" or "A", that part is non-numeric and report writer will delete trailing spaces (that is, it will not advance COLUMN-COUNTER over them). If the symbol after the "<" is "9" or "Z" or "-", that part is numeric and report writer will delete leading zeros by left-shifting the contents of the rest of the field. After a decimal point, either explicit (.) or implicit (V) followed by a "<" symbol, it is trailing zeros that are deleted.

  • When characters are deleted, any characters that follow them are pulled to the left over them. This gives a free format effect to variable fields that have several parts. When the field has been output, the horizontal pointer (COLUMN-COUNTER), will point to the last character stored. If your next entry has an absolute COLUMN, you will have a variable number of spaces from the end of this field to the fixed starting point of the next. If, however, your next entry has a relative COLUMN (COL +), the number of spaces between the fields will be fixed, but the starting position of the next field will vary.

  • You may use the "<" and ">" symbols to split any part of your field into two fragments, one variable and one fixed, resulting in a minimum size and a maximum size. For example: PIC XX means from 2 to 5 non-numeric characters; while PIC <999>9 means from 1 to 4 numeric characters (a form that is more useful than PIC <9(4) because a value of all zeros is reproduced as a zero).

  • Here are some examples of the "<" symbol:

    symbol examples

  • Special action is taken with the "," (comma) and "." (decimal point) symbols. If you write a "<" and a series of "9" symbols before "," and the numeric value that corresponds to them is zero, then the "," will also be deleted. Also, if you write "<" after a "." (decimal point) and all the numeric positions after the decimal point are zero, then the decimal point will also be deleted. For example, if your field is described as: PICTURE <99,<999,<999.<99. Then values of 00002345.10 and 00000001.00 will be reproduced as: picture values.

  • Any "," or "." encountered in a numeric field after a "<" symbol turns off the effect of the "<". If you want its effect to persist across such an insertion character, you must turn it on again by coding another "<" symbol; for example: PIC 9,<999>,<999>.99.

Compatibility

Only new Report Writer allows the '<' and '>' symbols and general insertion characters in quotes or apostrophes. In all other aspects of the PICTURE clause, both implementations are compatible.

The general insertion character feature may be incompatible with Codasyl (and hence some future standard) if quotes or apostrophes in a PICTURE are ascribed some different significance.