DataWindow Reference
Accessing DataWindow Object Properties in Code

In PowerBuilder, using the Describe and Modify methods to access DataWindow object property values has an advantage and some drawbacks. The examples here use Modify as illustrations, but similar considerations apply to Describe.

Advantage

Allows you to specify column and property names dynamically

In your script, you can build a string that specifies the column and property names.

For example, the following code builds a string in which the default color value and the two color values in the If function are determined in the script. Notice how the single quotes around the expression are included in the first and last pieces of the string:

red_amount = Integer(sle_1.Text)
modstring = "emp_id.Color='" + &
      String(RGB(red_amount, 0, 0)) + &
      "~tIf(emp_status=~~'A~~'," + &
      String(RGB(255, 0, 0)) + &
      "," + &
      String(RGB(red_amount, 0, 0)) + &
      ")'"
Modify(modstring)

The resulting string when red_amount is set to 128 is:

emp_id.Color='128~tIf(emp_status=~'A~',255,128)'

The following is a simpler example without the If function. You do not need quotes around the value if you are not specifying an expression. Here the String and RGB functions result in a constant value in the resulting modstring:

Modify(ls_columnname + ".Color=" + &
      String(RGB(red_amount, 255, 255)))

Drawbacks

Setting several properties at once is possible but hard to debug

Although you can set several properties in a single method call, it is harder to understand and debug scripts that do so.

For example, assume the following is entered on a single line in the script editor:

rtn = dw_1.Modify("emp_id.Font.Italic=0
oval_1.Background.Mode=0
oval_1.Background.Color=255")

Less efficient than an expression

Using a DWObject variable in several property expressions is a little more efficient than setting several properties in a single call to Describe or Modify. However, if you want to be able to name controls dynamically, you might still choose to use Describe or Modify.

For examples of using a DWObject variable, see Using the DWObject variable in PowerBuilder.

Can require complex quoted strings

When you specify an expression for a property value, it is difficult to specify nested quotes correctly -- the code is hard to understand and prone to error. For Describe, this is less of a drawback -- strings do not become as complex because they do not include an expression.

For example, this string entered on a single line in a script assigns a DataWindow expression to the Color property:

Modify("emp_id.Color=~"16777215 ~t
If(emp_status=~~~"A~~~",255,16777215)~"")

For more information about quoted strings, see Nested strings and special characters for DataWindow object properties.

In PowerBuilder, no runtime error occurs when Describe and Modify try to access invalid controls or properties in the DataWindow object. The validity of the argument string is evaluated before the controls are accessed.

Modify

When the string that specifies the control and property to be accessed is invalid, Modify returns an error string, instead of the expected value, such as:

Line 1 Column 12: incorrect syntax.

You can use the error message to figure out what part of the string is incorrect. This is most useful when you are testing your scripts. The error message, which names the line and column number after which the string was not recognized, might not be helpful after your application is deployed.

Describe

When the string for Describe has an unrecognized property, Describe's return value ends with an exclamation point (!). Describe returns as many values as it recognizes up to the incorrect one.

When you specify a valid property but that property doesn't have a value (either because it hasn't been set or because its value is an expression that can't be evaluated), Describe returns a question mark (?) for that property. The property's actual value is null.

For more information

For more information on syntax and usage, see Describe and Modify in Methods for the DataWindow Control