Rational Developer for System z
COBOL for Windows, Version 7.5, Language Reference


SEARCH statement

The SEARCH statement searches a table for an element that satisfies the specified condition and adjusts the associated index to indicate that element.

Format 1: serial search
Read syntax diagramSkip visual syntax diagram>>-SEARCH--identifier-1--+---------------------------+---------->
                         '-VARYING--+-identifier-2-+-'  
                                    '-index-name-1-'    
 
>--+-------------------------------------+---------------------->
   '-+----+--END--imperative-statement-1-'  
     '-AT-'                                 
 
   .-----------------------------------------------.  
   V                                               |  
>----WHEN--condition-1--+-imperative-statement-2-+-+------------>
                        '-NEXT-SENTENCE----------'    
 
>--+------------+----------------------------------------------><
   '-END-SEARCH-'  
 

Format 2: binary search
Read syntax diagramSkip visual syntax diagram>>-SEARCH ALL--identifier-1------------------------------------->
 
>--+-------------------------------------+---------------------->
   '-+----+--END--imperative-statement-1-'  
     '-AT-'                                 
 
>--WHEN--+-data-name-1--+----+--+-EQUAL--+----+-+--+-identifier-3------------+-+-->
         |              '-IS-'  |        '-TO-' |  +-literal-1---------------+ |  
         |                      '- = -----------'  '-arithmetic-expression-1-' |  
         '-condition-name-1----------------------------------------------------'  
 
   .----------------------------------------------------------------------------------.  
   V                                                                                  |  
>----+------------------------------------------------------------------------------+-+-->
     '-AND--+-data-name-2--+----+--+-EQUAL--+----+-+--+-identifier-4------------+-+-'    
            |              '-IS-'  |        '-TO-' |  +-literal-2---------------+ |      
            |                      '- = -----------'  '-arithmetic-expression-2-' |      
            '-condition-name-2----------------------------------------------------'      
 
>--+-imperative-statement-2-+--+------------+------------------><
   '-NEXT SENTENCE----------'  '-END-SEARCH-'  
 

Use format 1 (serial search) when the table that you want to search has not been sorted. Use format 1 to search a sorted table when you want to search serially through the table or you want to control subscripts or indexes.

Use format 2 (binary search) when you want to efficiently search across all occurrences in a table. The table must previously have been sorted.

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:

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:

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:

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.

Begin description. 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. End description.

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:

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 data-name-1 is a numeric item, the temporary data item is signed or unsigned consistent with the presence or absence of a sign in the data description of data-name-1. If the search argument is signed and data-name-1 is unsigned, the sign will be removed from the search argument before the comparison is done.

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:

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:

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

 

END-SEARCH phrase

This explicit scope terminator delimits the scope of the SEARCH statement. END-SEARCH permits a conditional SEARCH statement to be nested in another conditional statement.

For more information, see Delimited scope statements.

The function of END-SEARCH is the same for a serial search and a binary search


Terms of use | Feedback

Copyright IBM Corporation 1996, 2008.
This information center is powered by Eclipse technology. (http://www.eclipse.org)