 |
HP COBOL
Reference Manual
6.8.31 SEARCH
Function
The SEARCH statement searches for a table element that satisfies a
condition. It sets the value of the associated index to point to the
table element.
src-table
is a table identifier.
pointr
is an index-name or the identifier of a data item described as USAGE
INDEX, or an elementary numeric data item with no positions to the
right of the assumed decimal point.
cond
is any conditional expression.
stment
is an imperative statement.
elemnt
is an indexed data-name. It refers to the table element against which
the argument is compared.
arg
is the argument tested against each elemnt in the search. It
is an identifier, a literal, or an arithmetic expression.
cond-name
is a condition-name.
Syntax Rules
Both Formats
- src_table must not be subscripted, indexed, or reference
modified. However, its description must contain an OCCURS clause with
the INDEXED BY phrase.
- If the END-SEARCH phrase is specified, the NEXT SENTENCE phrase
must not be specified.
Format 2
- src_table must contain the KEY IS phrase in its OCCURS
clause.
- Each cond-name must be defined as having only one value.
The data-name associated with cond-name must be in the KEY IS
phrase of the OCCURS clause for src-table.
- Each elemnt:
- Can be qualified
- Must be indexed by the first index-name associated with
src-table, in addition to other indexes or literals required
for uniqueness
- Must be in the KEY IS phrase of the OCCURS clause for
src-table
- Neither arg nor any identifier in its arithmetic
expression can either:
- Be used in the KEY IS phrase of the OCCURS clause for
src-table
- Be indexed by the first index-name associated with
src-table
- When elemnt or the data-name associated with cond-name
is in the KEY phrase of the OCCURS clause for src-table,
each preceding data-name (or associated cond-name) in that
phrase must also be referenced.
General Rules
Both Formats
- After executing a stment that does not end with a GO TO
statement, control passes to the end of the SEARCH statement.
- src_table can be subordinate to a data item that contains
an OCCURS clause. In that case, an index-name must be associated with
each dimension of the table through the INDEXED BY phrase of the OCCURS
clause. The SEARCH statement modifies the setting of only the
index-name for src-table (and pointr, if there is
one).
A single SEARCH statement can search only one dimension of a
table; therefore, you must execute SEARCH statements repeatedly to
search through a multidimensional table. Before each execution, SET
statements must execute to change the values of index-names that need
adjustment.
Format 1
- The Format 1 SEARCH statement searches a table serially, starting
with the current index setting.
- The index-name associated with src-table can contain a
value that indicates a higher occurrence number than is allowed for
src-table. If the SEARCH statement execution starts when this
condition exists, the search terminates immediately. If there is an AT
END phrase, stment then executes. Otherwise, control passes to
the end of the SEARCH statement.
- If the index-name associated with src-table indicates a
valid src-table occurrence number, the SEARCH statement
evaluates the conditions in the order they appear. It uses the index
settings to determine the occurrence numbers of items to test.
If
no condition is satisfied, the index-name for src-table is
incremented to refer to the next occurrence. The condition evaluation
process repeats using the new index-name settings. However, if the new
value of the index-name for src-table indicates a table
element outside its range, the search terminates as in General Rule 3a.
When a condition is satisfied:
- The search terminates immediately.
- The stment associated with the condition executes.
- The index-name remains set at the occurrence that satisfied the
condition.
- If there is no VARYING phrase, the index-name used for the search
is the first index-name in the OCCURS clause for src-table.
Other src-table index-names are unchanged.
- If there is a VARYING phrase, pointr can be an index-name
for src-table. (pointr is named in the INDEXED BY
phrase of the OCCURS clause forsrc-table.) The search then
uses that index-name. Otherwise, it uses the first index-name in the
INDEXED BY phrase.
- pointr also can be an index-name for another table.
(pointr is named in the INDEXED BY phrase in the OCCURS clause
for that table entry.) In this case, the search increments the
occurrence number represented by pointr by the same amount,
and at the same time, as it increments the occurrence number
represented by the src-table index-name.
- If pointr is an index data item rather than an index-name,
the search increments it by the same amount, and at the same time, as
it increments the src-table index-name. If pointr is
not an index data item or an index-name, the search increments it by
one when it increments the src-table index-name.
- Example 3, "Serial search with two WHEN phrases," illustrates the
operation of a Format 1 SEARCH statement with two WHEN phrases.
Format 2
- A SEARCH ALL operation yields predictable results only when:
- The data in the table has the same order as described in the KEY IS
phrase of the OCCURS clause for src-table.
- The contents of the keys in the WHEN phrase identify a unique table
element.
- SEARCH ALL causes a nonserial (or binary) search. It ignores the
initial setting of the src-table
index-name and varies its setting during execution.
- If the WHEN phrase conditions are not satisfied for any index
setting in the allowed range, control passes to the AT END phrase
stment, if there is one, or to the end of the SEARCH
statement. In either case, the setting of the src-table
index-name is not predictable.
- If all the WHEN phrase conditions are satisfied for an index
setting in the allowed range, control passes to either stment
or the next sentence, whichever is in the statement. The
src-table index-name then indicates the occurrence number that
satisfied the conditions.
- The index-name used for the search is the first index-name in the
OCCURS clause for src-table. Other src-table
index-names are unchanged.
Additional References
Examples
The examples assume these Data Division entries:
01 CUSTOMER-REC.
03 CUSTOMER-USPS-STATE PIC XX.
03 CUSTOMER-REGION PIC X.
03 CUSTOMER-NAME PIC X(15).
01 STATE-TAB.
03 FILLER PIC X(153)
VALUE
"AK3AL5AR5AZ4CA4CO4CT1DC1DE1FL5GA5HI3
- "IA2ID3IL2IN2KS2KY5LA5MA1MD1ME1MI2MN2
- "MO5MS5MT3NC5ND3NE2NH1NJ1NM4NV4NY1OH2
- "OK4OR3PA1RI1SC5SD3TN5TX4UT4VA5VT1WA3
- "WI2WV5WY4".
01 STATE-TABLE REDEFINES STATE-TAB.
03 STATES OCCURS 51 TIMES
ASCENDING KEY IS STATE-USPS-CODE
INDEXED BY STATE-INDEX.
05 STATE-USPS-CODE PIC XX.
05 STATE-REGION PIC X.
01 STATE-NUM PIC 99.
01 STATE-ERROR PIC 9.
01 NAME-TABLE VALUE SPACES.
03 NAME-ENTRY OCCURS 8 TIMES
INDEXED BY NAME-INDEX.
05 LAST-NAME PIC X(15).
05 NAME-COUNT PIC 999.
|
- Binary search:
(The correctness of this statement's operation
depends on the ascending order of key values in the source table.)
INITIALIZE-SEARCH.
MOVE "NH" TO CUSTOMER-USPS-STATE.
SEARCH ALL STATES
AT END
MOVE 1 TO STATE-ERROR
GO TO SEARCH-END
WHEN STATE-USPS-CODE (STATE-INDEX) = CUSTOMER-USPS-STATE
MOVE 0 TO STATE-ERROR
MOVE STATE-REGION (STATE-INDEX) TO CUSTOMER-REGION.
SEARCH-END.
DISPLAY " ".
DISPLAY "Customer State index number = " STATE-INDEX WITH CONVERSION
" Region = " STATE-REGION (STATE-INDEX)
" State Error Code = " STATE-ERROR.
|
Following are the results of the binary search:
Customer State index number = 31 Region = 1 State Error Code = 0
|
- Serial search with WHEN phrase:
INITIALIZE-SEARCH.
MOVE "2" TO CUSTOMER-REGION.
SEARCH-LOOP.
SEARCH STATES
AT END
MOVE 1 TO STATE-ERROR
GO TO SEARCH-END
WHEN STATE-REGION (STATE-INDEX) = CUSTOMER-REGION
MOVE 0 TO STATE-ERROR
DISPLAY STATE-USPS-CODE (STATE-INDEX)
" " STATE-INDEX WITH CONVERSION
" " STATE-ERROR.
SET STATE-INDEX UP BY 1.
GO TO SEARCH-LOOP.
SEARCH-END.
|
The following lists the results of this serial search:
IA 13 0
IL 15 0
IN 16 0
KS 17 0
MI 23 0
MN 24 0
NE 30 0
OH 36 0
WI 49 0
|
- Serial search with two WHEN phrases:
|
