USAGE and Numeric Representation

USAGE is an optional clause of a data description entry, written as USAGE IS COMP-3 or just COMP-3 (the words USAGE and IS are optional). It may be given on any level number except 66 and 88. On a group item it applies to every elementary item in the group, and an elementary item may not contradict the group’s usage. When no usage is written, it is implied from the PICTURE: DISPLAY when the picture has no G, N or U; NATIONAL for an N picture only when the NSYMBOL(NATIONAL) option is in effect, DISPLAY-1 (DBCS) when NSYMBOL(DBCS) is; UTF-8 for a U picture (Enterprise COBOL 6.5).

Source: Enterprise COBOL 6.5 Language Reference: USAGE clause

A computational item is one meant for arithmetic: it must be numeric, and its picture may contain only 9, S, V and P. Enterprise COBOL limits it to 18 decimal digits, except PACKED-DECIMAL, which holds 18 digits under ARITH(COMPAT) (the default) and 31 under ARITH(EXTEND). GnuCOBOL accepts up to 38 digits in any numeric field, but a binary item is limited to 18 digits and cobc says so. This program is deliberately wrong: a 19-digit binary item and a 39-digit packed item (the first message is the 38-digit limit, the second the binary one):

Source: Enterprise COBOL 6.5 Language Reference: Computational items and GnuCOBOL 3.2 manual

A numeric item with USAGE DISPLAY is zoned decimal: one digit per byte, in printable form. Each byte holds the character for the digit, so on z/OS (EBCDIC) the digits are F0 to F9 and under GnuCOBOL on ASCII systems they are 30 to 39. The numeric class test for a DISPLAY item checks that the digit nibble of each byte is 0 to 9 and that the zone nibbles and the sign are valid. Zoned decimal is the format of reports, terminals and most text files, and it is the right format for data that people or other systems read; it is the slowest for arithmetic, because the compiler converts it before and after every operation. IBM recommends the computational types for intensive arithmetic.

The sign. A signed DISPLAY item (S in the picture) carries its sign in the zone of one digit byte, the overpunch. Without a SIGN clause that byte is the last one. The valid signs on z/OS are C, A, E and F for positive and D and B for negative; the compiler itself generates C for positive or zero, D for negative and F for an unsigned item. An unsigned item, PIC 9(4), has no sign at all and ignores the sign of what is moved into it: the absolute value is stored. So +1234 is F1 F2 F3 C4 and -1234 is F1 F2 F3 D4 on z/OS, while an unsigned 1234 is F1 F2 F3 F4.

The SIGN clause moves or separates the sign. SIGN IS LEADING puts the overpunch on the first digit; SIGN IS TRAILING is the default and is the same as no clause. SEPARATE CHARACTER puts the sign in a byte of its own, + or -, before or after the digits; the S of the picture is then counted in the size of the item, so PIC S9(4) SIGN LEADING SEPARATE is five bytes. The SIGN clause applies only to DISPLAY and NATIONAL items with an S; it cannot be written on a binary or packed item (the compiler says so, shown below). With SIGN IS SEPARATE on a NATIONAL item the sign is a UTF-16 + or -, and a file described with CODE-SET must use separate signs for every signed numeric item.

This program shows the bytes of every sign form. In GnuCOBOL on ASCII a positive value is not overpunched at all and a negative value sets the high nibble of the last digit to 7; -fsign=EBCDIC selects the mainframe zones instead, on top of ASCII digits.

Default sign handling (ASCII):

With -fsign=EBCDIC the overpunch is the printable character that stands for the EBCDIC zone, the classic text form of a mainframe sign: the digits 1 to 9 become A to I when positive and J to R when negative (the digit 0 becomes { or }), so +1234 ends in D (44) and -1234 in M (4D):

The last six lines are identical in both runs, because the separate sign is a plain + (2B) or - (2D). That is the form to use for text files that other systems read, and for any file that must look the same on ASCII and EBCDIC machines.

Source: Enterprise COBOL 6.5 Language Reference: SIGN clause, Programming Guide: Sign representation of zoned and packed-decimal data and GnuCOBOL 3.2 manual: -fsign

Packed decimal stores two digits in each byte, one per nibble (four bits), and uses the last nibble for the sign. PACKED-DECIMAL and COMP-3 are synonyms. A field of n digits occupies n plus one nibbles, rounded up to whole bytes, so PIC S9(5)V99 (seven digits) takes four bytes and PIC S9(7) takes four. When the digit count is even the first nibble is unused and set to zero, which is why IBM recommends an odd number of digits: no space is wasted and the generated code is simpler. (Enterprise COBOL’s RULES(NOEVENPACK) option reports packed items with an even digit count.)

The sign nibble is C for positive, D for negative and F for unsigned, the same bit pattern as the zone of a signed DISPLAY item. So +1234 in PIC S9(4) COMP-3 is the three bytes 01 23 4C and -1234 is 01 23 4D. The value 12345 in an unsigned PIC 9(5) COMP-3 is 12 34 5F. Packed data is fixed point for arithmetic purposes and is the usual format of money on the mainframe, because decimal fractions are exact and the field is half the size of the zoned form.

A COMP-3 item always carries a sign nibble, whether or not the picture has an S; storing a negative value in an unsigned packed item stores the absolute value. Enterprise COBOL limits a packed item to 18 digits with ARITH(COMPAT) and 31 with ARITH(EXTEND); GnuCOBOL allows up to 38. GnuCOBOL’s Programmer’s Guide adds COMP-6, an unsigned packed item with no sign nibble at all, which Enterprise COBOL does not have.

BINARY, COMP, COMP-4 and COMPUTATIONAL are synonyms: a two’s-complement binary integer, scaled by the picture (a V or P is a power of ten, not a binary fraction). The storage is chosen from the number of digits: one to four digits is a halfword (2 bytes), five to nine a fullword (4 bytes), ten to eighteen a doubleword (8 bytes). On z/OS binary data is big-endian, the machine’s own order, so 12345 is 00 00 30 39. GnuCOBOL also stores COMP big-endian by default, whatever the host, for compatibility with the mainframe; the binary-byteorder configuration option may change it to the native order. It is slower on a little-endian machine, which the GnuCOBOL manual notes under "Optimize binary".

COMP-5 is native binary. It uses the byte order of the machine, and, more importantly, it is not limited to the value implied by the picture: a PIC 9(4) COMP-5 holds 0 to 65535, not 0 to 9999, because its capacity is the size of the storage (2, 4 or 8 bytes), and moves into it truncate at the binary field size. IBM’s ranges for COMP-5 are: S9(1) to S9(4) -32768 to +32767; S9(5) to S9(9) -2147483648 to +2147483647; the S9(10) to S9(18) range is the full signed 64 bits; an unsigned item has the corresponding 0 to 65535, 0 to 4294967295 and 0 to 18446744073709551615. A scaling picture works as expected: PIC S99V99 COMP-5 is a halfword and holds -327.68 to +327.67. COMP-5 is the usage for data that comes from or goes to non-COBOL code (C structures, CALL parameters, Db2 host variables, sockets and so on), where the bytes do not respect a decimal picture. One IBM subtlety: with ON SIZE ERROR a COMP-5 receiver is limited to the value of its decimal picture, not to its binary range.

GnuCOBOL adds COMP-X (big-endian unsigned, or signed with an S), and the C-like BINARY-CHAR, BINARY-SHORT, BINARY-LONG and BINARY-DOUBLE, with SIGNED or UNSIGNED: native binary integers of 1, 2, 4 and 8 bytes with no picture. They are the natural types for CALL interfaces to C (see Interoperability with C, Java and Python); the Enterprise COBOL 6.5 manuals list them only as reserved words.

A binary item has two limits: the number the picture allows (PIC 9(4) COMP means four digits, 0 to 9999) and the number the storage allows (two bytes hold up to 65535 unsigned). What happens to a value between the two, or beyond both, is the subject of the TRUNC option on z/OS and of the binary-truncate setting in GnuCOBOL. It affects BINARY, COMP and COMP-4 receiving fields in MOVE statements and arithmetic; it never affects COMP-5, packed or zoned items, or floating point.

IBM’s own example is MOVE 123451 TO BIN-VAR for PIC S99 USAGE BINARY: the result is 51 with TRUNC(STD), and -7621 with TRUNC(OPT) or TRUNC(BIN), because the low two bytes of 123451 are X'E23B', which overflows into the sign bit. TRUNC(BIN) is the recommended setting for programs whose binary fields are set by other products (IMS, Db2, C, PL/I), which place values that do not respect the picture. COMP-5 on selected items gives the same behaviour for just those items, without the performance cost of TRUNC(BIN) everywhere.

This program moves 12345 into a four-digit item of each usage, adds one to 9999, and then uses ON SIZE ERROR. It reads 12345 from a variable, because a constant that does not fit the picture is diagnosed at compile time (shown after the example).

Default dialect (binary-truncate: yes):

The binary item is truncated to 2345 and wraps to 0000 on 9999 + 1; the COMP-5 item holds the full values, ON SIZE ERROR fires for the COMP item, which did not raise it for the plain ADD above it, and COMP-3 and DISPLAY truncate to the picture. With -std=ibm the program behaves like TRUNC(BIN):

This is a real difference between GnuCOBOL and the mainframe: the ibm dialect of GnuCOBOL 3.2 sets binary-truncate to no, whereas Enterprise COBOL’s default is TRUNC(STD). A program that depends on truncation and is compiled for GnuCOBOL with -std=ibm keeps the extra digits, and no size error is raised until the value exceeds the storage. To get the TRUNC(STD) behaviour with that dialect, add -fbinary-truncate; the output then is as in the default dialect, except that DISPLAY pads a binary item to the digits of its size (02345) because pretty-display is off:

The compile-time diagnostic. A literal that does not fit the picture is reported by cobc -Wall as a truncation, and the program then runs with the truncated value (this example is deliberately wrong):

Source: Programming Guide: TRUNC, Language Reference: Computational items and GnuCOBOL 3.2 manual: -fbinary-truncate, -fno-trunc, -fbinary-size

The Taulli book says that binary data is "not good for math because there could be rounding differences". That is not right, and the difference matters when choosing a usage. A binary integer, COMP or COMP-5, is an exact integer in a fixed number of bits; addition, subtraction and multiplication give exact results as long as the result fits, and the scale of a picture such as S9(5)V99 COMP is a decimal scale factor applied to an exact integer, so 12.50 is stored exactly as 1250. What can go wrong with binary is not rounding:

The next example sums 0.10 one thousand times in COMP-3, COMP and COMP-2. The two integer-based types give exactly 100.00. The floating-point sum is not 100, and the same program shows the COMP-2 value of 0.1 after one conversion.

The result with -std=ibm was the same. A caveat on the digits: GnuCOBOL converts floating-point values through decimal in some operations, so the last digits of such a sum depend on that conversion and on the library, and are not the same as a sum in C. The point is not the digits, it is that fixed-point decimal usage (COMP-3, DISPLAY, or COMP with a scale) is the right choice for money, and floating point is not.

Source: Programming Guide: Formats for numeric data and GnuCOBOL 3.2 Programmer’s Guide: USAGE

COMP-1 is a single-precision (4 bytes) and COMP-2 a double-precision (8 bytes) floating-point number. They take no PICTURE, so there is no way to say how many digits are meaningful; VALUE is allowed. In COBOL 2002, FLOAT-SHORT and FLOAT-LONG are the standard names for the same two types; GnuCOBOL accepts both pairs, Enterprise COBOL 6.5 only COMP-1 and COMP-2 in the USAGE clause (FLOAT-SHORT and FLOAT-LONG are listed as potential reserved words).

The format differs. On z/OS the items are in System z hexadecimal floating point (HFP): sign bit, a 7-bit exponent that counts powers of 16, and a hexadecimal fraction, so 1.5 is 41 18 00 00 (COMP-1) and 41 18 00 00 00 00 00 00 (COMP-2) . GnuCOBOL stores IEEE 754 binary32 and binary64, native byte order: here 1.5 is 00 00 C0 3F and 00 00 00 00 00 00 F8 3F, as the program above printed. Binary data moved between the two systems must be converted; this is a classic migration issue, discussed in Legacy Features and Migration.

COBOL 2014 adds FLOAT-DECIMAL-16 and FLOAT-DECIMAL-34, IEEE 754 decimal floating point (Decimal64 and Decimal128), which keep decimal fractions exact for up to 16 or 34 digits. GnuCOBOL 3.2 accepts them (8 and 16 bytes, as printed above); Enterprise COBOL 6.5 does not list them in its USAGE clause, so they are not portable to the mainframe. GnuCOBOL also accepts FLOAT-EXTENDED, with a warning that its handling is unfinished.

The practical rules are short. Do not use floating point for money or for quantities compared for equality; do not use it as a loop counter. Use it for scientific or statistical values for which a relative error of a part in 10 to the power of 7 (single) or 15 (double) is acceptable. Convert to a decimal item before comparing or printing with a picture. Enterprise COBOL has the further rule that a floating-point item converted to a fixed-point one passes through intermediate precision whose rules fill Appendix A of the Programming Guide.

Source: Programming Guide: Formats for numeric data, Language Reference: Computational items and GnuCOBOL 3.2 Programmer’s Guide: USAGE

USAGE INDEX defines an index data item: an item that can hold the value of a table index, so the position found by a SEARCH can be saved in a field of the record or a parameter, and restored with SET. It has no picture, may not be used in arithmetic except through SET, and has the size the compiler chooses (4 bytes in GnuCOBOL; the table pages explain how an index relates to subscripts and displacements: Tables and OCCURS). Do not move a subscript into an index data item with MOVE; use SET index-item TO index-name.

USAGE POINTER defines a data pointer, an address that SET ADDRESS OF and ALLOCATE produce and that a CALL can pass. Its size is that of an address: 4 bytes with LP(32), 8 with LP(64); POINTER-32 is always 4 (Enterprise COBOL 6.3 and later, for 31-bit addressable data in a 64-bit program). PROCEDURE-POINTER and FUNCTION-POINTER hold the address of an entry point. In GnuCOBOL 3.2 a pointer is 8 bytes on a 64-bit host and a null POINTER is all zero bytes, as printed above; POINTER-32 is rejected with unknown USAGE: POINTER-32. Pointers are covered in Pointers and Dynamic Storage.

Source: Enterprise COBOL 6.5 Language Reference: USAGE clause

USAGE NATIONAL (with PIC N) holds characters as UTF-16, two bytes each; numeric items can be national too (a national decimal item uses two bytes per digit, and a signed one must have SIGN IS SEPARATE). USAGE UTF-8 (with PIC U, Enterprise COBOL 6.3 and later) holds UTF-8. DISPLAY-1 is the older double-byte (DBCS) type. The character sets, the conversion functions NATIONAL-OF and DISPLAY-OF, and the CODEPAGE option are on National UTF-8 and Code Pages; this page lists only their storage, in the table above. GnuCOBOL 3.2 recognises NATIONAL and UTF-8 and warns that they are unfinished, and its Programmer’s Guide states that NATIONAL is not supported. This program is deliberately a poor choice for portable code:

COBOL 2023 adds a NO SIGN phrase to USAGE (INCITS summary of the 2023 changes). It is not in the USAGE clause of Enterprise COBOL 6.5, and GnuCOBOL 3.2 rejects it with a syntax error. As the standard is paywalled and not read here, what the phrase means is not described on this page; an unsigned numeric item is written with a picture without an S, as always.

Source: Enterprise COBOL 6.5 Language Reference: USAGE clause, Programming Guide: Formats for numeric data and GnuCOBOL 3.2 Programmer’s Guide: USAGE

The NUMPROC option decides whether Enterprise COBOL trusts the sign nibbles of zoned and packed data. It has no effect on binary, national decimal or floating-point data.

The result of a numeric class test depends on NUMPROC and on NUMCLS, an installation option: with NUMCLS(PRIM) and NOPFD, signed items accept C, D and F; with NUMCLS(ALT) A to F; with PFD only C, D and positive zero. A system programmer knows the installation setting. GnuCOBOL has no NUMPROC. Its Programmer’s Guide says that a D sign nibble is negative and any other is positive, and the class test is stricter than the computation (above); -fhostsign relaxes it for an F sign.

Source: Programming Guide: NUMPROC, Sign representation of zoned and packed-decimal data and GnuCOBOL 3.2 Programmer’s Guide: USAGE

The quickest way to learn a usage is to look at its bytes. Three tools do that.

The program below prints the bytes of +1234.5 and -1234.5 in PIC S9(5)V9 for the formats; the figure after it is drawn from this output (its EBCDIC row has the same digits with the mainframe zones, computed from the rules above and not run here).

The figure puts the bytes side by side. The decimal point is never stored: V is an instruction to the compiler, and the value is the integer 12345 scaled by a tenth.

Figure: the same value, five storage formats; the amber box is the byte that carries the sign.

The output is identical with -std=ibm. The SIGN LEADING SEPARATE and SIGN TRAILING SEPARATE items are seven bytes long (six digits plus the sign byte), the other DISPLAY item is six.

Source: Enterprise COBOL 6.5 Language Reference: HEX-OF, Programming Guide: Converting to hexadecimal or bit data (HEX-OF, BIT-OF) and GnuCOBOL 3.2 manual: intrinsic functions

The choice follows from where the data lives and what is done with it.

The Circulation scenario shows the pattern. The member file USERID.CIRC.MEMBMAST (copybook MEMBREC) keeps the outstanding fine in MEMBER-FINES, PIC S9(5)V99, as zoned decimal in a 60-byte record. A program that reads the member master and does arithmetic on the fines can move each value to a packed or binary work item, so the computation does not pay for the zoned conversion. This program reads the sample MEMBMAST (the layout copied from MEMBREC) and shows the fine in each format:

Grace Hopper’s fine of 12.50 is 00 01 25 0C packed, 000004E2 big-endian binary (1250 scaled by two decimals), and E2040000 as COMP-5 on this host. Under -std=ibm the DISPLAY of the fine is 0001250+, the digits followed by the sign, because pretty-display is off there. The input is a file of text records, so the positive zoned values are plain digits with no overpunch, and the negated value of 12.50 dumps as 30303031323570: the digits 0001250 with the last one’s high nibble set to 7, GnuCOBOL’s ASCII sign for a negative item.

Source: GnuCOBOL 3.2 manual and Enterprise COBOL 6.5 Programming Guide: Formats for numeric data

The Taulli book introduces COMP-3 and BINARY in its chapter 4 with a short table and a few sentences. Three points need correcting or adding. First, binary integers are exact, and its remark that binary data is "not good for math because there could be rounding differences" confuses binary integers with binary floating point; the real concerns are truncation (TRUNC) and decimal scaling, as shown above. Second, it does not mention COMP-5, which is the usage to use when binary data crosses a language or product boundary, or the TRUNC and NUMPROC options that decide how COMP and the signs of zoned and packed data are processed. Third, since the book was written the usage set has grown: Enterprise COBOL 6.3 added UTF-8 and POINTER-32, COBOL 2014 added FLOAT-DECIMAL-16 and FLOAT-DECIMAL-34, and COBOL 2023 added NO SIGN; and the open-source compiler most readers use, GnuCOBOL 3.2, has a different default for truncation in its IBM dialect than the mainframe does.