Documentation Comments

Use this form to comment on this topic. You can also provide any general observations about the Online Documentation, or request that additional information be added in a future release.

Reality V15.0 ()

ESEARCH Command (English) (m618304+esearch.htm)

To	Reality
Version
Topic
Submitted by
Company
Location
Email address
Comment

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 RETURNis 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 nitems 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 Noption 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.

U Specifies that case is significant when comparing strings.

W Specifies that case should be ignored when comparing strings.

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.

Case Sensitivity

If neither U nor W is specified, the current data case setting (set with the DATA.CC environment option or the CASE TCL command) is used. See Case Sensitivity for more details.

If both U and W are specified an error message is displayed and no list is generated.

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.