ESEARCH

Selects items in a file if they contain, or do not contain, one or more occurrences of specified character strings. ESEARCH generates an implicit item-list.

Syntax

ESEARCH file-specifier {item-list} {selection-criteria} {USING file-specifier} {sort-criteria} {macro-call} {(options}

Refer to Sentence Structure for descriptions of these parameters.

Prompts

After the sentence is entered, the processor prompts:

STRING:

Enter a character string and press RETURN. The prompt is repeated until only RETURN is pressed. The total character strings entered can consist of up to 500 characters.

Double quotes should not be entered.

Special Options

A ANDs string together. Items must contain all specified strings.

C{n} Display running counters of the number of items selected and items processed. The counter display is refreshed after every n items processed (default 500) or after the total number of items if less than 500. For example, (C25) refreshes the display after every 25 items processed.

F Include the item-id in the search.

G{n} Completes once n items have been selected (default 500), or the end of the file is reached, whichever occurs first.

I Lists item-ids selected.

L Saves the line numbers where the specified strings are found. The resulting list contains the item-id followed by multi-valued line numbers.

Ignores an A and N option if either or both are specified with the L option.

N Selects only those items that do not contain the specified string(s).

R Suppresses the Item not on file  message that is generated if no items are selected.

S Suppresses the list but displays the item-ids selected.

More than one option can be entered as follows:

(AS

SSEARCH

Performs a similar function to ESEARCH, but generates a sorted item-list.

Comments

The list generated by ESEARCH contains only the item-ids and optionally attribute numbers. This is most useful for inclusion in a DataBasic program or a Proc.

Unless the S option is used, after RETURN is pressed, the number of items selected and the prompt '>' are displayed. Any of the following can then be used to act on the list:

• Another English sentence without an item-list.
• A Cataloged DataBasic program. The list is then available to the specified program via a READNEXT statement. For more information, refer to the DataBasic Reference.
• List processing commands - for example, SAVE-LIST.
• A TCL-II command such as EDIT.
• A Proc command. If the ESEARCH sentence is processed within a Proc, the list can be accessed via a number of Proc commands. For more information, refer to the Proc Reference.

Example

:ESEARCH GUESTS (S

STRING: Henn
STRING: Mc
STRING: Return
234
143

2 ITEMS SELECTED
:

In this example, the implicit list is suppressed through the S option and the item-ids containing the specified strings are displayed.