EXAMINE

IBM DOS/VS COBOL has an EXAMINE statement, which duplicates some of the functionality of the ACUCOBOL-GT INSPECT statement, but with slightly different syntax. ACUCOBOL-GT accepts this statement in the IBM DOS/VS COBOL compatibility mode.

Format 1 of the EXAMINE statement is as follows:

EXAMINE identifier-1 TALLYING {ALL        } literal-1 [REPLACING BY literal-2]
                              {LEADING    }
                              {UNTIL FIRST}

Format 2 is:

EXAMINE identifier-1 REPLACING {ALL        } literal-1 BY literal-2
                               {FIRST      }
                               {LEADING    }
                               {UNTIL FIRST}

Here identifier-1 is the name of a data item containing characters to be counted or replaced. Its USAGE must be DISPLAY (implicitly or explicitly). Each literal is a single-character literal or one of the following figurative literals:

ZERO

ZEROS

ZEROES

SPACE

SPACES

QUOTE

QUOTES

LOW-VALUE

LOW-VALUES

HIGH-VALUE

HIGH-VALUES

ACUCOBOL-GT does not enforce the one-character limitation. If a string literal has two or more characters, it uses only the first character.

The special register TALLY, whose PICTURE is 9(5) and whose USAGE is
COMP-N, counts the number of characters in Format 1 which obey certain conditions.

The characters to be counted and replaced are determined by the key words following TALLYING or REPLACING. Counting is done only in Format 1, and replacement is done only in Format 2 and when specified in Format 1.

Key Words
Characters To Be Counted And Replaced
ALL
Count all instances of literal-1 in the data item and replace them with literal-2.
FIRST
Replace the first (leftmost) instance of literal-1 in the data item to literal-2.
LEADING
Count the instances of literal-1 in the data item which appear before (to the left of) any other character in the data item, and replace them with literal-2.
UNTIL FIRST
Count the characters to the left of the first (leftmost) instance of literal-1 and replace them with literal-2. If literal-1 does not appear in the data item, count and replace all characters in the data item.

It should be noted that the substitution of literal-2 for characters other than literal-1 occurs only in the last case.

The contents of the TALLY register are unchanged in Format 2. In Format 1, its contents are replaced by the appropriate character count, regardless of the previous contents.

Key Words	Characters To Be Counted And Replaced
ALL	Count all instances of literal-1 in the data item and replace them with literal-2.
FIRST	Replace the first (leftmost) instance of literal-1 in the data item to literal-2.
LEADING	Count the instances of literal-1 in the data item which appear before (to the left of) any other character in the data item, and replace them with literal-2.
UNTIL FIRST	Count the characters to the left of the first (leftmost) instance of literal-1 and replace them with literal-2. If literal-1 does not appear in the data item, count and replace all characters in the data item.