SetValidate

Description

Sets the input validation rule for a column in a DataWindow control or DataStore.

Applies to

DataWindow type

Method applies to

PowerBuilder

DataWindow control, DataWindowChild object, DataStore object


Syntax

PowerBuilder

integer dwcontrol.SetValidate ( string column, string rule )
integer dwcontrol.SetValidate ( integer column, string rule )

Argument

Description

dwcontrol

A reference to a DataWindow control, DataStore, or child DataWindow.

column

The column for which you want to set the input validation rule. Column can be a column number or a column name.

rule

A string whose value is the validation rule for validating the data.


Return value

Returns 1 if it succeeds and -1 if an error occurs. If any argument's value is null, in PowerBuilder and JavaScript the method returns null.

Usage

Validation rules are boolean expressions that usually compare the value in the column's edit control to some other value. When data the user enters fails to meet the criteria established in the validation rule, an ItemError event occurs.

You can specify validation rules in the Database painter or the DataWindow painter, and you can change the rules in scripts using SetValidate. A validation rule can include any DataWindow painter function. For more information, see the section called “Defining validation rules” in Users Guide.

If you want to change a column's validation rule temporarily, you can use GetValidate to get and save the current rule. To include the value the user entered in the validation rule, use the GetText method. You can compare its return value to the validation criteria.

If the validation rule contains numbers, the DataWindow expects the numbers in U.S. format. In PowerBuilder, be aware that the String function formats numbers using the current system settings. If you use it to build the rule, specify a display format that produces U.S. notation.

Examples

The following assigns a validation rule to the current column in dw_employee. The rule ensures that the data entered is greater than zero:

dw_employee.SetValidate(dw_employee.GetColumn(), &
      "Number(GetText( )) > 0")

The following assigns a validation rule to the current column in dw_employee. The rule checks that the value entered is less than the value in the Full_Price column:

dw_employee.SetValidate(dw_employee.GetColumn(), &
      "Number(GetText( )) < Full_Price")

This example defines a new validation rule for the column emp_state in the DataWindow control dw_employee. The new rule is [A-Z]+ , meaning the data in emp_state must be all uppercase characters. The text pattern must be enclosed in quotes within the quoted validation rule. The embedded quotes are specified with ~". The script saves the old rule, assigns the new rule, performs some processing, and then sets the validation rule back to the old rule:

string OldRule, NewRule
 
NewRule = "Match(GetText(), ~"[A-Z]+~")"
 
OldRule = dw_employee.GetValidate("emp_state")
 
dw_employee.SetValidate("emp_state", NewRule)
... //Process data using the new rule.
 
// Set the validation rule back to the old rule.
dw_employee.SetValidate("emp_state", OldRule)

See also

GetValidate