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

Read syntax diagramSkip visual syntax diagramFUNCTION LENGTH(argument-1 )
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.