The USAGE clause specifies the format of a data item in computer memory or in a file record.
In some circumstances, a data item's file-record format may differ from its computer-memory format as specified by the USAGE clause. This can occur when non-COBOL file systems with different data storage formats are being accessed through an interface. For example, Acu4GL uses SQL to access non-COBOL file systems, and in the process a translation occurs on the data.
General Format
[ USAGE IS ] {COMPUTATIONAL }
{COMP }
{COMPUTATIONAL-1 }
{COMP-1 }
{COMPUTATIONAL-2 }
{COMP-2 }
{COMPUTATIONAL-3 }
{COMP-3 }
{COMPUTATIONAL-4 }
{COMP-4 }
{COMPUTATIONAL-5 }
{COMP-5 }
{COMPUTATIONAL-6 }
{COMP-6 }
{COMPUTATIONAL-X }
{COMP-X }
{COMPUTATIONAL-N }
{COMP-N }
{BINARY }
{PACKED-DECIMAL }
{DISPLAY }
{INDEX }
{POINTER }
{FLOAT }
{DOUBLE }
{SIGNED-SHORT }
{UNSIGNED-SHORT }
{SIGNED-INT }
{UNSIGNED-INT }
{SIGNED-LONG }
{UNSIGNED-LONG }
{HANDLE [ OF {WINDOW } ] }
{SUBWINDOW }
{FONT [font-name] }
{control-type }
{THREAD }
{MENU }
{VARIANT }
{LAYOUT-MANAGER [layout-name] }
Syntax Rules
COMP COMPUTATIONAL COMP-1 COMPUTATIONAL-1 COMP-2 COMPUTATIONAL-2 COMP-3 COMPUTATIONAL-3 COMP-4 COMPUTATIONAL-4 COMP-5 COMPUTATIONAL-5 COMP-6 COMPUTATIONAL-6 COMP-X COMPUTATIONAL-X COMP-N COMPUTATIONAL-N
01 F-DATA-1 USAGE IS FLOAT
VALUE IS 3.97E+24.
The data description entry for a C-style data type cannot contain any of the following clauses: BLANK WHEN ZERO, JUSTIFIED, or PICTURE.
General Rules
| # of "9"s | Default | -D1 | -Dm | -D7 |
|---|---|---|---|---|
| 1-2 | 2 | 1 | 1 | 1 |
| 3-4 | 2 | 2 | 2 | 2 |
| 5-6 | 4 | 4 | 3 | 3 |
| 7 | 4 | 4 | 4 | 3 |
| 8-9 | 4 | 4 | 4 | 4 |
| 10-11 | 8 | 8 | 5 | 5 |
| 12 | 8 | 8 | 6 | 5 |
| 13-14 | 8 | 8 | 6 | 6 |
| 15-16 | 8 | 8 | 7 | 7 |
| 17-18 | 8 | 8 | 8 | 8 |
| 19 | 12 | 12 | 9 | 8,9 |
| 20 | 12 | 12 | 9 | 9 |
| 21 | 12 | 12 | 9 | 9 |
| 22 | 12 | 12 | 10 | 10 |
| 23 | 12 | 12 | 10 | 10 |
| 24 | 12 | 12 | 11 | 10,11 |
| 25 | 12 | 12 | 11 | 11 |
| 26 | 12 | 12 | 11 | 11 |
| 27 | 12 | 12 | 12 | 12 |
| 28 | 12 | 12 | 12 | 12 |
| 29 | 16 | 16 | 13 | 13 |
| 30 | 16 | 16 | 13 | 13 |
| 31 | 16 | 16 | 13 | 13 |
The format of a COMP-5 data item is identical to a COMP-4 data item, except that the data is stored in a machine-dependent format. It is stored in an order that is natural to the host machine. For example, a PIC S9(9) COMP-5 data item is equivalent to a 32-bit binary word on the host machine, and a PIC S9(20) COMP-5 item is equivalent to a 64-bit word.
A VALUE clause for a COMP-5 data item is stored in a machine-independent format and is adjusted when it is loaded into the data item. This ensures that the value is the same from machine to machine.
On arithmetic and non-arithmetic stores into COMP-5 items, if truncation is required, by default ACUCOBOL-GT truncates in decimal to the number of digits given in the PICTURE clause. You can use the "--TruncANSI" compiler option to force truncation in binary to the capacity of the allocated storage of COMP-5 items. The "-Dz" and "--noTrunc"options also effects truncation. See Book 1, section 2.1.9, "Data Storage Options," for more information.
Level 01 and level 77 data items that are COMP-5 are automatically synchronized to an appropriate machine boundary, regardless of any compile-time settings. This allows you to pass these items safely to C subroutines without having to concern yourself with alignment.
If COMP-5 is used with a PIC X(n) data item and assigned an alphanumeric value, the results are undefined. For example, the following code fragment causes NUM to have an undefined number and the resulting value for the last line will be "100":
NUM PIC X(5) COMP-5. ALPHANUM PIC X(9). MOVE "ABC" TO NUM. MOVE "1,000" TO NUM. MOVE ALPHANUM TO NUM. MOVE "100" TO NUM.
A PIC X(n) data item used with COMP-5 cannot be signed.
Regardless of the number of "9" symbols in the item's picture string, the maximum value that can be stored in a COMP-X item is determined by the number of bytes allocated to it (to a maximum of 18 digits, or a maximum of 31 digits if 31-digit support is in effect). For example, a COMP-X item consisting of 1 byte can hold a range of numbers from 0 to 255. A 2-byte COMP-X number can hold from 0 to 65535. A size error occurs on a COMP-X item only when the value is larger than the data item can physically hold. When COMP-X is used with a PIC(X) data item, the maximum is PIC X(8). (This maximum is increased to PIC X(16) when 31-digit support is in effect.)
Pointer data items occupy 8 bytes. This provides enough space to hold an address on a 64-bit machine. If you are on a smaller machine, the runtime uses only the first 4 bytes of pointer data items (the trailing 4 bytes remain in memory, they are just left unused). You can use the "-Dw" compile-time option to adjust the space allocated to pointer data items. You can do this to conserve storage if you know you will not be running on a 64-bit machine.
Pointers may be used in conditional expressions, where they can be compared to each other or to the value NULL. A comparison involving a pointer must be either "equals" or "not equals" ("greater" and "less than" comparisons are not allowed).
Level 01 and level 77 data items that are POINTER items are automatically synchronized to an appropriate machine boundary, regardless of any compile-time settings. This allows you to pass these items safely to C subroutines without having to concern yourself with alignment.
Except for the automatic synchronization, USAGE POINTER data items are treated in all respects like USAGE UNSIGNED-LONG data items. This handles all current machines correctly. This behavior may change to meet the requirements of some future machine.
Level 01 and level 77 data items that are USAGE FLOAT or DOUBLE are automatically synchronized to appropriate machine boundaries, regardless of any compile-time settings. This allows you to pass these items safely to C subroutines without having to concern yourself with alignment.
The storage convention affects how data appears in USAGE DISPLAY, COMP-2, and COMP-3 data types. In USAGE DISPLAY, standard ASCII storage, if the sign is incorporated into a digit position, the digit is encoded according to the following table:
USAGE DISPLAY
| DIGIT VALUE | -Dca,
-Dcb, -Dcm, -Dcr Positive |
-Dci,
-Dcn Positive |
-Dca,
-Dci, -Dcn Negative |
-Dcb
Negative |
-Dcm
Negative |
-Dcr
Negative |
|---|---|---|---|---|---|---|
| 0 | '0' | '{' | '}' | '@' | 'p' | ' ' (space) |
| 1 | '1' | 'A' | 'J' | 'A' | 'q' | '!' |
| 2 | '2' | 'B' | 'K' | 'B' | 'r' | '"' (double-quote) |
| 3 | '3' | 'C' | 'L' | 'C' | 's' | '#' |
| 4 | '4' | 'D' | 'M' | 'D' | 't' | '$' |
| 5 | '5' | 'E' | 'N' | 'E' | 'u' | '%' |
| 6 | '6' | 'F' | 'O' | 'F' | 'v' | '&' |
| 7 | '7' | 'G' | 'P' | 'G' | 'w' | ''' (single-
quote) |
| 8 | '8' | 'H' | 'Q' | 'H' | 'x' | '(' |
| 9 | '9' | 'I' | 'R' | 'I' | 'y' | ')' |
For import compatibility with some systems that do not have the symbols "{" and "}", the symbols "[" and "?" are considered equivalent to "{", and the symbols "]", ":", and "!" are considered equivalent to "}", when an item with USAGE DISPLAY is read.
The next two tables show sign representation for COMP-2 and COMP-3 items, when you are using the "-Dca", "-Dcb", "-Dci", "-Dcm", "-Dcn", "-Dcr", and "-Dcv" storage conventions. For COMP-2, the trailing byte is reserved for the sign. For COMP-3, the trailing half-byte is reserved for the sign.
USAGE COMP-2
| -Dca Positive | x'0B' |
| -Dcb/-Dci/-Dcm/-Dcn/-Dcr Positive | x'0C' |
| -Dca/-Dcb/-Dci/-Dcm/-Dcn/-Dcr Negative | x'0D' |
USAGE COMP-3
| -Dca Positive | x'0F' |
| -Dcb/-Dci/-Dcm/-Dcr Positive | x'0C' |
| -Dca/-Dcb/-Dci/-Dcm/-Dcr Negative | x'0D |
| -Dca/-Dcb/-Dci/-Dcm/-Dcr Unsigned | x'0F' |
| -Dcv Unsigned | x'0C' |
These USAGE types are specified without a PICTURE clause (like USAGE INDEX and POINTER).
The names of the types are:
| SIGNED-SHORT | UNSIGNED-SHORT |
| SIGNED-INT | UNSIGNED-INT |
| SIGNED-LONG | UNSIGNED-LONG |