The INSPECT statement supports counting and modification of single characters or groups of characters within a data item. INSPECT performs its operations on strings and requires that the source data item be designated USAGE DISPLAY.
INSPECT performs three basic functions: TALLYING, REPLACING, and CONVERTING. (CONVERTING is a specialized, shorthand form of REPLACING).
Format 1
INSPECT source
[ TALLYING { counter FOR { { {ALL } comp-val }
{ {LEADING} }
{ CHARACTERS }
[delim] } ... } ... ]
[ REPLACING
{ CHARACTERS BY repl-char [delim] }
{ {ALL } }
{ {LEADING} { targ BY repl [delim] } ... }
{ {FIRST } }
... ]
Format 2
INSPECT source
CONVERTING comp-chars TO conv-chars [delim]
{ {BEFORE} INITIAL delimiter } ...
{AFTER }
Format 3
INSPECT source
[ TALLYING counter FOR TRAILING comp-value ]
[ REPLACING TRAILING target BY replace ]
Syntax Rules
1. Source is a data item with USAGE DISPLAY.
2. Counter is an elementary numeric data item.
3. Comp-val is a nonnumeric literal (other than an ALL literal) or an elementary alphabetic, alphanumeric, or numeric data item with USAGE DISPLAY.
4. Repl-char is a one-character item with the same restrictions as comp-val.
5. Targ, delimiter, repl, comp-chars, and conv-chars have the same restrictions as comp-val.
6. In Formats 1 and 3, at least one of the TALLYING or REPLACING phrases must be specified.
7. Any delim phrase may have no more than one AFTER and one BEFORE phrase in it.
8. The sizes of the data referred to by targ and repl must be the same. If repl is a figurative constant, its size is set equal to the size of targ.
9. When the CHARACTERS phrase of the REPLACING clause is used, delimiter (if specified) must have a data size of one character.
10. The sizes of the data referred to by comp-chars and conv-chars must be the same. When conv-chars is a figurative constant, its size equals that of comp-chars.
11. The same character cannot appear more than once in the data referred to by comp-chars.
12. Comp-value, target, and replace are nonnumeric literals or single-character alphanumeric data items.
General Rules
1. Inspection starts at the leftmost character of source and proceeds character by character until it reaches the rightmost character.
2. Source, comp-val, delimiter, targ, repl, repl-char, comp-chars, and conv-chars are treated as if they were redefined by an alphanumeric elementary data item. The data referred to by these items is treated as a character string.
3. If the size of source is zero characters, no inspection occurs.
4. If the size of comp-val or targ is zero characters, no match in source by these items is successful.
5. Comp-val and targ are matched in the source string according to the following rules:
a) Comparison starts at the leftmost character and proceeds character by character until the rightmost character of source is reached.
b) The first comp-val or targ item is checked at the current character location for a match. A match occurs if every character of comp-val or targ is the same as the corresponding characters in source starting at the current character position.
c) If no match occurs, successive comp-val or targ items are checked at the current character position until a match occurs or the list of items is exhausted. The next character position is then checked and the process repeats.
d) When a match occurs, the specified tallying or replacement is performed. Further checking for matching items at this character position is not performed. The new next character position to use for matching is set to be the character to the immediate right of the rightmost character position that matched in the preceding comparison.
e) Inspection halts when the rightmost character of source has served as the current matching character position or has been successfully matched in the preceding rule.
f) When the CHARACTERS phrase is present, inspection proceeds as if a single-character value were being compared and it successfully matches every character in source.
6. The BEFORE phrase modifies the character position to use as the rightmost position in source for the corresponding comparison operation. Comparisons in source occur only to the left of the first occurrence of delimiter. If delimiter is not present in source, then the comparison proceeds as if there were no BEFORE phrase.
7. The AFTER phrase modifies the character position to use as the leftmost position in source for the corresponding comparison operation. Comparisons in source occur only to the right of the first occurrence of delimiter. This character position is the one immediately to the right of the rightmost character of the delimiter found. If delimiter is not found in source, the INSPECT statement has no effect (no tallying or replacement occurs).
8. If both the TALLYING and REPLACING phrases are present, the TALLYING option is performed first, and then the REPLACING option is performed as if it were written as a separate INSPECT statement.
TALLYING Option
1. The INSPECT statement does not initialize counter.
2. If the ALL phrase is present, counter is incremented by one for each occurrence of comp-val in source.
3. If the LEADING phrase is present, counter is incremented by one for each contiguous occurrence of comp-val in source. These occurrences must start at the position in source where comparison begins. Otherwise, no tallying occurs.
4. If the CHARACTERS phrase is present, counter is incremented by one for each character in source that is matched (see rule 5f).
5. If the FOR TRAILING phrase is present, counter is incremented by one for each contiguous occurrence of comp-value in source, starting at the rightmost (trailing) character and scanning leftwards. If the rightmost character is not comp-value, then counter is not incremented.
REPLACING Option
1. The adjectives ALL, LEADING, and FIRST apply to succeeding compare items until the next such adjective appears.
2. If the CHARACTERS phrase is used, each character matched in source is replaced by the single character repl-char.
3. When the ALL phrase is present, each occurrence of targ matched in source is replaced by repl.
4. If the LEADING phrase is present, each contiguous occurrence of targ matched in source is replaced by repl. These occurrences must begin at the leftmost position in source used for comparison.
5. When the FIRST phrase is present, the leftmost occurrence of targ matched in source is replaced by repl.
6. If the TRAILING phrase is present, the REPLACING option causes all contiguous occurrences of target to be replaced by replace, provided that these occurrences end in the rightmost character position of source.
CONVERTING Option
1. The CONVERTING form of the INSPECT statement has the effect of replacing every character in source found in comp-chars with the corresponding character in conv-chars. This is done according to the following rules:
a) The INSPECT statement is treated as if it were specified with the REPLACING option containing a series of ALL phrases, one for each character of comp-chars.
b) The targ item in each ALL phrase refers to a single character of comp-chars.
c) The repl item in each ALL phrase refers to a single character of conv-chars.
d) The individual characters of comp-chars and conv-chars correspond by ordinal position.
2. INSPECT CONVERTING is usually more efficient than the corresponding INSPECT REPLACING statement.
More: