Micro Focus Visual COBOL 2.3 for Visual Studio 2015 > General Reference > COBOL Language Reference > Part 2. Program Definition > Data Division > File and Data Description > Data Description Entry Skeleton > The USAGE Clause

The USAGE Clause

The USAGE clause specifies the format of a data item in the computer storage.

General Format

Directives

In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
- COBOL370 – controls whether four or eight bytes of storage are allocated to USAGE PROCEDURE-POINTER data items.
- COMP-5 – controls the handling of the operational sign when storing into a USAGE COMP-5 data item.
- IBMCOMP – controls the storage allocated for USAGE COMP and USAGE COMP-5 data items.

Syntax Rules

The USAGE clause may be written in any data description entry with a level number other than 66 or 88.
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.
An elementary data item whose declaration contains, or an elementary data item subordinate to a group item whose declaration contains, a USAGE clause specifying COMPUTATIONAL
, BINARY, PACKED-DECIMAL

, COMPUTATIONAL-3

, COMPUTATIONAL-4

, or COMPUTATIONAL-5

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 topic The PICTURE Clause.

An elementary data item whose declaration contains no USAGE clause and that is subordinate to a group item whose declaration contains a USAGE clause specifying a format from the list may be declared with a PICTURE character-string that describes an alphabetic, alphanumeric, alphanumeric-edited or numeric-edited data item.
An elementary data item whose declaration contains, or an elementary data item subordinate to a group item whose declaration contains, a USAGE clause specifying COMPUTATIONAL-5
or COMPUTATIONAL-X

must be declared with a picture character-string that describes a numeric item

or describes an alphanumeric item with a size of between one and sixteen bytes inclusive. If it describes an alphanumeric item of size 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, or 16 bytes, then this is equivalent to specifying an integer item with 2, 4, 7, 9, 12, 14, 16, 18, 19, 21, 24, 26, 28, 31, 33, 36 or 38 decimal digit positions respectively
.

The PICTURE character-string can contain up to 18 digit positions by default or if you set INTLEVEL"2", and up to 38 digit positions if you set INTLEVEL"4".

When COMPUTATIONAL-X is specified and the PICTURE character-string describes a numeric item, then that item must be unsigned.
The BLANK WHEN ZERO, JUSTIFIED and SIGN clauses must not be specified for data items whose usage is not explicitly or implicitly DISPLAY.
The SYNCHRONIZED and VALUE clauses must not be specified for data items whose usage is INDEX.
The SYNCHRONIZED clause can be specified for data items whose usage is INDEX.
COMP is an abbreviation for COMPUTATIONAL.
COMP-1 is an abbreviation for COMPUTATIONAL-1.

COMP-2 is an abbreviation for COMPUTATIONAL-2.

COMP-3 is an abbreviation for COMPUTATIONAL-3.

COMP-4 is an abbreviation for COMPUTATIONAL-4.

COMP-5 is an abbreviation for COMPUTATIONAL-5.

COMP-X is an abbreviation for COMPUTATIONAL-X.
An index item can be referenced explicitly only in a SEARCH or SET statement, a relation condition, the USING phrase of a Procedure Division,
the USING statement of an ENTRY statement,

an intrinsic function argument

the USING phrase of an INVOKE statement, an inline method invocation argument

an INITIALIZE statement

or the USING phrase of a CALL statement.
A pointer
or procedure-pointer

item can be referenced explicitly only in a SET statement, a relation condition, a CALL statement, the USING phrase of a Procedure Division, the USING statement of an ENTRY statement

an INVOKE statement, the argument list of an inline invocation of a method, the argument list of a function,
An elementary data item described with usage INDEX,
OBJECT,

POINTER,

or PROCEDURE-POINTER

EVENT-POINTER, MONITOR-POINTER, MUTEX-POINTER, PROCEDURE-POINTER, SEMAPHORE-POINTER or THREAD-POINTER

clause must not be a conditional variable.
Typedef-name-1 must be previously defined in the same source file as a record with the TYPEDEF clause.
If USAGE typedef-name-1 is specified, the following clauses cannot also be specified:
- BLANK
- JUSTIFIED
- PICTURE
- SIGN
- SYNCHRONIZED
- VALUE
It is an error to specify USAGE typedef-name-1 if there is an explicit USAGE clause at a higher level in the same hierarchy.
It is an error to specify any subordinate items (items with a higher level number other than 78) immediately following an item defined with USAGE typedef-name-1.
The USAGE OBJECT REFERENCE clause must not be specified in the data description entry for a group item, but may be specified on subordinate elementary data items.
The USAGE OBJECT REFERENCE clause must not be specified in the File Section.
The USAGE OBJECT REFERENCE clause can be specified in the File Section.

Note: Whether the object reference still references an active object depends on the application logic.
The ACTIVE-CLASS phrase can be specified only in a factory definition, object definition, or method definition.
A data item whose usage is EVENT-POINTER can be referenced explicitly only in a CLOSE statement, an OPEN statement, a SET statement, a WAIT statement or a USING phrase.
A data item whose usage is MONITOR-POINTER, MUTEX-POINTER, or SEMAPHORE-POINTER can be referenced explicitly only in a CLOSE statement, an OPEN statement, a SET statement or a USING phrase.
A data item whose usage is THREAD-POINTER can be referenced explicitly only in a START statement, a WAIT statement or a USING phrase.
An elementary data item whose description contains, or an elementary data item subordinate to a group item whose description contains, a USAGE NATIONAL clause must be declared with a picture character-string that describes a national or national-edited data item.
When a USAGE clause is not specified for an elementary data item or for any group to which the data item belongs:
1. if the explicit or implicit picture character-string contains the symbol 'N', a USAGE NATIONAL clause is implied;
2. otherwise, a USAGE DISPLAY clause is implied.
A USAGE clause with the OBJECT REFERENCE, POINTER, or PROGRAM-POINTER phrase must be specified only for an elementary data item with level 1.
This restriction is not enforced.
If program-prototype-name-1 is specified, the TYPEDEF clause must be specified for the subject of the entry.
This restriction is not enforced.
The NATIONAL phrase must be specified in a USAGE clause associated with an elementary data item whose explicit or implicit picture character-string contains the symbol 'N'.
A USAGE clause with the CONDITION-VALUE phrase must be specified only for an elementary data item with level 1.
If the EVENT phrase is specified, then class-name-1 shall reference a delegate definition and the FACTORY phrase shall not be specified.
integer-1 must have a value between 1 and 16.

General Rules

If the USAGE clause is written at the group level, it applies to each elementary item in the group
except when there is a PICTURE clause and the data item described is non-numeric
The USAGE clause specifies the manner in which a data item is represented in the storage of the 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. See the section Selection of Character Representation and Radix in the chapter Concepts of the COBOL Language for more details of the format of each usage.
The USAGE IS BINARY clause specifies that a radix of 2 is used to represent a numeric item in the storage of the computer. This clause is equivalent to specifying USAGE IS COMPUTATIONAL.
The USAGE IS PACKED-DECIMAL clause specifies that a radix of 10 is used to represent a numeric item in the storage of the computer. Furthermore, this clause specifies that each digit position must occupy the minimum possible configuration in computer storage.
This clause is equivalent to specifying USAGE IS COMPUTATIONAL-3.
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 USAGE IS DISPLAY clause is valid for the following types of items:
- Alphabetic
- Alphanumeric
- Alphanumeric edited
- Numeric edited
- External floating-point
- External decimal (numeric)
The USAGE IS INDEX clause specifies that a data item is an index data item and contains a value which must correspond to an occurrence number of a table element.
When a MOVE statement or an input-output statement that references a group item that contains an index,
or pointer,

or procedure-pointer

data item is executed, no conversion of the index,

or pointer

or procedure-pointer

data item takes place.
The USAGE IS COMPUTATIONAL-4 clause is equivalent to specifying USAGE IS COMPUTATIONAL.
The USAGE IS POINTER clause identifies a data item in which you can store the address of a data item (see the topic The SET Statement).
The USAGE IS PROCEDURE-POINTER clause specifies that a data item is a procedure pointer data item in which you can store the address of a procedure. (See the topic The SET Statement.) The procedure can be written in any language: if COBOL, it represents the Procedure Division of a program that is not nested and identified by either:
- The program-name of the Program-ID paragraph; or
- The entry-name of an ENTRY statement.
If typedef-name-1 was specified as an elementary item, then the USAGE typedef-name-1 clause specifies an elementary item with the same attributes as the programmer-defined usage referenced by typedef-name-1.
If typedef-name-1 was specified as a group item, then the USAGE typedef-name-1 clause specifies a group item with an identical structure. The effect is as if the data declarations subordinate to the data description entry identified by typedef-name-1 had been specified identically, subordinate to the item declared with the USAGE typedef-name-1 clause. Data-names of the subordinate data items are identical to those declared within the programmer-defined structure referenced by typedef-name-1 and can be uniquely referenced using qualification.
A data item described with a USAGE OBJECT REFERENCE clause is called an object reference. An object reference is a data item of class object and category object-reference. It must contain either null or a reference to an object, subject to the following rules:
1. The amount of storage allocated for an object reference data item is four bytes.
2. If none of the optional phrases is specified, this data item is called a universal object reference. Its content may be a reference to any object.
3. If interface-name-1 is specified, the object referenced by this data item must implement interface-name-1.
4. If class-name-1 is specified, the object referenced by this data item must be an object of class-name-1 or of a subclass of class-name-1, subject to the following rules:
  1. If the ONLY phrase is not specified:
    1. If the FACTORY phrase is specified, the object referenced by this data item must be the factory object of the specified class or of a subclass of the specified class.
    2. If the FACTORY phrase is not specified, the object referenced by this data item must be an object of the specified class or of a subclass of the specified class.
  2. If the ONLY phrase is specified:
    1. If the FACTORY phrase is specified, the object referenced by this data item must be the factory object of the specified class.
    2. If the FACTORY phrase is not specified, the object referenced by this data item must be an object of the specified class.
5. If ACTIVE-CLASS is specified, the object referenced by this data item must be an object of the class of the object that was used to invoke the method in which the object referenced is specified, subject to the following rules:
  1. If the FACTORY phrase is specified, the object referenced by this data item must be the factory object of that class.
  2. If the FACTORY phrase is not specified, the object referenced by this data item must be an object of that class.
The USAGE IS EVENT-POINTER clause identifies an synchronization data item that flags an occurrence of a software event. An event data item has a value of either TRUE or FALSE.
The USAGE IS MONITOR-POINTER clause identifies a synchronization data item, known as a monitor, on which one can request read locks, browse locks, and write locks.
Note: A monitor is typically used to protect a data structure that different threads might want to read from or read from and write to.
The USAGE IS MUTEX-POINTER clause identifies a synchronization data item, known as a mutex, that can be used to protect critical sections in a multi-threaded application. A mutex data item has a value of either ON or OFF. Only one thread can have a mutex data item in the ON state at a time.
The USAGE IS SEMAPHORE-POINTER clause identifies a counting synchronization data item that cannot go below zero.
The USAGE IS THREAD-POINTER clause identifies a data item in which you can store the handle for a thread.
The implicit or explicit USAGE IS NATIONAL clause identifies a data item that is stored in the computer in national-coded characters and aligned on a character boundary. National characters are represented in the storage of the computer as characters of a uniform size. See your COBOL system documentation on national data (UNICODE) for further information.

The USAGE IS BINARY-CHAR, USAGE IS BINARY-SHORT, USAGE IS BINARY-LONG and USAGE IS BINARY-DOUBLE clauses identify a numeric data item that has a radix of 2 in the storage of the computer. These usages are equivalent to specifying USAGE IS COMP-5 with the picture character-strings as shown below. An S is included in the equivalent picture character-string unless the UNSIGNED phrase is specified in the USAGE clause.

USAGE	Equivalent PICTURE character-string
BINARY-CHAR	[S]9(2)
BINARY-SHORT	[S]9(4)
BINARY-LONG	[S]9(9)
BINARY-DOUBLE	[S] 9(18)

The USAGE IS FLOAT-SHORT clause is equivalent to specifying USAGE IS COMPUTATIONAL-1.
The USAGE IS FLOAT-LONG clause is equivalent to specifying USAGE IS COMPUTATIONAL-2.
A data description entry that specifies the USAGE PROGRAM-POINTER clause specifies a procedure-pointer data item, also called a program-pointer and a procedure-pointer, that may contain the address of a program. (See the topic The SET Statement.) The procedure can be written in any language: if COBOL, it represents the Procedure Division of a program that is not nested and identified by one of :
- The program-name of the Program-ID paragraph
- The entry-name of an ENTRY statement.
If program-prototype-name-1 is specified, this data item is a restricted program-pointer. A restricted program pointer must contain only the predefined address NULL or the address of a program with the same signature as that identified by the specified program-prototype-name.
The USAGE IS CONDITION-VALUE clause specifies a boolean data item that can have the value TRUE or FALSE. A CONDITION-VALUE boolean data item maps onto the .NET framework System.Boolean type, so data items with this usage can be passed to methods that accept System.Boolean parameters.
If the class-name specified in the USAGE IS OBJECT REFERENCE class-name clause is a value type, a compiler warning is produced. The item will be treated as a value type, i.e. no reference is produced.
The USAGE IS class-name clause phrase specifies:
- If class-name references a reference type, this is exactly equivalent to USAGE OBJECT REFERENCE class-name-1. The data item represents a reference to an object allocated on the heap, or the value NULL.
- If class-name references a value type, this clause specifies a data item that is a value type.
If the EVENT phrase is specified, the two methods add_ChangeEvent and remove_ChangeEvent are automatically created. These methods can be used, respectively, to hook a new method into the delegate, and subsequently to remove it.
The USAGE BIT clause specifies that bits are used to represent a boolean data item. A data item described with USAGE BIT is a bit data item. See the topic Aligning Bit Data Items for information on how boolean data items are aligned.
Integer-1 specifies the number of bytes allocated for a binary (radix-2) data item. If the IBMCOMP directive is specified, the value is adjusted, if necessary, to the next word storage number of bytes that is equal or greater to the number of bytes specified. The length specification can specify a value less than, equal to or greater than the number of bytes that would otherwise be allocated for the binary data item based on the number of 9 symbols in the PICTURE character-string.
If the integer-1 length specification is specified in a USAGE clause at a group level, the length specification applies to each binary data item subordinate to that group except when a data item is subordinate to another group that specifies a different length specification or the elementary data item itself is described with a length specification. That is, the nearest containing group that has a length specification is applied for binary data items in a group that do not have their own length specification.