LENGTH OF

The LENGTH OF special register contains the number of bytes used by a data item.

LENGTH OF creates an implicit special register that contains the current byte length of the data item referenced by the identifier.

For example:
IDENTIFICATION DIVISION.
PROGRAM-ID. LengthOfExample.

DATA DIVISION.
WORKING-STORAGE SECTION.
01 MyString PIC X(20) VALUE 'Hello, COBOL!'.
01 StringLength PIC 9(3).
       
PROCEDURE DIVISION.
    MOVE LENGTH OF MyString TO StringLength.
    DISPLAY 'Length of MyString is ' StringLength.
    STOP RUN.
The output is: 
Length of MyString is 020

For data items described with usage DISPLAY-1 (DBCS data items) and data items described with usage NATIONAL, each character occupies 2 bytes of storage. For data items described with usage UTF-8, each character occupies between 1 and 4 bytes.

LENGTH OF can be used in the PROCEDURE DIVISION anywhere a numeric data item that has the same definition as the implied definition of the LENGTH OF special register can be used.

If LP(32) is in effect, the LENGTH OF special register has the implicit definition:

PICTURE 9(9) USAGE IS BINARY.
If LP(64) is in effect, the LENGTH OF special register has the implicit definition:
PICTURE 9(18) USAGE IS BINARY.

If the data item referenced by the identifier contains the GLOBAL clause, the LENGTH OF special register is a global data item.

The LENGTH OF special register can appear within either the starting character position or the length expressions of a reference-modification specification. However, the LENGTH OF special register cannot be applied to any operand that is reference-modified.

The LENGTH OF operand cannot be a function, but the LENGTH OF special register is allowed in a function where an integer argument is allowed.

If the LENGTH OF special register is used as the argument to the LENGTH function, the result is 4 when LP(32) is in effect, and the result is 8 when LP(64) is in effect.

If the ADDRESS OF special register is used as the argument to the LENGTH function, the result is 4 when LP(32) is in effect, and the result is 8 when LP(64) is in effect.

LENGTH OF cannot be either of the following items:

  • A receiving data item
  • A subscript

When the LENGTH OF special register is used as a parameter on a CALL statement, it must be passed BY CONTENT or BY VALUE.

When a table element is specified, the LENGTH OF special register contains the length in bytes of one occurrence. When referring to a table element, the element name need not be subscripted.

A value is returned for any identifier whose length can be determined, even if the area referenced by the identifier is currently not available to the program.

A separate LENGTH OF special register exists for each identifier referenced with the LENGTH OF phrase. For example:


MOVE LENGTH OF A TO B
DISPLAY LENGTH OF A, A
ADD LENGTH OF A TO B
CALL "PROGX" USING BY REFERENCE A BY CONTENT LENGTH OF A

The intrinsic function LENGTH can also be used to obtain the length of a data item. For data items of usage NATIONAL, the length returned by the LENGTH function is the number of national character positions, rather than bytes; thus the LENGTH OF special register and the LENGTH intrinsic function have different results for data items of usage NATIONAL. Also, for table elements, the intrinsic function LENGTH requires a subscript, while the LENGTH OF special register does not. For all other data items, the result is the same.

The intrinsic function LENGTH can also be used to obtain the length of a data item. For data items of usage NATIONAL, the length returned by the LENGTH function is the number of national character positions. For data items of usage UTF-8, the length returned by the LENGTH function is the number of UTF-8 character positions. Thus, the LENGTH OF special register and the LENGTH intrinsic function have different results for data items of usage NATIONAL and UTF-8. Also, for table elements, the intrinsic function LENGTH requires a subscript, while the LENGTH OF special register does not. For all other data items, the result is the same.

The LENGTH intrinsic function, when applied to a null-terminated alphanumeric literal, returns the number of bytes in the literal prior to but not including the terminating null. (The LENGTH special register does not support literal operands.) For details about null-terminated alphanumeric literals, see Null-terminated alphanumeric literals.