USAGE Clause (ACUCOBOL-GT)

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.

Note: There are numerous compiler options for affecting data storage behavior. See Data Storage Options in the ACUCOBOL-GT Compatibility section.

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

  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, or the name of an ActiveX, COM, or .NET control.
  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. For more information, see section 5.4 in Transitioning to ACUCOBOL-GT.
  16. Layout-name is the name of one of the system's standard layout managers. Currently, this can only be LM-RESIZE.

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 32-bit signed binary. Its size is always four, and it holds a range of values from -2147483647 to 2147483647. When using a compile switch for compatibility with versions prior to 6.0.0 (-Z52 for example) an index item is 16-bit unsigned binary, size is always two, and it holds 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. For example, you may include more than eighteen "9"s only if your program has been compiled for 31-digit support. 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
    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
    Note: Where two values are given, the smaller value applies to unsigned data items, and the larger value applies to signed data items.
  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.

    Note: Data stored in a COMP-5 field may not be transportable to other machines because different machines have different natural byte-orderings. On many machines (68000, most RISC), COMP-5 is identical to COMP-4. On others (80x86, VAX), it is the same with the bytes in the reverse order.

    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.

  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, 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.)

  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 mode, 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 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 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 run-time system 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 options "-Dca", '-Dcb", "-Dci", "-Dcm", "-Dcn", "-Dcr", and "-Dcv". 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.2.10, "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:

    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' ')'
    Note:

    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'
  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.2.10, "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

    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.

    Note: The sizes listed in the table above cover all current and anticipated machines that run ACUCOBOL-GT. Future architectures may require changes to the maximum size assigned to these items.

    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
  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 run-time 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.

Parent topic: Data Division
Related tasks
Data Storage Options