01 WS-TOTAL-OUT PIC ZZZ.99 BLANK WHEN ZERO. defines an output field that becomes spaces when it receives a numeric value of zero. Without the clause, the same edited PICTURE leaves the decimal point and fractional zeroes visible as .00.
What COBOL BLANK WHEN ZERO does
The COBOL BLANK WHEN ZERO clause specifies that an elementary numeric or numeric-edited item contains only spaces when its value is zero. It is intended for print lines, reports, screens, and other presentation fields where a row of zeroes would distract from meaningful amounts.
The clause acts on the whole item. It does not merely remove leading zeroes. When the value is not zero, currency signs, commas, decimal points, sign controls, and zero-suppression symbols behave according to the PICTURE string.
Syntax and a working example
The clause is coded in a Data Division entry after the PICTURE and optional USAGE clauses. IBM also accepts ZEROS and ZEROES as alternative spellings, but BLANK WHEN ZERO is the form most programmers recognize.
The displayed characters between > and < are spaces. The source field may be signed or packed decimal; the restriction on the S symbol applies to the receiving item that contains the clause, not to a separate arithmetic source.
For broader PICTURE rules and data categories, use the COBOL data types and PICTURE guide. The COBOL USAGE clause guide explains why packed-decimal work fields and display fields serve different jobs.
Zero and nonzero output comparison
Assume WS-AMOUNT-OUT is defined as PIC $ZZZ,ZZZ.99 BLANK WHEN ZERO. The brackets below are diagnostic delimiters and are not part of the data item.
| Numeric source | Display idea | Reason |
|---|---|---|
0 | > < | The complete 11-character receiving field is filled with spaces. |
1250.50 | >$ 1,250.50< | The value is nonzero, so the PICTURE editing characters are applied. |
0.01 | >$ .01< | The value is not zero; BLANK WHEN ZERO does not activate. |
A displayed result can be hard to diagnose when spaces are expected. Surrounding the field with delimiters during testing proves whether the item is blank and exposes its exact width. See the COBOL DISPLAY examples for terminal and diagnostic output.
BLANK WHEN ZERO versus Z suppression
| Definition | Zero result | Nonzero result |
|---|---|---|
PIC 9(5) | 00000 | All five digit positions are present. |
PIC ZZZZ9 | 0 | Leading zeroes become spaces, but the final digit position remains. |
PIC ZZZ.99 | .00 | Leading positions are suppressed; the decimal point and fractional positions remain. |
PIC ZZZ.99 BLANK WHEN ZERO | Six spaces | The normal edited result appears for a nonzero value. |
The Z symbol is selective zero suppression. BLANK WHEN ZERO is an all-or-nothing test on the numeric value stored in the item. Choose the clause when a true zero amount should leave no punctuation or digits on the report.
The item becomes numeric-edited
An item with a numeric PICTURE becomes category numeric-edited when BLANK WHEN ZERO is added. Numeric-edited items are primarily receivers for display and printing. They cannot be sending operands in arithmetic expressions or in ADD, SUBTRACT, MULTIPLY, DIVIDE, or COMPUTE statements.
Here, WS-NET-AMOUNT remains suitable for arithmetic and WS-NET-OUT owns the presentation rule. The COBOL COMPUTE guide covers arithmetic results and size handling; the COBOL ROUNDED guide covers discarded fractional digits.
USAGE DISPLAY and USAGE NATIONAL
Enterprise COBOL for z/OS allows the clause on eligible items whose usage is explicitly or implicitly DISPLAY or NATIONAL. Most traditional report fields use DISPLAY. NATIONAL is available when the output field is numeric-edited national data.
If a shop standard or downstream file expects EBCDIC display data, do not change the usage merely to use the clause. Match the receiving field to the actual report, file, or interface contract.
Restrictions that cause compile errors
- The item must be elementary and described as numeric or numeric-edited.
- The receiving PICTURE string cannot contain the sign symbol
S. - The receiving PICTURE string cannot contain the check-protect symbol
*. - The clause cannot be used together with the
TYPEclause. - Because the result is numeric-edited, do not design the item as an arithmetic work field.
S9(...) on the numeric source. Use an eligible edited receiver with +, -, CR, or DB when the report must show the sign of a nonzero value.Asterisk suppression and BLANK WHEN ZERO cannot be coded on the same entry. Enterprise COBOL migration guidance calls out old OS/VS COBOL source that used both; remove BLANK WHEN ZERO when asterisk check protection is the required behavior.
VALUE clause behavior
BLANK WHEN ZERO does not change initialization performed by the VALUE clause. Do not assume that an item declared with VALUE ZERO starts as spaces merely because BLANK WHEN ZERO is also present. If the initial output must be blank, initialize it deliberately according to the program's data contract, or move a numeric zero into the display receiver before it is used.
The second MOVE invokes the receiving field's editing behavior. Keeping that conversion close to report construction also makes the source of blank output clear during maintenance.
Report-line example
A report often contains several numeric fields, but only optional amounts should disappear at zero. Apply the clause to those output columns rather than to every total.
The debit and credit columns remain aligned because blanking replaces characters without changing field length. Arithmetic such as division still belongs in numeric fields; see the COBOL DIVIDE examples before moving a result to a report line.
Common mistakes and checks
- Only part of zero disappears: the item uses
Zsuppression but not BLANK WHEN ZERO. - The compiler rejects the entry: inspect the receiving PICTURE for
Sor*, and check for a conflicting TYPE clause. - An arithmetic statement is rejected: the item became numeric-edited. Calculate in a numeric field and move the result.
- A nonzero value appears blank: display delimiters around the item, inspect the source value, and confirm that the correct receiver is moved into the output record.
- Unexpected initial contents appear: review the VALUE or INITIALIZE logic instead of assuming the clause controls initialization.
Official IBM references
- Enterprise COBOL 6.5 BLANK WHEN ZERO clause
- Displaying numeric data
- Symbols used in the PICTURE clause
- Data categories and PICTURE rules
- Unsupported OS/VS COBOL extensions
Frequently asked questions
What does BLANK WHEN ZERO do in COBOL?
It fills the entire receiving item with spaces when the numeric value stored in that item is zero. For a nonzero value, the normal PICTURE editing rules apply.
Can BLANK WHEN ZERO be used with PIC S9 fields?
No. The PICTURE string on the item that contains BLANK WHEN ZERO cannot contain the S symbol. Keep the signed value in a separate numeric field and move it to an eligible numeric-edited display field.
Is a field with BLANK WHEN ZERO still numeric?
If the item has a numeric PICTURE, adding BLANK WHEN ZERO changes its category to numeric-edited. Treat it as an output field rather than an arithmetic work field.
Does BLANK WHEN ZERO suppress only leading zeros?
No. Z picture symbols suppress selected leading positions. BLANK WHEN ZERO replaces the entire item with spaces only when its value is zero.
No comments:
Post a Comment