USAGE clause
The USAGE clause specifies the format of a data item in the computer storage.
General format
USAGE IS ] {Usage-String-1}
             {Usage-String-2}
Usage-String-1 format:
  { DISPLAY         }
{ {BINARY          [(size)] } }
  {COMP-5          [(size)] } 
  {COMPUTATIONAL-5 [(size)] }
{ {COMP                     } }
  {COMPUTATIONAL            }
  {COMP-4          [(size)] }
  {COMPUTATIONAL-4 [(size)] }
{ {COMP-1         } }
  {COMPUTATIONAL-1}
{ {COMP-2         } }
  {COMPUTATIONAL-2}
{ {COMP-3         } }
  {COMPUTATIONAL-3}
  {PACKED-DECIMAL }
{ {COMP-6         } }
  {COMPUTATIONAL-6}
{ {COMP-9         } }
  {COMPUTATIONAL-9}
{ {COMP-N         } }
  {COMPUTATIONAL-N}
{ {COMP-X         } }
  {COMPUTATIONAL-X}
{ {COMP-0         } }
  {COMPUTATIONAL-0}
Usage-String-2 format:
CDATA                                                       }
DOUBLE                                                      }
FLOAT                                                       }
INDEX                                                       }
OBJECT REFERENCE [ { [ FACTORY OF ] Class-Name [ ONLY ] } ] }
                   [ { [ FACTORY OF ] ACTIVE-CLASS  ]     }   }
{ {SIGNED-INT}                                                }
  {INTEGER   }
SHORT                                                       }
INT                                                         }
LONG                                                        }
SIGNED-INT                                                  }
SIGNED-LONG                                                 }
SIGNED-SHORT                                                }
UNSIGNED-INT                                                }
UNSIGNED-LONG                                               }
UNSIGNED-SHORT                                              }
{ {HANDLE } [ OF { Control                 } ]                }
  {POINTER}      { MENU                    }
                 { SUBWINDOW               }
                 { THREAD                  }
                 { VARIANT                 }
                 { LAYOUT-MANAGER          }
                 { control-class           }
                 { FONT [DEFAULT-FONT    ] }
                        [FIXED-FONT      ]
                        [LARGE-FONT      ]
                        [MEDIUM-FONT     ]
                        [SMALL-FONT      ]
                        [TRADITIONAL-FONT]
 
Syntax rules
1. The USAGE clause may be specified for both group and elementary data items.
2. If the USAGE clause is written in the data description entry for a group item, it may also be written in the data description entry for any subordinate elementary item or group item, but the same usage must be specified in both entries.
3. An elementary data item whose declaration contains, or an elementary data item subordinate to a group item whose declaration contains, a USAGE clause specifying Usage-String-1 must be declared with a PICTURE character-string that describes a numeric item, i.e., a PICTURE character-string that contains only the symbols 'P', 'S', 'V', and '9' (see the PICTURE clause). Data items with USAGE COMP-N, USAGE COMP-5 and USAGE COMP-X may also be declared PICTURE character-string containing only 'X' symbols.
4. The words COMP, COMPUTATIONAL, COMP-4, COMPUTATIONAL-4 and BINARY are equivalent.
5. size is a numeric literal.
6. The words COMP-1 and COMPUTATIONAL-1 are equivalent.
7. The words COMP-2 and COMPUTATIONAL-2 are equivalent.
8. The words COMP-3 and COMPUTATIONAL-3 are equivalent.
9. The words COMP-5 and COMPUTATIONAL-5 are equivalent.
10. The words COMP-6 and COMPUTATIONAL-6 are equivalent.
11. The words COMP-9 and COMPUTATIONAL-9 are equivalent.
12. The words COMP-N and COMPUTATIONAL-N are equivalent.
13. The words COMP-X and COMPUTATIONAL-X are equivalent.
14. The words SIGNED-INT and INTEGER are equivalent.
15. The BLANK WHEN ZERO, JUSTIFIED, PICTURE, SYNCHRONIZED, and VALUE clauses must not be specified for data items whose usage is Usage-String-2.
16. Class-Name may be a Nonnumeric Literal referring to an existing class or a class defined in the REPOSITORY Paragraph in the Configuration Section of the ENVIRONMENT DIVISION.
17. Control may be one of the supported controls. See the Controls Reference for the complete list.
18. The words COMP-0, COMPUTATIONAL-0 and SIGNED-SHORT are equivalent.
19. The ACTIVE-CLASS phrase may be specified only in a factory definition, an instance definition, or the linkage or working-storage section of a method definition.
General rules
1. If the USAGE clause is written at a group level, it applies to each elementary item in the group.
2. The USAGE clause specifies the manner in which a data item is represented in the storage of a computer. It does not affect the use of the data item, although the specifications for some statements in the Procedure Division may restrict the USAGE clause of the operands referred to. The USAGE clause may affect the radix or type of character representation of the item.
3. If the USAGE clause is not specified for an elementary item, or for any group to which the item belongs, the usage is implicitly DISPLAY.
4. Decimal storage means that only half of a byte is used to store the value of a digit in binary format.
5. Binary storage means that one byte is used to store the value of one or more digits.
6. Big Endian and Little Endian refer to sequencing methods used to store bytes. Big Endian (big units first) means that bytes are stored from left to right, that is, from lowest to highest memory address. Little Endian (little units first) means that bytes are stored from right to left, that is, from highest to lowest memory address.
7. The USAGE IS DISPLAY clause (whether specified explicitly or implicitly) specifies that a standard data format is used to represent a data item in the storage of the computer, and that the data item is aligned on a character boundary. The effective size of data item depends on the PICTURE and SIGN clauses. Each digit occupies one byte. If the data item is signed, the sign is stored in the rightmost byte. The SIGN clause, and the Compiler Options may affect this behavior. The following table shows a mapping of digits to characters stored in USAGE DISPLAY items when specifying the different data storage compatibility compiler options:
Compiler Option
DIGIT
-Dca
-Dcb
-Dcd
-Dcdm
-Dcm
-Dcmi
-Dcr
-Dcm
-Dcmi
-Dci
-Dcii
-Dcn
-Dca
-Dcd
-Dcdm
-Dci
-Dcii
-Dcn
-Dcb
-Dcr
 
Positive
Negative
Positive
Negative
Negative
Negative
0
‘0’
‘p’
‘{‘
‘}’
‘@’
x’20’
1
‘1’
‘q’
‘A’
‘J’
‘A’
!
2
‘2’
‘r’
‘B’
‘K’
‘B’
3
‘3’
‘s’
‘C’
‘L’
‘C’
#
4
‘4’
‘t’
‘D’
‘M’
‘D’
$
5
‘5’
‘u’
‘E’
‘N’
‘E’
%
6
‘6’
‘v’
‘F’
‘O’
‘F’
&
7
‘7’
‘w’
‘G’
‘P’
‘G’
8
‘8’
‘x’
‘H’
‘Q’
‘H’
(
9
‘9’
‘y’
‘I’
‘R’
‘I’
)
8. The USAGE IS COMPUTATIONAL clause specifies that the numeric item is stored in Big Endian binary format. The data item may be signed.
 
The effective size of data item depends on the PICTURE clause and compile flags, according to the following table:
Number of digits
Bytes
 
-Dca
-Dcb
-Dcmi
-Dci
-Dcii
Bytes
 
-Dcd
-Dcm
-Dcr
Bytes
 
-Dcdm
Bytes
 
-Dci + -D1
-Dcn
1-2
2
1
1
1
3-4
2
2
2
2
5-6
4
3
3
4
7
4
3
4
4
8-9
4
4
4
4
10-11
8
5
5
8
12
8
5
6
8
13-14
8
6
6
8
15-16
8
7
7
8
17-18
8
8
8
8
19
12
8
9
12
20-21
12
9
9
12
22-23
12
10
10
12
24
12
10
11
12
25-26
12
11
11
12
27-28
12
12
12
12
29-31
16
13
13
16
If size is specified, it takes priority on the above table.
9. The USAGE IS COMPUTATIONAL-1 clause specifies that the numeric item is stored in Big Endian binary format. The data item occupies two bytes and it is always signed. It can store values from -32767 to +32767, regardless of the PICTURE clause. Under the -cv compiler option, COMPUTATIONAL-1 is treated as FLOAT and occupies four bytes.
10. The USAGE IS COMPUTATIONAL-2 clause specifies that the numeric item is stored in Big Endian decimal format. Each digit occupies one byte and uses only the low-order half-byte. When the data item is signed, an additional trailing byte is used.
The following table shows the rightmost byte value used to represent the sign representation for USAGE COMP-2 items when specifying the different data storage compatibility compiler options:
Compiler Option
-Dca
-Dcd
-Dcdm
-Dcb
-Dci
-Dcii
-Dcm
-Dcmi
-Dcn
-Dcr
-Dca
-Dcb
-Dcd
-Dcdm
-Dci
-Dcii
-Dcm
-Dcmi
-Dcn
-Dcr
Positive
Positive
Negative
x‘0B’
x‘0C’
x‘0D’
Under the -cv compiler option, COMPUTATIONAL-2 is treated as DOUBLE.
11. The USAGE IS COMPUTATIONAL-3 clause specifies that the numeric item is stored in Big Endian decimal format. Each digit occupies half of a byte. The last trailing half-byte is always reserved for sign, even if the PICTURE clause does not contain the 'S' symbol.
 
The effective size of data item depends on the PICTURE clause, according to the following table:
Number of digits
Bytes
1
1
2-3
2
4-5
3
6-7
4
8-9
5
10-11
6
12-13
7
14-15
8
16-17
9
18-19
10
20-21
11
22-23
12
24-25
13
26-27
14
28-29
15
30-31
16
The following table shows the rightmost nibble value used to represent the sign representation for USAGE COMP-3 items when specifying the different data storage compatibility compiler options:
Compiler Option
 
-Dca
-Dcd
-Dcdm
-Dcb
-Dci
-Dcii
-Dcm
-Dcmi
-Dcr
-Dcn
-Dca
-Dcb
-Dcd
-Dcdm
-Dci
-Dcii
-Dcm
-Dcmi
-Dcn
-Dcr
-Dca
-Dcb
-Dcd
-Dcdm
-Dci
-Dcii
-Dcm
-Dcmi
-Dcn
-Dcr
Positive
Positive
Positive
Negative
Unsigned
x‘0F’
x‘0C’
x’0B’
x‘0D’
x‘0F’
12. The USAGE IS COMPUTATIONAL-5 is primarily used to communicate with external programs that expect native data storage. The format of a COMPUTATIONAL-5 data item is identical to a COMPUTATIONAL data item, except that the data is stored in a machine-dependent format. A VALUE clause for a COMPUTATIONAL-5 data item is stored in a machine-independent format and is adjusted when it is loaded into the data item. If COMPUTATIONAL-5 is used with a PIC X(n) data item and assigned an alphanumeric value, the results are undefined. A PIC X(n) data item used with COMPUTATIONAL-5 cannot be signed.
13. The USAGE IS COMPUTATIONAL-6 clause specifies that the numeric item is stored in Big Endian decimal format. Each digit occupies half of a byte. The data item may not be signed.
 
The effective size of data item depends on the PICTURE clause, according to the following table:
Number of digits
Bytes
1-2
1
3-4
2
5-6
3
7-8
4
9-10
5
11-12
6
13-14
7
15-16
8
17-18
9
19-20
10
21-22
11
23-24
12
25-26
13
27-28
14
29-30
15
31
16
14. The USAGE IS COMPUTATIONAL-9 clause specifies that the numeric item is stored in Big Endian decimal format. Each digit occupies half of abyte. The first leading half-byte is always reserved for sign, even if the PICTURE clause does not contain the 'S' symbol.
 
The effective size of data item depends on the PICTURE clause, according to the following table:
Number of digits
Bytes
1
1
2-3
2
4-5
3
6-7
4
8-9
5
10-11
6
12-13
7
14-15
8
16-17
9
18-19
10
20-21
11
22-23
12
24-25
13
26-27
14
28-29
15
30-31
16
15. The USAGE IS COMPUTATIONAL-N clause specifies that the numeric item is stored in Big Endian binary format.
 
The effective size of data item depends on the PICTURE clause, according to the following table:
Number of digits
Bytes
1-2
1
3-4
2
5-7
3
8-9
4
10-12
5
13-14
6
15-16
7
17-18
8
 
When the PICTURE clause contains only 'X' symbols, the number of 'X's represent the actual storage size of the data item. The maximum size of the item is 8. The maximum value that the data item can store is summarized in the following table:
Size
Value
1
255
2
65.535
3
16.777.215
4
4.294.967.295
5
1.099.511.627.775
6
281.474.976.710.655
7
72.057.594.037.927.935
8
9.223.372.036.854.775.807
16. The USAGE IS COMPUTATIONAL-X clause specifies that the numeric item is stored in Big Endian binary format.
 
The effective size of data item depends on the PICTURE clause, according to the following table:
Number of digits
Bytes
1-2
1
3-4
2
5-7
3
8-9
4
10-12
5
13-14
6
15-16
7
17-19
8
20-21
9
22-24
10
25-26
11
27-28
12
29-31
13
When the PICTURE clause contains only 'X' symbols, the number of 'X's represent the actual storage size of the data item. The maximum allowed size of the item is 8. The maximum value that the data item can store is summarized in the following table:
Size
Value
1
255
2
65.535
3
16.777.215
4
4.294.967.295
5
1.099.511.627.775
6
281.474.976.710.655
7
72.057.594.037.927.935
8
9.223.372.036.854.775.807
17. The USAGE IS DOUBLE clause specifies that the numeric item is stored as a floating point double precision type.
18. The USAGE IS FLOAT clause specifies that the numeric item is stored as a floating point single precision type.
19. The USAGE IS INDEX clause specifies that the numeric item is stored in Big Endian binary format. The data item occupies four bytes. The data item can store positive integers ranging from 0 to 4.294.967.295.
20. The USAGE IS OBJECT clause specifies that the data item is a reference to an object.
a. The USAGE IS OBJECT clause may be specified only for 01 or 77 data items.
b. If none of the optional phrases is specified, the data item being defined is called a universal object reference. Its content may be a reference to any object.
c. If Class-Name-1 is specified, the object referenced by this data item shall be an object of Class-Name-1 or of a subclass of Class-Name-1, subject to the following rules:
i. If the FACTORY phrase is specified, the object referenced by this data item shall be the factory object of the specified class.
ii. If the FACTORY phrase is not specified, the object referenced by this data item shall be an instance object of the specified class.
 
The ONLY phrase is treated as a commentary.
d. If ACTIVE-CLASS is specified, the object referenced by this data item shall be of the same class as the object that was used to invoke the method in which this data description entry is specified, subject to the following rules
i. If the FACTORY phrase is specified, the object referenced by this data item shall be the factory object of the specified class.
ii. If the FACTORY phrase is not specified, the object referenced by this data item shall be an instance object of the specified class.
21. The USAGE IS SIGNED-INT clause specifies that the numeric item is stored as a C-style int type.
22. The USAGE IS SIGNED-LONG clause specifies that the numeric item is stored as a C-style long type.
23. The USAGE IS SIGNED-SHORT clause specifies that the numeric item is stored as a C-style short type.
24. The USAGE IS UNSIGNED-INT clause specifies that the numeric item is stored as a C-style unsigned int type.
25. The USAGE IS UNSIGNED-LONG clause specifies that the numeric item is stored as a C-style unsigned long type.
26. The USAGE IS UNSIGNED-SHORT clause specifies that the numeric item is stored as a C-style unsigned short type.
27. The USAGE IS HANDLE clause specifies that the data item refers to a COBOL object.
a. If none of the optional phrases is specified, the data item being defined is a generic handle. Its type is returned by the HANDLE-TYPE Function.
b. Items defined as USAGE IS HANDLE OF Control can be used with the DISPLAY, ACCEPT, MODIFY, INQUIRE and DESTROY Statements.
c. Items defined as USAGE IS HANDLE OF MENU can be used with the "W$MENU" Routine and as an argument of the POP-UP Property of Controls.
d. Items defined as USAGE IS HANDLE OF SUBWINDOW can be used with the DISPLAY and CLOSE Statements.
e. Items defined as USAGE IS HANDLE OF THREAD can be used with the ACCEPT, CALL, PERFORM, RECEIVE, SEND and WAIT Statements.
f. Items defined as USAGE IS HANDLE OF FONT can be used with the "W$FONT" Routine, as an argument of the FONT and CONTROL FONT Properties of Controls and with the DESTROY Statement.
 
When one of the optional phrases DEFAULT-FONT, FIXED-FONT, LARGE-FONT, MEDIUM-FONT, SMALL-FONT or TRADITIONAL-FONT is specified, the data item being defined will refer to the corresponding font. The iscobol.font.* properties can be used to set the fonts to be used.
28. USAGE POINTER requires either -ca or -cp compiler options to be compiled correctly. In the first case, it’s treated as USAGE HANDLE, in the second case it’s treated as a real POINTER and can be shared with external C routines.
29. USAGE VARIANT is reserved for future use and it’s currently treated as USAGE DISPLAY.
30. USAGE CDATA can be used only for variable whose parent is an XML element, otherwise an error is raised.
When writing an XML document the content of variable with such a USAGE is generated between the CDATA tags. For example, the following variable:
05 xml-cdata pic x any length cdata value "<<<TEST>>>".
generates:
<![CDATA[<<<TEST>>>]]>
If a variable contains the sequence "]]>" in some point, then as many CDATA tags as the number of such occurrences are generated in order to be compliant with the XML syntax.
This clause doesn’t work in conjunction with BASE64BINARY, BOOLEAN, HEXBINARY and RAW caluses.
31. The USAGE IS COMPUTATIONAL-0 is a Microsoft COBOL extension and requires the -cms compile flag.