COBOL INSPECT statement

The INSPECT statement examines and optionally modifies a string in place. You can TALLY (count characters or substrings), REPLACING (replace characters), or CONVERTING (character-by-character mapping). INSPECT is a single statement that does the work of a loop, so it is efficient and readable for cleaning data or counting occurrences.

What INSPECT can do

REPLACING: replace characters

INSPECT identifier REPLACING ... changes characters in the string. ALL literal-1 BY literal-2 replaces every occurrence of literal-1 with literal-2 (lengths must match). LEADING affects only the leftmost run of the character; FIRST affects only the first occurrence.

1
2
3
4
5
6
7
8
9
       *> Replace every comma with a space
       MOVE "A,B,C,D" TO WS-TEXT
       INSPECT WS-TEXT REPLACING ALL "," BY " ".
       *> WS-TEXT is now "A B C D"
 
       *> Replace only leading spaces with zeros
       MOVE "    123" TO WS-NUM
       INSPECT WS-NUM REPLACING LEADING " " BY "0".
       *> WS-NUM is now "0000123"

TALLYING: count occurrences

INSPECT identifier TALLYING counter FOR ... adds a count to the numeric counter field. FOR CHARACTERS counts every character. FOR ALL literal counts how many times the literal appears. FOR LEADING literal counts only the contiguous occurrences at the start. The counter is increased (not set); initialize it to zero first if you want a fresh count.

1
2
3
4
5
6
7
       MOVE ZEROS TO WS-COUNT
       INSPECT WS-LINE TALLYING WS-COUNT FOR ALL ",".
       *> WS-COUNT now holds the number of commas in WS-LINE
 
       MOVE ZEROS TO WS-LEN
       INSPECT WS-NAME TALLYING WS-LEN FOR CHARACTERS.
       *> WS-LEN holds the length of WS-NAME (if WS-NAME is the target)

Combined TALLYING and REPLACING

You can combine both in one INSPECT: first TALLYING is done, then REPLACING. Both operate on the same identifier. Use BEFORE INITIAL or AFTER INITIAL to limit the region (e.g. only before the first period).

1
2
3
4
5
       MOVE ZEROS TO WS-COMMA-COUNT
       INSPECT WS-BUFFER
           TALLYING WS-COMMA-COUNT FOR ALL ","
           REPLACING ALL "," BY " ".
       *> Count commas and replace them with spaces in one pass

CONVERTING: character mapping

CONVERTING literal-1 TO literal-2 maps each character in literal-1 to the character at the same position in literal-2. So INSPECT WS-TEXT CONVERTING "abc" TO "ABC" converts every 'a' to 'A', every 'b' to 'B', every 'c' to 'C'. Useful for case conversion or simple substitution tables.

Step-by-step: replace all spaces with hyphens

• Define a field large enough (e.g. PIC X(80)).
• Move the source string into it (or read into it).
• Write: INSPECT field REPLACING ALL " " BY "-".
• The field is modified in place; no second field is required.

Related concepts