SetItem method (DataWindows)
Description
Sets the value of a row and column in a DataWindow control
or DataStore to the specified value.
Controls
|
DataWindow type |
Method applies to |
|---|---|
|
PowerBuilder |
DataWindow control, DataWindowChild object, DataStore |
|
Web |
Client control |
|
Web ActiveX |
DataWindow control, DataWindowChild object |
Syntax
[PowerBuilder]
|
1 |
integer <span>dwcontrol</span>.<span>SetItem</span> ( long <span>row</span>, integer <span>column</span>, any <span>value</span> )<br>integer <span>dwcontrol</span>.<span>SetItem</span> ( long <span>row</span>, string <span>column</span>, any <span>value</span> ) |
[Web DataWindow client control and Web ActiveX]
|
1 |
number <span>dwcontrol</span>.<span>SetItem</span> ( number <span>row</span>, number <span>column</span>, variant <span>value</span> ) <br>number <span>dwcontrol</span>.<span>SetItem</span> ( number <span>row</span>, string <span>column</span>, variant <span>value</span> ) |
|
Argument |
Description |
|---|---|
|
dwcontrol |
The name of the DataWindow control, DataStore, |
|
row |
The row location of the data. |
|
column |
The column location of the data. Column can |
|
value |
The value to which you want to set the |
Return Values
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
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.
Displaying data in character columns
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.
Group and TreeView DataWindows
In Group and TreeView DataWindow objects, you must call GroupCalc after
you call SetItem to display data correctly.
Using SetItem in the ItemChanged and ItemError events
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.
Examples
This statement sets the value of row 3 of the column
named hire_date of the DataWindow control dw_order
to 2003-06-07:
|
1 |
dw_order.<span>SetItem</span>(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:
|
1 |
integer null_num //to contain null value |
|
1 |
|
1 |
SetNull(null_num) |
|
1 |
|
1 |
// Special processing for column 2 |
|
1 |
IF dwo.ID = 2 THEN |
|
1 |
// If user entered nothing (""), set to null |
|
1 |
IF data = "" THEN |
|
1 |
This.<span>SetItem</span>(row, dwo.ID, null_num) |
|
1 |
RETURN 2 |
|
1 |
END IF |
|
1 |
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:
|
1 |
string snum, c |
|
1 |
integer cnt |
|
1 |
|
1 |
// Extract the digits from the user's data |
|
1 |
FOR cnt = 1 to Len(data) |
|
1 |
c = Mid(data, cnt, 1) // Get character |
|
1 |
IF IsNumber(c) THEN snum = snum + c |
|
1 |
NEXT |
|
1 |
This.<span>SetItem</span>(row, dwo.ID, Long(snum)) |
|
1 |
RETURN 3 |