Manipulating data in a DataWindow control

To handle user requests to add, modify, and delete data in
a DataWindow, you can write code to process that data, but first
you need to understand how DataWindow controls manage data.

How a DataWindow control manages data

As users add or change data, the data is first handled as
text in an edit control. If the data is accepted, it is then stored
as an item in a buffer.

About the DataWindow buffers

A DataWindow uses three buffers to store data:

Table 2-1: DataWindow buffers

Buffer	Contents
Primary	Data that has not been deleted or filtered out (that is, the rows that are viewable)
Filter	Data that was filtered out
Delete	Data that was deleted by the user or through code

About the edit control

As the user moves around the DataWindow control, the DataWindow
places an edit control over the current cell (row and column):

About text

The contents of the edit control are called text. Text is
data that has not yet been accepted by the DataWindow control. Data
entered in the edit control is not in a DataWindow buffer yet; it
is simply text in the edit control.

About items

When the user changes the contents of the edit control and
presses enter or leaves the cell (by tabbing,
using the mouse, or pressing up arrow or down arrow),
the DataWindow processes the data and either accepts or rejects
it, depending on whether it meets the requirements specified for
the column. If the data is accepted, the text is moved to the current
row and column in the DataWindow Primary buffer. The data in the
Primary buffer for a particular column is referred to as an item.

Events for changing text and items

When data is changed in the edit control, several events occur.
The names of the events are different in each environment, as shown
in the table. This chapter refers to events using PowerBuilder names.

Table 2-2: Event names in different environments

Event		Description
For PowerBuilder, Web DataWindow client control	For Web ActiveX
EditChanged (not available on client control)	onEditChange	Occurs for each keystroke the user types in the edit control
ItemChanged	beforeItemChange	Occurs when a cell has been modified and loses focus
ItemError	onItemError	Occurs when new data fails the validation rules for the column
ItemFocusChanged	onItemFocusChange	Occurs when the current item in the control changes

How text is processed in the edit control

When the data in a column in a DataWindow has been changed
and the column loses focus (for example, because the user tabs to
the next column), the following sequence of events occurs:

1. The DataWindow control converts
   the text into the correct datatype for the column. For example,
   if the user is in a numeric column, the DataWindow control converts
   the string that was entered into a number. If the data cannot be
   converted, the ItemError event is triggered.
2. If the data converts successfully to the correct
   type, the DataWindow control applies any validation rule used by
   the column. If the data fails validation, the ItemError event is
   triggered.
3. If the data passes validation, then the ItemChanged
   event is triggered. If you set an action/return code of
   1 in the ItemChanged event, the DataWindow control rejects the data
   and does not allow the focus to change. In this case, the ItemError
   event is triggered.
4. If the ItemChanged event accepts the data, the ItemFocusChanged
   event is triggered next and the data is stored as an item in a buffer.

Figure 2-2: How text is processed in edit controls

Action/return codes for events

You can affect the outcome of events by specifying numeric
values in the event’s program code. For example, step 3
above describes how you can force data to be rejected with a code
of 1 in the ItemChanged event.

To specify action/return codes:

• PowerBuilder and Web DataWindow Use a RETURN statement
• Web ActiveX Call the SetActionCode or setActionCode method

For information about codes for individual
events, see the DataWindow Reference
.

Accessing the text in the edit control

Using methods

The following methods allow you to access the text in the
edit control:

• GetText—Obtains the
  text in the edit control
• SetText—Sets the text in the edit control

In event code

In addition to these methods, the following events provide
access to the text in the edit control:

• EditChanged
• ItemChanged
• ItemError

Use the Data parameter, which is passed into the event, to
access the text of the edit control. In your code for these events,
you can test the text value and perform special processing depending
on that value.

For an example, see “Coding the ItemChanged
event”.

Manipulating the text in the edit control

When you want to further manipulate the contents of the edit
control within your DataWindow control, you can use any of these
methods:

CanUndo Clear Copy Cut LineCount Paste Position ReplaceText

Scroll SelectedLength SelectedLine SelectedStart SelectedText SelectText TextLine Undo

For more information about these methods,
see the DataWindow Reference
.

Coding the ItemChanged event

If data passes conversion and validation, the ItemChanged
event is triggered. By default, the ItemChanged event accepts the
data value and allows focus to change. You can write code for the
ItemChanged event to do some additional processing. For example,
you could perform some tests, set a code to reject the data, have
the column regain focus, and trigger the ItemError event.

Example

The following sample code for the ItemChanged event for a
DataWindow control called dw_Employee sets the return code
in dw_Employee to reject data that is less than the employee’s
age, which is specified in a SingleLineEdit text box control in
the window.

This is the PowerBuilder version of the code:

Coding the ItemError event

The ItemError event is triggered if there is a problem with
the data. By default, it rejects the data value and displays a message
box. You can write code for the ItemError event to do some other
processing. For example, you can set a code to accept the data value,
or reject the data value but allow focus to change.

For more information about the events of the
DataWindow control, see the DataWindow Reference
.

Accessing the items in a DataWindow

You can access data values in a DataWindow by using methods
or DataWindow data expressions. Both methods allow you to access
data in any buffer and to get original or current values.

The method you use depends on how much data you are accessing
and whether you know the names of the DataWindow columns when the
script is compiled.

For guidelines on deciding which method to
use, see the DataWindow Reference
.

Using methods

There are several methods for manipulating data in a DataWindow
control.

These methods obtain the data in a specified row and column
in a specified buffer (Web DataWindow methods have separate methods
for overloaded versions):

• PowerBuilder GetItemDate, GetItemDateTime, GetItemDecimal, GetItemNumber,
  GetItemString, GetItemTime
• Web ActiveX GetItemDate, GetItemNumber, GetItemString
• Web DataWindow server component GetItemDate, GetItemDateByColNum, GetItemDateByColNumEx, GetItemDateEx, GetItemDateTime,
  GetItemDateTimeByColNum, GetItemDateTimeByColNumEx, GetItemDateTimeEx,
  GetItemNumber, GetItemNumberByColNum, GetItemNumberByColNumEx, GetItemNumberEx,
  GetItemStatus, GetItemStatusByColNum, GetItemString, GetItemStringByColNum,
  GetItemStringByColNumEx, GetItemStringEx, GetItemTime, GetItemTimeByColNum, GetItemTimeByColNumEx,
  GetItemTimeEx

This method sets the value of a specified row and column:

• PowerBuilder
  and Web ActiveX SetItem
• Web DataWindow server component SetItemDate, SetItemDateByColNum, SetItemDateTime, SetItemDateTimeByColNum,
  SetItemNumber, SetItemNumberByColNum, SetItemStatus, SetItemStatusByColNum, SetItemString,
  SetItemStringByColNum, SetItemTime, SetItemTimeByColNum

For example, the following statement, using PowerBuilder syntax,
assigns the value from the empname column of the first row to the
variable ls_Name:

This PowerBuilder statement sets the value of the empname
column in the first row to the string Waters:

Uses You call the GetItem methods to obtain the data that has been
accepted into a specific row and column. You can also use them to
check the data in a specific buffer before you update the database.
You must use the method appropriate for the column’s datatype.

For more information about the methods listed
above, see the DataWindow Reference

.

Using expressions

DataWindow data expressions refer to single items, columns,
blocks of data, selected data, or the whole DataWindow.

The way you construct data expressions depends on the environment:

• PowerBuilder Use dot notation
• Web ActiveX Data expressions are not supported

Expressions in PowerBuilder The Object property of the DataWindow control lets you specify
expressions that refer directly to the data of the DataWindow object
in the control. This direct data manipulation allows you to access
small and large amounts of data in a single statement, without calling methods:

The next statement sets the value of the first column in the
first row in the DataWindow to Smith:

For complete instructions on how to construct
DataWindow data expressions, see the DataWindow Reference
.

Using other DataWindow methods

There are many more methods you can use to perform activities
in DataWindow controls. Here are some of the more common ones:

Table 2-3: Common methods in DataWindow controls

Method	Purpose
AcceptText	Applies the contents of the edit control to the current item in the DataWindow control
DeleteRow	Removes the specified row from the DataWindow control, placing it in the Delete buffer; does not delete the row from the database
Filter	Displays rows in the DataWindow control based on the current filter
GetRow	Returns the current row number
InsertRow	Inserts a new row
Reset	Clears all rows in the DataWindow control
Retrieve	Retrieves rows from the database
RowsCopy, RowsMove	Copies or moves rows from one DataWindow control to another
ScrollToRow	Scrolls to the specified row
SelectRow	Highlights a specified row
ShareData	Shares data among different DataWindow controls.
Update	Sends to the database all inserts, changes, and deletions that have been made in the DataWindow control

Some, but not all, of these methods are available
for the Web DataWindow client control, server component, or both.
Each development environment provides a reference list of methods.
For a complete list of DataWindow methods, see the PowerBuilder
Browser for PowerScript targets or the Components tab of the System
Tree for Web targets.For complete information on DataWindow methods,
see the DataWindow Reference

.

---