The SEARCH statement searches a table for an element that satisfies the specified condition and adjusts the associated index to indicate that element.
Format 1: SEARCH statement for serial search >>-SEARCH--identifier-1--+---------------------------+----------> '-VARYING--+-identifier-2-+-' '-index-name-1-' >--+-------------------------------------+----------------------> '-+----+--END--imperative-statement-1-' '-AT-' .-----------------------------------------------. V | >----WHEN--condition-1--+-imperative-statement-2-+-+------------> '-NEXT-SENTENCE----------' >--+------------+---------------------------------------------->< '-END-SEARCH-'
Format 2: SEARCH statement for binary search >>-SEARCH ALL--identifier-1-------------------------------------> >--+-------------------------------------+----------------------> '-+----+--END--imperative-statement-1-' '-AT-' >--WHEN--+-data-name-1--+----+--+-EQUAL--+----+-+--+-identifier-3------------+-+--> | '-IS-' | '-TO-' | +-literal-1---------------+ | | '-=-------------' '-arithmetic-expression-1-' | '-condition-name-1----------------------------------------------------' .----------------------------------------------------------------------------------. V | >----+------------------------------------------------------------------------------+-+--> '-AND--+-data-name-2--+----+--+-EQUAL--+----+-+--+-identifier-4------------+-+-' | '-IS-' | '-TO-' | +-literal-2---------------+ | | '-=-------------' '-arithmetic-expression-2-' | '-condition-name-2----------------------------------------------------' >--+-imperative-statement-2-+--+------------+------------------>< '-NEXT SENTENCE----------' '-END-SEARCH-'
Use format 1 (serial search) when the table that you want to search has not been sorted. Use format 1 to search a sorted table when you want to search serially through the table or you want to control subscripts or indexes.
Use format 2 (binary search) when you want to efficiently search across all occurrences in a table. The table must previously have been sorted.
The data description entry for identifier-1 must contain an OCCURS clause.
The data description entry for identifier-1 should contain an OCCURS clause with the INDEXED BY phrase, but a table can be searched using an index defined for an appropriately described different table.
identifier-1 can reference a data item that is subordinate to a data item that is described with an OCCURS clause (that is, identifier-1 can be a subordinate table within a multidimensional table). In this case, the data description entries must specify an INDEXED BY phrase for each dimension of the table.
identifier-1 must not be subscripted or reference-modified.
Before executing a serial search, you must set the value of the first (or only) index associated with identifier-1 (the search index) to indicate the starting occurrence for the search.
Before using a serial search on a multidimensional table, you must also set the value of the index for each superordinate dimension.
The SEARCH statement modifies only the value in the search index, and, if the VARYING phrase is specified, the value in index-name-1 or identifier-2. Therefore, to search an entire two-dimensional to seven-dimensional table, you must execute a SEARCH statement for each dimension. In the WHEN phrases, you must specify the indexes for all dimensions. Before the execution of each SEARCH statement, you must initialize the associated indexes with SET statements.
The SEARCH statement executes a serial search beginning at the current setting of the search index.
When the search begins, if the value of the index associated with identifier-1 is not greater than the highest possible occurrence number, the following actions take place:
If, when the search begins, the value of the index-name associated with identifier-1 is greater than the highest possible occurrence number, the search terminates immediately.
When the search terminates, if the AT END phrase is specified, imperative-statement-1 is executed. If the AT END phrase is omitted, control passes to the next statement after the SEARCH statement.
Example: multidimensional serial search
The following code fragment shows a search of the inner dimension (table C) in the third occurrence within the superordinate table (table R):
. . .
Working-storage section.
1 G.
2 R occurs 10 indexed by Rindex.
3 C occurs 10 ascending key X indexed by Cindex.
4 X pic 99.
1 Arg pic 99 value 34.
Procedure division.
. . .
* To search within occurrence 3 of table R, set its index to 3
* To search table C beginning at occurrence 1, set its index to 1
Set Rindex to 3
Set Cindex to 1
* In the SEARCH statement, specify C without indexes
Search C
* Specify indexes for both dimensions in the WHEN phrase
when X(Rindex Cindex) = Arg
display "Found " X(Rindex Cindex)
End-search
. . .
When the VARYING index-name-1 phrase is omitted, the first (or only) index-name for identifier-1 is used for the search.
If indexing is used to search a table without an INDEXED BY phrase, correct results are ensured only if both the table defined with the index and the table defined without the index have table elements of the same length and with the same number of occurrences.
When the object of the VARYING phrase is an index-name for another table element, one serial SEARCH statement steps through two table elements at once.
The following figure illustrates a format-1 SEARCH operation containing two WHEN phrases.

The data description entry for identifier-1 must contain an OCCURS clause with the INDEXED BY and KEY IS phrases.
identifier-1 can reference a data item that is subordinate to a data item that contains an OCCURS clause (that is, identifier-1 can be a subordinate table within a multidimensional table). In this case, the data description entry must specify an INDEXED BY phrase for each dimension of the table.
identifier-1 must not be subscripted or reference-modified.
The SEARCH ALL statement executes a binary search. The index associated with identifier-1 (the search index) need not be initialized by SET statements. The search index is varied during the search operation so that its value is at no time less than the value of the first table element, nor ever greater than the value of the last table element. The index used is always that associated with the first index-name specified in the OCCURS clause.
Before using a binary search on a multidimensional table, you must execute SET statements to set the value of the index for each superordinate dimension.
The SEARCH statement modifies only the value in the search index. Therefore, to search an entire two-dimensional to seven-dimensional table, you must execute a SEARCH statement for each dimension. In the WHEN phrases, you must specify the indexes for all dimensions.
If the search ends without the WHEN condition being satisfied and the AT END phrase is specified, imperative-statement-1 is executed. If the AT END phrase is omitted, control passes to the next statement after the SEARCH statement.
The results of a SEARCH ALL operation are predictable only when:
If a relation condition is specified in the WHEN phrase, the evaluation of the relation is based on the USAGE of the data item referenced by data-name-1. The search argument is moved to a temporary data item with the same USAGE as data-name-1, and this temporary data item is used for the compare operations associated with the SEARCH.
If the WHEN phrase cannot be satisfied for any setting of the index within this range, the search is unsuccessful. Control is passed to imperative-statement-1 of the AT END phrase, when specified, or to the next statement after the SEARCH statement. In either case, the final setting of the index is not predictable.
If the WHEN phrase can be satisfied, control passes to imperative-statement-2, if specified, or to the next executable sentence if the NEXT SENTENCE phrase is specified. The index contains the value indicating the occurrence that allowed the WHEN conditions to be satisfied.
After imperative-statement-2 is executed, control passes to the end of the SEARCH statement, unless imperative-statement-2 ends with a GO TO statement.
data-name-1 must be a valid operand for comparison with identifier-3, literal-1, or arithmetic-expression-1 according to the rules of comparison.
data-name-2 must be a valid operand for comparison with identifier-4, literal-2, or arithmetic-expression-2 according to the rules of comparison.
data-name-1 and data-name-2 cannot reference:
identifier-3 and identifier-4 cannot be data items defined with any of the usages POINTER, FUNCTION-POINTER, PROCEDURE-POINTER, or OBJECT REFERENCE.
identifier-3 and identifier-4 cannot be windowed date fields.
If identifier-3 or literal-1 is of class national, data-name-1 must be of class national.
If identifier-4 or literal-2 is of class national, data-name-2 must be of class national.
When an ASCENDING KEY or DESCENDING KEY data item is specified, explicitly or implicitly, in the WHEN phrase, all preceding ASCENDING KEY or DESCENDING KEY data-names for identifier-1 must also be specified.
Index data items cannot be used as subscripts, because of the restrictions on direct reference to them.
To ensure correct execution of a SEARCH statement for a variable-length table, make sure the object of the OCCURS DEPENDING ON clause (data-name-1) contains a value that specifies the current length of the table.
The scope of a SEARCH statement can be terminated by any of the following:
After imperative-statement-1 or imperative-statement-2 is executed, control passes to the end of the SEARCH statement, unless imperative-statement-1 or imperative-statement-2 ends with a GO TO statement.
The function of the AT END phrase is the same for a serial search and a binary search.
NEXT SENTENCE transfers control to the first statement following the closest separator period.
When NEXT SENTENCE is specified with END-SEARCH, control does not pass to the statement following the END-SEARCH. Instead, control passes to the statement after the closest following period.
For the format-2 SEARCH ALL statement, 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.
The function of the NEXT SENTENCE phrase is the same for a serial search and a binary search.
This explicit scope terminator delimits the scope of the SEARCH statement. END-SEARCH permits a conditional SEARCH statement to be nested in another conditional statement.
For more information, see Delimited scope statements.
The function of END-SEARCH is the same for a serial search and a binary search.