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 data items described with usage DISPLAY-1 (DBCS data items) and data items described with usage NATIONAL, each character occupies 2 bytes of storage.
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.
When the ADDR(32) compiler option is specified the LENGTH OF special register has the implicit definition:
USAGE IS BINARY PICTURE 9(9).
USAGE IS BINARY PICTURE 9(18).
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 always 4 when the ADDR(32) compiler option is specified or always 8 when the ADDR(64) compiler option is specified, independent of the argument specified for LENGTH OF.
If the ADDRESS OF special register is used as the argument to the LENGTH function, the result is always 4 when the ADDR(32) compiler option is specified or always 8 when the ADDR(64) compiler option is specified, independent of the argument specified for ADDRESS OF.
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. 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.