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