Describe

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 Chapter 3, “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

DataWindow type

Method applies to

PowerBuilder

DataWindow control, DataWindowChild object, DataStore object

Web

Server component

Web ActiveX

DataWindow control, DataWindowChild object

Syntax

PowerBuilder, Web DataWindow, and Web ActiveX

string dwcontrol.Describe ( string propertylist ) 

Argument

Description

dwcontrol

A reference to a DataWindow control, DataStore, or child DataWindow.

propertylist

A string whose value is a blank-separated list of properties or Evaluate functions.

For a list of valid properties, see Chapter 3, “DataWindow Object Properties.”

Returns

Returns a string that includes a value for each property or Evaluate function. A newline character (~n or \n) 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).

NoteWhen you can obtain the DataWindow’s SQL statement When you use the Select painter to graphically create a SELECT statement, PowerBuilder saves its own SELECT statement (called a PBSELECT statement), and not a SQL SELECT statement, with the DataWindow definition.

When you call Describe with the property Table.Select, it returns a SQL SELECT statement only if you are connected to the database. If you are not connected to the database, Describe returns a PBSELECT statement.

Property syntax The syntax for a property in the property list is:

controlname.property

For the types of controls in a DataWindow and their properties with examples, see Chapter 3, “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:

Table 9-1: Specifying special characters in different environments

Character

PowerBuilder

JavaScript

tab

~t

\t

newline

~n

\n

single quote

~

\

double quote

~"

\"

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.

Evaluate ( 'expression', rownumber )

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:

ls_ret = dw_1.Describe( &

"Evaluate('If(salary > 100000, 255, 0)', 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.

Table 9-2: Examples of return values for Describe method

Property

Reported value

datawindow.Bands

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

datawindow.Objects

emp[tab]empname[tab]emp_h[tab]empname_h

emp.Type

column

empname.Type

column

empname_h.Type

text

emp.Coltype

char(20)

state.Type

! (! indicates an invalid item—there is no column named state)

empname_h.Visible

?

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 (!):

string ls_request, ls_report


ls_request = "DataWindow.Bands DataWindow.Objects "&

		+ "empname_h.Text " &

		+ "empname_h.Type emp.Type emp.Coltype " &

		+ "state.Type empname.Type empname_h.Visible"


ls_report = dw_1.Describe(ls_request)

Example 2

Describe sets the value of ls_report to the following string:

header~tdetail~tsummary~tfooter~theader.1~ttrailer.1~N emp~tempname~temp_h~tempname_h~N "Employee~R~NName"~N text~N column~Nchar(20)~N!

Example 3

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

string ls_data_type

integer li_rate


ls_data_type = dw_1.Describe("salary.ColType")

IF ls_data_type = "number" THEN

li_rate = dw_1.GetItemNumber(5, "salary")

ELSE

	 . . . // Some processing

END IF

Example 4

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

s = This.Describe(This.GetColumnName()+ ".ColType")

Example 5

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

s = This.Describe("#" + String(This.GetColumn()) &

		+ ".ColType")

Example 6

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:

s = This.Describe("DataWindow.FirstRowOnPage")

IF IsNumber(s) THEN This.SetRow(Integer(s))

Example 7

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:

string rownumber, displayvalue


rownumber = String(dw_1.GetRow())

displayvalue = dw_1.Describe( &

		"Evaluate('LookUpDisplay(state_code) ', " &

		+ rownumber + ")")

Example 8

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

dw_1.PostEvent("getdisplayvalue")

Example 9

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:

string s

s = This.Describe(This.GetColumnName() &

		+ ".Coltype")


CHOOSE CASE s

		CASE "number"

		IF Trim(data) = "" THEN

			integer null_num

			SetNull(null_num)

			This.SetItem(row, &

				This.GetColumn(), null_num)

			RETURN 3

		END IF


CASE "date"

		IF Trim(data) = "" THEN

		date null_date

		SetNull(null_date)

		This.SetItem(row, &

		This.GetColumn(), null_date)

		RETURN 3

		END IF


		. . . // Additional cases for other datatypes


END CHOOSE

See also