The
LENGTH function returns an integer equal to the length of the argument
in national character positions for arguments of usage NATIONAL and
in alphanumeric character positions or bytes for all other arguments. An
alphanumeric character position and a byte are equivalent.
The
type of the function is integer.

Format
>>-FUNCTION LENGTH--(--argument-1--)---------------------------><
- argument-1
- Can be:
- An alphanumeric literal or a national literal
- A data item of any class except DBCS
- A data item described with usage POINTER, PROCEDURE-POINTER, FUNCTION-POINTER,
or OBJECT REFERENCE
- The ADDRESS OF special register
- The LENGTH OF special register
- The XML-NTEXT special register
- The XML-TEXT special register
The returned value is a nine-digit integer if the ADDR(32) compiler option
is specified or an 18-digit integer if the ADDR(64) compiler option
is specified and is determined as follows:
- If argument-1 is an alphanumeric
literal or an elementary data item of class alphabetic or alphanumeric,
the value returned is equal to the number of alphanumeric character
positions in the argument.
If argument-1 is
a null-terminated alphanumeric literal, the returned value is equal
to the number of alphanumeric character positions in the literal excluding
the null character at the end of the literal.
The length of
an alphanumeric data item or literal containing a mix of single-byte
and double-byte characters is counted as though each byte were a single-byte
character.
- If argument-1 is an alphanumeric
group item, the value returned is equal to the length of argument-1 in
alphanumeric character positions regardless of the content of the
group. If any data item subordinate to argument-1 is
described with the DEPENDING phrase of the OCCURS clause, the length
of argument-1 is determined using the contents
of the data item specified in the DEPENDING phrase. This evaluation
is accomplished according to the rules of the OCCURS clause for a
sending data item. For more information, see the discussions of the
OCCURS clause
and the USAGE clause.
The returned value includes
implicit FILLER positions, if any.
- If argument-1 is a national
literal or an elementary data item described with usage NATIONAL,
the value returned is equal to the length of argument-1 in
national character positions.
For example, if argument-1 is
defined as PIC 9(3) with usage NATIONAL, the returned value is 3,
although the storage size of the argument is 6 bytes.
- If argument-1 is a national
group item, the value returned is equal to the length of argument-1 in
national character positions. If any data item subordinate to argument-1 is
described with the DEPENDING phrase of the OCCURS clause, the length
of argument-1 is determined using the contents
of the data item specified in the DEPENDING phrase. This evaluation
is accomplished according to the rules of the OCCURS clause for a
sending data item. For more information, see the discussions of the
OCCURS clause
and the USAGE clause.
The returned value includes
implicit FILLER positions, if any.
- Otherwise, the returned value is the number of bytes of storage
occupied by argument-1.