Start of change

BYTE-LENGTH

The BYTE-LENGTH function returns an integer equal to the length of the argument in bytes.

The function type is integer.

Format

Read syntax diagramSkip visual syntax diagramFUNCTION BYTE-LENGTH (argument-1 )
argument-1
Can be:
  • An alphanumeric, national, or DBCS literal
  • A group item (including unbounded groups) or an elementary data item of any class, including 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:
  • The returned value is an integer that is the length of argument-1 in number of bytes.
  • If argument-1 is an alphanumeric or national group item, the value returned is equal to the length of argument-1 in bytes. 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.

The only difference between the BYTE-LENGTH and LENGTH functions is that BYTE-LENGTH always returns the byte length of argument-1, even when argument-1 is of class national. The BYTE-LENGTH function also accepts DBCS arguments.

Function BYTE-LENGTH is similar to the LENGTH OF special register, which also always returns the byte length of its argument, but the LENGTH OF special register can be used in more contexts. For more information, see Finding the length of data items in the Enterprise COBOL Programming Guide.

related references
LENGTH
LENGTH OF

End of change