HP 3000 Manuals HP 3000 Manuals
General Formats (Continued)
The INSPECT Statement
Function.
The INSPECT statement provides the ability to tally (Format 1), replace
(Format 2), tally and replace (Format 3) or convert (Format 4) (ANS85
only) occurrences of single characters or group of characters in a data
item.
Examples:.
1. Examples of using INSPECT TALLYING, REPLACING, and CONVERTING are
provided in the Examples chapter in your Language Reference -
Additional Topics.
General Formats.
Format 1.
![[]](../../pic3k/M015064/FFN2353c50.gif)
Format 2.
![[]](../../pic3k/M015064/FFN2363c50.gif)
Format 3.
![[]](../../pic3k/M015064/FFN2373c50.gif)
For ANS85 only: Format 4.
![[]](../../pic3k/M015064/FFN2383c50.gif)
Syntax Rules.
All Formats.
1. Identifier-1 must reference either a group item or any category of
elementary item, described (either implicitly or explicitly) as
USAGE IS DISPLAY.
2. Identifier-3...identifier-n must reference either an elementary
alphabetic, alphanumeric or numeric item described (either
implicitly or explicitly) as USAGE IS DISPLAY.
3. Each literal must be nonnumeric and can be any figurative
constant, except ALL. If literal-1, literal-2 or literal-4 is a
figurative constant, it refers to an implicit one character data
item.
4. No more than one BEFORE phrase and/ (ANS85 only) or one AFTER
phrase can be specified for any one ALL, LEADING, CHARACTERS,
FIRST or CONVERTING (ANS85 only) phrase.
5. Literal-1, literal-2, literal-3, literal-4, and literal-5, and the
data items referenced by identifier-3, identifier-4, identifier-5,
identifier-6, and identifier-7 can be any number of characters in
length up to the limit allowed for literals or data items.
6. For MF only: 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.
Formats 1 and 3.
7. Identifier-2 must reference an elementary numeric data item.
Formats 2 and 3.
8. 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.
9. 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.
For ANS85 only: This restriction does not apply to literal-2 or
identifier-4.
For ANS85 only: Format 4.
10. 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.
11. The same character must not appear more than once either in
literal-4 or in the data item referenced by identifier-6.
General Rules.
All Formats.
1. For ANS85 only: For the purpose of determining its length,
identifier-1 is treated as if it were a sending data item. (See
the section The OCCURS clause in this chapter).
2. 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 11, 12 and 13.
3. For use in the INSPECT statement, the contents of the data item
referenced by identifier-1, identifier-3, identifier-4,
identifier-5, identifier-6 or identifier-7 will be treated as
follows:
a. If any of identifier-1, identifier-3, identifier-4,
identifier-5, identifier-6 or identifier-7 is described as
alphanumeric, the INSPECT statement treats the contents of
each such identifier as a character-string.
b. If any of identifier-1, identifier-3, identifier-4,
identifier-5, identifier-6 or identifier-7 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.
c. If any of identifier-1, identifier-3, identifier-4,
identifier-5, identifier-6 or identifier-7 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 section The MOVE Statement
later in this chapter.)
4. In General Rules 6 through 19, all references to literal-1,
literal-2, literal-3, literal-4, and literal-5 apply equally to
the contents of the data item referenced by identifier-3,
identifier-4, identifier-5, identifier-6, and identifier-7,
respectively.
5. If any identifier is subscripted or is a function-identifier
(ANS85 only) , the subscript or function-identifier (ANS85 only)
is evaluated only once as the first operation in the execution of
the INSPECT statement.
Format 1.
6. For ANS85 only: Identifier-1 is a sending data item.
7. The required words ALL and LEADING are adjectives that apply to
each succeeding literal-1 until the next adjective appears.
8. The contents of the data item referenced by identifier-2 are not
initialized by the execution of the INSPECT statement.
9. The rules for tallying are as follows:
a. 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.
b. 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.
c. 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 12e, in the contents of the data item
referenced by identifier-1.
10. 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 section Overlapping Operands earlier
in this chapter.)
Formats 1 and 2.
11. 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).
12. The comparison operation to determine the occurrences of
literal-1 to be tallied or to be replaced, occurs as follows:
a. 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:
a. If neither LEADING nor FIRST is specified, or:
b. If the LEADING adjective applies to literal-1 and
literal-1 is a leading occurrence as defined in
General Rules 9 and 15, or:
c. If the FIRST adjective applies to literal-1 and
literal-1 is the first occurrence as defined in
General Rule 9.
b. 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.
c. Whenever a match occurs, tallying and/or replacing takes
place as described in General Rules 9 and 15. 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.
d. 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.
e. If the CHARACTERS phrase is specified, an implied one
character operand participates in the cycle described in
paragraphs 12a through 12d 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.
13. The comparison operation defined in General Rule 12 is affected
by the BEFORE and AFTER phrases as follows:
a. 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.
b. 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 12 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.
c. 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 12 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.
Format 2.
14. The required words ALL, LEADING and FIRST are adjectives that
apply to each succeeding BY phrase until the next adjective
appears.
15. The rules for replacement are as follows:
a. When the CHARACTERS phrase is specified, each character
matched in the sense of Format 1 and 2, General Rule 12e
in the contents of the data item referenced by
identifier-1, is replaced by literal-3.
b. 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.
c. 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.
d. 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.
16. 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 section Overlapping Operands earlier
in this chapter.)
Format 3.
17. 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.
For ANS85 only: Format 4.
18. 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.
19. 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 MERGE Statement
Function.
The MERGE statement combines two or more identically sequenced files on a
set of specified keys, and during the process makes records available, in
merge order, to an output procedure or to an output file.
General Format.
![[]](../../pic3k/M015064/FFN2393c50.gif)
Syntax Rules.
1. File-name-1 must be described in a sort-merge file description
entry in the Data Division.
2. Procedure-name-1 represents the name of an output procedure.
3. Procedure-name-1 and procedure-name-2 must be section-names.
For ANS85and OSVS only: This restriction is removed.
4. For ANS85 only: If the file referenced by file-name-1 contains
variable length records, the size of the records contained in the
files referenced by file-name-2 and file-name-3 must not be less
than the smallest record, nor greater than the largest record
described for file-name-1. If the file referenced by file-name-1
contains fixed length records, the size of the records contained
in the files referenced by file-name-2 and file-name-3 must not be
greater than the largest record described for file-name-1.
5. File-name-2, file-name-3, and file-name-4 must be described in a
file description entry, not in a sort-merge file description
entry, in the Data Division.
6. The words THRU and THROUGH are equivalent.
7. Data-name-1 is a KEY data-name and is subject to the following
rules:
a. The data items identified by KEY data-names must be
described in records associated with file-name-1.
b. KEY data-names can be qualified.
c. The data items identified by KEY data-names must not be
variable length items.
d. If file-name-1 has more than one record description, then
the data items identified by KEY data-names need be
described in only one of the record descriptions. The same
character position referenced by a key data-name in one
record description entry are taken as the key in all
records of the file.
e. None of the data items identified by KEY data-names can be
described by an entry which either contains an OCCURS
clause or is subordinate to an entry which contains an
OCCURS clause.
f. For OSVS, VSC2 and MF only: KEY data items can be
floating-point items .
g. For OSVS, VSC2 and MF only: If the KEY is an external
floating-point item, the key is treated as alphanumeric.
The sequence in which the records are merged depends on the
collating sequence used.
h. For OSVS, VSC2 and MF only: If the KEY is an internal
floating-point item, the sequence of key values will be in
numeric order.
8. No more than one file-name from a multiple file reel can appear in
the MERGE statement.
9. File-names must not be repeated in the MERGE statement.
10. MERGE statements can appear anywhere except in the declaratives
portion of the Procedure Division.
11. For ANS85 only: If file-name-4 references an indexed file, the
first specification of data-name-1 must be associated with an
ASCENDING phrase, and the data item referenced by that data-name-1
must occupy the same character positions in its record as the data
item associated with the prime record key for that file.
12. For ANS85 only: If the GIVING phrase is specified and the file
referenced by file-name-4 contains variable length records, the
size of the records contained in the file referenced by
file-name-1 must be less than the smallest record nor greater than
the record described for file-name-4. If the file referenced by
file-name-4 contains fixed length records, the size of the records
contained in the file referenced by file-name-1 must not be
greater than the largest record described for file-name-4.
13. If you want to specify more than 10 file-names in the USING or
GIVING clause, you must use the system directive CALLSORT"EXTSM";
this allows you to specify up to 255 files.
General Rules.
1. The MERGE statement merges all records contained on the files
referenced by file-name-2 and file-name-3.
2. If the file referenced by file-name-1 contains only fixed length
records, any record in the file referenced by file-name-2 or
file-name-3 containing fewer character positions than that fixed
length is space filled on the right, beginning with the first
character position after the last character in the record, when
that record is released to the file referenced by file-name-1.
3. The data-names following the word KEY are listed from left to
right in the MERGE statement in order of decreasing significance
without regard to how they are divided into KEY phrases. The
leftmost data-name is the major key, the next data-name is the
next more significant key, and so on.
a. When the ASCENDING phrase is specified, the merged sequence
will be from the lowest value of the contents of the data
items identified by the key data-names to the highest
value, according to the rules for comparison of operands in
a relation condition.
b. When the DESCENDING phrase is specified, the merged
sequence will be from the highest value of the contents of
the data items identified by the key data-names to the
lowest value, according to the rules for comparison of
operands in a relation condition.
4. When, according to the rules for comparison of operands in
relation condition, the contents of all the key data items of one
data record are equal to the corresponding key data items of one
or more other data records, the order of return of these records:
a. follows the order of the associated input files as
specified in the MERGE statement
b. is such that all records associated with one input file are
returned prior to the return of records from another input
file.
5. The collating sequence that applies to the comparison of the
nonnumeric key data items specified is determined at the beginning
of the execution of the MERGE statement in the following order of
precedence:
a. First, the collating sequence established by the COLLATING
SEQUENCE phrase, if specified, in that MERGE statement.
b. Second, the collating sequence established as the program
collating sequence.
6. The results of the merge operation are undefined unless the
records in the files referenced by file-name-2 and file-name-3 are
ordered as described in the ASCENDING or DESCENDING KEY phrases
associated with the MERGE statement.
7. All the records in the files referenced by file-name-2 and
file-name-3 are transferred to the file referenced by file-name-1.
At the start of execution of the MERGE statement, the files
referenced by file-name-2 and file-name-3 must not be in the open
mode. For each of the files referenced by file-name-2 and
file-name-3 the execution of the MERGE statement causes the
following actions to be taken:
a. The processing of the file is initiated. The initiation is
performed as if an OPEN statement with the INPUT phrase had
been executed. If an output procedure is specified, this
initiation is performed before control passes to the output
procedure.
b. The logical records are obtained and released to the merge
operation. Each record is obtained as if a READ statement
with the NEXT and the AT END phrases had been executed.
If the file referenced by file-name-1 is described with
variable length records, the size of any record written to
file-name-1 is the size of that record when it was read
from file-name-2 or file-name-3, regardless of the content
of the data item referenced in the DEPENDING ON phrase of
either a RECORD IS VARYING clause or an OCCURS clause
specified in the sort-merge file description entry for
file-name-1.
For a relative file, the content of the relative data key
item is undefined after the execution of the MERGE
statement.
c. The processing of the file is terminated. The termination
is performed as if a CLOSE statement without optional
phrases had been executed. If an output procedure is
specified, this termination is not performed until after
control passes the last statement in the output procedure.
These implicit functions are performed such that any
associated USE AFTER EXCEPTION/ERROR procedures are
executed.
The value of the data item referenced by the DEPENDING ON
phrase of a RECORD IS VARYING clause specified in the file
description entry for file-name-2 or file-name-3 is
undefined upon completion of the MERGE statement.
8. The output procedure can consist of any procedure needed to
select, modify or copy the records that are made available one at
a time by the RETURN statement in merged order from the file
referenced by file-name-1. The range includes all statements that
are executed as the result of a transfer of control by CALL, EXIT,
GO TO, and PERFORM statements in the range of the output
procedure, as well as all statements in declarative procedures
that are executed as a result of the execution of statements in
the range of the output procedure. The range of the output
procedure must not cause the execution of any MERGE, RELEASE, or
SORT statement. (See the section Explicit and Implicit
Specifications in the chapter Concepts of the COBOL Language.)
9. If an output procedure is specified, control passes to it during
execution of the MERGE statement. The compiler inserts a return
mechanism at the end of the last statement in the output
procedure. When control passes the last statement in the output
procedure, the return statement provides for termination of the
merge, and then passes control to the next executable statement
after the MERGE statement. Before entering the output procedure,
the merge procedure reaches a point at which it can select the
next record in merged order when requested. The RETURN statements
in the output procedure are the requests for the next record.
10. During the execution of the output procedure, no statement can be
executed manipulating the file referenced by, or accessing the
record area associated with, file-name-2, file-name-3, or
file-name-4.
11. If the GIVING phrase is specified, all the merged records are
written on the file referenced by file-name-4 as the implied
output procedure for the MERGE statement. At the start of
execution of the MERGE statement, the file referenced by
file-name-4 must not be in the open mode. For each of the files
referenced by file-name-4, the execution of the MERGE statement
causes the following actions to be taken:
a. The processing of the file is initiated. The initiation is
performed as if an OPEN statement with the OUTPUT phrase
had been executed.
b. The merged logical records are returned and written onto
the file. Each record is written as if a WRITE statement
without any optional phrases had been executed.
If the file referenced by file-name-4 is described with
variable length records, the size of any record written to
file-name-4 is the size of that record when it was read
from file-name-1, regardless of the content of the data
item referenced in the DEPENDING ON phrase of either a
RECORD IS VARYING clause or an OCCURS clause specified in
the file description entry for file-name-4.
For a relative file, the relative key data item for the
first record returned contains the value "1"; for the
second record returned, the value "2", and so on. The
content of the relative key data item is undefined after
execution of the MERGE statement.
c. The processing of the file is terminated. The termination
is performed as if a CLOSE statement without optional
phrases had been executed.
These implicit functions are performed such that any associated
USE AFTER EXCEPTION/ERROR procedures are executed; however, the
execution of such a USE procedure must not cause the execution of
any statement manipulating the file referenced by, or accessing
the record area associated with, file-name-4. On the first
attempt to write beyond the externally defined boundaries of the
file, any USE AFTER EXCEPTION/ERROR procedure specified for the
file is executed; if control is returned from the USE procedure or
if no such USE procedure is specified, the processing of the file
is terminated as in paragraph 11c above.
The value of the data item referenced by the DEPENDING ON phrase
of a RECORD IS VARYING clause specified in the file description
entry for file-name-1 is undefined upon completion of the MERGE
statement for which the GIVING phrase is specified.
12. If the file referenced by file-name-4 contains only fixed length
records, any record in the file referenced by file-name-1
containing fewer character positions than that fixed length is
space filled on the right, beginning with the first character
position after the last character in the record, when that record
is returned to the file referenced by file-name-4.
13. Segmentation, as defined in the chapter Segmentation in your
Language Reference - Additional Topics, can be applied to programs
containing the MERGE statement. However, the following
restrictions apply:
a. If the MERGE statement appears in a section that is not in
an independent segment, then any output procedure
referenced by that merge statement must appear:
i. totally within non-independent segments, or
ii. wholly contained in a single independent segment.
b. If a MERGE statement appears in an independent segment,
then any output procedure referenced by that MERGE
statement must be contained:
i. totally within non-independent segments, or
ii. wholly within the same independent segment as that
MERGE statement.
14. For VSC2, OSVS and MF only: The SORT-RETURN special register is
available to MERGE programs. It contains a return code of 0
(successful) or 16 (unsuccessful) at the completion of the merge
operation. You can set the special register to 16 in the output
procedure to terminate a merge operation before all records are
processed. The operation is terminated on the next RETURN
statement.