Binary search

The topic provides information of using the SEARCH statement for binary search.

identifier-1 (binary search)

identifier-1 identifies the table that is to be searched. identifier-1 references all occurrences within that table.

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.

AT END

The condition that exists when the search operation terminates without satisfying the conditions specified in the WHEN phrase.

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:

The data in the table is ordered in ASCENDING KEY or DESCENDING KEY order
The contents of the ASCENDING or DESCENDING keys specified in the WHEN clause provide a unique table reference.

WHEN phrase (binary search)

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.

condition-name-1 , condition-name-2

Each condition-name specified must have only a single value, and each must be associated with an ASCENDING KEY or DESCENDING KEY data item for this table element.

data-name-1 , data-name-2

Must specify an ASCENDING KEY or DESCENDING KEY data item in the table element referenced by identifier-1 and must be subscripted by the first index-name associated with identifier-1. Each data-name can be qualified.

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:

Floating-point data items
Group items containing variable-occurrence data items

identifier-3 , identifier-4

Must not be an ASCENDING KEY or DESCENDING KEY data item for identifier-1 or an item that is subscripted by the first index-name for identifier-1.

identifier-3 and identifier-4 cannot be data items defined with any of the usages POINTER, FUNCTION-POINTER, PROCEDURE-POINTER, or OBJECT REFERENCE.

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.

literal-1 , literal-2

literal-1 or literal-2 must be a valid operand for comparison with data-name-1 or data-name-2, respectively.

arithmetic-expression

Can be any of the expressions defined under Arithmetic expressions, with the following restriction: Any identifier in arithmetic-expression must not be an ASCENDING KEY or DESCENDING KEY data item for identifier-1 or an item that is subscripted by the first index-name for identifier-1.

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.