Chapter 9: Methods for the DataWindow Control

SetItem

Description

Sets the value of a row and column in a DataWindow control or DataStore to the specified value.

Syntax

integer dwcontrol.SetItem ( long row, integer column, any value )

integer dwcontrol.SetItem ( long row, string column, any value )

Argument	Description
dwcontrol	The name of the DataWindow control, DataStore, or child DataWindow in which you want to set a specific row and column to a value.
row	The row location of the data.
column	The column location of the data. Column can be a column number or a column name. The column number is the number of the column as it is listed in the Column Specification view of the DataWindow painter—not necessarily the number of the column in the Design view.
value	The value to which you want to set the data at the row and column location. The datatype of the value must be the same datatype as the column.

Returns

Returns 1 if it succeeds and -1 if an error occurs. If any argument’s value is NULL, the method returns NULL.

Usage

SetItem sets a value in a DataWindow buffer. It does not affect the value currently in the edit control over the current row and column, which is the data the user has changed or might change. The value in the edit control does not become the value of the DataWindow item until it is validated and accepted (see AcceptText). In a script, you can change the value in the edit control with the SetText method.

You can use SetItem when you want to set the value of an item in a DataWindow control or DataStore that has script as the source.

You can also use SetItem to set the value of an item when the data the user entered is not valid. When you use a return code that rejects the data the user entered but allows the focus to change (return code of 2 in the script of the ItemChanged event or return code of 3 in the ItemError event), you can call SetItem to put valid data in the row and column.

Using SetItem to correct user input If PocketBuilder cannot properly convert the string the user entered, you must include statements in the script for the ItemChanged or ItemError event to convert the data and use SetItem with the converted data. For example, if the user enters a number with commas and a dollar sign (for example, $1,000), PocketBuilder is unable to convert the string to a number and you must convert it in the script.

If you use SetItem to set a row and column to a value other than the value the user entered, you can use SetText to assign the new value to the edit control so that the user sees the current value.

Using with other PocketBuilder controls For use with ListView and TreeView controls, see SetItem in the PowerScript Reference.

Examples

Example 1

This statement sets the value of row 3 of the column named hire_date of the DataWindow control dw_order to 1993-06-07:

dw_order.SetItem(3, "hire_date", 1993-06-07)

Example 2

When a user starts to edit a numeric column and leaves it without entering any data, PocketBuilder tries to assign an empty string to the column. This fails the datatype validation test. In this example, code in the ItemError event sets the column’s value to NULL and allows the focus to change.

This example assumes that the datatype of column 2 is numeric. If it is date, time, or datetime, replace the first line (integer null_num) with a declaration of the appropriate datatype:

integer null_num //to contain null value

SetNull(null_num)

// Special processing for column 2

IF dwo.ID = 2 THEN

		// If user entered nothing (""), set to null

		IF data = "" THEN

			This.SetItem(row, dwo.ID, null_num)

			RETURN 2

		END IF

END IF

Example 3

The following example is a script for a DataWindow’s ItemError event. If the user specifies characters other than digits for a numeric column, the data will fail the datatype validation test. You can include code to strip out characters such as commas and dollar signs and use SetItem to assign the now valid numeric value to the column. The return code of 3 causes the data in the edit control to be rejected because the script has provided a valid value:

string snum, c

integer cnt

// Extract the digits from the user's data

FOR cnt = 1 to Len(data)

		c = Mid(data, cnt, 1) // Get character

		IF IsNumber(c) THEN snum = snum + c

NEXT

This.SetItem(row, dwo.ID, Long(snum))

RETURN 3