The INSPECT statement examines characters or groups of characters in a data item and does the following:
Format 1: INSPECT statement with TALLYING phrase >>-INSPECT--identifier-1--TALLYING------------------------------> .--------------------------------------------------------------------------------. | .---------------------------------------------------------. | | | .--------------. | | V V V | | | >----identifier-2--FOR----+-CHARACTERS----| phrase 1 |-+------------------------+-+-+->< | .------------------------------------. | | | .--------------. | | | V V | | | '-+-ALL-----+----+-identifier-3-+----| phrase 1 |-+-+-' '-LEADING-' '-literal-1----' phrase 1 |--+-BEFORE-+--+---------+--+-identifier-4-+--------------------| '-AFTER--' '-INITIAL-' '-literal-2----'
Format 2: INSPECT statement with REPLACING phrase >>-INSPECT--identifier-1--REPLACING-----------------------------> .-------------------------------------------------------------------------------. | .--------------. | V V | | >----+-CHARACTERS BY--+-identifier-5-+----| phrase 1 |-+-------------------------+-+->< | '-literal-3----' | | .----------------------------------------------------------. | | | .--------------. | | | V V | | | '-+-ALL-----+----+-identifier-3-+--BY--+-identifier-5-+----| phrase 1 |-+-+-' +-LEADING-+ '-literal-1----' '-literal-3----' '-FIRST---' phrase 1 |--+-BEFORE-+--+---------+--+-identifier-4-+--------------------| '-AFTER--' '-INITIAL-' '-literal-2----'
Format 3: INSPECT statement with TALLYING and REPLACING phrases >>-INSPECT--identifier-1--TALLYING------------------------------> .--------------------------------------------------------------------------------. | .---------------------------------------------------------. | | | .--------------. | | V V V | | | >----identifier-2--FOR----+-CHARACTERS----| phrase 1 |-+------------------------+-+-+--> | .------------------------------------. | | | .--------------. | | | V V | | | '-+-ALL-----+----+-identifier-3-+----| phrase 1 |-+-+-' '-LEADING-' '-literal-1----' >--REPLACING----------------------------------------------------> .-------------------------------------------------------------------------------. | .--------------. | V V | | >----+-CHARACTERS BY--+-identifier-5-+----| phrase 1 |-+-------------------------+-+->< | '-literal-3----' | | .----------------------------------------------------------. | | | .--------------. | | | V V | | | '-+-ALL-----+----+-identifier-3-+--BY--+-identifier-5-+----| phrase 1 |-+-+-' +-LEADING-+ '-literal-1----' '-literal-3----' '-FIRST---' phrase 1 |--+-BEFORE-+--+---------+--+-identifier-4-+--------------------| '-AFTER--' '-INITIAL-' '-literal-2----'
Format 4: INSPECT statement with CONVERTING phrase >>-INSPECT--identifier-1--CONVERTING--+-identifier-6-+--TO------> '-literal-4----' >--+-identifier-7-+---------------------------------------------> '-literal-5----' .-------------------------------------------. V | >----+-BEFORE-+--+---------+--+-identifier-4-+-+--------------->< '-AFTER--' '-INITIAL-' '-literal-2----'
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.
None of the identifiers in an INSPECT statement can be windowed date fields.
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 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.
This phrase fills all or portions of a data item with specified characters, such as spaces or zeros.
The subject field and the substitution field must be the same 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.
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:
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.
Delimiters are not counted or replaced.
The BEFORE and AFTER phrases change how counting and replacing are done:
This phrase converts all occurrences of a specific character or string of characters in a data item (identifier-1) to user-supplied replacement characters.
The same character must not appear more than once in either literal-4 or identifier-6.
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:
| 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 |
Except when the BEFORE or AFTER phrase is specified, inspection begins at the leftmost character position of the inspected item (identifier-1) and proceeds character-by-character to the rightmost position.
The comparands of the following phrases are compared in the left-to-right order in which they are specified in the INSPECT statement:
If any identifier is subscripted or reference modified, or is a function-identifier, the subscript, reference-modifier, or function is evaluated only once as the first operation in the execution of the INSPECT statement.
For examples of TALLYING and REPLACING, see the Enterprise COBOL Programming Guide.
The comparison cycle consists of the following actions:
If the CHARACTERS phrase is specified, an implied one-character comparand is used. The implied character is always considered to match the inspected character in the inspected item.
If there are more character positions in the inspected item, the first character position following the rightmost matching character is now considered to be in the leftmost character position. The process described in actions 1 and 2 is then repeated.
When the BEFORE or AFTER phrase is specified, the comparison cycle is modified, as described in BEFORE and AFTER phrases (all formats).