Chapter 6
In the other chapters of this manual, you learned about the parts of the FIND syntax that
tell the system what to retrieve. Command parameters tell the system how to control
supplemental activities performed during or after the retrieval process. There are five
features that the command parameters affect: result sets, thesauri, command procedures
(also called procs), programs, and general processes. See the following table for a
description of each command parameter’s purpose. In the following table the commands
are grouped according to the feature they affect.
Table 6-1: FIND command parameters
Result
Sets
To
Use this parameter
Create or display information about
intermediate result sets, or suppress this
action.
INTERMEDIATE
Count and highlight references in the retrieved
records, or suppress this action.
REFERENCES
Display a message about the result set after a
search is completed, or suppress this action.
RESULT_MESSAGE
193
Thesauri
Procs and
Programs
General
Processes
194 
To
Use this parameter
Use a particular language, in multilingual
applications using multilingual thesauri, to
interpret the search values you enter.
LANGUAGE
Limit the hierarchical levels used when
referencing a thesaurus.
LEVEL
Use a thesaurus to enhance your search
value(s), or suppress this action.
THESAURUS
Branch to a particular label in a proc or
program if the FIND command fails.
ERR
Set record-level locks during a transaction
within a proc or program.
INTENT
Branch to a particular label in a proc or
program if a deadlock situation occurs.
ROLLBACK
Specify a time limit for processing the FIND
command.
TIMEOUT
Wait for locked records to become available,
or suppress this action within a proc or
program.
WAIT
Specify whether retrieval tests are evaluated
by using indexes or scanning records
SEARCH_OPTION
FIND Command Parameter Syntax
END Delimiter
You can add command parameters to the end of any of the FIND syntax variations
discussed in this manual. The first command parameter that you add must be preceded by
the END delimiter and a comma, as shown in the syntax below:
END ,
command
parameter
=
value
,
command
parameter
=
value
Command Parameters
All values that can be entered for the command parameter box are listed in Table 6-1
above. You can also use the command parameters’ abbreviations. These abbreviations,
as well as the values which can be entered for the value box, are given in each command
parameter’s description below.
The following are examples of FIND commands that use command parameters:
FIND EMPLOYEE WHERE DNO = 201 END, RESULT_MESSAGE = NO
FIND PLACE WHERE LOCATION = 'UNITED STATES' END, +
THESAURUS = YES, REFERENCES = NO
FIND EMPLOYEE, DEPENDENT WHERE EMPLOYEE.ENO := +
DEPENDENT.ENO AND JOB = CLERK AND +
RELATIONSHIP = 'HUSBAND', 'WIFE' END, +
INTERMEDIATE = COUNT, WAIT = YES, INTENT = UPDATE
The command parameters are listed below alphabetically. Parameter names that can be
abbreviated are displayed in a combination of uppercase (required) and lowercase
(optional) characters. For example, the command parameter WAIt can be abbreviated to
WAI. Default values are bolded.
195
ERR
ERR = errlabel
(Optional)
This parameter tells the system to branch to a particular label in a command procedure or
program if the FIND command fails. It is not necessary for FIND commands executed
during an interactive session.
The following is a sample proc using a FIND command with the ERR parameter:
FIND EMPLOYEE WHERE DNO = 201 END, ERR = ERROR_MESSAGE
.
.
.
ERROR_MESSAGE
TELL 'The FIND command failed.'
RETURN
For more information about procs, see Command Procedures. For more information
about programs, see the BASIS programming manuals:

Programming with OpenAPI

Programming with DHI

Programming for BASIS Conventional Records
INTENT
INTENT = CURRENT | CHECKOUT | READ | UPDATE
(Optional)
This parameter tells the system which record-level locks to set during a transaction within
a command procedure or program. It is necessary only for FIND commands executed in a
transaction. A transaction is a sequence of operations that constitute one logical action
on a view. Transactions are mainly used to update records in a view. For more
information about transactions, see Database Loading and Maintenance.
When you access records through a transaction, you can set several levels of protection
(i.e., locks). These locks determine what you and other users can and can’t do to the
records during the transaction. There are four levels of protection: database, model,
view, and record. The INTENT command parameter sets protection at the record level;
that is, each record retrieved by the FIND command is locked according to the value
196 
specified for INTENT. The possible values for INTENT are described in the following
table. The default value is CURRENT.
Value
Description
CURRENT
This value acts the same as the last START/TRAN parameter (see
below) you specified for the view that your FIND command
searches. Therefore, if the view appears on the list of EX, PW, or
SW START/TRAN parameters, CURRENT translates to UPDATE.
If the view appears on the list of PR or SR START/TRAN
parameters, or if there was no view lock defined, CURRENT
translates to READ. If the FIND command is executed outside of a
transaction, CURRENT translates to READ. The default is
CURRENT.
CHECKOUT
Records in the result set are placed in the queue area and given the
status of CHECKOUT. The records remain with CHECKOUT
status in the queue area until they are explicitly or implicitly checked
back in. To specify this value for INTENT, you must have the
HOLD privilege, and the FIND command must be executed within a
transaction. For information about the queue area, see “Components
of Advanced Searches.” For additional information, see Interactive
FQM Commands.
Note: On Windows operating systems, the queue area does not store
data records; it stores only Queue Status Records. For information
about the queue area on Windows, see Database Loading and
Maintenance, “Using Queues.”
READ
Records in the result set may be read only.
UPDATE
Records in the result set may be modified or deleted. To specify this
value, you must execute the FIND command within a transaction.
Within a transaction, the record-level locks are affected by the view-level locks set with
the parameters in the START/TRAN command. The possible parameters for
START/TRAN are EX, PW, SW, PR, and SR. For more information about the
START/TRAN command, see Interactive FQM Commands.
The table below shows what you and others can do to the records in the view when you
set the INTENT parameters for FIND and the parameters for START/TRAN to each
possible value. When the transaction is complete, the locks disappear.
197
START/
TRAN
FIND
You can
Others can
EX
CHECKOUT
read or update
not access any records in
view
READ
read
"
UPDATE
read or update
"
CHECKOUT
read or update
read any record in view
READ
read
"
UPDATE
read or update
"
CHECKOUT
read or update
read any record in view
READ
read
read any record in view
update records not in
result set
UPDATE
read or update
read any record in view
CHECKOUT
N/A
N/A
READ
read
read any record in view
UPDATE
N/A
N/A
CHECKOUT
N/A
N/A
READ
read
read any record in view
update other records in
view
UPDATE
N/A
N/A
PW
SW
PR
SR
Note: N/A means that the INTENT value for FIND is Not Allowed, given the INTENT
value for START/TRAN. In this case, the system will return an error message.
198 
INTERMEDIATE
INTERmediate = NONE | COUNTS | SETS
(Optional)
This parameter tells the system whether or not to create or display information about
intermediate result sets. An intermediate result set is the result set that each retrieval test
in a FIND command that combines multiple retrieval tests would generate had each been
executed in a separate FIND command. By default, when you execute a FIND command,
the system does not create intermediate result sets so that it may process the command
more efficiently. However, there may be times when you need information about the
intermediate result sets. For instance, you may want to see the number of members and
references for each intermediate result set, or you may want to display the contents of
each.
The possible values and their effects are shown in the table below:
If you enter
The system
NONE
executes the FIND command without regard to the intermediate
result sets
COUNTS
displays a message showing the number of members and references
for each intermediate result set
SETS
creates intermediate result sets whose contents can be displayed
This parameter cannot be set to COUNTS or SETS for commands that search nonindexed fields or for commands that contain a nested WHERE clause. Intermediate sets
are not available for composite views. The default is NONE.
Example 1: COUNTS
Suppose you want to retrieve the records of operators who make less than 1000.
However, you also want to know how many operators there are all together and how many
employees have salaries less than 1000. You could enter the following FIND command:
FIND EMPLOYEE WHERE JOB = 'OPERATOR' AND SALARY < 1000 +
END, INTERMEDIATE = COUNTS
199
A message showing the number of members and references for the intermediate result sets
and the final result set replaces the usual result set message.
intermediate
Set
1
Ref
9
14
4
Mem
9
14
2
result sets
Description
EMPLOYEE WHERE JOB = 'OPERATOR'
EMPLOYEE WHERE SALARY < 1000
employee where job = 'operator' and salary <1000
Now you know that:

there are 9 operators in the company

14 of the employees earn less than 1000

2 of the operators earn less than 1000
Notice that only the final result set is assigned a set number. This is because the system
does not create the intermediate result sets; it only displays information about them. If
you display the final result set, you can see which operators earn less than 1000:
TYPE NAME, JOB, SALARY
Name
-------------FORREST, CATHY
WOOD, DWAYNE
Job Title
-----------Operator
Operator
Sal/Month
---------$902.00
$930.00
Example 2: SETS
Suppose you want the same information as in example 1, but you also want the system to
create the intermediate result sets so you can display their contents. Then you would
execute the same command as in example 1 but set INTERMEDIATE to SETS:
FIND EMPLOYEE WHERE JOB = 'OPERATOR' AND SALARY < 1000 END, +
INTERMEDIATE = SETS
The system displays the following message:
Set
3
4
5
Ref
9
14
4
Mem
9
14
2
Description
EMPLOYEE WHERE JOB = 'OPERATOR'
EMPLOYEE WHERE SALARY < 1000.00
employee where job = 'operator' and
salary < 1000
Notice that this time the system assigns set numbers to the intermediate result sets as well
as to the final result set. The final result set is the current result set since it is the last one
200 
created. Therefore, since the TYPE command displays the current result set by default,
you must specify a set number to display an intermediate result set. For more information
about the TYPE command, see Interactive FQM Commands.
To display the records of operators, you would enter:
TYPE NAME, JOB, SALARY, SET = 3
Name
-------------CLARK, RICHARD
WELCH, PATRICIA
BECK, GARY
MILLS, GLENN
CHERNIAVSKY, ELAINE
FORREST, CATHY
WOOD, DWAYNE
BREKHOVSKIKH, LARRY
HANKLEY, DAVE
Job Title
-----------Operator
Operator
Operator
Operator
Operator
Operator
Operator
Operator
Operator
Sal/Month
---------$1,200.00
$1,400.00
$1,450.00
$1,193.00
$1,093.00
$902.00
$930.00
$1,100.00
$1,015.00
To display the records of employees who earn less than 1000, you would enter:
TYPE NAME, JOB, SALARY, SET = 4
Name
-------------WATSON, JOAN
EMERSON, RALPH
BODNARUK, ANN
DAVIS, SCOTT
READER, WILMA
KANG, SAM
MULLICK, STACEY
FAY, JENNIFER
FORREST, CATHY
WEINSTEIN, ALFRED
WOOD, DWAYNE
LOVE, ALLEN
WADE, REGGIE
TRASK, ABRAHAM
Job Title
-----------Secretary
Clerk
Clerk
Clerk
Clerk
Administrative
Assistant
Clerk
Clerk
Operator
Clerk
Operator
Clerk
Clerk
Administrative
Assistant
Sal/Month
---------$900.00
$750.00
$811.00
$867.00
$829.00
$933.00
$989.00
$979.00
$902.00
$757.00
$930.00
$953.00
$998.00
$993.00
201
To display the records of operators who earn less than 1000, you would enter:
TYPE NAME, JOB, SALARY
Name
-------------FORREST, CATHY
WOOD, DWAYNE
Job Title
-----------Operator
Operator
Sal/Month
--------$902.00
$930.00
LANGUAGE
LANGuage = lang_code
(Optional)
This parameter tells the system what language to use when interpreting the search values
in your FIND command. It is necessary only for multilingual applications that reference a
multilingual thesaurus. Your DBA defines the language codes associated with various
languages; see your DBA for these values. Although there is no default for this
parameter, you can set one using the SET/THESAURUS_OPTION command. For more
information about the SET/THESAURUS_OPTION command, see Interactive FQM
Commands.
LEVEL
LEVEL = level
(Optional)
This parameter tells the system what hierarchical levels in a thesaurus to access when you
use a thesaurus to enhance your search. The system will access levels 1 through the
number you specify for this parameter. The level can be any integer between 1 and the
maximum number of levels in the thesaurus you are referencing. Although all levels are
accessed by default, you can change this default with the SET/THESAURUS_OPTION
command.
For more information about the SET/THESAURUS_OPTION command, see Interactive
FQM Commands. For more information about using a thesaurus with the FIND
command, see the THESAURUS command parameter below.
202 
REFERENCES
REFerences = YES | NO
(Optional)
This parameter tells the system whether to count and highlight the references in the
retrieved records. A reference is any term(s) in a record’s field that matches the search
value(s) in your FIND command. The possible values for this parameter and their effects
are listed below:
YES
The system counts the number of references in the retrieved records and
displays the number in the result set message, which would look like this:
Result set 5 contains 30 references to 20 members.
UNIX, VMS
Unless one of the following conditions exists, the system also highlights the
references when you display the records with the TYPE command:
*
There is a search filter on the field
*
The field has DM-style hide markup in it
*
The TYPE command references a portion of the field
(TYPE STREET[1:20], instead of TYPE STREET, for example)
*
The field value is displayed in response to the Replace action on a
screen displayed by FQM USE/SCREEN
All
NO
The system does not count the number of references; therefore, the result set
message appears as follows:
Result set 5 contains 20 members.
203
Although the default is YES, you can change it with the SET/DEFAULTS command. For
more information on SET/DEFAULTS, see Interactive FQM Commands.
Note: Since counting and highlighting references can slow performance, you may want
to set this parameter to NO if the reference information is not important to you.
RESULT_MESSAGE
RESULT_message = YES | NO
(Optional)
This parameter tells the system whether to display a message about the result set after the
FIND command has executed successfully. If you select YES, the system displays one of
the following messages:
Result set 5 contains 10 references to 20 members.
Result set 5 contains 20 members.
The type of message displayed depends on the REFERENCES command parameter. For
more information about the possible messages, see the REFERENCES command
parameter above. If you select NO, the system does not display a message. Although the
default is YES, you can change it with the SET/DEFAULTS command. For more
information about SET/DEFAULTS, see Interactive FQM Commands.
ROLLBACK
ROLLBACK = rlabel
(Optional)
This parameter tells the system to branch to a particular label in a command procedure or
program if a deadlock situation occurs. You do not need to use ROLLBACK in FIND
commands executed during an interactive session.
A deadlock occurs when two users or processes are waiting for a resource that the other
has. Although rare, a deadlock can occur if each of two transactions is waiting for a
document or view which the other has locked. When BASIS detects a deadlock situation,
it returns DMSTAT message 866 and automatically removes any changes made by the
newer transaction and aborts it. Then, if you specified a label for the ROLLBACK
command parameter, the system performs the actions listed at this label.
204 
The following is a sample proc using a FIND command with the ROLLBACK parameter:
FIND EMPLOYEE WHERE DNO = 201 END, ROLLBACK = DEADLOCK
.
.
.
DEADLOCK:
TELL 'The records you want to update are locked.'
TELL 'Please try again later.'
RETURN
SEARCH_OPTION
SEARCH_option = OPTIMIZE | INDEX | INDEX_ONLY | SCAN
(Optional)
This parameter tells the system how to use indexes to evaluate the retrieval test(s) in your
FIND command. Possible values are shown below:
This value
Tells the system to
OPTIMIZE
Use the standard BASIS optimization strategy.
INDEX
Always use an index when searching indexed fields. Scan
records when searching non-indexed fields.
If you specify an indexed field and an incompatible test operator
in your FIND command, the system returns the following error
message:
An error occurred using SEARCH_OPTION = INDEX or
SEARCH_OPTION = INDEX_ONLY. The FIND command
contains an incompatible search of an indexed
field. Possible reasons are:
INDEX_ONLY
1.
The FIND command was used with the INCLUDES
operator to search a non-inclusive index.
2.
The FIND command was used with the EQUALS
operator to search an inclusive index.
Search only indexed fields and use their indexes.
If you specify a non-indexed field in your FIND command, the
system returns the following error message:
205
This value
Tells the system to
The FIND command contains a retrieval test with
a non-indexed field. When SEARCH_OPTION =
INDEX_ONLY for the FIND command, only indexed
fields can be searched.
If, in your FIND command, you specify a test operator that is
incompatible with indexed fields, the system returns the same
error message shown for INDEX.
SCAN
Scan records when searching indexed or non-indexed fields.
Ignore all indexes.
Although the default is OPTIMIZE, you can change it with the SET/DEFAULTS
command. For more information about SET/DEFAULTS, see Interactive FQM
Commands. For information about how the SCAN search option affects FIND commands
with inclusive operators, see “Components of Basic Searches.”
THESAURUS
THESaurus = YES | NO
(Optional)
This command parameter tells the system whether to use a thesaurus to enhance the
search value(s) in your FIND command. A thesaurus is a database that is set up by your
DBA and contains possible search terms for a particular field in a record.
The search value can include a wildcard (? for single-character wildcard, % for zerosingle-character wildcard or * for multiple-character wildcard) or a range. The FIND
command cannot, however, use a phrase pattern (# in the phrase). For thesaurus
processing to be invoked for FIND commands containing a wildcard or range, the
DM_TWILD environment variable must be set to YES. For information about the
DM_TWILD environment variable, see BASIS Reference, “Environment Variables.”
206 
The way a thesaurus affects your search depends on the options your DBA has activated
in the SEARCH_CONTROL_SET portion of the DDL. The possible options are
COMBINE, SWITCH, and NOTIFY. When you search a field that is linked to a
thesaurus and set the THESAURUS parameter to YES, the system will automatically do
any of the following actions according to the thesaurus option(s) activated:
COMBINE
The system adds to your FIND command search values that are
related to your original search value(s). The system will then
retrieve records containing any of these search values. The type of
related values added by the system is determined by your DBA.
For instance, it might add search values that are synonymous with
your original search value(s).
SWITCH
The system adds a preferred search term to the search value(s) in
your FIND command. The system will then retrieve records
containing any of these search values. This preferred search term
is usually synonymous with your original search value. For
instance, if you search for the term CAR, the system could add the
term AUTOMOBILE to your search.
Also, if your original search term is ambiguous, that is, if it has
two or more meanings, the system may display an error message
along with a list of possible replacement search values. You can
enter one or more of these replacement values in a new FIND
command. For instance, if you search for the term TRAIN, the
system may display an error message asking you to use the term(s)
LOCOMOTIVE and/or TEACH.
NOTIFY
The system displays information directly from the thesaurus. The
specific type of information is controlled by your DBA. It is often
used to notify you of any changes made to your search command
because of the COMBINE or SWITCH feature. When NOTIFY is
used in searching ranges, the results retrieved can become very
large.
207
Although the default is YES, you can change it with SET/THESAURUS_OPTION. For
more information about the SET/THESAURUS_OPTION command, see Interactive
FQM Commands. For more information about thesaurus-related
SEARCH_CONTROL_SET parameters, see Database Definition and Development,
“ADM Definitions.” For more information about thesauri in general, see Thesaurus.
Example 1
In the TOUR database, the LOCATION field in the PLACE view has a thesaurus defined
for it. The DBA has set up the COMBINE option to add terms defined as specific
instances of the search value in your FIND command. Suppose you want to find records
in the PLACE view that contain information about any location in the United States.
Instead of entering each state and city as a search value in your FIND command, you can
enter UNITED STATES as your search value and set the THES command parameter to
YES, like this:
FIND PLACE WHERE LOCATION = 'UNITED STATES' END, THES = YES
The system retrieves records containing your original search value or any of the terms it
added from the thesaurus. The display would look similar to the following:
TYPE LOCATION
LOCATION
-------ATLANTIC CITY
ATLANTA
BOSTON
CALIFORNIA
CHICAGO
DALLAS
COLUMBUS
DENVER
FLORIDA
LOS ANGELES
MIAMI
MINNEAPOLIS
NEW YORK
NEW YORK CITY
OHIO
PORTLAND
RENO
SAN FRANCISCO
SEATTLE
208 
If the NOTIFY option is set to tell you of the changes made to your FIND command, the
system will display a message like this:
UNITED STATES
NARROW TERM
NARROW TERM
NARROW TERM
NARROW TERM
NARROW TERM
NARROW TERM
NARROW TERM
NARROW TERM
NARROW TERM
NARROW TERM
NARROW TERM
NARROW TERM
NARROW TERM
NARROW TERM
NARROW TERM
NARROW TERM
NARROW TERM
NARROW TERM
NARROW TERM
ATLANTIC CITY
ATLANTA
BOSTON
CALIFORNIA
CHICAGO
DALLAS
COLUMBUS
DENVER
FLORIDA
LOS ANGELES
MIAMI
MINNEAPOLIS
NEW YORK
NEW YORK CITY
OHIO
PORTLAND
RENO
SAN FRANCISCO
SEATTLE
Example 2
Suppose that you perform the same search as in example 1, but you enter USA as your
search value rather than UNITED STATES:
FIND PLACE WHERE LOCATION = 'USA'
If the SWITCH option is set to add the expanded term for an abbreviation or vice versa,
the system will add the term UNITED STATES to your search value. If COMBINE is set
as above, the system will add all the search values it defines as specific instances of your
search term as well. Therefore, the system retrieves records that contain USA or
UNITED STATES or any of the terms defined as specific instances of the general term.
The result set would be the same as in Example 1. Notice that because the THESAURUS
parameter default is YES, the END, THES=YES need not be appended to the FIND
command.
Example 3
Search for locations beginning with UNITED.
FIND PLACE WHERE LOCATION = 'UNITED'*
The thesaurus will be used to aid in retrieval. All of the terms in the thesaurus for
LOCATION that match this pattern will be expanded to include their thesaurus relations.
209
Example 4
Search for TEXT beginning with UNITED.
FIND PLACE WHERE TEXT INC 'UNIT'*
The thesaurus will be used to aid in retrieval. All of the terms in the thesaurus for TEXT
that match this pattern will be expanded to include their thesaurus relations.
Example 5
Search for locations within the range of UNITED and UNITY.
FIND PLACE WHERE LOCATION = 'UNITED':'UNITY'
The thesaurus will be used to aid in retrieval. All of the terms in the thesaurus for
LOCATION that match this pattern will be expanded to include their thesaurus relations.
Example 6
Search for words in the TEXT within the range of UNITED and UNITY.
FIND PLACE WHERE TEXT INC 'UNITED':'UNITY'
The thesaurus will be used to aid in retrieval. All of the terms in the thesaurus for TEXT
that match this pattern will be expanded to include their thesaurus relations.
210 
TIMEOUT
TIMEOUT = time
(Optional)
This parameter tells the system the maximum number of CPU seconds to process the
FIND command you entered. The time can be any integer from zero to 2000000. When
the CPU time limit is reached, the system returns the following error message:
The FIND command timed out.
If you do not want to set a time limit, let this parameter default to zero. However, you can
change the default with the SET/DEFAULTS command. For more information about
SET/DEFAULTS, see Interactive FQM Commands.
Note: Your system administrator can also set a time limit by using the
DM_FIND_TIMEOUT environment variable. If your FIND command exceeds the time
limit set by your system administrator (when you haven’t also specified a time limit), the
system returns the following error message:
The FIND command exceeded the *** second CPU timeout limit.
where “***” is the value of DM_FIND_TIMEOUT. The value of this variable also
affects what value you can enter for the TIMEOUT parameter. You cannot specify a
time limit greater than the one your administrator specifies for this variable. If you
enter a higher time limit, the system returns the following error message:
The system timeout limit is currently *** CPU seconds.
The user cannot increase this limit.
If your system administrator has not set a time limit, you can specify any of the possible
values for the TIMEOUT parameter shown above.
For information about environment variables, see BASIS Reference, “Environment
Variables.”
211
WAIT
WAIt = YES | NO
(Optional)
This parameter tells the system whether to wait for locked records to become available. If
you select YES, the system will wait until the desired records are unlocked and then
proceed with the retrieval as normal. If you select NO, the system will abort the FIND
command and display a message like this:
The records are locked at this time.
Although the default is YES, you can change it with the SET/DEFAULTS command. For
more information about the SET/DEFAULTS command, see Interactive FQM
Commands.
212 