Describe method (DataWindows)
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
38, “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.
Controls
|
DataWindow type |
Method applies to |
|---|---|
|
PowerBuilder |
DataWindow control, DataWindowChild object, DataStore |
|
Web |
Server component |
|
Web ActiveX |
DataWindow control, DataWindowChild object |
Syntax
[PowerBuilder, Web DataWindow, and Web ActiveX]
|
1 |
string <span>dwcontrol</span><span>.</span><span>Describe</span> ( string <span>propertylist</span> ) |
|
Argument |
Description |
|---|---|
|
dwcontrol |
A reference to a DataWindow control, |
|
propertylist |
A string whose value is a blank-separated For a list of valid properties, see Chapter |
Return Values
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).
When 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:
|
1 |
<span>controlname</span>.<span>property</span> |
For the types of controls in a DataWindow
and their properties with examples, see Chapter
38, “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:
|
Character |
PowerBuilder |
JavaScript |
|---|---|---|
|
tab |
~t |
|
|
newline |
~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.
|
1 |
Evaluate ( '<span>expression</span>', <span>rownumber</span> ) |
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:
|
1 |
ls_ret = dw_1.Describe( & |
|
1 |
"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.
|
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 |
|
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 (!):
|
1 |
string ls_request, ls_report |
|
1 |
|
1 |
ls_request = "DataWindow.Bands DataWindow.Objects "& |
|
1 |
+ "empname_h.Text " & |
|
1 |
+ "empname_h.Type emp.Type emp.Coltype " & |
|
1 |
+ "state.Type empname.Type empname_h.Visible" |
|
1 |
|
1 |
ls_report = dw_1.<span>Describe</span>(ls_request) |
Describe sets the value of ls_report to
the following string:
|
1 |
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! |
These statements check the datatype of the column
named salary before using GetItemNumber to obtain
the salary value:
|
1 |
string ls_data_type |
|
1 |
integer li_rate |
|
1 |
|
1 |
ls_data_type = dw_1.<span>Describe</span>("salary.ColType") |
|
1 |
IF ls_data_type = "number" THEN |
|
1 |
li_rate = dw_1.GetItemNumber(5, "salary") |
|
1 |
ELSE |
|
1 |
. . . // Some processing |
|
1 |
END IF |
This statement finds out the column type of the current column,
using the column name:
|
1 |
s = This.<span>Describe</span>(This.GetColumnName()+ ".ColType") |
For comparison, this statement finds out the same
thing, using the current column’s number:
|
1 |
s = This.<span>Describe</span>("#" + String(This.GetColumn()) & |
|
1 |
+ ".ColType") |
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:
|
1 |
s = This.<span>Describe</span>("DataWindow.FirstRowOnPage") |
|
1 |
IF IsNumber(s) THEN This.SetRow(Integer(s)) |
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:
|
1 |
string rownumber, displayvalue |
|
1 |
|
1 |
rownumber = String(dw_1.GetRow()) |
|
1 |
displayvalue = dw_1.<span>Describe</span>( & |
|
1 |
"Evaluate('LookUpDisplay(state_code) ', " & |
|
1 |
+ rownumber + ")") |
This code, as part of the ItemChanged event’s
script, posts the getdisplayvalue event:
|
1 |
dw_1.PostEvent("getdisplayvalue") |
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:
|
1 |
string s |
|
1 |
s = This.<span>Describe</span>(This.GetColumnName() & |
|
1 |
+ ".Coltype") |
|
1 |
|
1 |
CHOOSE CASE s |
|
1 |
CASE "number" |
|
1 |
IF Trim(data) = "" THEN |
|
1 |
integer null_num |
|
1 |
SetNull(null_num) |
|
1 |
This.SetItem(row, & |
|
1 |
This.GetColumn(), null_num) |
|
1 |
RETURN 3 |
|
1 |
END IF |
|
1 |
|
1 |
CASE "date" |
|
1 |
IF Trim(data) = "" THEN |
|
1 |
date null_date |
|
1 |
SetNull(null_date) |
|
1 |
This.SetItem(row, & |
|
1 |
This.GetColumn(), null_date) |
|
1 |
RETURN 3 |
|
1 |
END IF |
|
1 |
|
1 |
. . . // Additional cases for other datatypes |
|
1 |
|
1 |
END CHOOSE |