action.skip

INSPECT Statement

The INSPECT statement provides TALLYING, REPLACING, and CONVERTING functions for counting and modifying elements in character strings within a program.

Format 1

       inspect identifier-1 
       [ tallying tallying-phrase   ] 
       [ replacing replacing-phrase ] 
       [ after-before-phrase        ]

Format 2

       inspect identifier-1 
       [converting converting-phrase ] 
       [after-before-phrase ]

Syntax:

identifier-n is a data element, literal, or data returned from a function call.

Tallying phrase format

       tallying numeric-data-1 for [ CHARACTERS ] 
                                   [ { ALL      }
                                     { LEADING  } identifier-2 ] 
                                     { FIRST    } 
                                     { TRAILING }

Syntax:

  1. numeric-data-n is a numeric data item.
  2. identifier-n is a data element, literal, or data returned from a function call.

General Rules:

  1. The TALLYING clause is designed to count the number of CHARACTERS, or the iterations of a character string found in identifier-1, or in a subset of the characters in identifier-1 as defined by the after before clause.
  2. The CHARACTERS phrase causes a simple count of the number of characters in the named identifier to be tallied, and stored in numeric-data-1.
  3. The ALL phrase causes a count of the number of iterations of identifier-2 in the named identifier to be tallied, and stored in numeric-data-1.
  4. The LEADING phrase causes a count of the number of contiguous iterations of identifier-2 , starting at the left most position in the named identifier.
  5. The FIRST phrase causes numeric-data-1 to be incremented if/when the first iteration of identifier-2 is located in the named identifier.
  6. The TRAILING phrase causes a count of the number of contiguous iterations of identifier-2, starting at the right-most position in the named identifier, and parsing from right to left.

    Replacing phrase format:
       replacing [ CHARACTERS ] 
                 [ { ALL      } 
                   { LEADING  } identifier-3 ] BY identifier-4 
                   { FIRST    } 
                   { TRAILING }

Syntax:

identifier-n is a data element, literal, or data returned from a function call.

General Rules:

  1. The REPLACING clause is designed to identify a string of characters in identifier-1 or in a subset of the characters in identifier-1 as defined by the after before clause, and replace them with an alternative string of characters of the same size.
  2. The CHARACTERS phrase causes every character in identifier-1 to be replaced by identifier-4 . When using the CHARACTERS phrase, identifier-3 is an alphanumeric data item that is a single character.
  3. The ALL phrase causes all instances of identifier-3 inside identifier-1 to be replaced by identifier-4.
  4. The LEADING phrase causes all contiguous iterations of identifier-3 inside identifier-1, starting at the left most position in identifier-1 to be replaced by identifier-4.
  5. The FIRST phrase causes the first iteration of identifier-3 to be replaced by identifier-4.
  6. The TRAILING phrase causes all contiguous iterations of identifier-3 inside identifier-1, starting at the right most position in the named identifier, and parsing from right to left, to be replaced with identifier-4
  7. Note that when using the ALL, LEADING, FIRST, and TRAILING phrases, identifier-3 and identifier-4 must be strings of the same length.

    after-before phrase format:
       [ { BEFORE } INITIAL identifier-5 ] 
         { AFTER  }

Syntax:

identifier-n is a data element, literal, or data returned from a function call.

General Rules:

  1. The optional AFTER-BEFORE phrase specifies the end-point or beginning-point in the named identifier that will be parsed in the INSPECT statement.
  2. The BEFORE phrase causes the INSPECT/TALLYING/REPLACING statement to locate a parsing end point in the named identifier. Parsing begins at the first byte of the named identifier, and ends when the string named in identifier-5 is located.
  3. The AFTER phrase causes the INSPECT/TALLYING/REPLACING statement to locate a parsing beginning point in the named identifier. The named identifier is scanned from right to left. If an identifier-5 is located, it marks the parsing beginning-point, and parsing continues to the end of the identifier.

    CONVERTING phrase format:
       [converting identifier-2 TO identifier-3] 
       [ after-before-phrase                   ]

Syntax:

identifier-n is a data element, literal, or data returned from a function call.

General Rules:

  1. The CONVERTING phrase dictates a conversion of characters within identifier-1 according to rules established by the ordinal positions of characters in identifier-2 and identifier-3. To clarify with an example, the statement:
  2. INSPECT identifier-1 CONVERTING “AB ” TO “CD” causes every instance of “A” in identifier-1 (the first character in identifier-2), to be converted to “C” (the first character in identifier-3), and causes every instance of “B” in identifier-1 (the second character in identifier-2) to be replaced by “D” (the second character in identifier-3).
  3. To further clarify, INSPECT CONVERTING is commonly used to convert lower-case characters to upper-case, as follows:

    INSPECT identifier-1 CONVERTING “abcdefghijklmnopqrstuvwxyz” to “ABCDEFGHIJKLMNOPQRSTUVWXYZ”.

    The effect of this statement is to convert every lower case letter in identifier-1 to its corresponding upper-case letter.

    after-before phrase format:
       [ { BEFORE } INITIAL identifier-5 ] 
         { AFTER  }

Syntax:

identifier-n is a data element, literal, or data returned from a function call.

General Rules:

  1. The optional AFTER-BEFORE phrase specifies the end point or beginning point in the named identifier that will be parsed in the INSPECT statement.
  2. The BEFORE phrase causes the INSPECT/CONVERTING statement to locate a parsing end-point in the named identifier. Parsing begins at the first byte of the named identifier, and ends when the string named in identifier-6 is located .
  3. The AFTER phrase cases the INSPECT/CONVERTING statement to locate a parsing beginning-point in the named identifier. The named identifier is scanned from right to left. If an identifier-6 is located, it marks the parsing beginning-point, and parsing continues to the end of the identifier.

Code Sample:

       IDENTIFICATION DIVISION. 
       PROGRAM-ID. INSPECT-1. 
       ENVIRONMENT DIVISION. 
       DATA DIVISION. 
       WORKING-STORAGE SECTION. 
       77 TALLY-CTR1 PIC 99 VALUE 0. 
       77 STRING-1 PIC X(10) VALUE "COBOL-IT". 
       77 STRING-2 PIC X(20) VALUE "OPEN SOURCE COBOL". 
       77 STRING-3 PIC X(42) 
              VALUE "A QUICK BROWN FOX JUMPED OVER THE LAZY DOG". 
       77 DUMMY PIC X. 
       PROCEDURE DIVISION. 
       MAIN. 
              INSPECT STRING-1 TALLYING TALLY-CTR1 FOR ALL "O". 
              DISPLAY "THERE ARE " TALLY-CTR1 " O'S IN " STRING-1 
                     LINE 5 COL 10.
                     INSPECT STRING-2 REPLACING ALL "E" BY "-". 
                     DISPLAY STRING-2 LINE 6 COL 10. 

                     INITIALIZE TALLY-CTR1. 
                     INSPECT STRING-2 TALLYING TALLY-CTR1 FOR ALL "O" 
                            REPLACING ALL "S" BY "+". 
                     DISPLAY STRING-2 LINE 7 COL 10. 
                     DISPLAY "THERE ARE " TALLY-CTR1 " O'S IN " STRING-2 
                            LINE 8 COL 10. 

                     DISPLAY STRING-3 LINE 10 COL 10. 
                     DISPLAY "CONVERTING TO UPPER-CASE...." LINE 11 COL 10. 
                     INSPECT STRING-3 CONVERTING 
                            "ABCDEFGHIJKLMNOPQRSTUVWXYZ" TO 
                            "abcdefghijklmnopqrstuvwxyz". 

                     DISPLAY STRING-3 LINE 12 COL 10. 

                     DISPLAY "INSPECT-1 FINISHED!" LINE 15 COL 10. 
                     ACCEPT DUMMY LINE 15 COL 30. 
                     STOP RUN.