One of the major improvements that came when PB5 was released was the ability to encapsulate expressions within DataWindows. To understand a DataWindow and work with its expressions, you need to know the difference between a DataWindow control, a DataWindow object, and now a DWObject.

In previous versions of PowerBuilder we had one method to access data in a DataWindow object (i.e., SetItem(), GetItemString(), GetItemNumber(), etc.). If you wanted to change a DataWindow object's property such as background color or column border you needed to specify an attribute expression or use a Modify() function. This was a very tedious task due to the complexity necessary to specify an expression, such as using tildes. As a result, PowerBuilder developers requested the ability to use dot notation to reference data and properties.

Since PowerBuilder 5.0 came out a few years ago, we've been able to directly reference a DataWindow's data and properties through dot notation. To provide this feature a new external object, DWObject, was added. Now there are three objects that need to be understood (see Table 1).

DWObject
The object property (DWObject) of a DataWindow control allows us to access data and properties of the DataWindow object using dot notation. PowerBuilder uses this new object in several DataWindow events as arguments (Clicked, DoubleClicked, ItemChanged, etc.). The object appears in the drop-down list of arguments as DWO. To use DWObject you need to determine the type of object (see Table 2).

Some events guarantee that the DWO argument will be of type "Column", Itemchanged and EditChanged, but in events such as Clicked we need to determine the type of object prior to referencing its properties. For example if the user clicked a text object we couldn't reference the id property because text objects don't have a property of id.

If dw_1.object.type = "column' Then sz_id = dw_1.object.id End If

When using DataWindow expressions there's no compiler checking. Expressions that refer to DataWindow object properties or data aren't verified until runtime. This should be obvious in the example above. If the property reference doesn't exist, an error will occur.

Property Expressions
By using DWO or DWObject we can get and change the values of DataWindow properties directly. The data type of a property expression is ANY, not a string, but the value of the property expression data in the ANY variable will always be a string. An example will help clarify this point:

string sz_FirstName, sz_LastName, sz_FullName
any a_FirstName, a_LastName
sz_FirstName = "Dean"
sz_LastName = "Jones"
a_FirstName = "Dean"
a_LastName = "Jones"
//String Data Type
If Len(sz_FirstName ) > 0 Then
sz_FullName = sz_FirstName + " " + sz_LastName
//Any Data Type
If Len(a_FirstName ) > 0 Then
sz_FullName = a_FirstName +" " + a_LastName

The first IF statement will compile fine, the second won't. Even though the ANY variables values are strings, you can't use it in the function LEN(). To make this compile we need to strongly type the ANY data type into the appropriate data type ( i.e., string).

If Len( String(a_FirstName ) ) > 0 Then
sz_FullName = a_FirstName +" " + a_LastName

This may seem confusing but it's important to understand the difference. If a function doesn't accept an argument of ANY you must strongly type the variable before you can call the function.

Setting Property Values
The values of DataWindow object properties are strings. Although the property values are strings, the script compiler allows you to assign numbers and Boolean values to properties whose strings represent numeric values or contain yes/no strings. This doesn't mean the data type is integer or Boolean. It's just a convenience when assigning a value to the property. For example, both of these statements are correct:

dw_1.object.age.visible = FALSE
dw_1.object.age.visible = "NO"
dw_1.object.age.visible = 0
string sz_visible
sz_visible = dw_1.object.age.visible

When you test the value of a property in an expression, you must compare your test value to the stored values.

IF dw_1.object.age.visible = '1' THEN
NOT
IF dw_1.object.age.visible = true THEN
IF dw_1.object.age.visible = 'yes' THEN

You need to verify the data type prior to casting it into another variable. A good example of why would be a column's x position. In most cases x will be a number, but in some cases the developer may have written an expression for the x property. This would cause the application to crash! Make sure to check the data type before you strongly type the property.

If IsNumber(dw_1.object.customer_id.x ) Then
li_x = Integer( dw_1.object.customer_id.x )
NOT
li_x = Integer( dw_1.object.customer_id.x )

Destroying Objects You Didn't Create
If you declare a data type of DWObject, PowerBuilder creates an object for you but it doesn't destroy it. If you reference properties or data of a DataWindow DWObject, PowerBuilder manages the object dynamically, creating and destroying it as needed. However, if you move the object into your own variable for performance, instead of accessing its properties, you override the built-in CREATE and DESTROY of DWObject and assume responsibility for destroying the object. When you declare a data type of DWObject you're not declaring a pointer as with other class objects. When you use an assignment statement PowerBuilder makes a deep copy of the object in the assignment. Even if you don't destroy the object the Garbage Collector will when the variable goes out of scope.

DWObject dwo_customer
dwo_customer = dw_1.Object.customer
n_Rows = RowCount( dw_1 )
FOR i = 1 TO n_Rows
tvi_browse.label = dwo_name.current[ i ]
InsertItemLast(0, tvi_browse )
NEXT
DESTROY dwo_customer

Data Expressions
The DWObject property of the DataWindow control also allows you to specify data expressions that refer directly to the data of the DataWindow object. This direct data manipulation allows you to access small and large amounts of data in a single statement without calling functions. There are several variations of data expression syntax depending on whether you're accessing a single value or an array of values.

When You Know The Name
Syntax for one or all items in the column:

dw_1.Object.columnname {.buffer } {.datasource } { [ rownum ] }

Syntax for selected items:

dw_1.Object.columnname {.Primary}{.datasource } .Selected

Syntax for a range of items:

dw_1.Object.columnname {.buffer } {.datasource } [ startrow, endrow ]

Data in Numbered Columns
Syntax for single items:

dw_1.Object.Data {.buffer } {.datasource } [ row, col ]

Syntax for blocks of data involving a range of rows and columns:

dw_1.Object.Data {.buffer } {.datasource } [ startrow, startcol, endrow, endcol ]

Whole Rows
Syntax for a single row or all of the rows:

dw_1.Object.Data {.buffer } {.datasource } { [ row ] }

Syntax for selected rows:

dw_1.Object.Data {.Primary } {.datasource } .Selected

Is the Expression a DWObject or Data?
When you want to access all the data in the column, remember to specify at least one of the other optional parameters. Otherwise, the expression you specify refers to the column object, not its data. The following expression shows an example:

dw_1.Object.customer_id.current

not

dw_1.Object.customer_id

The first expression refers to all the data in the customer_id column. The second expression refers to the column object DWObject. This is also true for computed fields.

Row Numbers for Computed Fields
When you refer to an object in a band other than the detail band, usually a computed field, you still specify a row number. For the header, footer, or summary, specify a row number of 1. For the group header or trailer specify the group number:

dw_1.Object.avg_cf[1]

When the Expression Is an Array
Whenever you're working with variables you need to pay attention to data types. You can't use mixed type assignments. Therefore when working with expressions that return an array, you must assign the result to an array. This is true even if you know there's only one row in the result. The following statement returns an array:

dw_1.Object.customer_id.Primary

This expression returns a single value:

dw_1.Object.customer_id[22]

Data Structures for Setting Data
When you set data in a Data Window control, the data types of the source values must match the data types of the columns being set. When your data expression refers to a single row and column, you can set the value in the DataWindow control with a value that matches the column's data type. When you're setting values in a single column and specifying an expression that can refer to multiple rows, the values you assign must be in an array of the appropriate data type.

Defining User Objects or Structures
When the expression refers to more than one column, you can assign the data with an any, structure, or user object to the DataWindow data. When you create the definition, the fields in a structure or instance variables in a user object must match the columns. There must be the same number of fields or variables, defined in the same order as the columns, with compatible data types. This creates a limitation when developing an application using object-oriented techniques. Advanced objects will have other objects nested, in them, which stops you from using data expressions to load all your objects.

The following example will move the selected rows from dw_1 into an ANY variable, then moves the ANY variable into dw_2. any a_rows:

a_row = dw_1.object.data.selected dw_2.object.data = a_rows

Example and Testing
Go to our site, www.powerobjects.com and download the example on our objects page, Demo 4. This will allow you to test the performance of the dot notation for moving data.

• Figure 1
• Figure 2
• Figure 3