LENGTH
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.
- argument-1
- Can be:
- An alphanumeric literal or a national literal
- A group item (including unbounded groups) or an elementary 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 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.