Sets the value of a row and column in a DataWindow control or DataStore to the specified value.
DataWindow type |
Method applies to |
|---|---|
PowerBuilder |
DataWindow control, DataWindowChild object, DataStore object |
Web |
Client control |
Web ActiveX |
DataWindow control, DataWindowChild object |
integer dwcontrol.SetItem ( long row, integer column, any value ) integer dwcontrol.SetItem ( long row, string column, any value )
Web DataWindow client control and Web ActiveX
number dwcontrol.SetItem ( number row, number column, variant value ) number dwcontrol.SetItem ( number row, string column, variant 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 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.
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.
When you use SetItem (or dot notation) to assign a value to a character column that is defined to have 512 characters or less, the actual size of the column in the DataWindow definition is ignored. If the assigned value has more than 512 characters, the value displayed in the DataWindow is truncated at 512 characters. If the DataWindow column is defined to have more than 512 characters, its size is respected. For example, if the DataWindow column is defined to have 1, 10, or 100 characters, up to 512 characters of the assigned value are displayed. If the DataWindow column is defined to have 1000 characters, up to 1000 characters are displayed.
In Group and TreeView DataWindow objects, you must call GroupCalc after you call SetItem to display data correctly.
In the ItemChanged and ItemError events, you can call SetItem to set the value of an item when the data the user entered is not valid. If you want the user to have an opportunity to enter a different value, after calling SetItem you can call SetText to put that same value in the edit control so that the user sees the value too. In the script, use a return code that rejects the value in the edit control, avoiding further processing, but does not allow the focus to change. To retain focus and display an error message, return 1 for ItemChanged or 0 for ItemError.
When you use a return code that rejects the data the user entered but allows the focus to change (a return code of 2 in the script for the ItemChanged event or 3 in the ItemError event), you do not need to call SetText because the value set with SetItem displays.
If PowerBuilder 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), PowerBuilder is unable to convert the string to a number and you must convert it in the script.
PowerBuilder environment
For use with PowerBuilder ListView and TreeView controls,
see SetItem in the PowerScript Reference.
This statement sets the value of row 3 of the column named hire_date of the DataWindow control dw_order to 2003-06-07:
dw_order.SetItem(3, "hire_date", 2003-06-07)
When a user starts to edit a numeric column and leaves it without entering any data, PowerBuilder 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
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
