Find method (DataWindows)

Description

Finds the next row in a DataWindow or DataStore in which data
meets a specified condition.

Controls

DataWindow type	Method applies to
PowerBuilder	DataWindow control, DataWindowChild object, DataStore object
Web	Server component
Web ActiveX	DataWindow control, DataWindowChild object

Syntax

[PowerBuilder and Web DataWindow server component]

long <span>dwcontrol</span><span>.</span><span>Find </span>( string <span>expression</span>, long <span>start</span>, long <span>end </span>)

1	long <span>dwcontrol</span><span>.</span><span>Find </span>( string <span>expression</span>, long <span>start</span>, long <span>end </span>)

[Web DataWindow and Web ActiveX]

number <span>dwcontrol</span><span>.Find </span>( string <span>expression</span>, number <span>start</span>, number <span>end</span> )

1	number <span>dwcontrol</span><span>.Find </span>( string <span>expression</span>, number <span>start</span>, number <span>end</span> )

Argument	Description
dwcontrol	A reference to the DataWindow control, DataStore, or child DataWindow in which you want to search the detail band.
expression	A string whose value is a boolean expression that you want to use as the search criterion. The expression includes column names.
start	A value identifying the row location at which to begin the search. Start can be greater than the number of rows.
end	A value identifying the row location at which to end the search. End can be greater than the number of rows. To search backward, make end less than start.

Return Values

Returns the number of the first row that meets the search
criteria within the search range. Returns 0 if no rows are found
and one of these negative numbers if an error occurs:

–1 General
error
–5 Bad argument

If any argument’s value is null, in PowerBuilder
and JavaScript the method returns null.

Usage

PowerBuilder environment

For use with a RichTextEdit control or presentation style,
see Find in the PowerScript Reference.

The search is case sensitive. When you compare text to a value
in a column, the case must match.

When the Find expression includes quotes

If the text you want to find includes quotes, you must treat
the nested quote as doubly nested, because the DataWindow parses
the string twice before the Find method uses
it. Therefore, you cannot simply alternate double and single quotes, as
you can in most strings.

For example, to find the name O’Connor, the Find
expression can be:

"O~~~'Connor" (3
tildes and single quote) or
"O~~~~~"Connor" (5
tildes and double quote)

but not:

"O'Connor" or "O~"OConnor"

When the last row satisfies the search criteria

If you use Find in a loop that searches
through all rows, you may end up with an endless loop if the last
row satisfies the search criteria. When the start value
becomes greater than end, the search reverses
direction and Find would always succeed, resulting in an endless
loop.

To solve this problem, you could make the end value
1 greater than the number of rows (see the examples). Another approach,
shown below, would be to test within the loop whether the current
row is greater than the row count and, if so, exit. This PowerBuilder
code illustrates how:

long ll_find = 1, ll_end

1	long ll_find = 1, ll_end

ll_end = dw_main.RowCount()

1	ll_end = dw_main.RowCount()

ll_find = dw_main.Find(<span>searchstr</span>, ll_find, ll_end)

1	ll_find = dw_main.Find(<span>searchstr</span>, ll_find, ll_end)

DO WHILE ll_find &gt; 0

1	DO WHILE ll_find > 0

        ... // Collect found row

1	... // Collect found row

        ll_find++

ll_find++

        // Prevent endless loop

1	// Prevent endless loop

        IF ll_find &gt; ll_end THEN EXIT

1	IF ll_find > ll_end THEN EXIT

        ll_find = dw_main.Find(<span>searchstr</span>, ll_find, ll_end)

1	ll_find = dw_main.Find(<span>searchstr</span>, ll_find, ll_end)

LOOP

LOOP

Examples

This statement searches for the first row in dw_status
in which the value of the emp_salary column is greater
than 100,000. The search begins in row 3 and continues until it
reaches the last row in dw_status:

long ll_found

1	long ll_found

ll_found = dw_status.<span>Find</span>("emp_salary &gt; 100000", &amp;

1	ll_found = dw_status.<span>Find</span>("emp_salary > 100000", &

        3, dw_status.RowCount())

1	3, dw_status.RowCount())

To test values in more than one column, use boolean
operators to join conditional expressions. The following statement
searches for the employee named Smith whose salary exceeds 100,000:

long ll_found

1	long ll_found

ll_found = dw_status.<span>Find</span>( &amp;

1	ll_found = dw_status.<span>Find</span>( &

<span></span>        "emp_lname = 'Smith' and emp_salary &gt; 100000", &amp;

1	<span></span> "emp_lname = 'Smith' and emp_salary > 100000", &

        1, dw_status.RowCount())

1	1, dw_status.RowCount())

These statements search for the first row in dw_emp
that matches the value that a user entered in the SingleLineEdit
called Name (note the single quotes embedded in the search expression
around the name):

string ls_lname_emp

1	string ls_lname_emp

long ll_nbr, ll_foundrow

1	long ll_nbr, ll_foundrow

ll_nbr = dw_emp.RowCount()

1	ll_nbr = dw_emp.RowCount()

// Remove leading and trailing blanks.

1	// Remove leading and trailing blanks.

ls_lname_emp = Trim(sle_Name.Text)

1	ls_lname_emp = Trim(sle_Name.Text)

ll_foundrow = dw_emp.<span>Find</span>( &amp;

1	ll_foundrow = dw_emp.<span>Find</span>( &

        "emp_lname = '" + ls_lname_emp + "'", 1, ll_nbr)

1	"emp_lname = '" + ls_lname_emp + "'", 1, ll_nbr)

This script excerpt finds the first row that has
a null value in emp_id. If no null is found, the script
updates the DataWindow object. If a null is found, it displays a
message:

IF dw_status.AcceptText() = 1 THEN

1	IF dw_status.AcceptText() = 1 THEN

        IF dw_status.<span>Find</span>("IsNull(emp_id)", &amp;

1	IF dw_status.<span>Find</span>("IsNull(emp_id)", &

                1, dw_status.RowCount()) &gt; 0 THEN

1	1, dw_status.RowCount()) > 0 THEN

            MessageBox("Caution", "Cannot Update")

1	MessageBox("Caution", "Cannot Update")

        ELSE

ELSE

            dw_status.Update()

1	dw_status.Update()

        END IF

END IF

END IF

END IF

The following script attached to a Find Next command
button searches for the next row that meets the specified criteria
and scrolls to that row. Each time the button is clicked, the number
of the found row is stored in the instance variable il_found.
The next time the user clicks Find Next, the search continues from
the following row. When the search reaches the end, a message tells
the user that no row was found. The next search begins again at
the first row.

Note that although the search criteria are hard-coded here,
a more realistic scenario would include a Find button that prompts
the user for search criteria. You could store the criteria in an
instance variable, which Find Next could use:

long ll_row

1	long ll_row

// Get the row num. for the beginning of the search

1	// Get the row num. for the beginning of the search

// from the instance variable, il_found

1	// from the instance variable, il_found

ll_row = il_found

1	ll_row = il_found

// Search using predefined criteria

1	// Search using predefined criteria

ll_row = dw_main.<span>Find</span>( &amp;

1	ll_row = dw_main.<span>Find</span>( &

        "item_id = 3 or item_desc = 'Nails'", &amp;

1	"item_id = 3 or item_desc = 'Nails'", &

        ll_row, dw_main.RowCount())

1	ll_row, dw_main.RowCount())

IF ll_row &gt; 0 THEN

1	IF ll_row > 0 THEN

        // Row found, scroll to it and make it current

1	// Row found, scroll to it and make it current

        dw_main.ScrollToRow(ll_row)

1	dw_main.ScrollToRow(ll_row)

ELSE

ELSE

        // No row was found

1	// No row was found

        MessageBox("Not Found", "No row found.")

1	MessageBox("Not Found", "No row found.")

END IF

END IF

// Save the number of the next row for the start

1	// Save the number of the next row for the start

// of the next search. If no row was found,

1	// of the next search. If no row was found,

// ll_row is 0, making il_found 1, so that

1	// ll_row is 0, making il_found 1, so that

// the next search begins again at the beginning

1	// the next search begins again at the beginning

il_found = ll_row + 1

1	il_found = ll_row + 1

This example searches all the rows in dw_main
and builds a list of the names that include a lowercase a. Note
that the end value of the search is one greater than the row count,
avoiding an infinite loop if the name in the last row satisfies
the search:

long ll_find, ll_end

1	long ll_find, ll_end

string ll_list

1	string ll_list

// The end value is one greater than the row count

1	// The end value is one greater than the row count

ll_end = dw_main.RowCount() + 1

1	ll_end = dw_main.RowCount() + 1

ll_find = 1

1	ll_find = 1

ll_find = dw_main.Find("Pos(last_name,'a') &gt; 0", &amp;

1	ll_find = dw_main.Find("Pos(last_name,'a') > 0", &

        ll_find, ll_end)

1	ll_find, ll_end)

DO WHILE ll_find &gt; 0

1	DO WHILE ll_find > 0

        //collect names

1	//collect names

        ll_list = ll_list + '~r' &amp;

1	ll_list = ll_list + '~r' &

            + dw_main.GetItemString(ll_find,'last_name')

1	+ dw_main.GetItemString(ll_find,'last_name')

        // Search again

1	// Search again

        ll_find++

ll_find++

        ll_find = dw_main.Find("Pos(last_name,'a') &amp;

1	ll_find = dw_main.Find("Pos(last_name,'a') &

            &gt; 0", ll_find, ll_end )

1	> 0", ll_find, ll_end )

LOOP

LOOP

Find – PB Docs 150

Find method (DataWindows)

Description

Controls

Syntax

Return Values

Usage

When the Find expression includes quotes

When the last row satisfies the search criteria

Examples

See Also

My Website Links