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.
[ 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] }
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.
| # 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 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' | ')' |
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 |
Each of these represents a binary value that is stored using the machine's native byte ordering. Since there is no PICTURE phrase, size checking for these items is performed only on byte boundaries. These data types are automatically SYNCHRONIZED.
The unusual characteristic of these data types is that their size is not necessarily set at compile time. Instead, the size of these items is determined at execution time. This allows them to match the working characteristics of the host machine. For example, a SIGNED-LONG data item will contain 64 bits when run on a DEC Alpha machine, but it will have 32 bits when run on an Intel 80486-based machine. This lets you write one program that can communicate effectively with an external routine written in another language (such as C), regardless of the target environment.
In order to lay out memory, the compiler assigns a maximum size to each of these data types. This is the number of bytes that the item will occupy. At run time, these items may be reduced in size to match the host machine's characteristics. Any remaining bytes are then treated as FILLER. The -Dw compile option determines the maximum size of these types:
| USAGE | -Dw32 | -Dw64 |
|---|---|---|
| SIGNED-SHORT
UNSIGNED-SHORT |
2* | 2* |
| SIGNED-INT
UNSIGNED-INT |
4 | 4 |
| SIGNED-LONG
UNSIGNED-LONG |
4* | 8 |
Table entries marked with an asterisk indicate fixed-size items. A fixed-size item is the same size regardless of the target machine. Entries without an asterisk are variable in size. These items will occupy space up to the number of bytes listed in the table.
In the execution environment, these items act in all ways as if they were fixed-size data items of the appropriate size.
For example, the following code fragment:
77 LONG-1 SIGNED-LONG. 77 SIZE-1 PIC 9. SET SIZE-1 TO SIZE OF LONG-1. DISPLAY SIZE-1.
will print 4 when run on a 32-bit machine, but it will print 8 when run on a 64-bit machine.
Examples
In the following examples, each byte is represented by two hexadecimal digits or by a single quoted character. Each value is shown in the various formats. Also shown is USAGE DISPLAY using the various SIGN options. The following examples use the default ACUCOBOL-GT sign-storage conventions.
PIC 9(3) VALUE 123. TRAILING '1' '2' '3' TRAILING SEPARATE '1' '2' '3' LEADING '1' '2' '3' LEADING SEPARATE '1' '2' '3' COMP-1 00 7B COMP-2 01 02 03 COMP-3 12 3F COMP-4 00 7B COMP-5(68000) 00 7B COMP-5(8086) 7B 00 COMP-6 01 23 PIC S9(3) VALUE -123. TRAILING '1' '2' 'L' TRAILING SEPARATE '1' '2' '3' '-' LEADING 'J' '2' '3' LEADING SEPARATE '-' '1' '2' '3' COMP-1 FF 85 COMP-2 01 02 03 0D COMP-3 12 3D COMP-4 FF 85 COMP-5(68000) FF 85 COMP-5(8086) 85 FF COMP-6 illegal PIC 9(5)V9 VALUE 12345.6. TRAILING '1' '2' '3' '4' '5' '6' TRAILING SEPARATE '1' '2' '3' '4' '5' '6' LEADING '1' '2' '3' '4' '5' '6' LEADING SEPARATE '1' '2' '3' '4' '5' '6' COMP-1 illegal COMP-2 01 02 03 04 05 06 COMP-3 01 23 45 6F COMP-4 00 01 E2 40 COMP-5(68000) 00 01 E2 40 COMP-5(8086) 40 E2 01 00 COMP-6 12 34 56 PIC S9(5)V9 VALUE -12345.6. TRAILING '1' '2' '3' '4' '5' '0' TRAILING SEPARATE '1' '2' '3' '4' '5' '6' '-' LEADING 'J' '2' '3' '4' '5' '6' LEADING SEPARATE '-' '1' '2' '3' '4' '5' '6' COMP-1 illegal COMP-2 01 02 03 04 05 06 0D COMP-3 01 23 45 6D COMP-4 FF FE 1D C0 COMP-5(68000) FF FE 1D C0 COMP-5(8086) C0 1D FE FF COMP-6 illegal
HANDLE data items come in two forms: typed and generic. You create a generic handle when you omit the OF phrase. You create a typed handle when you include the OF phrase.
ACCEPT data-item FROM STANDARD OBJECT "font-name"
at the beginning of your program, where data-item is the data item described by the USAGE clause and font-name is the same as font-name in the USAGE clause.