SetItem

method (DataWindows)

Description

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

Applies to

DataWindow type	Method applies to
PowerBuilder	DataWindow control, DataWindowChild object, DataStore object

Syntax

PowerBuilder

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

1 2	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.

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

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
the section called “SetItem” in 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:

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

1	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

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

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