HP 3000 Manuals

INSPECT Statement [ HP COBOL II/XL Reference Manual ] MPE/iX 5.0 Documentation

HP COBOL II/XL Reference Manual

INSPECT Statement

The INSPECT statement can be used to perform one of three actions:

* It can count the number of occurrences of a given character or
character substring within a data item.

* It can replace a given character or characters within a specified
data item with another character or set of characters.

* It can perform both of the functions described above in a single
operation.

By using the LEADING, BEFORE, and AFTER phrases, you can use INSPECT to
replace only certain occurrences of characters within a data item. Also,
by using CHARACTERS, you can tally and replace every character (or subset
of characters when used in conjunction with LEADING, BEFORE, and AFTER)
in a data item.

Syntax

The INSPECT statement has four formats as shown below.

NOTE Format 4 (INSPECT CONVERTING) is a way to specify a translation
table converting one set of characters into another. Format 4 is
equivalent to format 2, but provides a concise way of achieving
the same results.

Parameters

identifier-1 a variable representing either a group item or any
category of elementary item described implicitly or
explicitly as USAGE IS DISPLAY. This is the data item to
be inspected.

identifier-2 names an elementary numeric data item. It is used to
contain the results of tallying occurrences of a character
or characters in the data item represented by
identifier-1. Identifier-2 is not initialized by the
INSPECT statement; therefore, if you want it initialized,
you must do so programmatically before the INSPECT
statement is executed.

identifier-3 each must reference either an elementary alphabetic,
through alphanumeric, or numeric data item described implicitly or
identifier-n explicitly as USAGE IS DISPLAY.

literal-1 are each nonnumeric literals. Each may be any figurative
through constant except ALL.
literal-5
If, in formats 1 and 3, literal-1 is a figurative
constant, that implicitly refers to a single character
constant.

In 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 item referenced by literal-1 or identifier-3.

If literal-3 is a figurative constant, its size is
implicitly equal to the size of literal-1, or the size of
the data item referenced by identifier-3.

If literal-1 is a figurative constant, the data referenced
by literal-3 or identifier-5 must be a single character.

When the CHARACTERS phrase is used, literal-3 (or
literal-2), or the size of the data item referenced by
identifier-5 (or identifier-4) must be one character in
length.

No more than one BEFORE phrase and one AFTER phrase can be
specified for any one ALL, LEADING, CHARACTERS, FIRST, or
CONVERTING phrase.

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.

Description

When inspection takes place, the data items referenced by identifier-1
and identifiers-3 through 5 are all considered to be character strings,
regardless of whether they are alphanumeric, alphanumeric-edited,
numeric-edited, unsigned or signed numeric.

For any data item except signed numeric or alphanumeric, inspection is
accomplished by inspecting the items as though they have been redefined
as alphanumeric, and the INSPECT statement written to reference the
redefined data item.

For signed numeric data items, inspection is accomplished by treating the
data item as if it had been moved to an unsigned numeric data item, and
then inspecting it as described in the preceding paragraph.

CONVERTING Phrase

A format 4 INSPECT statement is interpreted and executed as though a
format 2 INSPECT statement specifying the same identifier-1 has been
written. This is done with a series of ALL phrases, one for each
character of literal 4. The result is as if each of these ALL phrases
were 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 occupy the same storage
area as identifier-1, the result of the execution of this statement is
undefined. This is true even if they are defined by the same data
description entry. Refer to "Overlapping Operands and Incompatible Data"
in Chapter 8 for more information.

Example

The following two INSPECT statements are equivalent:

INSPECT D-ITEM CONVERTING "ABCD" TO "XYZX" AFTER QUOTE BEFORE "#".

INSPECT D-ITEM REPLACING
ALL "A" BY "X" AFTER QUOTE BEFORE "#"
ALL "B" BY "Y" AFTER QUOTE BEFORE "#"
ALL "C" BY "Z" AFTER QUOTE BEFORE "#"
ALL "D" BY "X" AFTER QUOTE BEFORE "#".

The results of these statements are:

Initial value of D-ITEM: AC"AEBDFBCD#AB"D
Final value of D-ITEM: AC"XEYXFYZX#AB"D

How the Comparison Operation Occurs

To facilitate the following description of the comparison operation, the
various groups of identifiers and literals are renamed. The names used
and the identifiers or literals they represent are:

searchchars represents literal-1 or the contents of identifier-3 and
5%.

initchars represents literal-2 or the contents of identifier-4.

replacechars represents literal-3 or the contents of identifier-5.

data represents the contents of identifier-1.

When inspection takes place, the elements of data are compared to
searchchars. For each properly matched occurrence of searchchars:

* In formats 1 and 3, tallying occurs using identifier-2 to contain
the results.

* In formats 2 and 3, each set of properly matched characters in
data is replaced by replacechars.

When the INSPECT statement is used in its simplest form, that is, without
the LEADING, BEFORE, and AFTER phrases, the inspection occurs as follows:

The first set of searchchars is compared with an equal number of
characters in data, starting with the leftmost character of data.

If no match occurs, the second set of searchchars is compared with an
equal number of characters in data, again starting with the leftmost
character of data.

This process continues for each set of searchchars until either a match
occurs or all sets of searchchars are exhausted.

If all sets of searchchars are exhausted and no matches have occurred,
comparison begins again using the first set of searchchars, but starting
this time with the character immediately to the right of the leftmost
character of data.

Again, comparison proceeds as described above until either a match occurs
or all sets of searchchars are used.

If all sets are used and no matches have occurred, comparison begins
again, starting with the character of data to the right of the leftmost
character of data.

This continuing cycle of shifting one character to the right in the
characters of data and using all of the sets of searchchars is terminated
when, if no matches have occurred, the rightmost character of data has
been used in a comparison with the last set of searchchars.

If a match does occur for some set of searchchars and TALLYING is
specified, identifier-2 is incremented by one. If REPLACING is
specified, the matched characters of data are replaced by the
replacechars that correspond to the set of searchchars being compared
when the match occurred.

When a match occurs for a particular set of searchchars, the characters
of data that matched are not compared with any following searchchars.
Comparison begins again using the first set of searchchars, but starting
with the character immediately to the right of the leftmost character of
data that matched.

Inspection continues in the manner described above until the rightmost
character of data has been used as the first character in a comparison
with the last set of searchchars, or has been matched.

If TALLYING and REPLACING are both specified in the INSPECT statement,
two completely separate comparisons, as described above, take place. The
first comparison is used for TALLYING, and the second is used for
REPLACING.

Example

The following INSPECT statement illustrates this form of inspection:

INSPECT WORD TALLYING COUNTER FOR ALL "X"
REPLACING ALL "EE" BY "OX", "9" BY "E".

WORD contains the alphanumeric data, YEEXE9XY, and COUNTER is the
variable used to hold the tally. Since INSPECT does not initialize
COUNTER, assume it is initialized to zero before the INSPECT statement.

Following are the step-by-step comparisons that take place when this
INSPECT statement executes:

1. Initially, WORD=YEEXE9XY and COUNTER=0. Begin the comparison
starting at the first character of YEEXE9XY:

YEEXE9XY
uparrow
=X?

2. No match occurred. Begin the comparison again, starting at the
second character:

YEEXE9XY
uparrow
=X?

3. No match occurred. Begin the comparison again, starting at the
third character:

YEEXE9XY
uparrow
=X?

4. No match occurred. Begin the comparison again, starting at the
fourth character:

YEEXE9XY
uparrow
=X?

5. A match occurred. Increment COUNTER by 1, and begin the
comparison again, starting with the fifth character of YEEXE9XY:

YEEXE9XY
uparrow
=X?

6. No match occurred. Begin the comparison again, starting with the
sixth character:

YEEXE9XY
uparrow
=X?

7. No match occurred. Begin the comparison again, starting with the
seventh character:

YEEXE9XY
uparrow
=X?

8. A match occurred. Increment COUNTER by 1, and begin the
comparison again, starting with the eighth character of YEEXE9XY:

YEEXE9XY
uparrow
=X?

9. No match occurred. The last character of YEEXE9XY has been used
as the first element in a comparison. The tallying cycle is
complete. Begin the replacing cycle starting with the first
characters of YEEXE9XY:

YEEXE9XY -> YEEXE9XY
uparrowuparrow uparrow
=EE? =9?

10. No match occurred. Begin the comparison again, starting with the
second character:

YEEXE9XY
uparrowuparrow
=EE?

11. A match occurred. Change EE to OX, and begin the comparison
again, starting with the fourth character of YOXXE9XY:

YOXXE9XY -> YOXXE9XY
uparrowuparrow uparrow
=EE? =9?

12. No match occurred. Begin the comparison again, starting with the
fifth character:

YOXXE9XY -> YOXXE9XY
uparrowuparrow uparrow
=EE? =9?

13. No match occurred. Begin the comparison again, starting with the
sixth character:

YOXXE9XY -> YOXXE9XY
uparrowuparrow uparrow
=EE? =9?

14. A match occurred. Replace 9 by E in YOXXE9XY, and begin the
comparison again, at the seventh character of YOXXEEXY:

YOXXEEXY -> YOXXEEXY
uparrowuparrow uparrow
=EE? =9?

15. No match occurred. Begin the comparison again, starting with the
eighth character:

YOXXEEXY -> YOXXEEXY
uparrowuparrow uparrow
=EE? =9?

16. No match occurred. The last character of YOXXEEXY has been used
as the first character in a comparison. The comparison cycle for
REPLACING is complete. This ends execution of the INSPECT
statement.

The result of this INSPECT statement is summarized by the fact that WORD
now contains the character string, YOXXEEXY, and COUNTER now contains the
integer 2.

BEFORE and AFTER Phrases

No more than one BEFORE phrase and one AFTER phrase can be specified for
any one ALL, LEADING, CHARACTERS, FIRST, or CONVERTING phrase.

The comparison operation described on the preceding pages is affected by
the BEFORE and AFTER phrases in the following way:

If the BEFORE phrase is used, the associated searchchars are used only in
those comparison cycles that make comparisons of characters of data to
the left of the first occurrence of the associated initchars.

If initchars does not appear in data, the BEFORE phrase has no effect
upon the comparison operation.

If the AFTER phrase is used, the associated searchchars are used only in
those comparison cycles that make comparisons of characters of data to
the right of the first occurrence of the associated initchars.

If initchars does not appear in data, the associated searchchars are
never used in the comparison cycle. This is equivalent to not using the
clause in which the AFTER phrase appears.

Multiple occurrences of the BEFORE/AFTER phrase allow the
TALLYING/REPLACING operation to be initiated after the beginning of the
inspection of data begins and/or is terminated before the end of the
inspection of data ends.

LEADING Phrase

If the LEADING phrase is used in an INSPECT statement, it causes
identifier-2 (the variable used to hold the tally) to be incremented by
one for each contiguous matching of searchchars with a character of data,
provided that the matching begins with the leftmost character of the
characters that make up data.

For replacing, the LEADING phrase has the effect of replacing each
contiguous occurrence of matched characters to be replaced by
replacechars, provided that the matching begins with the leftmost
character of data.

If the first character (or characters) of data is not the same as
searchchars, the clause in which the LEADING phrase appears has no effect
upon the data, or the variable used to hold the tally.

ALL Phrase

When used in tallying, the ALL phrase causes the contents of identifier-2
to be incremented by one for each occurrence of searchchars within data.
When used in replacing, the ALL phrase causes each set of characters in
data matched with the searchchars to be replaced.

CHARACTERS Phrase

When the CHARACTERS phrase is used in tallying, the contents of
identifier-2 are incremented by 1 for each character in the set of
characters used in the comparison cycle. This does not necessarily imply
that all characters are tallied, since the BEFORE and AFTER phrases can
limit comparison to only part of data.

When the CHARACTERS phrase is used in replacement, each character in the
set of characters used in the comparison cycle is replaced by
replacechars, regardless of what the character in data is. For example,
this phrase can be used to initialize a data item by not using the BEFORE
or AFTER phrases to limit the part of data to be acted upon.

Multiple occurrences of the REPLACING CHARACTERS phrase are allowed.

FIRST Phrase

When the FIRST phrase is used in replacement, the leftmost occurrence in
data of searchchars is replaced by the associated replacechars.

Examples

Assuming that the variable THISONE has the data "WARNING" in it, the
INSPECT statement,

INSPECT THISONE REPLACING ALL "N" by "P" BEFORE INITIAL "I".

results in THISONE having the data WARPING in it.

If REC has the data "JIMGIRAFFEEGAVEGUMDROPS" and ACUM is zero initially,
the following INSPECT statement results in ACUM being 2, and REC
containing JIMRIRAFFEERAVERUMDROPS.

INSPECT REC TALLYING ACUM FOR ALL "F", REPLACING ALL "G" BY "R".

If PETE has the data "CBVFEET" before execution of the following INSPECT
statement, then following execution, PETE contains CBVFOOO.

INSPECT PETE REPLACING LEADING "BV" BY "AT",
CHARACTERS BY "0" AFTER INITIAL "F".

In the following example, COUNT-n is assumed to be zero immediately prior
to execution of the statement. Table 9-1 shows the result of
executing the two successive INSPECT statements.

INSPECT ITEM TALLYING
COUNT-0 FOR ALL "AB" BEFORE "BC"
COUNT-1 FOR LEADING "B" AFTER "D"
COUNT-2 FOR CHARACTERS AFTER "A" BEFORE "C".

INSPECT ITEM REPLACING
ALL "AB" BY "XY" BEFORE "BC"
LEADING "B" BY "W" AFTER "D"
FIRST "E" BY "V" AFTER "D"
CHARACTERS BY "Z" AFTER "A" BEFORE "C".

Table 9-1. Results of INSPECT Statement Execution

-----------------------------------------------------------------------------------------------------
| | | | | |
| Initial Value of | COUNT-0 | COUNT-1 | COUNT-2 | Final Value of |
| Item | | | | Item |
| | | | | |
-----------------------------------------------------------------------------------------------------
| | | | | |
| BBEABDABABBCABEE | 3 | 0 | 2 | BBEXYZXYXYZCABVE |
| | | | | |
-----------------------------------------------------------------------------------------------------
| | | | | |
| ADDDDC | 0 | 0 | 4 | AZZZZC |
| | | | | |
-----------------------------------------------------------------------------------------------------
| | | | | |
| ADDDDA | 0 | 0 | 5 | AZZZZZ |
| | | | | |
-----------------------------------------------------------------------------------------------------
| | | | | |
| CDDDDC | 0 | 0 | 0 | CDDDDC |
| | | | | |
-----------------------------------------------------------------------------------------------------
| | | | | |
| BDBBBDB | 0 | 3 | 0 | BDWWWDB |
| | | | | |
-----------------------------------------------------------------------------------------------------

MPE/iX 5.0 Documentation