Describe – PB Docs 2017

Description

Reports the values of properties of a DataWindow object and controls
within the DataWindow object. Each column and graphic control in the
DataWindow has a set of properties (listed in DataWindow Object Properties). You
specify one or more properties as a string, and Describe returns the
values of the properties.

Describe can also evaluate expressions involving values of a
particular row and column. When you include Describe’s Evaluate function
in the property list, the value of the evaluated expression is included in
the reported information.

Applies to

Syntax

PowerBuilder

Return value

Returns a string that includes a value for each property or
Evaluate function. A newline character (~n or
) separates the value of
each item in propertylist.

If the property list contains an invalid item, Describe returns an
exclamation point (!) for that item and ignores the rest of the property
list. Describe returns a question mark (?) if there is no value for a
property.

When the value of a property contains an exclamation point or a
question mark, the value is returned in quotes so that you can distinguish
between the returned value and an invalid item or a property with no
value.

If any argument’s value is null, in PowerBuilder and JavaScript the
method returns null.

Usage

Use Describe to understand the structure of a DataWindow. For
example, you can find out which bands the DataWindow uses and what the
datatypes of the columns are. You can also use Describe to find out the
current value of a property and use that value to make further
modifications.

Describe is often used to obtain the DataWindow’s SELECT statement
in order to modify it (for example, by adding a WHERE clause).

Property syntax

The syntax for a property in the property list is:

For the types of controls in a DataWindow and their properties with
examples, see DataWindow Object
Properties

Properties whose value is a list

When a property returns a list, the tab character separates the
values in the list. For example, the Bands property reports all the bands
in use in the DataWindow as a list.

   header[tab]detail[tab]summary[tab]footer[tab]header.1[tab]trailer.1

If the first character in a property’s returned value list is a
quotation mark, it means the whole list is quoted and any quotation marks
within the list are single quotation marks.

For example, the following is a single property value.

   ” Student[tab]’Andrew’or'[newline]Andy’ “

Specifying special characters

There are different ways of specifying special characters in a
string in each environment:

Quoted property values

Describe returns a property’s value enclosed in quotes when the text
would otherwise be ambiguous. For example, if the property’s value
includes a question mark, then the text is returned in quotes. A question
mark without quotes means that the property has no value.

Column name or number

When the control is a column, you can specify the column name or a
pound sign (#) followed by the column number. For example, if salary is
column 5, then “salary.coltype” is equivalent to “#5.coltype”.

Control names

The DataWindow painter automatically gives names to all controls.
(In previous versions of PowerBuilder, the painter only named columns and
column labels.)

Evaluating an expression

Describe’s Evaluate function allows you to evaluate DataWindow
painter expressions within a script using data in the DataWindow. Evaluate
has the following syntax, which you specify for  propertylist.

Expression is the expression you want to evaluate and rownumber is
the number of the row for which you want to evaluate the expression. The
expression usually includes DataWindow painter functions. For example, in
the following statement, Describe reports either 255 or 0 depending on the
value of the salary column in row 3:

You can call DataWindow control functions in a script to get data
from the DataWindow, but some painter functions (such as LookUpDisplay)
cannot be called in a script. Using Evaluate is the only way to call them.
(See the example Evaluating the
display value of a DropDownDataWindow.)

Sample property values

To illustrate the types of values that Describe reports, consider a
DataWindow called dw_emp with one group level. Its columns are named emp
and empname, and its headers are named emp_h and empname_h. The following
table shows several properties and the returned value. In the first
example below, a sample command shows how you might specify these
properties for Describe and what it reports.

Examples

PowerBuilder examples

This example calls Describe with some of the properties shown in the
previous table. The reported values (formatted with tabs and newlines)
follow. Note that because state is not a column in the DataWindow,
state.type returns an exclamation point (!):

Describe sets the value of ls_report to the following string:

These statements check the datatype of the column named salary
before using GetItemNumber to obtain the salary value:

Column name or number

This statement finds out the column type of the current column,
using the column name:

For comparison, this statement finds out the same thing, using the
current column’s number:

Scrolling and the current
row

This example, as part of the DataWindow control’s ScrollVertical
event, makes the first visible row the current row as the user scrolls
through the DataWindow:

Evaluating the display value of a
DropDownDataWindow

This example uses Describe’s Evaluate function to find the display
value in a DropDownDataWindow column called state_code. You must execute
the code after the ItemChanged event, so that the value the user selected
has become the item value in the buffer. This code is the script of a
custom user event called getdisplayvalue:

This code, as part of the ItemChanged event’s script, posts the
getdisplayvalue event:

Assigning null values based on the column’s
datatype

The following excerpt from the ItemError event script of a
DataWindow control allows the user to blank out a column and move to the
next column. For columns with datatypes other than string, the user cannot
leave the value empty (which is an empty string and does not match the
datatype) without the return code. Data and row are arguments of the
ItemError event:

See also

Create

Modify