INSPECT statement
The INSPECT statement examines characters or groups of characters in a data
item and does the following:
- Counts the occurrences of a specific character (alphanumeric, DBCS, or
national) in a data item (formats 1 and 3).
- Counts the occurrences of specific characters and fills all or portions of
a data item with specified characters, such as spaces or zeros (formats 2
and 3).
- Converts all occurrences of specific characters in a data item to
user-supplied replacement characters (format 4).
| Format 1 |
 >>-INSPECT--identifier-1--TALLYING------------------------------>
.------------------------------------------------------------------------------------.
| .-------------------------------------------------------------. |
| | .------------------. | |
V V V | | |
>----identifier-2--FOR----+-CHARACTERS----+--------------+-+------------------------+-+-+-><
| '-| phrase 1 |-' |
| .----------------------------------------. |
| | .------------------. | |
| V V | | |
'-+-ALL-----+----+-identifier-3-+----+--------------+-+-+-'
'-LEADING-' '-literal-1----' '-| phrase 1 |-'
phrase 1:
|--+-BEFORE-+--+---------+--+-identifier-4-+--------------------|
'-AFTER--' '-INITIAL-' '-literal-2----'
|
| Format 2 |
 >>-INSPECT--identifier-1--REPLACING----------------------------->
.-----------------------------------------------------------------------------------.
| .------------------. |
V V | |
>----+-CHARACTERS BY--+-identifier-5-+----+--------------+-+-------------------------+-+-><
| '-literal-3----' '-| phrase 1 |-' |
| .--------------------------------------------------------------. |
| | .------------------. | |
| V V | | |
'-+-ALL-----+----+-identifier-3-+--BY--+-identifier-5-+----+--------------+-+-+-'
+-LEADING-+ '-literal-1----' '-literal-3----' '-| phrase 1 |-'
'-FIRST---'
phrase 1:
|--+-BEFORE-+--+---------+--+-identifier-4-+--------------------|
'-AFTER--' '-INITIAL-' '-literal-2----'
|
| Format 3 |
 >>-INSPECT--identifier-1--TALLYING------------------------------>
.------------------------------------------------------------------------------------.
| .-------------------------------------------------------------. |
| | .------------------. | |
V V V | | |
>----identifier-2--FOR----+-CHARACTERS----+--------------+-+------------------------+-+-+-->
| '-| phrase 1 |-' |
| .----------------------------------------. |
| | .------------------. | |
| V V | | |
'-+-ALL-----+----+-identifier-3-+----+--------------+-+-+-'
'-LEADING-' '-literal-1----' '-| phrase 1 |-'
>--REPLACING---------------------------------------------------->
.-----------------------------------------------------------------------------------.
| .------------------. |
V V | |
>----+-CHARACTERS BY--+-identifier-5-+----+--------------+-+-------------------------+-+-><
| '-literal-3----' '-| phrase 1 |-' |
| .--------------------------------------------------------------. |
| | .------------------. | |
| V V | | |
'-+-ALL-----+----+-identifier-3-+--BY--+-identifier-5-+----+--------------+-+-+-'
+-LEADING-+ '-literal-1----' '-literal-3----' '-| phrase 1 |-'
'-FIRST---'
phrase 1:
|--+-BEFORE-+--+---------+--+-identifier-4-+--------------------|
'-AFTER--' '-INITIAL-' '-literal-2----'
|
| Format 4 |
 >>-INSPECT--identifier-1--CONVERTING--+-identifier-6-+--TO------>
'-literal-4----'
>--+-identifier-7-+--------------------------------------------->
'-literal-5----'
.-------------------------------------------.
V |
>----+-BEFORE-+--+---------+--+-identifier-4-+-+---------------><
'-AFTER--' '-INITIAL-' '-literal-2----'
|
- identifier-1
- Is the inspected item and can be any of the following:
- An alphanumeric group item or national group item
- An elementary data item described explicitly or implicitly with
usage DISPLAY, DISPLAY-1, or NATIONAL. The item can have any category
that is valid for the selected usage.
- identifier-3, identifier-4,
identifier-5, identifier-6,
identifier-7
- Must reference an elementary data item described explicitly or
implicitly with usage DISPLAY, DISPLAY-1, or NATIONAL.
- literal-1, literal-2,
literal-3, literal-4
- Must be of category alphanumeric, DBCS, or national.
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.
TALLYING phrase (formats 1 and 3)
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
- Is the count field, and must be an elementary integer item
defined without the symbol P in its PICTURE character-string.
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.
- identifier-3 or literal-1
- Is the tallying field (the item whose occurrences will be
tallied).
- CHARACTERS
- When CHARACTERS is specified and neither the BEFORE nor AFTER phrase is
specified, the count field (identifier-2) is increased by 1 for
each character (including the space character) in the inspected item (identifier-1).
Thus, execution of an INSPECT statement with the TALLYING phrase increases
the value in the count field by the number of character positions in the
inspected item.
- ALL
- When ALL is specified and neither the BEFORE nor AFTER phrase is
specified, the count field (identifier-2) is increased by 1 for
each nonoverlapping occurrence of the tallying comparand (identifier-3
or literal-1) in the inspected item (identifier-1),
beginning at the leftmost character position and continuing to the
rightmost.
- LEADING
- When LEADING is specified and neither the BEFORE nor AFTER phrase is
specified, the count field (identifier-2) is increased by 1 for
each contiguous nonoverlapping occurrence of the tallying comparand in the
inspected item (identifier-1), provided that the leftmost such
occurrence is at the point where comparison began in the first comparison
cycle for which the tallying comparand is eligible to participate.
- FIRST (format 3 only)
- When FIRST is specified and neither the BEFORE nor AFTER phrase is
specified, the substitution field replaces the leftmost occurrence of the
subject field in the inspected item (identifier-1).
REPLACING phrase (formats 2 and 3)
This phrase fills all or portions of a data item with specified characters,
such as spaces or zeros.
- identifier-3 or literal-1
- Is the subject field (it identifies the characters to be
replaced).
- identifier-5 or literal-3
- Is the substitution field (the item that replaces the subject
field).
The subject field and the substitution field must be the same length.
- CHARACTERS BY
- When the CHARACTERS BY phrase is used, the substitution field must be one
character position in 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.
- ALL
- When ALL is specified and neither the BEFORE nor AFTER phrase is
specified, the substitution field replaces each nonoverlapping occurrence of
the subject field in the inspected item (identifier-1), beginning
at the leftmost character position and continuing to the rightmost.
- LEADING
- When LEADING is specified and neither the BEFORE nor AFTER phrase is
specified, the substitution field replaces each contiguous nonoverlapping
occurrence of the subject field in the inspected item (identifier-1),
provided that the leftmost such occurrence is at the point where comparison
began in the first comparison cycle for which this substitution field is
eligible to participate.
- FIRST
- When FIRST is specified and neither the BEFORE nor AFTER phrase is
specified, the substitution field replaces the leftmost occurrence of the
subject field in the inspected item (identifier-1).
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).
Replacement rules
The following replacement rules apply:
- When the subject field is a figurative constant, the one-character
substitution field replaces each character in the inspected item that is
equivalent to the figurative constant.
- When the substitution field is a figurative constant, the substitution
field replaces each nonoverlapping occurrence of the subject field in the
inspected item.
- When the subject and substitution fields are character-strings, the
character-string specified in the substitution field replaces each
nonoverlapping occurrence of the subject field in the inspected item.
- After replacement has occurred in a given character position in the
inspected item, no further replacement for that character position is made
in this execution of the INSPECT statement.
BEFORE and AFTER phrases (all formats)
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.
- identifier-4 or literal-2
- Is the delimiter.
Delimiters are not counted or replaced.
- INITIAL
- The first occurrence of a specified item.
The BEFORE and AFTER phrases change how counting and replacing are done:
- When BEFORE is specified, counting or replacing of the inspected item (identifier-1)
begins at the leftmost character position and continues until the first
occurrence of the delimiter is encountered. If no delimiter is present in
the inspected item, counting or replacing continues toward the rightmost
character position.
- When AFTER is specified, counting or replacing of the inspected item (identifier-1)
begins with the first character position to the right of the delimiter and
continues toward the rightmost character position in the inspected item. If
no delimiter is present in the inspected item, no counting or replacement
takes place.
CONVERTING phrase (format 4)
This phrase converts
all occurrences of a specific character or string of characters in a data item (identifier-1)
to user-supplied replacement characters.
- identifier-6 or literal-4
- Specifies the character string to be replaced.
The same character must not appear more than once in either literal-4
or identifier-6.
- identifier-7 or literal-5
- Specifies the replacing character string.
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.
Data types for identifiers and literals
Table 41. Treatment of the content of data items
| 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 |
Data flow
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:
- TALLYING (literal-1 or identifier-3, ... )
- REPLACING (literal-3 or identifier-5, ... )
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
COBOL for Windows Programming Guide.
Comparison cycle
The comparison cycle consists of the following actions:
- The first comparand is compared with an equal number of leftmost
contiguous character positions in the inspected item. The comparand matches
the inspected characters only if both are equal, character-for-character.
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 no match occurs for the first comparand and there are more comparands,
the comparison is repeated for each successive comparand until either a
match is found or all comparands have been acted upon.
- Depending on whether a match is found, these actions are taken:
- Actions 1 through 3 are repeated until the rightmost character position in
the inspected item either has been matched or has been considered as being
in the leftmost character position.
When the BEFORE or AFTER phrase is specified, the comparison cycle is
modified, as described in BEFORE and AFTER phrases (all formats).
Example of the INSPECT statement
The following figure shows an example of INSPECT statement results.
|