INSPECT statement

The INSPECT statement examines characters or groups of characters in a data item.

The INSPECT statement does the following tasks:

Counts the occurrences of a specific character (alphanumeric, DBCS, or national) in a data item (formats 1 and 3).
Counts the occurrences of specific characters and fills all or portions of a data item with specified characters, such as spaces or zeros (formats 2 and 3).
Converts all occurrences of specific characters in a data item to user-supplied replacement characters (format 4).

Format 1: INSPECT statement with TALLYING phrase

phrase 1

Format 2: INSPECT statement with REPLACING phrase

phrase 1

Format 3: INSPECT statement with TALLYING and REPLACING phrases

phrase 1

Format 4: INSPECT statement with CONVERTING phrase

identifier-1

Is the inspected item and can be any of the following items:

An alphanumeric group item or a national group item
An elementary data item described explicitly or implicitly with usage DISPLAY, DISPLAY-1, or NATIONAL. The item can have any category that is valid for the selected usage.

identifier-3 , identifier-4 , identifier-5 , identifier-6 , identifier-7

Must reference an elementary data item described explicitly or implicitly with usage DISPLAY, DISPLAY-1, or NATIONAL.

literal-1 , literal-2 , literal-3 , literal-4

Must be of category alphanumeric, DBCS, or national.

When identifier-1 is of usage NATIONAL, literals must be of category national.

When identifier-1 is of usage DISPLAY-1, literals must be of category DBCS.

When identifier-1 is of usage DISPLAY, literals must be of category alphanumeric.

When identifier-1 is of usage DISPLAY-1 (DBCS) literals may be the figurative constant SPACE.

When identifier-1 is of usage DISPLAY or NATIONAL, literals can be any figurative constant that does not begin with the word ALL, as specified in Figurative constants. The figurative constant is treated as a one-character alphanumeric literal when identifier-1 is of usage DISPLAY, and as a one-character national literal when identifier-1 is of usage NATIONAL.

All identifiers (except identifier-2) must have the same usage as identifier-1. All literals must have category alphanumeric, DBCS, or national when identifier-1 has usage DISPLAY, DISPLAY-1, or NATIONAL, respectively.

All identifiers may not be dynamic-length group or dynamic-length elementary items.

TALLYING phrase (formats 1 and 3)

This phrase counts the occurrences of a specific character or special character in a data item.

When identifier-1 is a DBCS data item, DBCS characters are counted; when identifier-1 is a data item of usage national, national characters (encoding units) are counted; otherwise, alphanumeric characters (bytes) are counted.

identifier-2

Is the count field, and must be an elementary integer item defined without the symbol P in its PICTURE character-string.

identifier-2 cannot be of category external floating-point.

You must initialize identifier-2 before execution of the INSPECT statement begins.

Usage note: The count field can be an integer data item defined with usage NATIONAL.

identifier-3 or literal-1

Is the tallying field (the item whose occurrences will be tallied).

CHARACTERS

When CHARACTERS is specified and neither the BEFORE nor AFTER phrase is specified, the count field (identifier-2) is increased by 1 for each character (including the space character) in the inspected item (identifier-1). Thus, execution of an INSPECT statement with the TALLYING phrase increases the value in the count field by the number of character positions in the inspected item.

ALL

When ALL is specified and neither the BEFORE nor AFTER phrase is specified, the count field (identifier-2) is increased by 1 for each nonoverlapping occurrence of the tallying comparand (identifier-3 or literal-1) in the inspected item (identifier-1), beginning at the leftmost character position and continuing to the rightmost.

LEADING

When LEADING is specified and neither the BEFORE nor AFTER phrase is specified, the count field (identifier-2) is increased by 1 for each contiguous nonoverlapping occurrence of the tallying comparand in the inspected item (identifier-1), provided that the leftmost such occurrence is at the point where comparison began in the first comparison cycle for which the tallying comparand is eligible to participate.

FIRST (format 3 only)

When FIRST is specified and neither the BEFORE nor AFTER phrase is specified, the substitution field replaces the leftmost occurrence of the subject field in the inspected item (identifier-1).

Start of change TALLYING phrase example End of change

WORKING-STORAGE SECTION.
77 CNTR PIC 9(3) COMP.
77 CHARS PIC X(18).
PROCEDURE DIVISION.
...........
     MOVE 'In order to form a' To CHARS         
     MOVE 0 To CNTR                             
     INSPECT CHARS TALLYING CNTR FOR ALL SPACES 
     DISPLAY 'Number of spaces = ' CNTR

The example output:

Number of spaces = 004

REPLACING phrase (formats 2 and 3)

This phrase fills all or portions of a data item with specified characters, such as spaces or zeros.

identifier-3 or literal-1: Is the subject field, which identifies the characters to be replaced.
identifier-5 or literal-3: Is the substitution field (the item that replaces the subject field).
The subject field and the substitution field must be the same length.
CHARACTERS BY: When the CHARACTERS BY phrase is used, the substitution field must be one character position in length.
When CHARACTERS BY is specified and neither the BEFORE nor AFTER phrase is specified, the substitution field replaces each character in the inspected item (identifier-1), beginning at the leftmost character position and continuing to the rightmost.
ALL: When ALL is specified and neither the BEFORE nor AFTER phrase is specified, the substitution field replaces each nonoverlapping occurrence of the subject field in the inspected item (identifier-1), beginning at the leftmost character position and continuing to the rightmost.
LEADING: When LEADING is specified and neither the BEFORE nor AFTER phrase is specified, the substitution field replaces each contiguous nonoverlapping occurrence of the subject field in the inspected item (identifier-1), provided that the leftmost such occurrence is at the point where comparison began in the first comparison cycle for which this substitution field is eligible to participate.
FIRST: When FIRST is specified and neither the BEFORE nor AFTER phrase is specified, the substitution field replaces the leftmost occurrence of the subject field in the inspected item (identifier-1).

When both the TALLYING and REPLACING phrases are specified (format 3), the INSPECT statement is executed as if an INSPECT TALLYING statement (format 1) were specified, immediately followed by an INSPECT REPLACING statement (format 2).

The following replacement rules apply:

When the subject field is a figurative constant, the one-character substitution field replaces each character in the inspected item that is equivalent to the figurative constant.
When the substitution field is a figurative constant, the substitution field replaces each nonoverlapping occurrence of the subject field in the inspected item.
When the subject and substitution fields are character-strings, the character-string specified in the substitution field replaces each nonoverlapping occurrence of the subject field in the inspected item.
After replacement has occurred in a given character position in the inspected item, no further replacement for that character position is made in this execution of the INSPECT statement.

Start of change REPLACING phrase example End of change

WORKING-STORAGE SECTION.
77 CNTR PIC 9(3) COMP.
77 CHARS PIC X(18).
PROCEDURE DIVISION.
  . . .
      MOVE 'more,perfect,union' To CHARS         
      MOVE 0 To CNTR                             

      INSPECT CHARS TALLYING CNTR FOR ALL ','    
        REPLACING ALL ',' BY SPACES             

      DISPLAY 'Number of commas replaced = ' CNTR
      DISPLAY 'CHARS is now = ' CHARS

The example result:

Number of commas replaced = 002
CHARS is now = more perfect union

BEFORE and AFTER phrases (all formats)

This phrase narrows the set of items being tallied or replaced.

No more than one BEFORE phrase and one AFTER phrase can be specified for any one ALL, LEADING, CHARACTERS, FIRST or CONVERTING phrase.

identifier-4 or literal-2: Is the delimiter.
Delimiters are not counted or replaced.
INITIAL: The first occurrence of a specified item.

The BEFORE and AFTER phrases change how counting and replacing are done:

When BEFORE is specified, counting or replacing of the inspected item (identifier-1) begins at the leftmost character position and continues until the first occurrence of the delimiter is encountered. If no delimiter is present in the inspected item, counting or replacing continues toward the rightmost character position.
When AFTER is specified, counting or replacing of the inspected item (identifier-1) begins with the first character position to the right of the delimiter and continues toward the rightmost character position in the inspected item. If no delimiter is present in the inspected item, no counting or replacement takes place.

BEFORE and AFTER phrases example

WORKING-STORAGE SECTION.                                       
77 CNTR1 PIC 9(3) COMP.                                         
77 CNTR2 PIC 9(3) COMP.                                         
77 CNTR3 PIC 9(3) COMP.                                         
77 CHARS PIC X(50).                                             
                                                               
PROCEDURE DIVISION.                                             
                                                                
     MOVE '$some.confusing_text with.hyphens-periods.spaces'    
         To CHARS                                               
     MOVE 0 To CNTR1 CNTR2 CNTR3                                
     INSPECT CHARS                                              
        TALLYING CNTR1 FOR CHARACTERS AFTER '$' BEFORE '_'      
                 CNTR2 FOR ALL '.' AFTER  'h'                   
                 CNTR3 FOR ALL '.' BEFORE INITIAL 'a'           
        REPLACING ALL '.' BY SPACES BEFORE 'h'                  
                  ALL '"' BY SPACES AFTER  's'                  
                  ALL '_' BY SPACES                             
     DISPLAY 'Number of characters after $ and before _  =' CNTR1
     DISPLAY 'Number of periods after h =' CNTR2                
     DISPLAY 'Number of periods before initial a =' CNTR3       
     DISPLAY 'CHARS is now = ' CHARS

The example result:

Note: For each BEFORE and AFTER phrase, the scanning continues after the previous phrase is done rather than starting at the beginning of CHARS.

Number of characters after $ and before _  =014               
Number of periods after h =002                                
Number of periods before initial a =000                       
CHARS is now = $some confusing text with.hyphens-periods.spaces

CONVERTING phrase (format 4)

This phrase converts all occurrences of a specific character or string of characters in a data item (identifier-1) to user-supplied replacement characters.

identifier-6 or literal-4: Specifies the character string to be replaced.
The same character must not appear more than once in either literal-4 or identifier-6.
identifier-7 or literal-5: Specifies the replacing character string.
The replacing character string (identifier-7 or literal-5) must be the same size as the replaced character string (identifier-6 or literal-4).

A format-4 INSPECT statement is interpreted and executed as if a format-2 INSPECT statement had been written with a series of ALL phrases (one for each character of literal-4), specifying the same identifier-1. The effect is as if each single character of literal-4 were referenced as literal-1, and the corresponding single character of literal-5 referenced as literal-3. Correspondence between the characters of literal-4 and the characters of literal-5 is by ordinal position within the data item.

If identifier-4, identifier-6, or identifier-7 occupies the same storage area as identifier-1, the result of the execution of this statement is undefined, even if they are defined by the same data description entry.

The following table describes the treatment of data items that can be used as an operand in the INSPECT statement:

Table 1. **Treatment of the content of data items**
When referenced by any identifier except `identifier-2`, the content of each item of category ...	Is treated ...
Alphanumeric or alphabetic	As an alphanumeric character string
DBCS	As a DBCS character string
National	As a national character string
Alphanumeric-edited, numeric-edited with usage DISPLAY, or numeric with usage DISPLAY (unsigned, external decimal)	As if redefined as category alphanumeric, with the INSPECT statement referring to an alphanumeric character string
National-edited, numeric-edited with usage NATIONAL or numeric with usage NATIONAL (unsigned, external decimal)	As if redefined as category national, with the INSPECT statement referring to a national character string
Numeric with usage DISPLAY (signed, external decimal)	As if moved to an unsigned external decimal item of usage DISPLAY with the same length as the identifier and then redefined as category alphanumeric, with the INSPECT statement referring to an alphanumeric character string If the sign is a separate character, the byte containing the sign is not examined and, therefore, not replaced. If the referenced item is `identifier-1`, the string that results from any replacing or converting action is copied back to `identifier-1`.
Numeric with usage NATIONAL (signed, external decimal)	As if moved to an unsigned external decimal item of usage NATIONAL with the same length as the identifier and then redefined as category national, with the INSPECT statement referring to a national character string If the sign is a separate character, the byte containing the sign is not examined and, therefore, not replaced. If the referenced item is `identifier-1`, the string that results from any replacing or converting action is copied back to `identifier-1`.
External floating-point with usage DISPLAY	As if redefined as category alphanumeric, with the INSPECT statement referring to an alphanumeric character-string
External floating-point with usage NATIONAL	As if redefined as category national, with the INSPECT statement referring to a national character-string

Start of change CONVERTING phrase example End of change

The following example shows the use of INSPECT CONVERTING with AFTER and BEFORE phrases to examine and replace characters in data item DATA-4. All characters that follow the first instance of the character / but that precede the first instance of the character ? (if any) are translated from lowercase to uppercase.

01  DATA-4            PIC X(11).
. . .
    INSPECT DATA-4
      CONVERTING
         "abcdefghijklmnopqrstuvwxyz" TO
         "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
      AFTER INITIAL "/"
      BEFORE INITIAL "?"

Table 2. CONVERTING example result
DATA-4 before converting	DATA-4 after converting
a/five/?six	a/FIVE/?six
r/Rexx/RRRr	r/REXX/RRRR
zfour?inspe	zfour?inspe