Function
The SEARCH statement is used to search a table for a table element that satisfies a specified condition, and to adjust the value of the associated index to indicate that table element, i.e. to set it to the corresponding occurrence number.
Format 1 | is used to perform a serial search of a table. The search for identifier-1 begins at the current value of the index assigned to identifier-1. |
Format 2 | is used to perform a binary search of a table. |
Format 1
SEARCH identifier-1 [VARYING {index-1 | identifier-2}]
[AT END imperative-statement-1]
{WHEN condition-1 {imperative-statement-2 | NEXT SENTENCE}}...
[END-SEARCH]
Syntax rules
identifier-1 specifies the table to be searched.
The data description entry of identifier-1 must include an OCCURS clause with an INDEXED BY phrase.
identifier-1 must not be subscripted or indexed or subjected to reference modification.
index-1 or identifier-2 specifies an item whose value is to be varied during execution of the SEARCH statement.
index-1 may be one of the indices for identifier-1, or an index for another table entry.
identifier-2 must therefore be described as an index data item (USAGE IS INDEX), or it must be a fixed-point numeric item described as an integer.
The AT END phrase specifies a statement which is to be executed if the search is unsuccessful.
Each condition (condition-1, condition-2,...) must be a valid condition (see section "Conditions").
condition-1... specify the conditions to be satisfied during the execution of the SEARCH statement.
imperative-statement-2... or NEXT SENTENCE specifies an action to be taken when the associated WHEN condition is satisfied: control passes to the imperative-statement or to the next sentence (that is, the statement following the SEARCH statement), depending on the option specified.
A serial search of a table begins at the table element pointed to by the index associated with identifier-1.
If, at the start of a SEARCH statement, the value of the index associated with identifier-1 is greater than the highest permissible occurrence number for identifier-1, the search will terminate immediately. If the AT END phrase is specified, imperative-statement-1 is executed. If this phrase is omitted, processing continues with the next statement.
If, at the start of a SEARCH statement, the value of the index associated with identifier-1 corresponds to a valid occurrence number for identifier-1, the serial search takes place as follows:
The WHEN conditions are evaluated in the order in which they are written.
If none of the conditions is satisfied, the index-name for identifier-1 is incremented to refer to the next occurrence of a table element; and step a) is repeated, unless the new value of the index corresponds to an occurrence number outside the valid range, in which case step d) is performed.
If one of the WHEN conditions is satisfied, the search terminates immediately. The index points to the table element that satisfied the condition. The imperative statement associated with that condition is executed.
If the end of the table is reached without the WHEN condition being satisfied, the search terminates. If AT END is specified, imperative-statement-1 is executed. If this phrase is omitted, control passes to the next sentence.
When identifier-1 is a data item subordinate to a data item that contains an OCCURS clause, then multi-dimensional tables can be searched. In this case, an index-name must be associated with each dimension of the table through the INDEXED BY phrase of the OCCURS clause. Execution of a SEARCH statement modifies only the setting of the index associated with identifier-1 (and, if present, of index-1 or identifier-2). Therefore, in order to search a two- or three-dimensional table, a SEARCH statement must be executed for each possible value of the superordinate index.
Before the SEARCH statements are executed, the corresponding indices must be preset with the required values by means of SET statements or with PERFORM VARYING (see "Example 8-69").
If, in the AT END phrase and the WHEN conditions, none of the imperative-statements specified terminates with a GO TO statement, then control will pass to the next statement after the imperative statement is executed.
If the VARYING index-1 phrase is specified, the following takes place:
If index-1 is one of the indices for identifier-1, index-1 is used for the search. No other indices are incremented.
If index-1 is an index for another table entry, the first, or only, index associated with identifier-1 is used for the search. When the index associated with identifier-1 is incremented, index-1 is simultaneously incremented to represent the next element in its table.
If the VARYING identifier-2 phrase is specified, the following actions take place:
The first, or only, index associated with identifier-1 is used for the search.
When the index associated with identifier-1 is incremented, identifier-2 is simultaneously incremented.
If identifier-2 is a numeric item, it is incremented by 1.
If identifier-2 is an index data item, it is incremented by a value equal to that used to increment the index associated with identifier-1.
If the VARYING phrase is not specified, the first, or only, index associated with identifier-1 (i.e. defined in the INDEXED BY phrase of the data description entry of identifier-1) will be used for the search.
If the END-SEARCH phrase is specified, the NEXT SENTENCE phrase must not be specified.
The scope of a SEARCH statement may 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.
Format 1 SEARCH statement
| 1) | These operations are included only when specified in the SEARCH statement. |
| 2) | Each of these control transfers is to the next sentence, unless the imperative-statement ends with a GO TO statement. |
Example 8-67
IDENTIFICATION DIVISION.
PROGRAM-ID. SEARCH1.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
TERMINAL IS T.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 LETTER-TEST PIC X VALUE LOW-VALUE.
88 LETTER-FOUND VALUE HIGH-VALUE.
01 INPUT-LETTER PICTURE A.
01 LETTER-WEIGHT-TABLE.
03 LETTER-TABLE OCCURS 26 TIMES INDEXED BY PI
VALUE FROM (1) "A01" "B03"
"C03" "D02" "E01" "F04" "G02" "H04" "I01" "J08"
"K05" "L01" "M03" "N01" "O01" "P03" "Q10" "R01"
"S01" "T01" "U01" "V04" "W04" "X08" "Y04" "Z10".
04 LETTER PICTURE A.
04 VAL PICTURE 99.
PROCEDURE DIVISION.
MAIN SECTION.
LETTER-SEARCH.
PERFORM UNTIL LETTER-FOUND
ACCEPT INPUT-LETTER FROM T
SET PI TO 1
SEARCH LETTER-TABLE VARYING PI
AT END DISPLAY "Letter is not alphabetic" UPON T
EXIT TO TEST OF PERFORM
WHEN LETTER (PI) = FUNCTION UPPER-CASE (INPUT-LETTER)
SET LETTER-FOUND TO TRUE
END-SEARCH
END-PERFORM.
FOUND.
DISPLAY LETTER (PI) " is assigned to " VAL (PI) UPON T.
STOP RUN.
In this example, the table named LETTER-TABLE consists of 26 elements.
Each element contains a letter of the alphabet followed by a value associated with the letter.
The table is indexed by the index-names LI and PI.
The SEARCH statement searches the table for the element whose LETTER matches the current contents of the area called INPUT-LETTER. The associated index is PI.The search starts at the beginning of the table since PI points to the first table element.If the search is successful, the statement GO TO FOUND is executed. In this case, the index PI points to the element satisfying the condition. For example, if INPUT-LETTER contains B, the index points to the second table element.
If the search is unsuccessful, the statements following the AT END phase are executed.
Format 2
SEARCH ALL identifier-1 [AT END imperative-statement-1]
WHEN condition {imperative-statement-2 | NEXT STATEMENT}
[END-SEARCH]
Syntax rules
identifier-1 specifies the table to be searched.
The description of identifier-1 must contain an OCCURS clause with the INDEXED BY and ASCENDING/DESCENDING phrases.
identifier-1 must not be subscripted or indexed or subjected to reference modification.
The AT END phrase specifies the statement to be executed if condition-1 cannot be satisfied for any setting of the index within the valid range (see rule 10).
condition specifies the condition that must be satisfied during the execution of the SEARCH statement.
condition must be one of the following types of conditions (see also section "Conditions" ):
A relation condition incorporating EQUAL TO or the equal sign (=) as relational operator. Either the subject or the object (but not both) of the relation condition must consist solely of one of the data-names that appear in the ASCENDING/DESCENDING phrase of identifier-1. Each data-name must be indexed by the first index associated with identifier-1. It may be qualified, but not subjected to reference modification.
A condition-name condition in which the VALUE clause describing the condition-name contains only a single literal. The conditional variable associated with the condition-name must be one of the data-names that appear in the ASCENDING/DESCENDING phrase of identifier-1.
A combine condition formed from simple conditions of the types described above, with AND as the only connective.
Any data-name that appears in the ASCENDING/DESCENDING phrase of identifier-1 may be tested in condition. However, all data-names in the ASCENDING/DESCENDING phrase preceding the data-name to be tested, must also be tested in condition. No other tests can be made in condition.
imperative-statement-2 or NEXT SENTENCE specifies an action to be taken when condition is satisfied. Control passes to imperative-statement-2 or to the statement following the SEARCH statement.
The first index associated with identifier-1 is used for the search. This index does not have to be initialized with a SET statement since its initial value is ignored for the search.
The SEARCH ALL statement is executed as follows, whereby the table must be arranged in ascending or descending order of the key fields listed in the ASCENDING/DESCENDING phrase:
During the search the value of the index associated with identifier-1 is varied.
This setting is never less than the value corresponding to the first table element, and never greater than the value corresponding to the last table element.
If condition cannot be satisfied for any setting of the index within this permitted range, control is passed to imperative-statement-1 if the AT END phrase is specified, or to the next statement if the AT END phrase is omitted.
If condition can be satisfied, the index points to the table element satisfying the condition. Control then passes to imperative-statement-2 or to the next sentence.
When identifier-1 is a data item subordinate to a data item that contains an OCCURS clause, then two- or three-dimensional tables can be searched. In this case, an index-name must be associated with each dimension of the table through the INDEXED BY phrase of the OCCURS clause. Execution of the SEARCH ALL statement modifies only the setting of the index-name associated with identifier-1. Therefore, in order to search a two- or three-dimensional table, a SEARCH ALL statement must be executed for each possible value of the superordinate index.
If, in the AT END phrase and the WHEN conditions, none of the statements specified terminates with a GO TO statement, then control will pass to the next statement after the imperative-statement is executed.
If the END-SEARCH phrase is specified, the NEXT SENTENCE phrase must not be specified.
The scope of a SEARCH statement may be terminated by any of the following:
An END-SEARCH phrase at the same level of nesting.
A period at the end of the SEARCH statement.
An ELSE or END-IF phrase associated with a previous IF statement.
Example 8-68
(WHEN conditions)
Data Division entries:
...
77 A-VALUE PICTURE 9.
...
02 TABLE-ITEM OCCURS 5 TIMES ASCENDING KEY IS A B C;
INDEXED BY I.
03 A PICTURE 99.
03 B PICTURE 9.
88 UNDER-30 VALUE 1.
88 OVER-30 VALUE 2.
03 C PICTURE 9.
...
Valid WHEN phrases (in Procedure Division)
WHEN A(I) = 10 WHEN A(I) = 20 AND UNDER-30(I) WHEN A(I) = 15 AND OVER-30(I) AND C(I) = A-VALUE
Example 8-69
IDENTIFICATION DIVISION.
PROGRAM-ID. SRCHALL.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
TERMINAL IS T
SYSIPT IS INFILE.
DATA DIVISION.
WORKING-STORAGE SECTION.
77 IPD PIC 9(3).
77 INPUT-LN PIC 9(6).
01 EMPLOYEE-TABLE.
02 PERSON OCCURS 100 TIMES INDEXED BY PI,
ASCENDING KEY IS DEPARTMENT LIFE-NUMBER.
03 DEPARTMENT PIC 9(3).
03 LIFE-NUMBER PIC 9(6).
03 NAME PIC X(20).
PROCEDURE DIVISION.
MAIN SECTION.
P1.
PERFORM VARYING PI FROM 1 BY 1 UNTIL PI > 100
ACCEPT PERSON (PI) FROM INFILE
END PERFORM
SEARCH ALL PERSON
AT END
DISPLAY "Person is missing" UPON T
WHEN DEPARTMENT (PI) = IPD AND LIFE-NUMBER (PI) = INPUT-LN
DISPLAY DEPARTMENT LIFE-NUMBER NAME UPON T
END-SEARCH
STOP RUN.
In this example, the table named PERSON consists of 2000 elements.
Each element in the table consists of a 3-byte numeric item called DEPARTMENT, a 6-byte numeric item called LIFE-NUMBER and a 20-byte alphanumeric item called NAME.
The table is arranged in ascending order by DEPARTMENT and, within DEPARTMENT, in ascending order by LIFE-NUMBER.
The first portion of the table might have the following contents:
DEPARTMENT | LIFE-NUMBER | NAME |
101 | 123456 | ADAM, D. |
101 | 234561 | LANGEWIESCHE, W. |
101 | 123456 | ADAM, D. |
101 | 523618 | EBERLE, F. |
183 | 200305 | DAUTZENBERG, K. |
183 | 328512 | REINHARDT, M. |
183 | 433333 | GRUEN, L. |
183 | 987245 | RICHTER, L. |
557 | 328835 | SCHMIDT, S. |
557 | 775247 | ALBRECHT, N. |
The SEARCH statement searches the table for an element whose DEPARTMENT matches the current contents of the area called IPD, and whose LIFE-NUMBER matches the current contents of the area called INPUT-LN. If the search is successful, the DISPLAY statement is executed. The index-name, PI, points to the element satisfying the condition.
For example, if IPD contains 183 and INPUT-LN contains 328512, the index-name points to the fifth element of the table.
If the search is unsuccessful, an appropriate message is issued.