Serial search

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

identifier-1 (serial 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.

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 Start of changealternate index defined for an appropriately defined alternate table. The element length of the table being searched and the element length of the alternate table to which the alternate index is associated should match. You must initialize the index (defined in the INDEXED BY phrase) for identifier-1 to a valid value for the table being searched, even when the index of the table is not referenced or used in the serial search.End of change

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.

identifier-1 must not be a dynamic-length group item or a dynamic-length elementary item.

AT END
The condition that exists when the search operation terminates without satisfying the condition specified in any of the associated WHEN phrases.

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:

  • The conditions in the WHEN phrase are evaluated in the order in which they are written.
  • If none of the conditions is satisfied, the index for identifier-1 is increased to correspond to the next table element, and step 1 is repeated.
  • If upon evaluation one of the WHEN conditions is satisfied, the search is terminated immediately, and the imperative-statement-2 associated with that condition is executed. The index points to the table element that satisfied the condition. If NEXT SENTENCE is specified, control passes to the statement following the closest period.
  • If the end of the table is reached (that is, the value of the incremented index is greater than the highest possible occurrence number) without the WHEN condition being satisfied, the search is terminated.

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
     . . . 

VARYING phrase

index-name-1
One of the following actions applies:
  • If index-name-1 is an index for identifier-1, this index is used for the search. Otherwise, the first (or only) index-name is used.
  • If index-name-1 is an index for another table element, then the first (or only) index-name for identifier-1 is used for the search; the occurrence number represented by index-name-1 is increased by the same amount as the search index-name and at the same time.

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.

identifier-2
Must be either an index data item or an elementary integer item. identifier-2 cannot be subscripted by the first (or only) index-name specified for identifier-1. During the search, one of the following actions applies:
  • If identifier-2 is an index data item, then, whenever the search index is increased, the specified index data item is simultaneously increased by the same amount.
  • If identifier-2 is an integer data item, then, whenever the search index is increased, the specified data item is simultaneously increased by 1.

WHEN phrase (serial search)

condition-1
Can be any condition described under Conditional expressions.

The following figure illustrates a format-1 SEARCH operation containing two WHEN phrases.

This figure shows that only one SEARCH WHEN phrase is selected; if no WHEN phrase is satisfied by the search, the AT END phrase is selected.