The SEARCH statement searches an indexed table for a specific table entry. The search may be sequential or binary (SEARCH or SEARCH ALL). The search terminates when either a match is found (first match), or when the entire table has been searched.
Format 1
SEARCH table-name [ VARYING index-item ]
[ AT END statement-1 ]
{ WHEN srch-cond {statement-2 } } ...
{NEXT SENTENCE }
[ END-SEARCH ]
Format 2
SEARCH ALL table-name
[ AT END statement-1 ]
WHEN { tbl-item {IS EQUAL TO} value }
{ {IS = } }
{ cond-name }
[ AND { tbl-item {IS EQUAL TO} value } ] ...
{ {IS = } }
{ cond-name }
{ statement-2 }
{ NEXT SENTENCE }
[ END-SEARCH ]
Syntax Rules
1. Table-name is a data item that must contain an OCCURS clause including an INDEXED BY phrase. Table-name must not be subscripted in the SEARCH statement. In Format 2, table-name must also contain the KEY IS phrase in its OCCURS clause.
2. Index-item is a numeric integer data item or an index name. It may not be subscripted by the first index name in the INDEXED BY phrase in the OCCURS clause of table-name.
3. Srch-cond is a conditional expression.
4. Statement-1 and statement-2 are imperative statements.
5. Value may be a data item, a literal, or an arithmetic expression. It must be legal to compare value with tbl-item. No data item in value may be referenced in the KEY IS phrase in the OCCURS clause of table-name, nor may it be subscripted by the first index-name associated with table-name.
6. Cond-name is a condition-name (level 88) that must be defined as having only a single value. The condition-variable associated with cond-name must appear in the KEY IS phrase in the OCCURS clause of table-name.
7. Tbl-item must be subscripted by the first index-name associated with table-name along with other subscripts as required. It must be referenced in the KEY IS phrase in the OCCURS clause of table-name. Tbl-item may not be reference modified.
8. In Format 2, when a tbl-item or a cond-name is referenced, all preceding data-names in the KEY IS phrase in the OCCURS clause of table-name (or their associated condition-names) must also be referenced.
Format 1
1. The Format 1 SEARCH statement searches a table serially starting with the current index setting.
a) If the index-name associated with table-name contains a value that is higher than the highest occurrence number for table-name, the search terminates immediately. If the AT END phrase is specified, statement-1 executes. Control then passes to the end of the SEARCH statement.
b) If the index-name associated with table-name contains a valid occurrence number, the SEARCH statement evaluates the WHEN conditions (srch-cond) in the order they appear. If no condition is satisfied, the index-name associated with table-name is set to the next occurrence number. The evaluation process is then repeated. This process ends when a condition is satisfied or an occurrence number outside of the range of table-name is generated. In this second case, processing continues as in step (1a) above.
c) When a srch-cond is satisfied, the SEARCH terminates and the associated statement-2 executes (or control passes to the next sentence if NEXT SENTENCE is used). The index-name associated with table-name remains set at its current value. Control then passes to the end of the SEARCH statement.
2. If there is no VARYING phrase specified, the index-name used for the search is the first index-name in the INDEXED BY phrase associated with table-name. Other index-names associated with table-name remain unchanged.
3. If the VARYING phrase is specified, and index-item names an index-name associated with table-name, then that index-name is used for the search operation. If index-name names some other index-name or a numeric data item, that item is incremented by 1 every time the index-name associated with the search operation is incremented. The index-name specified in rule 2 is used for the search procedure.
Format 2
1. A Format 2 SEARCH performs a binary search of an ordered table. It yields predictable results only when:
a) the data in the table has the same order as specified by the KEY IS phrase associated with table-name
b) the contents of the keys in the WHEN phrase identify a unique table element
2. The initial value of the table-name index-name is ignored. It is varied in a non-linear manner by the SEARCH operation until the WHEN conditions are satisfied or the table has been searched.
3. If the WHEN phrase conditions are not satisfied for any index setting, control passes to the AT END phrase statement-1, if any, or to the end of the SEARCH statement. The setting of the table-name index-name is not predictable in this case.
4. If all of the WHEN phrase conditions are satisfied for an index setting, control passes either to the associated statement-2 or to the next sentence, whichever is specified. The table-name index-name indicates the occurrence number that satisfied the conditions.
5. The index-name used for the search is the first index-name listed in the INDEXED BY phrase associated with table-name. Other index-names remain unchanged.
More: