Rational Developer for System z
Enterprise COBOL for z/OS, Version 4.1, Language Reference


SEARCH statement

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

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 a windowed date field. 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.

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
  • Windowed date fields
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.

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.

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.

Search statement considerations

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:

  • An END-SEARCH phrase at the same level of nesting
  • A separator period
  • An ELSE or END-IF phrase associated with a previous IF statement

AT END and WHEN phrases

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

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.


Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)