COBOL INSPECT

INSPECT is a COBOL verb that examines and optionally modifies a single alphanumeric or national field. It can count occurrences of characters or strings (TALLYING), replace them (REPLACING), or translate characters with a one-to-one map (CONVERTING). Modifiers—ALL, LEADING, FIRST, BEFORE INITIAL, AFTER INITIAL—control which part of the field is affected. INSPECT does not change the length of the field; it only replaces character for character or string for string within the same space. This page explains each form and modifier with examples.

Explain Like I'm Five: What Is INSPECT?

INSPECT is like a find-and-replace or counter that works on one line of text. You point at that line and say: "Count how many times the comma appears," or "Replace every comma with a space," or "Replace every letter a with A." The line stays the same length; you are only swapping or counting. You can also say "only at the beginning" (LEADING) or "only the first time" (FIRST) so you do not change or count the whole line.

Overview: TALLYING, REPLACING, CONVERTING

TALLYING adds to a tally (counter) field for each occurrence of a character or string you specify. The inspected field is not modified; only the tally field is updated. You must initialize the tally to zero before INSPECT if you want a fresh count, because TALLYING adds to the existing value. REPLACING changes the inspected field: you specify what to look for and what to put in its place (character by character or string by string). The replacement can be a single character, a literal, or an identifier. CONVERTING is a special case of replacement: you give two literals of equal length; any character in the field that appears in the first literal is replaced by the character at the same position in the second literal. Typical use is case conversion: CONVERTING 'abc...xyz' BY 'ABC...XYZ'. You can combine TALLYING and REPLACING in one INSPECT so that you count and replace in a single pass.

TALLYING in Detail

TALLYING identifier-1 FOR ALL|LEADING|FIRST literal-1 counts how many times literal-1 (or identifier-2) appears in the inspected field and adds that count to identifier-1. Identifier-1 must be numeric. FOR ALL counts every occurrence. FOR LEADING counts only consecutive occurrences at the start of the field (e.g. leading spaces or leading zeros). FOR FIRST counts only the first occurrence (so the tally increases by at most 1). You can list multiple FOR phrases: TALLYING WS-CNT FOR ALL SPACES FOR ALL "," adds the count of spaces plus the count of commas. The inspected field is never changed by TALLYING alone.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
       01 WS-TEXT   PIC X(40) VALUE '  HELLO, WORLD, AGAIN  '.
       01 WS-CNT   PIC 9(2).
 
       MOVE 0 TO WS-CNT
       INSPECT WS-TEXT TALLYING WS-CNT FOR ALL SPACES
       *> WS-CNT = number of spaces in WS-TEXT
 
       MOVE 0 TO WS-CNT
       INSPECT WS-TEXT TALLYING WS-CNT FOR LEADING SPACES
       *> WS-CNT = 2 (only the two leading spaces)
 
       MOVE 0 TO WS-CNT
       INSPECT WS-TEXT TALLYING WS-CNT FOR ALL ','
       *> WS-CNT = 2 (two commas)

REPLACING in Detail

REPLACING changes the inspected field. You specify what to replace and what to replace it with: REPLACING ALL|LEADING|FIRST literal-1 BY literal-2 (or BY identifier). ALL means every occurrence of literal-1 is replaced by literal-2. LEADING means only consecutive occurrences at the start. FIRST means only the first occurrence. The lengths of literal-1 and literal-2 can differ: for example, REPLACING ALL "," BY SPACE replaces each comma with one space (same length), but you could replace a two-character string by a single character (implementation may pad or truncate; check your manual). BEFORE INITIAL literal restricts the replacement to the portion of the field before the first occurrence of that literal; AFTER INITIAL restricts to the portion after. So you can replace only in a prefix or suffix of the field.

1
2
3
4
5
6
7
8
9
10
11
       01 WS-LINE   PIC X(30) VALUE 'A,B,C,D'.
 
       INSPECT WS-LINE REPLACING ALL ',' BY SPACE
       *> WS-LINE = 'A B C D '
 
       01 WS-NUM   PIC X(10) VALUE '00123456'.
       INSPECT WS-NUM REPLACING LEADING '0' BY SPACE
       *> WS-NUM = '  123456' (leading zeros become spaces)
 
       INSPECT WS-LINE REPLACING FIRST ',' BY SPACE
       *> Only first comma replaced: 'A B,C,D'

CONVERTING in Detail

CONVERTING literal-1 BY literal-2 (or identifier-1 BY identifier-2) performs a character-level translation. Literal-1 and literal-2 must have the same length. For each character in the inspected field, if it appears in literal-1 at some position, it is replaced by the character at the same position in literal-2. So CONVERTING "abcdefghijklmnopqrstuvwxyz" BY "ABCDEFGHIJKLMNOPQRSTUVWXYZ" converts lowercase to uppercase. If a character appears more than once in literal-1, the first occurrence usually determines the mapping (check your compiler). CONVERTING does not support ALL, LEADING, or FIRST in standard COBOL; it applies to the whole field. Use it for case conversion, digit substitution, or any one-to-one character map.

1
2
3
4
5
6
       01 WS-NAME   PIC X(20) VALUE 'john smith'.
 
       INSPECT WS-NAME CONVERTING
           'abcdefghijklmnopqrstuvwxyz'
           BY 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
       *> WS-NAME = 'JOHN SMITH'

Modifiers: ALL, LEADING, FIRST, BEFORE/AFTER INITIAL

ALL applies the operation to every occurrence in the field. LEADING applies only to consecutive occurrences at the very beginning: as soon as a character that does not match is found, no more are considered. FIRST applies only to the first occurrence in the field. BEFORE INITIAL literal restricts the operation to the substring from position 1 up to (but not including) the first occurrence of the literal. AFTER INITIAL literal restricts to the substring from the first character after that literal to the end of the field. These can be combined: for example, REPLACING LEADING SPACES BY ZEROS, or TALLYING ... FOR ALL "0" BEFORE INITIAL "." to count zeros only in the integer part of a number. The order of evaluation and exact behavior for overlapping or multiple modifiers can vary by compiler; refer to your manual.

Combined TALLYING and REPLACING

You can write one INSPECT that both tallies and replaces. For example: INSPECT WS-FIELD TALLYING WS-CNT FOR LEADING "0" REPLACING LEADING "0" BY SPACE. This counts the leading zeros and replaces them with spaces in one pass. The FOR phrase and the REPLACING phrase can use different modifiers and literals, but often you want them to match (same LEADING, same literal) so the count reflects what was replaced. Combined INSPECT is useful when you need both the count and the modified field without scanning twice.

What INSPECT Cannot Do

INSPECT cannot change the length of the field. REPLACING substitutes one character or string with another; the total number of characters in the field stays the same (padding or truncation may apply when replacement length differs). To remove characters and close the gap (e.g. remove all spaces and left-justify), you need a loop that shifts characters or UNSTRING with multiple receivers. INSPECT also operates on one field at a time; to combine or split fields use STRING or UNSTRING.

Step-by-Step: Count and Replace Leading Zeros

1. Have the field to inspect (e.g. PIC X(10) with value '001234') and a numeric tally field (e.g. PIC 9(2)).
2. MOVE 0 TO tally so the count starts at zero. INSPECT field TALLYING tally FOR LEADING "0" REPLACING LEADING "0" BY SPACE.
3. After INSPECT, the tally holds the number of leading zeros and the field has spaces where the leading zeros were. Use the tally if you need it (e.g. for formatting); the field is ready for display or further processing.

Step-by-Step: Case-Insensitive Compare Using CONVERTING

1. Copy the input to a work field so you do not lose the original. MOVE WS-INPUT TO WS-WORK.
2. INSPECT WS-WORK CONVERTING 'a..z' BY 'A..Z' (full alphabets in your code page).
3. Compare WS-WORK to an uppercase literal or another converted value: IF WS-WORK = 'YES' ... This gives case-insensitive comparison.

Best Practices

• Initialize the tally field to zero before TALLYING unless you intend to accumulate across multiple INSPECTs.
• Use LEADING or FIRST when you only care about the start or the first occurrence; it makes the intent clear and can be more efficient.
• For case conversion, use CONVERTING with full alphabets so no lowercase letter is missed. Consider using FUNCTION UPPER-CASE when available.
• Do not assume INSPECT can remove characters; use UNSTRING or a loop for that. Use INSPECT for in-place replace and count.
• Document the intended scope (ALL, LEADING, etc.) when the logic is non-obvious so maintainers understand which part of the field is affected.

Test Your Knowledge