Micro Focus Visual COBOL 2.3 Update 2 for Eclipse (Windows) > General Reference > COBOL Language Reference > Part 2. Program Definition > Procedure Division > Statements > The INSPECT Statement

The INSPECT Statement

The INSPECT statement provides the ability to tally (Format 1), replace (Format 2), tally and replace (Format 3) , convert (Format 4) and tally trailing (Format 5).

General Formats for Format 1

General Formats for Format 2

General Formats for Format 3

General Formats for Format 4

General Formats for Format 5

Syntax Rules for All Formats

Identifier-1 must reference either a group item or any category of elementary item, described (either implicitly or explicitly) as USAGE IS DISPLAY.
Identifier-3 ... identifier-n must reference
either a group item or

an elementary alphabetic, alphanumeric,

alphanumeric edited, numeric edited

or numeric item described (either implicitly or explicitly) as USAGE IS DISPLAY.
Each literal must be nonnumeric and can be any figurative constant, except ALL. If literal-1, literal-2 or literal-4 is a figurative constant, it refers to an implicit one-character data item.
No more than one BEFORE phrase
and /;

or one AFTER phrase can be specified for any one ALL, LEADING, CHARACTERS, FIRST

or CONVERTING

phrase.
Literal-1, literal-2, literal-3, literal-4, and literal-5, and the data items referenced by identifier-3, identifier-4, identifier-5, identifier-6, and identifier-7 can be any number of characters in length up to the limit allowed for literals or data items.
All identifiers, except identifier-2 (the TALLYING field), can be external floating-point items. External floating-point items are treated as if redefined as alphanumeric with the INSPECT statement referring to the alphanumeric item.

Syntax Rules for Formats 1 and 3

Identifier-2 must reference an elementary numeric data item.

Syntax Rules for Formats 2 and 3

The size of the data referenced by literal-3 or identifier-5 must be equal to the size of the data referenced by literal-1 or identifier-3. When a figurative constant is used as literal-3, the size of the figurative constant is equal to the size of literal-1 or the size of the data item referenced by identifier-3.
When the CHARACTERS phrase is used, literal-3 or the size of the data item referenced by identifier-5 must be one character in length.
This restriction does not apply to literal-2 or identifier-4.

Syntax Rules for Format 4

The size of literal-5 or the data item referenced by identifier-7 must be equal to the size of literal-4 or the data item referenced by identifier-6. When a figurative constant is used as literal-5, the size of the figurative constant is equal to the size of literal-4 or the size of the data item referenced by identifier-6.
The same character must not appear more than once either in literal-4 or in the data item referenced by identifier-6.

General Rules for All Formats

For the purpose of determining its length, identifier-1 is treated as if it were a sending data item. (See the topic The OCCURS Clause.)
Inspection (which includes the comparison cycle, the establishment of boundaries for the BEFORE or AFTER phrase, and the mechanism for tallying and/or replacing) begins at the leftmost character position of the data item referenced by identifier-1, regardless of its class, and proceeds from left to right to the rightmost character position as described in General Rules 11, 12 and 13.
For use in the INSPECT statement, the contents of the data item referenced by identifier-1, identifier-3, identifier-4, identifier-5, identifier-6 or identifier-7 is treated as follows:
1. If any of identifier-1, identifier-3, identifier-4, identifier-5, identifier-6 or identifier-7 is described as alphanumeric, the INSPECT statement treats the contents of each such identifier as a character-string.
2. If any of identifier-1, identifier-3, identifier-4, identifier-5, identifier-6 or identifier-7 is described as alphanumeric edited, numeric edited or unsigned numeric, the data item is inspected as though it had been redefined as alphanumeric (see General Rule 3a.) and the INSPECT statement had been written to reference the redefined data item.
3. If any of identifier-1, identifier-3, identifier-4, identifier-5, identifier-6 or identifier-7 is described as signed numeric, the data item is inspected as though it had been moved to an unsigned numeric data item with length equal to the length of the signed item excluding any separate sign position and then the rules in General Rule 3b had been applied. (See the topic The MOVE Statement.)
In General Rules 6 through 19, all references to literal-1, literal-2, literal-3, literal-4, and literal-5 apply equally to the contents of the data item referenced by identifier-3, identifier-4, identifier-5, identifier-6, and identifier-7, respectively.
If any identifier is subscripted
or is a function-identifier

, the subscript

or function-identifier

is evaluated only once as the first operation in the execution of the INSPECT statement.

General Rules for Format 1

Identifier-1 is a sending data item.
The required words ALL and LEADING are adjectives that apply to each succeeding literal-1 until the next adjective appears.
The contents of the data item referenced by identifier-2 are not initialized by the execution of the INSPECT statement.
The rules for tallying are as follows:
1. If the ALL phrase is specified, the contents of the data item referenced by identifier-2 are incremented by one for each occurrence of literal-1 matched in the contents of the data item referenced by identifier-1.
2. If the LEADING phrase is specified, the contents of the data item referenced by identifier-2 are incremented by one for the first and each subsequent contiguous occurrence of literal-1 matched in the contents of the data item referenced by identifier-1, provided that the leftmost such occurrence is at the point where comparison began in the first comparison cycle in which literal-1 was eligible to participate.
3. If the CHARACTERS phrase is specified, the contents of the data item referenced by identifier-2 are incremented by one for each character matched, in the sense of Format 1 and 2, General Rule 12e, in the contents of the data item referenced by identifier-1.
If identifier-1, identifier-3 or identifier-4 occupies the same storage area as identifier-2, the result of the execution of this statement is undefined, even if they are defined by the same data description entry. (See the topic Overlapping Operands.)

General Rules for Formats 1 and 2

During inspection of the contents of the data item referenced by identifier-1, each properly matched occurrence of literal-1 is tallied (Format 1) or replaced by literal-3 (Format 2).
The comparison operation to determine the occurrences of literal-1 to be tallied or to be replaced, occurs as follows:
1. The operands of the TALLYING or REPLACING phrases are considered in the order they are specified in the INSPECT statement from left to right. The first literal-1 is compared to an equal number of contiguous characters, starting with the leftmost character position in the data item referenced by identifier-1. Literal-1 matches that portion of the contents of the data item referenced by identifier-1 if, and only if, they are equal, character for character, and if one of the following is true:
  1. If neither LEADING nor FIRST is specified:
  2. If the LEADING adjective applies to literal-1 and literal-1 is a leading occurrence as defined in General Rules 9 and 15:
  3. If the FIRST adjective applies to literal-1 and literal-1 is the first occurrence as defined in General Rule 9.
2. If no match occurs in the comparison of the first literal-1, the comparison is repeated with each successive literal-1, if any, until either a match is found or there is no next successive literal-1. When there is no next successive literal-1, the character position in the data item referenced by identifier-1 immediately to the right of the leftmost character position considered in the last comparison cycle is considered as the leftmost character position, and the comparison cycle begins again with the first literal-1.
3. Whenever a match occurs, tallying and/or replacing takes place as described in General Rules 9 and 15. The character position in the data item referenced by identifier-1 immediately to the right of the rightmost character position that participated in the match is now considered to be the leftmost character position of the data item referenced by identifier-1, and the comparison cycle starts again with the first literal-1.
4. The comparison operation continues until the rightmost character position of the data item referenced by identifier-1 has participated in a match or has been considered as the leftmost character position. When this occurs, inspection is terminated.
5. If the CHARACTERS phrase is specified, an implied one-character operand participates in the cycle described in paragraphs 12a through 12d above, except that no comparison to the contents of the data item referenced by identifier-1 takes place. This implied character is considered always to match the leftmost character of the contents of the data item referenced by identifier-1 participating in the current comparison cycle.
The comparison operation defined in General Rule 12 is affected by the BEFORE and AFTER phrases as follows:
1. If neither the BEFORE nor the AFTER phrase is specified, literal-1 or the implied operand of the CHARACTERS phrase is first eligible to participate in matching at the leftmost character position of identifier-1.
2. If the BEFORE phrase is specified, the associated literal-1, or the implied operand of the CHARACTERS phrase participates only in those comparison cycles which involve that portion of the contents of the data item referenced by identifier-1 from its leftmost character position up to, but not including, the first occurrence of literal-2, in the contents of the data item referenced by identifier-1.
  The position of this first occurrence is determined before the first cycle of the comparison operation described in General Rule 12 is begun. If, on any comparison cycle, literal-1, or the implied operand of the CHARACTERS phrase is not eligible to participate, it is considered not to match the contents of the data item referenced by identifier-1. If there is no occurrence of literal-2, in the contents of the data item referenced by identifier-1, its associated literal-1, or the implied operand of the CHARACTERS phrase participates in the comparison operation as though the BEFORE phrase had not been specified.
3. If the AFTER phrase is specified, the associated literal-1, or the implied operand of the CHARACTERS phrase can participate only in those comparison cycles which involve that portion of the contents of the data item referenced by identifier-1 from the character position immediately to the right of the rightmost character position of the first occurrence of literal-2, in the contents of the data item referenced by identifier-1 to the rightmost character position of the data item referenced by identifier-1.
  The position of this first occurrence is determined before the first cycle of the comparison operation described in General Rule 12 is begun. If, on any comparison cycle, literal-1, or the implied operand of the CHARACTERS phrase is not eligible to participate, it is considered not to match the contents of the data item referenced by identifier-1. If there is no occurrence of literal-2, in the contents of the data item referenced by identifier-1, its associated literal-1, or the implied operand of the CHARACTERS phrase is never eligible to participate in the comparison operation.

General Rules for Format 2

The required words ALL, LEADING and FIRST are adjectives that apply to each succeeding BY phrase until the next adjective appears.
The rules for replacement are as follows:
1. When the CHARACTERS phrase is specified, each character matched in the sense of Format 1 and 2, General Rule 12e in the contents of the data item referenced by identifier-1, is replaced by literal-3.
2. When the adjective ALL is specified, each occurrence of literal-1 matched in the contents of the data item referenced by identifier-1 is replaced by literal-3.
3. When the adjective LEADING is specified, the first and each subsequent contiguous occurrence of literal-1 matched in the contents of the data item referenced by identifier-1 is replaced by literal-3, provided that the leftmost occurrence is at the point where comparison began in the first comparison cycle in which literal-1 was eligible to participate.
4. When the adjective FIRST is specified, the leftmost occurrence of literal-1 matched in the contents of the data item referenced by identifier-1 is replaced by literal-3.
If identifier-3, identifier-4 or identifier-5 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. (See the topic Overlapping Operands.)

General Rules for Format 3

A Format 3 INSPECT statement is interpreted and executed as though two successive INSPECT statements specifying the same identifier-1 had been written with one statement being a Format 1 statement with TALLYING phrases identical to those specified in the Format 3 statement, and the other statement being a Format 2 statement with REPLACING phrases identical to those specified in the Format 3 statement. The General Rules given for matching and counting apply to the Format 1 statement and the General Rules given for matching and replacing apply to the Format 2 statement.

General Rules for Format 4

A Format 4 INSPECT statement is interpreted and executed as though a Format 2 INSPECT statement specifying the same identifier-1 had been written with a series of ALL phrases, one for each character of literal-4. The effect is as if each of these ALL phrases referenced, as literal-1, a single character of literal-4 and referenced, as literal-3, the corresponding single character of literal-5. 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.

General Rules for Format 5

TRAILING is an MF extension, used to find the rightmost occurrence or set of contiguous occurrences in a source data item.
If a TRAILING occurrence is found, a right to left scan of the source data item is made to find contiguous occurrences.
The REPLACING option enables you to replace all contiguous occurrences.
The following items must be single-character items: identifier-3, identifier-4, identifier-5, literal-1, literal-2 and literal-3.

Examples

Examples of using INSPECT TALLYING, REPLACING, and CONVERTING are provided in the topic INSPECT Statement (Tallying, Replacing, and Converting).