General notes:
1. The table name identifier used in SEARCH must be the table name specified in the OCCURS phrase of the table declaration. You cannot use the 01 table label that starts the table declaration.
2. If END-SEARCH is used NEXT SENTENCE cannot be used. Where possible it is best to use the sentence terminator, END-SEARCH. Unintended logic errors are often introduced by the use of NEXT SENTENCE and are easily avoided by the use of END-SEARCH.
Notes regarding sequential searches (SEARCH):
1. A sequential search is conducted as follows:
a) The search cycle begins by verifying that the value of the index data item falls within the range of the table size (the range is from 1 to the value specified in the OCCURS clause of the record definition).
b) If the index value is valid, then each WHEN condition phrase is evaluated until either a match is found or until all WHEN conditions have been tested.
c) If there is no match, the value of the index is incremented by one, validated (as in step a), and the WHEN condition evaluation cycle is repeated.
d) Steps a - c iterate until either a match is found or the value of the index exceeds the table range, indicating that the entire table has been searched.
e) If a match is found, the search terminates and the imperative statement associated with the WHEN clause is executed. Program execution then resumes immediately after the SEARCH statement. Note that the value of the index data item remains set to the value of the subscript of the matched entry.
f) If the value of the search index ever becomes less than one or greater than the table size, the search terminates, the optional AT END statement, if present, is executed, and program execution continues immediately after the SEARCH statement.
2. The index data item named in the INDEXED BY clause is used to index the table in the sequential search and must be explicitly initialized in the program. Use SET to assign the initial value. When the search results in a match, the index data item remains set to the table subscript of the matching entry. Saving or preserving this value makes it possible to make another search of the table for a subsequent match.
Initializing the index data item:
a) If the entire table is to be searched, the index data item should be assigned, using SET, the value 1, thereby starting the search with the first record.
b) If the search is to begin with an entry other than the first, then the index data item should be assigned the value of the position of the first table entry to be checked. For example, to start the search at table entry 10, assign the value 10 to the index data item.
c) If, after a search finds a match, you want to make an additional search of the table to find a subsequent match, the value of the index data item should be preserved and then reassigned so that the next search begins at 1 + index-item.
3. When searching tables that are not full (do not contain valid entries for every occurrence in the table), use a WHEN clause to test for the actual end-of-table condition. If the search is allowed to proceed into the unused portion of the table, garbage values in the unfilled table space will give unpredictable results. See code example 2.
4. The relational match conditions associated with each WHEN clause may be connected with the logical connectors AND or OR thereby specifying multiple or alternate match conditions. For example:
WHEN NAME = SEARCH-NAME OR SIZE < MAX-SIZE
5. Use of the VARYING phrase: The VARYING phrase allows alternate or multiple indexes to be incremented by the search loop. If VARYING is omitted, the first index-item defined in the INDEXED BY phrase of the OCCURS clause (for the table) is incremented.
If the VARYING phrase is included, the index item named after VARYING is incremented, as well as the first named index in the INDEXED BY phrase, with one exception. If the index named after VARYING is also named in the INDEXED BY phrase, then it is the only index incremented.
Notes regarding binary searches (SEARCH ALL):
1. The binary search is conducted as follows:
a) The search begins at the midpoint of the table (for example, 50 of 100) and compares the value of the table entry with the search item to determine if there is a match.
b) If there is no match, SEARCH determines whether the search item is logically located in the upper or lower half of the table (0-49, or 51-100).
c) SEARCH then finds the midpoint of the half that logically contains the search item and determines if the table element at the midpoint matches the search item.
d) If there is no match, SEARCH again determines whether the search item is logically located in the upper or lower half of the remaining range.
e) This process iterates until the search item is found or until it is determined that the table does not contain the search item (the remaining table range becomes null).
f) If at any time a match is found, the search immediately terminates and the imperative statement associated with the WHEN clause is executed. Program execution then resumes immediately after the SEARCH statement.
2. Binary searches require sequential, ordered tables (via use of the ASCENDING/DESCENDING KEY phrase). The table must be ordered as specified by the KEY IS phrase of the table definition.
3. The matching conditions of the WHEN clause must identify a unique table entry.
4. Binary searches are best suited to large tables (typically 50 records or more) where the binary search algorithm significantly reduces the average number of lookups per match.
5. Unlike a sequential search, the binary search format permits only one WHEN clause.
6. Because only one WHEN clause is permitted and because the index value is automatically set by the program, it is not possible to SEARCH partially full tables.
7. The SEARCH ALL match conditions are very restrictive. Match condition evaluation is restricted to evaluation of a condition-name, which can represent only a single value (no range or sequence of values permitted), or a condition which tests for equality.
8. The table data item and the index must be on the left side of the condition statement.
9. Multiple condition tests are permitted but can be connected only with an AND (no OR).
10. Any table item or condition-name referenced must be named in the KEY IS phrase of the OCCURS clause of the table definition.
11. The VARYING option is not permitted.
12. When a match is found, the index retains the value of the table subscript of the matched entry. If no match is found the value of the index is unpredictable.