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.
![ENT](diale.gif)
Identifier-1 can also be USAGE NATIONAL or USAGE UTF-8.
- 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.
![ENT](diale.gif)
Identifier-3 ... identifier-n can also be NATIONAL or UTF-8, but the USAGE for identifier-1 and Identifier-3 ... identifier-n must match.
- Each literal must be nonnumeric and can be any figurative constant, except ALL. If literal-1 ... literal-9 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-9 and the data items referenced by identifier-3 ... identifier-11 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,
or literal-4, literal-9, identifier-6, or identifier-11.
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 12, 13 and
14.
- For use in the INSPECT statement, the contents of the data item referenced by identifier-1 ... identifier-11 is treated as
follows:
- If any of identifier-1 ... identifier-11 is described as alphanumeric, the INSPECT statement treats the contents of each such
identifier as a character-string.
- If any of identifier-1 ... identifier-11 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.
- If any of identifier-1 ... identifier-11 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 20, all references to literal-1 ... literal-9 apply equally to the contents of the equivalent data
items referenced by identifier-3 ... identifier11.
- 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.
![ENT](diale.gif)
No identifiers in the INSPECT statement can be dynamic-length group or dynamic-length elementary items.
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:
- 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.
- 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.
- 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 13e, 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:
- 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:
- If neither LEADING nor FIRST is specified:
- If the LEADING adjective applies to literal-1 and literal-1 is a leading occurrence as defined in General Rules 10 and 16:
- If the FIRST adjective applies to literal-1 and literal-1 is the first occurrence as defined in General Rule 10.
- 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.
- Whenever a match occurs, tallying and/or replacing takes place as described in General Rules 10 and 16. 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.
- 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.
- If the CHARACTERS phrase is specified, an implied one-character operand participates in the cycle described in paragraphs
13a through 13d 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 13 is affected by the BEFORE and AFTER phrases as follows:
- 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.
- 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 13 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.
- 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 13 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:
- When the CHARACTERS phrase is specified, each character matched in the sense of Format 1 and 2, General Rule 13e in the contents
of the data item referenced by identifier-1, is replaced by literal-3.
- 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.
- 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.
- 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).