Dissecting The Datawindow

Last Updated 16^th Feb 1998

Components of the Datawindow Technology

Any PowerBuilder developer worth his name knows that the Datawindow is one of PowerBuilder’s greatest strengths. The Datawindow technology can be split into two components -

The Datawindow Control
The Datawindow Object

The Datawindow Control is like other PowerBuilder controls with attributes, functions and events. The Datawindow Object is a definition - a resource - which decides how the Datawindow Control looks like and how it behaves. A rough analogy may be drawn with the Picture Control and a Bitmap. A Bitmap is the definition of the image which is to be displayed inside a Picture Control.

A Datawindow Object is usually created by painting it in the Datawindow Painter at design time. PowerBuilder provides the powerful Describe and Modify functions(and now with PB5 the ‘Dot notation’) to access and change the definition at runtime. However as the use of the Datawindow becomes more complex, there are times when one needs to create Datawindow Objects ‘on the fly’. One of the ways to achieve this is by using -

The Transaction object’s - SyntaxFromSQL() function and
The Datawindow Control’s Create() function

Though PowerBuilder provides the ‘External’ style for Datawindow Objects, it does not provide any way to generate syntax at run time that is not based on SQL. I have tried to address this need with ‘n_cst_dwgen’ - a Datawindow Syntax generator.

Understanding the Datawindow Syntax

A basic understanding of the Datawindow syntax can greatly help when you need to tweak the definition a bit or solve some pesky problem. So how do you get to a Datawindow Object’s syntax? At design time you can view the syntax by following these steps-

In the Library Painter open the PBL which contains the Datawindow Object
Right click on the object and choose ‘Export’ from the pop-up menu. PowerBuilder brings up the ‘Save File’ dialog box. Give the file a name(or accept the default) and save it.
The exported syntax will be written to a file with the name that you specified and a ‘SRD’ extension. Open this file in any ASCII editor like NotePad to view the syntax.

Sometimes you might want to view the syntax at run-time; for example to debug the syntax generated by using SyntaxFromSQL and Create. The entire syntax is stored in the Datawindows ‘Syntax’ attribute which can be accessed by using -

<DW Control Name>.Describe("DataWindow.Syntax"), or
<DW Control Name>.Object.DataWindow.Syntax

At first glance the syntax is indeed intimidating but after a closer inspection you will realize that the syntax is quite familiar and almost self explanatory. In fact, it is quite similar to the Modify and Describe syntax. To understand the Datawindow syntax generated by PowerBuilder lets export the simplest of datawindows - an external source Datawindow with a single column. I first painted this Datawindow in the Datawindow painter. This is what it looks like -

To make things very simple I deleted the column header text. Next I exported the syntax using the Library Painter. Here is that syntax:

$PBExportHeader$dw_study2.srd
release 5;
Datawindow(units=0 timer_interval=0 color=79741120 processing=0 print.documentname="" print.orientation = 0 print.margin.left = 110 print.margin.right = 110 print.margin.top = 97 print.margin.bottom = 97 print.paper.source = 0 print.paper.size = 0 print.prompt=no )
header(height=101 color="536870912" )
summary(height=1 color="536870912" )
footer(height=1 color="536870912" )
detail(height=113 color="536870912" )
table(column=(type=char(10) updatewhereclause=yes name=mycol dbname="MyCol" ) )
column(band=detail id=1 alignment="0" tabsequence=10 border="5" color="33554432" x="19" y="16" height="77" width="275" format="[general]" name=mycol edit.limit=0 edit.case=any edit.autoselect=yes edit.autohscroll=yes font.face="Arial" font.height="-10" font.weight="400" font.family="2" font.pitch="2" font.charset="0" background.mode="2" background.color="67108864" )

The Datawindow syntax can be divided into 5 sections-

Release information
Datawindow attributes
Datawindow Band attributes
Datawindow Source definition
Datawindow Object definitions

Release Information

release 5;

This section is easily the shortest of them all. It comprises of just one statement indicating the PowerBuilder release with which this Datawindow Object was constructed. So far I have only seen the major release number indicated here i.e. ‘release 4’, ‘release 5’, etc.. This information is used by the Datawindow engine to determine if it can handle the rest of the syntax. If the number is higher than the PowerBuilder release number then PowerBuilder gives the error message - ‘Datawindow Syntax has incorrect release number’. This is the error message you will get if you try to import a Datawindow generated with PB5 into a PB4 application. On the other hand, PB5 will happily import a Datawindow created in PB4. This section is mandatory. Also note the semicolon at the end. This is the only section which requires a semicolon at the end.

Datawindow Attributes

Datawindow(units=0 timer_interval=0 color=79741120 processing=0 print.documentname="" print.orientation = 0 print.margin.left = 110 print.margin.right = 110 print.margin.top = 97 print.margin.bottom = 97 print.paper.source = 0 print.paper.size = 0 print.prompt=no )

This section describes the attributes which affect the Datawindow as a whole. Attributes like the Datawindow units and print specifications. The ‘processing’ attribute specifies the Datawindow style -

Style Value

Group or Form or Tabular 0

Grid 1

Label 2

Graph 3

Crosstab 4

Tip
The next time you want to change the style of a Datawindow, there is no need to repaint the entire Datawindow. Just export the syntax, change the processing attribute and import it back in.

Also, at run time using Describe, the 'processing' attribute can be used to determine the Datawindow style.

This section is not mandatory to build the Datawindow object, and PowerBuilder uses default values for information not provided.

Datawindow Band Attributes

header(height=101 color="536870912" )
summary(height=1 color="536870912" )
footer(height=1 color="536870912" )
detail(height=113 color="536870912" )

This section consists of one statement for each band in the datawindow. It describes the attributes of each band like height and color. Again this section is not mandatory and PowerBuilder assumes default values for the information not provided. But the default height is assumed to be 1, as a result if the height of band is not specified no objects in that band will be visible. So if you plan to place any object in a band it is required that you at least specify the height of that band in this section.

Datawindow Source Definition

table( <Result set>
<SQL Source> )

This section actually consists of two parts - the Datawindow result set definition and the Datawindow SQL source definition. Since our Datawindow is an external source Datawindow there is no SQL source specified here.

The result set describes the data type, name and database name, initial value etc. of each column in the Datawindow.

column=(type=char(10) updatewhereclause=yes name=mycol dbname="MyCol" )

Tip
The type attribute defines the PowerBuilder datatype for the column. This attribute can be tweaked whenever PowerBuilder fails to correctly determine the datatype of a column. This typicaly happens with the computed columns in a SQL statement or a 'timestamp' column which PowerBuilder sometimes interprets as Char(0).

The order in which a column is defined here determines it’s numeric id which can be used in Describe and Modify to refer to the column. Ex. -

dw_1. Describe("#3.Visible=0")

In datawindows with the SQL or Stored Procedure source this section also describes the SQL which will generate the result set described above. Here is an example -

retrieve="PBSELECT( VERSION(400) TABLE(NAME=~"customer~" ) COLUMN(NAME=~"customer.fname~") COLUMN(NAME=~"customer.lname~")) " )

The SQL source is actually stored internally in a generic PowerBuilder SQL dialect called PBSELECT. Such is the case only if you ‘paint’ the SQL statement. If you choose the ‘Convert to Syntax’ option and type in the SQL statement then PowerBuilder just stores the SQL as is. Ex. -

retrieve=" SELECT ~"customer~".~"fname~",
~"customer~".~"lname~"
FROM ~"customer~" "

Datawindow Object Definitions

column(band=detail id=1 alignment="0" tabsequence=10 border="5" color="33554432" x="19" y="16" height="77" width="275" format="[general]" name=mycol edit.limit=0 edit.case=any edit.autoselect=yes edit.autohscroll=yes font.face="Arial" font.height="-10" font.weight="400" font.family="2" font.pitch="2" font.charset="0" background.mode="2" background.color="67108864" )

This section defines each object which is placed in one of the Datawindow bands. Objects like columns, text objects, computes fields, drawing objects etc. For each object it is important to specify the band to which the object belongs. In case of column objects, the ‘id’ links the object to a column in the result set.

Summary

The power and flexibility of the Datawindow technology lies in the simplicity of it’s architecture. The technology has been split into two primary constituents - The Datawindow Control and the Datawindow Object. The Datawindow Object is a syntactical definition which dictates how the Datawindow Control will portray the data and also how it will behave. The Datawindow syntax consists of five sections which describe the various visual and behavioural aspects of the Datawindow. I have tried to explain the content and significance of these sections using a very simple example.

The information provided in this article is purely based on empirical knowledge and my experience with developing PowerBuilder applications. Please send me your comments at jiggys@usa.net

Back to my HomePage

Style	Value
Group or Form or Tabular	0
Grid	1
Label	2
Graph	3
Crosstab	4