The USAGE clause specifies the format of a data item in computer memory or in a file record.
[ 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 }
Syntax Rules
1. The column on the left shows the accepted abbreviations for the terms on the right:
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
2. A USAGE clause may be used in any data description entry except those with level-numbers 66, 78, and 88.
3. A USAGE clause may not be used with an external floating-point data item.
4. If a USAGE clause is in the data description entry for a group item, then any USAGE clauses that appear for subordinate entries must be of the same type.
5. The PICTURE string of a COMP, COMP-1, COMP-2, COMP-3, COMP-4, COMP-5, COMP-6, BINARY, or PACKED-DECIMAL item can contain only the symbols "9", "S", "V", and "P". COMP-6 items may not use the "S" symbol.
6. The PICTURE string of a COMP-X or COMP-N item may contain only all "9" symbols or all "X" symbols.
7. The data description entry for a USAGE IS INDEX data item cannot contain any of the following clauses: BLANK WHEN ZERO, JUSTIFIED, PICTURE, and VALUE IS.
8. Level 88 items may not be specified for a USAGE IS INDEX data item.
9. The data description entry for a USAGE IS POINTER data item cannot contain any of the following clauses: BLANK WHEN ZERO, JUSTIFIED, or PICTURE. A POINTER data item may have a value clause specified for it, but the value must be the word NULL.
10. The data description entry for a USAGE IS FLOAT or a USAGE IS DOUBLE data item cannot contain any of the following clauses: BLANK WHEN ZERO, JUSTIFIED, or PICTURE. FLOAT or DOUBLE data items may have a value clause. The value may be a floating point literal, a numeric literal, or the word ZERO. Here is an example of a Working-Storage Section data item:
01 F-DATA-1 USAGE IS FLOAT
VALUE IS 3.97E+24.
11. The following are collectively called the "C-style" data types: SIGNED-INT, UNSIGNED-INT, SIGNED-SHORT, UNSIGNED-SHORT, SIGNED-LONG, UNSIGNED-LONG. These data types are similar to the data types found in the C programming language.
The data description entry for a C-style data type cannot contain any of the following clauses: BLANK WHEN ZERO, JUSTIFIED, or PICTURE.
12. Control-type is one of the graphical control type names known to the compiler, such as LABEL or ENTRY-FIELD.
13. The data description entry for USAGE HANDLE data items may not contain any of the following clauses: BLANK WHEN ZERO, JUSTIFIED, or PICTURE. If it contains a VALUE clause, the value specified must be the word NULL.
14. Font-name is one of the following identifiers: DEFAULT-FONT, FIXED-FONT, TRADITIONAL-FONT, SMALL-FONT, MEDIUM-FONT, LARGE-FONT.
15. It should be noted that either the "-Df" option or the "-Cv "option will cause the compiler to treat COMP-1 and COMP-2 as FLOAT and DOUBLE, respectively. See the the IBM DOS/VS COBOL appendix for more information.
General Rules
1. A USAGE clause written at a group level applies to every elementary item subordinate to that group item.
2. If no USAGE clause is specified, then USAGE IS DISPLAY is implied.
3. The internal format of a USAGE IS DISPLAY item is ASCII.
4. The format of an index item is 16-bit unsigned binary. Its size is always two, and it holds a range of values from 0 to 65535.
5. The format of a COMP-1 data item is 16-bit signed binary. The legal values range from -32767 to 32767. The size of the data item is always two bytes, and the high-order half of the data is stored in the leftmost byte. The PICTURE string that describes the item is irrelevant. Unlike other numeric data types, a size error will occur on a COMP-1, COMP-X, or COMP-N data item only when the value exceeds the physical storage of the item (in other words, the number of "9"s in the item's PICTURE is ignored when size error is determined).
6. For COMP-2 (decimal storage), each digit is stored in one byte in decimal format. If the value is signed, then an additional trailing byte is allocated for the sign. The storage of COMP-2 is identical with USAGE DISPLAY with the high-order four bits stripped from each byte.
7. For COMP-3 (packed-decimal storage), two digits are stored in each byte. An additional half byte is allocated for the sign, even if the value is unsigned. The sign is placed in the rightmost position, and its value is 0x0D for negative; all other values are treated as positive (but see rule 18 below). The size of an item (including one for the implied sign) is divided by two to arrive at its actual size (rounding fractions up).
8. The format of a COMP-4 item is two's-complement binary (the value without its decimal point). COMP-4 values are stored in a machine-independent format. This format places the highest-order part of the value in the leftmost position and follows down to the low-order part in the rightmost position. The number of bytes a data item occupies depends on the number of "9"s in its PICTURE and on the presence of various compile-time options. This is summarized in the following table:
| # 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 |
9. COMP-5 is primarily used to communicate with external programs that expect native data storage.
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.
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.
10. The format of a COMP-6 item is identical to a COMP-3 item except that it is unsigned and no space is allocated for the sign. If the number of digits is odd, a zero is added to the left end of the number before it is packed. Thus there are two decimal digits per byte, and the actual size of the item is determined by dividing its PICTURE size by two and rounding up.
11. A COMP-X data item must be described with a picture string consisting of only "9" or only "X" symbols. In either case, the data item is treated as an unsigned binary integer, with internal storage similar to that of a COMP-4 data item. If "X" symbols are used to describe the item, then the number of bytes allocated to the item is the same as the number of "X" symbols in the picture string. If "9" symbols are used instead, then the number of bytes allocated is the least number of bytes required to hold a number of that size. For example, a "PIC 99" data item will be allocated 1 byte; a "PIC 9(9)" data item will be allocated 4 bytes.
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). 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).
12. A COMP-N data item is identical to a COMP-X data item, except that the data is stored in the host machine's native format, instead of machine-independent format.
13. Data items described as PACKED-DECIMAL are identical to COMP-3. You can cause unsigned PACKED-DECIMAL to be treated as COMP-6 by using a compile-time option.
14. By default, a BINARY data item is identical to a COMP-4 data item. The compile-time option "-D5" treats BINARY data items as COMP-5 items instead.
15. In VAX/COBOL compatibility mode, a COMP data item is the same as COMP-4 and is treated as binary data. In RM/COBOL compatibility lmode, COMP is the same as COMP-2. You can use compile-time options to change the default behavior.
16. A pointer data item is treated as an unsigned numeric data item. The internal format differs for each machine. Pointer data items are intended to hold addresses of other data items (see this Reference Manual, section 6.6, the "SET Statement"). A pointer data item may have a VALUE clause specified for it, but the specified value must be the word NULL. This indicates that the pointer does not currently point to any item. If a pointer is not explicitly given an initial value, then its initial value is arbitrary.
Pointer data types are primarily used to pass address information to C subroutines or library routines. There are no facilities in COBOL for de-referencing the pointer.
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.
17. Floating-point data items are stored in a machine-dependent format. USAGE FLOAT items have 4 bytes allocated to them. USAGE DOUBLE items occupy 8 bytes.
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.
18. The ANSI definition of COBOL does not state how signs should be stored in numeric fields (except for the case of SIGN IS SEPARATE). ACUCOBOL-GT lets you select alternate sign-storage conventions by using the compile-time option "-Dca", "-Dci", "-Dcm", or "-Dcn". Specifying a sign-storage convention is sometimes useful when you are exporting and importing data. For additional information, see the User's Guide, section 2.1.7, "Data Storage Options."
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:
| DIGIT VALUE
| -Dca Positive
| -Dca Negative
| -Dci Positive
| -Dci Negative
| -Dcm Positive
| -Dcm Negative
|
| 0
| '0'
| '}'
| '{'
| '}'
| '0'
| 'p'
|
| 1
| '1'
| 'J'
| 'A'
| 'J'
| '1'
| 'q'
|
| 2
| '2'
| 'K'
| 'B'
| 'K'
| '2'
| 'r'
|
| 3
| '3'
| 'L'
| 'C'
| 'L'
| '3'
| 's'
|
| 4
| '4'
| 'M'
| 'D'
| 'M'
| '4'
| 't'
|
| 5
| '5'
| 'N'
| 'E'
| 'N'
| '5'
| 'u'
|
| 6
| '6'
| 'O'
| 'F'
| 'O'
| '6'
| 'v'
|
| 7
| '7'
| 'P'
| 'G'
| 'P'
| '7'
| 'w'
|
| 8
| '8'
| 'Q'
| 'H'
| 'Q'
| '8'
| 'x'
|
| 9
| '9'
| 'R'
| 'I'
| 'R'
| '9'
| 'y'
|
USAGE COMP-2
| -Dca Positive
| -Dca Negative
| -Dci/-Dcm/-Dcn Positive
| -Dci/-Dcm/-Dcn Negative
|
| x'0B'
| x'0D'
| x'0C'
| x'0D' |
USAGE COMP-3
| -Dca Positive
| -Dca Negative
| -Dca Unsigned
| -Dci/-Dcm Positive
| -Dci/-Dcm Negative
| -Dci/-Dcm Unsigned
|
| x'0F'
| x'0D'
| x'0F'
| x'0C'
| x'0D'
| x'0F' |
19. There are six USAGE types for integer data that simplify communications with other programming languages such as C. These types are designed to provide a portable method for handling machine-dependent data. The six USAGE types handle three classes of machine data: "short words," "words," and "long words." These three correspond to the C data types: "short", "int", and "long". There are signed and unsigned versions of each of these data types..
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 (see the User's Guide section 2.1.7, "Data Storage Options.") 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 |
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
20. HANDLE data items make up their own data class and category in COBOL. Internally they are stored as integer values, and behave like numbers when used. A HANDLE data item is normally used to store the handle of a dynamically created object such as a floating window or a graphical control.
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.
21. You may use HANDLE data items only when explicitly allowed, or as part of a MOVE statement, a CALL statement (as a parameter), or in a Boolean expression.
22. Generic handles may be used in any situation where handles are allowed. When you use a generic handle as the source of a MODIFY statement, you will not be able to use any control-specific property or style names in that statement. This is because the generic handle could be associated with any type of control. In this case, the compiler cannot determine which set of style and property names is valid.
23. Typed handles may be used in statements where any handle is allowed, or when you are referring to an object of a matching type. For example, a HANDLE OF WINDOW cannot be used as the handle in a DISPLAY LABEL statement. Instead, you must use either a generic handle or a HANDLE OF LABEL. Typed handles allow the compiler to recognize associated style and property names when appropriate. Typed handles also improve the readability of your program by providing additional information about the intended use of the handle, in addition to providing compile-time checking to ensure that you are using the handles in appropriate situations.
24. Handles may be used in comparisons. There are only two meaningful comparisons: checking for equality or inequality to NULL, and comparison to another handle data item. A handle value of NULL always indicates an invalid handle.
25. Handles are stored internally as 4-byte binary integers. This information can be useful when you are debugging a program (you can examine the values of handles in the debugger). You should not rely on this definition in your program, however, because it is subject to change in the future.
26. Handle data items are automatically SYNCHRONIZED on a 4-byte boundary. Note that this occurs regardless of the setting of the "-Dl" compile-time option (which limits the amount of synchronization). The runtime system requires this level of alignment to avoid generating bus errors on some machines.
27. If font-name is specified, then the data item described by the USAGE clause is initialized at program startup with the corresponding font handle. This acts identically to placing the statement:
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.