The USAGE Clause

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

General Format
Directives
  1. 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.
Syntax Rules
  1. The USAGE clause may be written in any data description entry with a level number other than 66 or 88.
  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 COMPUTATIONAL

    ANS85, BINARY, PACKED-DECIMAL

    OSVSVSC2MFXOPEN, COMPUTATIONAL-3

    OSVSVSC2MF, COMPUTATIONAL-4

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

    MFAn 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.

  4. MFXOPENOS390An 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

    MFor COMPUTATIONAL-X

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

    MFor describes an alphanumeric item with a size of between one and eight bytes inclusive. If it describes an alphanumeric item of size 1, 2, 3, 4, 5, 6, 7, or 8 bytes, then this is equivalent to specifying an integer item with 2, 4, 7, 9, 12, 14, 16 or 18 decimal digit positions respectively
    .

    MFWhen COMPUTATIONAL-X is specified and the PICTURE character-string describes a numeric item, then that item must be unsigned.

  5. The BLANK WHEN ZERO, JUSTIFIED and SIGN clauses must not be specified for data items whose usage is not explicitly or implicitly DISPLAY.
  6. The SYNCHRONIZED and VALUE clauses must not be specified for data items whose usage is INDEX.

    OSVSVSC2MFThe SYNCHRONIZED clause can be specified for data items whose usage is INDEX.

  7. COMP is an abbreviation for COMPUTATIONAL.

    OSVSVSC2MFCOMP-1 is an abbreviation for COMPUTATIONAL-1.

    OSVSVSC2MFCOMP-2 is an abbreviation for COMPUTATIONAL-2.

    OSVSVSC2MFXOPENCOMP-3 is an abbreviation for COMPUTATIONAL-3.

    OSVSVSC2MFCOMP-4 is an abbreviation for COMPUTATIONAL-4.

    MFXOPENOS390COMP-5 is an abbreviation for COMPUTATIONAL-5.

    MFCOMP-X is an abbreviation for COMPUTATIONAL-X.

  8. An index item can be referenced explicitly only in a SEARCH or SET statement, a relation condition, the USING phrase of a Procedure Division,

    OSVSVSC2MFthe USING statement of an ENTRY statement,

    ANS85an intrinsic function argument

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

    ANS85an INITIALIZE statement

    or the USING phrase of a CALL statement.

  9. ISO2002VSC2MFCOB370ISO2002VSC2MFA pointer

    MFCOB370or procedure-pointer

    VSC2MFitem 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

    ISO2002an INVOKE statement, the argument list of an inline invocation of a method, the argument list of a function,

  10. An elementary data item described with usage INDEX,

    ISO2002OBJECT,

    VSC2MFPOINTER,

    MFCOB370or PROCEDURE-POINTER

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

    clause must not be a conditional variable.

  11. MFTypedef-name-1 must be previously defined in the same source file as a record with the TYPEDEF clause.
  12. MFIf USAGE typedef-name-1 is specified, the following clauses cannot also be specified:
  13. MFIt is an error to specify USAGE typedef-name-1 if there is an explicit USAGE clause at a higher level in the same hierarchy.
  14. MFIt 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.
  15. ISO2002The 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.
  16. ISO2002The USAGE OBJECT REFERENCE clause must not be specified in the File Section.

    MFThe 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.

  17. ISO2002The ACTIVE-CLASS phrase can be specified only in a factory definition, object definition, or method definition.
  18. MFA 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.
  19. MFA 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.
  20. MFA data item whose usage is THREAD-POINTER can be referenced explicitly only in a START statement, a WAIT statement or a USING phrase.
  21. MFAn 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.
  22. MFWhen 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.
  23. MFA 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.

  24. MFIf program-prototype-name-1 is specified, the TYPEDEF clause must be specified for the subject of the entry.

    This restriction is not enforced.

  25. MFThe 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'.
  26. NET
    A USAGE clause with the CONDITION-VALUE phrase must be specified only for an elementary data item with level 1.
  27. NET
    If the EVENT phrase is specified, then class-name-1 shall reference a delegate definition and the FACTORY phrase shall not be specified.
  28. ISO2002MFAn elementary data item whose description contains, or an elementary data item subordinate to a group item whose description contains, a USAGE clause specifying BIT must be declared with a picture character-string that describes a boolean data item.
General Rules
  1. If the USAGE clause is written at the group level, it applies to each elementary item in the group

    MFexcept when there is a PICTURE clause and the data item described is non-numeric

  2. 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.
  3. 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.
  4. 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.

    OSVSVSC2MFXOPENThis clause is equivalent to specifying USAGE IS COMPUTATIONAL-3.

  5. 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.
  6. OSVSVSC2MFThe USAGE IS DISPLAY clause is valid for the following types of items:
  7. 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.
  8. When a MOVE statement or an input-output statement that references a group item that contains an index,

    VSC2MFor pointer,

    MFCOB370or procedure-pointer

    data item is executed, no conversion of the index,

    VSC2MFor pointer

    MFCOB370or procedure-pointer

    data item takes place.

  9. OSVSVSC2MFThe USAGE IS COMPUTATIONAL-4 clause is equivalent to specifying USAGE IS COMPUTATIONAL.
  10. VSC2MFThe 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).
  11. MFCOB370 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:
  12. MFIf 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.
  13. MFIf 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.
  14. ISO2002MFA 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.
  15. MFThe 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.
  16. MFThe 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.

    MFNote: A monitor is typically used to protect a data structure that different threads might want to read from or read from and write to.

  17. MFThe 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.
  18. MFThe USAGE IS SEMAPHORE-POINTER clause identifies a counting synchronization data item that cannot go below zero.
  19. MFThe USAGE IS THREAD-POINTER clause identifies a data item in which you can store the handle for a thread.
  20. ISO2002MFThe 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.
  21. ISO2002MFThe 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)
  22. ISO2002MFThe USAGE IS FLOAT-SHORT clause is equivalent to specifying USAGE IS COMPUTATIONAL-1.
  23. ISO2002MFThe USAGE IS FLOAT-LONG clause is equivalent to specifying USAGE IS COMPUTATIONAL-2.
  24. ISO2002MFA 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 :
  25. ISO2002MFIf program-prototype-name-1 is specified, this data item is a restricted program-pointer. A restricted programpointer 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.
  26. NET
    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.
  27. NET
    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.
  28. NET
    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 a .NET 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 .NET value type.
  29. NET
    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.
  30. ISO2002MFThe 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.

Related Topics