The SEARCH
Statement
The SEARCH statement is used to search a table for a table element that satisfies
the specified condition and to adjust the associated index-name to indicate
that table element.
General Format


Note that the required relational character "=" is not underlined to avoid
confusion with other symbols.
Syntax Rules
- Identifier-1 must not be subscripted or indexed, but its description must
contain an OCCURS clause and an INDEXED BY clause. The description of identifier-1
in Format 2 must also contain the KEY IS phrase in its OCCURS clause.
- Identifier-2, when specified, must be described as USAGE IS INDEX or as a
numeric elementary item without any positions to the right of the assumed
decimal point.
If the END-SEARCH phrase is specified, the NEXT SENTENCE phrase must not
be specified.

END-SEARCH can be specified with NEXT SENTENCE. If the NEXT SENTENCE phrase
is executed, control does not pass to the next statement following the END-SEARCH,
but instead passes to the statement after the closest following period.
Both imperative-statement-1 and imperative-statement-2 can be replaced by
a conditional statement.
- Condition-1, condition-2, and so on, can be any condition as described in
the section Conditional Expressions in the chapter Procedure Division.


Identifier-1, the table element being searched, can be an internal or external
floating-point item.
- All referenced condition-names must be defined as having only a single value.
The data-name associated with a condition-name must appear in the KEY clause
of identifier-1. Each data-name-1, data-name-2 can be qualified. Each data-name-1,
data-name-2 must be indexed by the first index-name associated with identifier-1
along with other indices or literals as required, and must be referenced in
the KEY clause of identifier-1. Identifier-3, identifier-4, or identifiers
specified in arithmetic-expression-1, arithmetic-expression-2 must not be
referenced in the KEY clause of identifier-1 or be indexed by the first index-name
associated with identifier-1.
When a data-name in the KEY clause of identifier-1 is referenced, or when
a condition-name associated with a data-name in the KEY clause of identifier-1
is referenced, all preceding data-names in the KEY clause of identifier-1
or their associated condition-names must also be referenced.


Identifier-1, the table element being searched, cannot be a floating-point
item.


Neither data-name-1 nor data-name-2, the key data items, can be floating-point
items. However, identifier-3, identifier-4, literal-1, or literal-2, the items
against which the key is compared, can be floating-point items.
General Rules
- The scope of a SEARCH statement can be terminated by any of the following:
- After execution of imperative-statement-1 or imperative-statement-2 that
does not terminate with a GO TO statement, control passes to the next executable
sentence.
-
If identifier-1
is a data item subordinate to a data item that contains an OCCURS clause (providing
for a two- or three-dimensional table), an index-name must be associated with
each dimension of the table through the INDEXED BY phrase of the OCCURS clause.
Only the setting of the index-name associated with identifier-1 (and the data
item identifier-2 or index-name-1, if present) is modified by the execution
of the SEARCH statement. To search an entire two- or three-dimensional table
it is necessary to execute a SEARCH statement several times. Prior to each
execution of a SEARCH statement, SET statements must be executed whenever
index-names must be adjusted to appropriate settings.
- If Format 1 of the SEARCH statement is used, a serial type of search operation
takes place, starting with the current index setting.
- If, at the start of execution of the SEARCH statement, the index-name associated
with identifier-1 contains a value that corresponds to an occurrence number
that is greater than the highest permissible occurrence number for identifier-1,
the SEARCH is terminated immediately. The number of occurrences of identifier-1,
the last of which is the highest permissible, is discussed in the topic The
OCCURS Clause in the chapter Data Division - File and Data Description.)
Then, if the AT END phrase is specified, imperative-statement-1 is executed;
if the AT END phrase is not specified, control passes to the next executable
sentence.
- If, at the start of execution of the SEARCH statement, the index-name associated
with identifier-1 contains a value that corresponds to an occurrence number
that is not greater than the highest permissible occurrence number for identifier-1
(the number of occurrences of identifier-1, the last of which is the highest
permissible is discussed in the topic The OCCURS Clause), the SEARCH statement
operates by evaluating the conditions in the order that they are written,
making use of the index settings, wherever specified, to determine the occurrence
of those items to be tested. If none of the conditions is satisfied, the index
name for identifier-1 is incremented to obtain reference to the next occurrence.
The process is then repeated using the new index-name settings unless the
new value of the index-name settings for identifier-1 corresponds to a table
element outside the permissible range of occurrence values, in which case
the search terminates as indicated in General Rule 4a above. If one of the
conditions is satisfied upon its evaluation, the search terminates immediately
and the imperative statement associated with that condition is executed; the
index-name remains set at the occurrence which caused the condition to be
satisfied.
- If the VARYING phrase is not used, the index-name that is used for the search
operation is the first (or only) index-name that appears in the INDEXED BY
phrase of identifier-1. Any other index-names for identifier-1 remain unchanged.
- If the VARYING index-name-1 phrase is specified, and if index-name-1 appears
in the INDEXED BY phrase of identifier-1, that index-name is used for this
search. If this is not the case, or if the VARYING identifier-2 phrase is
specified, the first (or only) index-name given in the INDEXED BY phrase of
identifier-1 is used for the search. In addition, the following operations
occur:
- If the VARYING index-name-1 phrase is used, and if index-name-1 appears in
the INDEXED BY phrase of another table entry, the occurrence number represented
by index-name-1 is incremented by the same amount as the index-name associated
with identifier-1, and at the same time.
- If the VARYING identifier-2 phrase is specified, and identifier-2 is an index
data item, then the data item referenced by identifier-2 is incremented by
the same amount as the index-name associated with identifier-1, and at the
same time. If identifier-2 is not an index data item, the data item referenced
by identifier-2 is incremented by the value (1) at the same time as the index
referenced by the index-name associated with identifier-1 is incremented.
- The results of the SEARCH ALL operation are predictable only when:
- The data in the table is ordered in the same manner as described in the ASCENDING/DESCENDING
KEY clause associated with the description of identifier-1, and:
- The contents of the key(s) referenced in the WHEN clause are sufficient to
identify a unique table element.
- If Format 2 of the SEARCH statement is used, a non-serial type of search
operation can take place; the initial setting of the index-name for identifier-1
is ignored and its setting is varied during the search operation with the
restriction that at no time is it set to a value that exceeds the value which
corresponds to the last element of the table, or that is less than the value
that corresponds to the first element of the table. The length of the table
is discussed in the topic The OCCURS Clause). If any of the conditions
specified in the WHEN clause cannot be satisfied for any setting of the index
within the permitted range, control is passed to imperative-statement-1 of
the AT END phrase, when specified, or to the next executable sentence when
this phrase is not specified; in either case the final setting of the index
is not predictable. If all conditions can be satisfied, the index indicates
an occurrence that allows the conditions to be satisfied, and control passes
to imperative-statement-2.
- The index-name that is used for the search operation is the first (or only)
index-name that appears in the INDEXED BY phrase of identifier-1. Any other
index-names for identifier-1 remain unchanged.


Neither imperative-statement-2 nor NEXT SENTENCE is required. Without them,
the SEARCH statement sets the index to the value in the table that matched
the condition.
Comments:
Figure 1 shows a flowchart of a Format 1 SEARCH operation containing
two WHEN phrases.

Figure 1: Flowchart of SEARCH Operation Showing Two WHEN Phrases
1 |
These operations are options included only when specified in the SEARCH statement |
2 |
Each of these control transfers is to the next executable sentence unless
the imperative-statement ends with a GO TO statement. |