FindRequired method (DataWindows)

Description

Reports the next row and column that is required and contains
a null value. The method arguments that specify where to start searching
also store the results of the search. You can speed up the search
by specifying that FindRequired check only inserted
and modified rows.

Controls

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

Syntax

[PowerBuilder]

integer <span>dwcontrol</span><span>.</span><span>FindRequired</span> ( DWBuffer <span>dwbuffer</span>, long <span>row</span>, integer&#160;<span>colnbr</span>, string <span>colname</span>, boolean <span>updateonly</span> )

1	integer <span>dwcontrol</span><span>.</span><span>FindRequired</span> ( DWBuffer <span>dwbuffer</span>, long <span>row</span>, integer <span>colnbr</span>, string <span>colname</span>, boolean <span>updateonly</span> )

[Web ActiveX]

number <span>dwcontrol</span><span>.Find</span>Required ( number <span>dwbuffer</span>, number <span>row</span>, number <span>colnbr</span>, string <span>colname</span>, boolean <span>updateonly</span> )

1	number <span>dwcontrol</span><span>.Find</span>Required ( number <span>dwbuffer</span>, number <span>row</span>, number <span>colnbr</span>, string <span>colname</span>, boolean <span>updateonly</span> )

Argument	Description
dwcontrol	A reference to the DataWindow control or DataStore in which you want to find required columns that have null values.
dwbuffer	A value indicating the DataWindow buffer you want to search for required columns. Valid buffers are: Primary! Filter!
row	A value identifying the first row to be searched. Row also stores the number of the found row. FindRequired increments the row number automatically after it validates each row’s columns. When it finds a row with a required column that contains a null value, the row number is stored in row. After FindRequired validates the last column in the last row, it sets row to 0. PowerBuilder The row argument must be a variable so it can return a value for the found row.
colnbr	A value identifying the first column to be searched. Colnbr also stores the number of the found column. After validating the last column, FindRequired sets colnbr to 1 and increments row. When it finds a required column that contains a null value, the column number is stored in colnbr. PowerBuilder The colnbr argument must be a variable so it can return a value for the found column.
colname	A string in which you want to store the name of the required column that contains a null value (the name of colnbr). PowerBuilder The colname argument must be a variable so it can hold a value for the name of the found column.
updateonly	A value indicating whether you want to validate all rows and columns or only rows that have been inserted or modified: true – Validate only those rows that have changed. Setting updateonly to true enhances performance in large DataWindows. false – Validate all rows and columns.

Return Values

Returns 1 if FindRequired successfully
checked the rows and –1 if an error occurs.

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

Usage

For FindRequired to report an empty required
column, the column’s value must actually be null, not an
empty string.

To make a column required, set the Required property to true
in a script or check the Required check box for the column in the
DataWindow painter.

New rows have null values in their columns, unless the columns
have default values. If updateonly is false, FindRequired reports
empty required columns in new rows. If updateonly is
true, FindRequired does not check new rows because
new, empty rows are not updated in the database.

When the user modifies a row and leaves a column empty, the
new value is an empty string, unless the column’s edit
style has the Empty String Is null check box checked. FindRequired does
not report empty required columns in modified rows unless this property
is set.

Examples

The following code makes a list of all the row numbers
and column names in dw_1 in which required columns are
missing values. The list is displayed in the MultiLineEdit mle_required:

long ll_row = 1

1	long ll_row = 1

integer colnbr = 0

1	integer colnbr = 0

string colname

1	string colname

mle_required.Text = ""

1	mle_required.Text = ""

DO WHILE ll_row &lt;&gt; 0

1	DO WHILE ll_row <> 0

        colnbr++ // Continue searching at next column

1	colnbr++ // Continue searching at next column

        // If there's an error, exit

1	// If there's an error, exit

        IF dw_1.<span>FindRequired</span>(Primary!, &amp;

1	IF dw_1.<span>FindRequired</span>(Primary!, &

            ll_row, colnbr, &amp;

1	ll_row, colnbr, &

            colname, false) &lt; 0 THEN EXIT

1	colname, false) < 0 THEN EXIT

        // If a row was found, save the row and column

1	// If a row was found, save the row and column

        IF ll_row &lt;&gt; 0 THEN

1	IF ll_row <> 0 THEN

            mle_required.Text = mle_required.Text &amp;

1	mle_required.Text = mle_required.Text &

                + String(ll_row) + "~t" &amp;

1	+ String(ll_row) + "~t" &

                + colname + "~r~n"

1	+ colname + "~r~n"

END IF

END IF

        // When FindRequired returns 0 (meaning

1	// When FindRequired returns 0 (meaning

        // no more rows found), drop out of loop

1	// no more rows found), drop out of loop

LOOP

LOOP

This example is a function that ensures that no required
column in a DataWindow control is empty (contains null). It takes
one argument—the DataWindow control, which is declared
in the function declaration like this:

DataWindow adw_control

1	DataWindow adw_control

The function returns –2 if the user’s last
entry cannot be accepted or if FindRequired returns
an error. It returns –1 if an empty required column is found.
It returns 1 if all required columns have data:

integer li_colnbr = 1

1	integer li_colnbr = 1

long ll_row = 1

1	long ll_row = 1

string ls_colname, ls_textname

1	string ls_colname, ls_textname

// Make sure the last entry is accepted

1	// Make sure the last entry is accepted

IF adw_control.AcceptText() = -1 THEN

1	IF adw_control.AcceptText() = -1 THEN

        adw_control.SetFocus()

1	adw_control.SetFocus()

        RETURN -2

RETURN -2

END IF

END IF

// Find the first empty row and column, if any

1	// Find the first empty row and column, if any

IF adw_control.<span>FindRequired</span>(Primary!, ll_row, &amp;

1	IF adw_control.<span>FindRequired</span>(Primary!, ll_row, &

            li_colnbr, ls_colname, true) &lt; 1 THEN

1	li_colnbr, ls_colname, true) < 1 THEN

        //If search fails due to error, then return

1	//If search fails due to error, then return

        RETURN -2

RETURN -2

END IF

END IF

// Was any row found?

1	// Was any row found?

IF ll_row &lt;&gt; 0 THEN

1	IF ll_row <> 0 THEN

        // Get the text of that column's label.

1	// Get the text of that column's label.

        ls_textname = ls_colname + "_t.Text"

1	ls_textname = ls_colname + "_t.Text"

        ls_colname = adw_control.Describe(ls_textname)

1	ls_colname = adw_control.Describe(ls_textname)

        // Tell the user which column to fill in

1	// Tell the user which column to fill in

        MessageBox("Required Value Missing", &amp;

1	MessageBox("Required Value Missing", &

            "Please enter a value for '" &amp;

1	"Please enter a value for '" &

            + ls_colname + "', row " &amp;

1	+ ls_colname + "', row " &

            + String(ll_row) + ".", &amp;

1	+ String(ll_row) + ".", &

            StopSign! )

1	StopSign! )

        // Make the problem column current.

1	// Make the problem column current.

        adw_control.SetColumn(li_colnbr)

1	adw_control.SetColumn(li_colnbr)

        adw_control.ScrollToRow(ll_row)

1	adw_control.ScrollToRow(ll_row)

        adw_control.SetFocus()

1	adw_control.SetFocus()

        RETURN -1

RETURN -1

END IF

END IF

// Return success code if all required

1	// Return success code if all required

// rows and columns have data

1	// rows and columns have data

RETURN 1

RETURN 1

FindRequired – PB Docs 150

FindRequired method (DataWindows)

Description

Controls

Syntax

Return Values

Usage

Examples

See Also

My Website Links