COBOL String Functions

COBOL provides intrinsic functions for string handling: length, case conversion, reversal, and (via reference modification) substrings. This page covers the most common string-related functions and how to use them in expressions and procedure code.

Explain Like I'm Five: What Are String Functions?

String functions are built-in tools that do one job on a piece of text: "how long is it?" (LENGTH), "make it all capitals" (UPPER-CASE), "spell it backwards" (REVERSE), or "give me just this part" (substring). You call them by name with the text you want to work on, and you get back a result you can use in a MOVE, IF, or COMPUTE.

FUNCTION LENGTH

FUNCTION LENGTH takes one argument (an alphanumeric or national identifier or literal) and returns its length in character positions as an integer. For a data item, the length is the declared length (e.g. PIC X(30) gives 30), not the number of non-blank characters. Use LENGTH when you need the size of a field for loops, validation, or passing to another program.

1
2
3
4
5
6
7
8
9
       01 WS-NAME   PIC X(30).
       01 WS-LEN   PIC 9(2).
 
       MOVE FUNCTION LENGTH(WS-NAME) TO WS-LEN
       *> WS-LEN is 30
 
       IF FUNCTION LENGTH(INPUT-FIELD) > 80
           DISPLAY 'Input too long'
       END-IF

The argument can be a literal: FUNCTION LENGTH("HELLO") returns 5. The result is numeric and can be used in arithmetic or comparisons.

FUNCTION UPPER-CASE and LOWER-CASE

FUNCTION UPPER-CASE(argument) returns a string with the same length as the argument and all alphabetic characters converted to uppercase. FUNCTION LOWER-CASE(argument) converts to lowercase. The argument is not modified; the function returns a new value. Use these for case-insensitive comparison (e.g. compare UPPER-CASE(WS-INPUT) with UPPER-CASE(WS-KEY)) or for normalizing data for display or storage.

1
2
3
4
5
6
7
8
9
       01 WS-CODE   PIC X(5) VALUE 'Ab12X'.
       01 WS-NORM   PIC X(5).
 
       MOVE FUNCTION UPPER-CASE(WS-CODE) TO WS-NORM
       *> WS-NORM is 'AB12X'
 
       IF FUNCTION UPPER-CASE(WS-INPUT) = 'YES'
           PERFORM CONFIRM-PROCESS
       END-IF

Non-alphabetic characters (digits, spaces, symbols) are unchanged. The result must be moved to a field of the same length (or longer) or used in an expression that accepts that length.

FUNCTION REVERSE

FUNCTION REVERSE(argument) returns a string with the same characters in reverse order. The argument is alphanumeric (or national). Common uses include reversing a numeric string for processing or reversing text. The argument is not modified.

1
2
3
4
5
       01 WS-DIGITS PIC X(5) VALUE '12345'.
       01 WS-REV    PIC X(5).
 
       MOVE FUNCTION REVERSE(WS-DIGITS) TO WS-REV
       *> WS-REV is '54321'

Reference Modification (Substring)

Reference modification lets you refer to a substring without a separate function in many COBOL compilers. The syntax is identifier(start:length) or identifier(start:). start is the starting character position (1-based). length is the number of characters; if omitted, the rest of the string is used. So WS-NAME(1:10) is the first 10 characters, and WS-NAME(5:) is from position 5 to the end. You can use this on the left or right of a MOVE, in IF, or in STRING/UNSTRING. Not all compilers use the same syntax (e.g. (start, length) instead of (start:length)); check your manual.

1
2
3
4
5
6
       01 WS-FULL   PIC X(20) VALUE 'SMITH,JOHN'.
       01 WS-LAST   PIC X(5).
       01 WS-FIRST  PIC X(4).
 
       MOVE WS-FULL(1:5)  TO WS-LAST   *> 'SMITH'
       MOVE WS-FULL(7:4)  TO WS-FIRST  *> 'JOHN'

Other String-Related Functions

NUMVAL and NUMVAL-C convert an alphanumeric (often edited numeric) string to a numeric value. Useful when you read a formatted number (e.g. with commas or currency) and need to use it in arithmetic. Some compilers offer WHEN-COMPILED, CURRENT-DATE, and others that return character or numeric values. For a full list, see your compiler’s intrinsic function documentation or the intrinsic-functions tutorial.

Using Functions in Expressions

Intrinsic functions are used in expressions: MOVE FUNCTION LENGTH(x) TO y, IF FUNCTION UPPER-CASE(a) = b, COMPUTE z = n + FUNCTION LENGTH(ws-field). The function reference is evaluated first; the result is then used in the statement. The result type (numeric or alphanumeric) must be compatible with where it is used. For STRING or UNSTRING, you can use reference modification to pick a slice of a field as source or target.

Step-by-Step: Case-Insensitive Comparison

1. Define the two fields you want to compare (or use literals).
2. In the IF, compare FUNCTION UPPER-CASE(field1) to FUNCTION UPPER-CASE(field2) (or to an uppercase literal).
3. If you need the normalized value elsewhere, MOVE FUNCTION UPPER-CASE(source) TO a working field and use that for display or storage.

Step-by-Step: Extracting a Substring

1. Identify the start position (1-based) and length of the substring you need.
2. Define a receiving field with at least that length (PIC X(n)).
3. Use reference modification: MOVE source(start:length) TO receiver. Adjust syntax for your compiler (e.g. (start, length) if required).

Best Practices

• Use UPPER-CASE or LOWER-CASE for comparisons when case should not matter; avoid multiple literal tests.
• Use LENGTH when the logic depends on declared size (e.g. loop bounds); remember it is declared length, not content length.
• Check your compiler documentation for exact syntax of reference modification and for availability of SUBSTRING or other string functions.

Test Your Knowledge