EXAMINE statement

The EXAMINE statement is used to count the number of occurrences of a given character in a data item. HP e3000 COBOL's EXAMINE statement duplicates some of the functionality of the ACUCOBOL-GT Format 1 INSPECT statement, but with slightly different syntax. (See Book 3, Reference Manual, section 6.6, "Procedure Division Statements," for a detailed discussion of the INSPECT Statement.) ACUCOBOL-GT accepts the EXAMINE statement in the HP e3000 COBOL compatibility mode.

Format 1

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

Format 2

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

Syntax Rules

1. identifier-1 is the name of a data item containing characters to be counted or replaced. Its USAGE must be DISPLAY (implicitly or explicitly).

2. 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.

General Rules

1. The number of characters in Format 1 that obey certain conditions are counted by a special register named TALLY. Its PICTURE is 9(5) and USAGE is COMP-N. Its default value is zero.

2. 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 and/or replace all instances of literal-1 with literal-2.
FIRST
Replace the first (leftmost) instance of literal-1 with literal-2.
LEADING
Count and/or replace all instances of literal-1 that appear before (to the left of) any other character in the data item.
UNTIL FIRST
Count and/or replace all characters to the left of the first (leftmost) instance of literal-1 with literal-2. If literal-1 does not appear in the data item, count and replace all characters in the data item.

3. Literal-1 is the character to be counted. Literal-2 is the character that will replace literal-1. Note that the substitution of literal-2 for characters other than literal-1 occurs only when UNTIL FIRST is specified.

4. 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 and/or replace all instances of literal-1 with literal-2.
FIRST	Replace the first (leftmost) instance of literal-1 with literal-2.
LEADING	Count and/or replace all instances of literal-1 that appear before (to the left of) any other character in the data item.
UNTIL FIRST	Count and/or replace all characters to the left of the first (leftmost) instance of literal-1 with literal-2. If literal-1 does not appear in the data item, count and replace all characters in the data item.