Guia Programador Datawindow Cap 1 - 3

8/9/2019 Guia Programador Datawindow Cap 1 - 3

1/58

Chapter 1 About DataWindow Technology

About this chapter

This chapter describes what DataWindow objects are and the ways you can use them in various application

architectures and programming environments.

About DataWindow objects, controls, and components

DataWindow technology is implemented in two parts:

• A DataWindow object The DataWindow object defines the data source and presentation style for

the data.

• A DataWindow control or component The control or component is a container for the

DataWindow object in the application. You write code that calls methods of the container to

manipulate the DataWindow object.

DataWindow controls and components

The DataWindow was originally invented for use in PowerBuilder to provide powerful data retrieval

manipulation and update capabilities for client!server applications. "ow the DataWindow is available in

several environments:

• PowerBuilder DataWindow # PowerBuilder control for use in client!server and distributed

PowerBuilder applications.

• Web DataWindow # thin$client DataWindow implementation for Web applications that provides

most of the data manipulation presentation and scripting capabilities of the PowerBuilderDataWindow re%uiring the Web DataWindow component on a component server but no

PowerBuilder D&&s on the client.

• Web DataWindow DTC # design$time control used to represent the Web DataWindow on a

development machine. The DT' is an #ctive( control that generates a set of instructions for theDataWindow component on a component server. The component generates a Web DataWindow for

display in a client browser. The client browser does not need to support #ctive( controls to display

the Web DataWindow.

• Sybase DataWindow Web control for Actie! #n #ctive( control for use on Web pages. The

client browser must support #ctive( controls to display a DataWindow object used by this control

• DataWindow plug"in # browser plug$in that displays Powersoft reports.

)or a comparison of each of these environments see *'hoosing a DataWindow technology*.

You can also use Data+tore objects as containers for a DataWindow object. Data+tores provide DataWindow

functionality for retrieving and manipulating data without the onscreen display. ,ses for Data+tores include

specifying layouts for printing and managing data in the server component of a distributed application.

1


2/58

What DataWindow objects are

# DataWindow object is an object that you use to retrieve present and manipulate data from a relational

database or other data source -such as an /cel wor0sheet or dB#+ file1. You can specify whether the

DataWindow object supports updating of data.

DataWindow objects have 0nowledge about the data they are retrieving. You can specify display formats

presentation styles and other data properties to ma0e the data meaningful -significativo1 to users.

2n the DataWindow painter you can also ma0e Powersoft report -P+31 files which you can use in

DataWindow controls or components. # P+3 file contains a report definition$$essentially a nonupdatable

DataWindow object$$as well as the data contained in the report when the P+3 file was created. 2t does not

retrieve data.

Where to defne DataWindow objects

You define DataWindow objects in the PowerBuilder DataWindow painter. You can also define nonupdatable

DataWindow objects in the 2nfo4a0er 3eport painter.

Presentation styles and data sources

When you define a DataWindow object you choose a presentation style and a data source.

Presentation styles

# presentation style defines a typical style of report and handles -maneja1 how rows are grouped on the page.

You can customi5e the way the data is displayed in each presentation style. The presentation styles include:

Table 6$6: DataWindow presentation styles

Presentation

styleDescription

Tabular Data columns across the page and headers above -sobre1 each column. +everal rows are

viewable at once.

)reeformData columns going down - bajando1 the page with labels ne/t to each column. 7ne row

displayed at a time.

8rid 3ow$and$column format li0e a spreadsheet with grid lines. ,sers can move borders and

2


3/58

columns.

&abel +everal labels per page with one row for each label. ,sed for mailing and other labels.

"$,p Two or more rows of data ne/t to each other across the page. ,seful for periodic datasuch as data for each day of the wee0 or each month in the %uarter -trimestre1.

8roup# tabular style with rows grouped under headings. ach group can have summary fields

with computed statistics.

'omposite+everal DataWindow objects grouped into a single presentation. "ot supported by the

Web DataWindow.

8raph 8raphical presentation of data. "ot supported by the Web DataWindow.

'rosstab Data summary in a row$and$column format.

3ichTe/tParagraphs of te/t with embedded data columns. "ot supported by the Web DataWindow

or the +ybase DataWindow Web control for #ctive(.

7&#n 7& object lin0ed or embedded in the DataWindow and associated with the retrieved

data. "ot supported by Web DataWindow.

)or e/amples of the presentation styles see the PowerBuilder User's Guide.

Data sources

The data source specifies where the data in the DataWindow comes from and what data items are displayed.

Data can come from tables in a database or you can import data from a file or specify the data in code. )or

databases the data specification is saved in a +9& statement. 2n all cases the DataWindow object saves the

names of the data items to display as well as their data types.

Table 6$: Data sources you can use for a DataWindow

Data

sourceDescription

9uic0

+elect

The data is coming from one or more tables in a +9& database. The tables must be related

through a foreign 0ey. You need to choose only columns selection criteria and sorting.

3


4/58

+9& +electYou want more control over the select statement that is generated for the data source. You

can specify grouping computed columns and so on.

9uery

The data has already been selected and the +9& statement is saved in a %uery object that you

have defined in the 9uery painter. When you define the DataWindow object the %uery

object is incorporated into the DataWindow and does not need to be present when you run

the application.

+tored

ProcedureThe data is defined in a database stored procedure.

/ternalThe data is not stored in a database but is imported from a file -such as a tab$separated or

dB#+ file1 or populated from code.

Basic process

,sing a DataWindow involves two main steps:

6. ,se the DataWindow painter to create or edit a DataWindow object.

2n the painter you define the data source presentation style and all other properties of the object

such as display formats validation rules sorting and filtering criteria and graphs.

. 2n your development environment put a DataWindow control or component in a window form orWeb page and associate a DataWindow object with it.

2t is through this control that your application communicates with the DataWindow object you

created in the DataWindow painter. You write code to manipulate the DataWindow control and the

DataWindow object it contains. Typically your code retrieves and updates data changes theappearance of the data handles errors and shares data between DataWindow controls.

Choosing a DataWindow technology

+ince DataWindow technology can be used in different environments it may not be obvious what approach

you should ta0e to implementing your data$enabled application. This section describes the DataWindow

technologies available for three basic application architectures and the re%uirements for each DataWindow

solution. +ee Building Internet and Enterprise Applications for further discussion of application architectures.

The basic architectures are:

• Client#serer # program running on a client wor0station accesses a database running on a server.

The user interface and business logic reside together - juntas1 on the client computer.

• Distributed application The user interface on the client computer calls components on a middle$tier

server which e/ecute business logic and access the database server.


5/58


6/58

# component server and a dynamic page server wor0 together to generate a client control with data and

include it in a Web page. ach time the user re%uests a new page of data updates data or inserts or deletes

rows the server gets a re%uest to generate a new page. Depending on how state is managed the component

may retrieve data each time it is called causing added load on the server.

De$elopment tools

The Web Target interface in PowerBuilder provides the Web DataWindow DT' that you can use to develop

Web DataWindows without hand coding. You can also write your own server$side scripts to create Web

DataWindows using the component server=s #P2. You can write the scripts for interpretation by a specific

page server type -PowerDynamo #ctive +erver Pages or


7/58

You can use the Web Target tools for wor0ing with #ctive( components to develop your Web application.

)or information see 'hapter @ *,sing the DataWindow Web 'ontrol for #ctive(*

DataWindow plug"in

The DataWindow plug$in is a browser plug$in that displays Powersoft reports -P+3s1.

!unctionality

# P+3 is a fro5en DataWindowA it cannot be modified and the data does not stay current. ;owever a P+3 is a

compact representation of the DataWindow definition and data and can be downloaded efficiently. 2t is an

efficient means of viewing batch$produced reports.

The user cannot modify or update the data.

Client re"uirements

The plug$in e/ecutable must be installed in the browser plug$in directory. 2t cannot be downloaded and

installed automatically. The plug$in wor0s in "etscape browsers. 2nternet /plorer browsers prior to version

. also support the plug$in.

DataWindow behavior that would compromise security of the client such as +ave#s is not disabled.

De$elopment tools

You can use PowerBuilder or 2nfo4a0er to create P+3s.

)or more information about the plug$in architecture see Application Techniues.

PowerBuilder DataWindow control

$eatures

The PowerBuilder DataWindow control is a container for DataWindow objects in a PowerBuilder application.

You can use it in a window to present an interactive display of data. The user can view and change data andsend changes to the database.

2n addition to the DataWindow control the Data+tore object provides a nonvisual container for server

applications and other situations where onscreen viewing is not necessary.

The DataWindow supports data retrieval with retrieval arguments and data update. You can use edit styles

display formats and validation rules for consistent data entry and display. The DataWindow provides manymethods for manipulating the DataWindow including 4odify for changing DataWindow object properties.

You can share a result set between several DataWindow controls and you can synchroni5e data between a

client and server.

Deelopment enironment

'


8/58

You can develop both parts of your DataWindow implementation in PowerBuilder. You use:

• The DataWindow painter to define DataWindow objects.

• The Window or ,ser 7bject painters to add DataWindow controls to windows or visual user objects.

The DataWindow control is on the painters= palette of controls.

2n these painters you write scripts that control the DataWindow=s behavior and manipulate the data itretrieves. Your scripts can also instantiate Data+tore objects.

2n the PowerBuilder Browser you can e/amine the properties events and methods of DataWindow controls

and Data+tore objects on the system tab page. 2f you have a library open that contains DataWindow objects

you can e/amine the internal properties of the DataWindow object on the Browser=s DataWindow tab page.

DataWindow objects

The DataWindow control or Data+tore object uses a DataWindow object which determines what data is

retrieved and how it is displayed. The control can also display Powersoft reports -P+3s1 which do not need to

retrieve data.

# DataWindow object for a PowerBuilder application can have any presentation style.

Database connections

The PowerBuilder DataWindow can use 7DB'


9/58

2n PowerBuilder you can ta0e advantage of object inheritance by defining a user object inherited from a

DataWindow control and adding your own custom functionality. You can reuse the customi5ed DataWindow

control throughout your applications.

You create Data+tore objects the nonvisual version of a DataWindow control by creating them in a script andcalling methods for the object. You can also define a user object that is inherited from a Data+tore and

customi5e it. )or more information see 'hapter > *,sing Data+tore 7bjects *.

%ibraries and applications

You store DataWindow objects in PowerBuilder libraries -PB&s1 during development. When you build your

application you can include the DataWindow objects in the application e/ecutable or in PowerBuilder

dynamic libraries -PBDs1.

)or more information about designing DataWindow objects and building a PowerBuilder application see

the PowerBuilder User's Guide and Application Techniues.

Chapter 2 )sing DataWindow *bjects

About this chapter

This chapter describes how to use DataWindow objects in an application.

+eore you begin

This chapter assumes that you 0now how to build DataWindow objects in the DataWindow painter as

described in the PowerBuilder User's Guide.

About using DataWindow objects

+uilding DataWindow objects

Before you can use a DataWindow object in an application you need to build it. PowerBuilder has separate

painters for database management DataWindow definition and library management.

You define and edit a DataWindow object in the DataWindow painter. You specify its data source and

presentation style then enhance -mejora1 the object by specifying display formats edit styles and more.

-


10/58

The DataWindow painter is also where you ma0e Powersoft report -P+31 files which you may want to use in

applications too. # P+3 file contains a report definition$$essentially a nonupdatable DataWindow object$$as

well as the data contained in that report when the P+3 file was created.

!eport ob"ects onl# in In$o%aker 7lder versions of PowerBuilder had a 3eport painter as well as a

DataWindow painter. # report object could retrieve but not update dataA it was essentially a nonupdatable

DataWindow object. The 3eport painter is now available only in 2nfo4a0er.

.anaging DataWindow objects

+everal painters let you manage and pac0age your DataWindow objects for use in applications.

2n particular you can maintain DataWindow objects in one or more libraries -PB& files1. When you are ready

to use your DataWindow objects in applications you can pac0age them in more compact runtime libraries

-PBD files1.

)or further details on how to build and organi5e DataWindow objects see the PowerBuilder User's Guide.

)sing DataWindow objects

#fter you build a DataWindow object -or P+3 file1 in the DataWindow painter you can use it to display and

process information from the appropriate data source. The sections that follow e/plore the details of how to

do this.

Putting a DataWindow object into a control

The DataWindow control is a container for DataWindow objects in an application. 2t provides properties

methods and events for manipulating the data and appearance of the DataWindow object. The DataWindow

control is part of the user interface of your application.

You also use DataWindow objects in the nonvisual Data+tore and in child DataWindows such as drop$down

DataWindows and composite presentation styles. )or more information about Data+tores see 'hapter >

*,sing Data+tore 7bjects *. )or more information about drop$down DataWindows and composite

DataWindows see the PowerBuilder User's Guide.

To use the DataWindow object in an application you add a DataWindow control to a window or form then

associate that control with the DataWindow object:

1/


11/58

$igure &"1' Putting a DataWindow object into a DataWindow control

This section has information about:

• "ames for DataWindow controls and DataWindow objects

• Procedures for inserting a control and assigning a DataWindow object to the control

• +pecifying the DataWindow object during e/ecution

)or information about assigning a DataWindow object to a Web DataWindow control see Working with Web

and JSP Targets or *&oading the DataWindow object*.

)or information about assigning a DataWindow object to a Web control for #ctive( see *+pecifying a

DataWindow object for the control*.

(ames for DataWindow controls and DataWindow objects

There are two names to be aware -tener en cuenta1 of when you are wor0ing with a DataWindow:

• The name of the DataWindow control

• The name of the DataWindow object associated with the control

The DataWindow control name When you place a DataWindow control in a window or form it gets a

default name. You should change the name to be something meaningful for your application.

2n PowerBuilder the name of the control has traditionally had a prefi/ of dw. This is a useful convention to

observe in any development environment. )or e/ample if the DataWindow control lists customers you mightwant to name it dwcustomer.

Using the na&e 2n code always refer to a DataWindow by the name of the control -such as

dwcustomer1. Do not refer to the DataWindow ob"ect that is in the control.

The DataWindow object name To avoid confusion you should use different prefi/es for DataWindow

objects and DataWindow controls. The prefi/ d is commonly used for DataWindow objects. )or e/ample if

11


12/58

the name of the DataWindow control is dwcustomer you might want to name the corresponding

DataWindow object dcustomer.

Wor)ing with the DataWindow control in PowerBuilder

To place a DataWindow control in a window:

6. 7pen the window that will contain the DataWindow control.

. +elect 2nsertE'ontrolEDataWindow from the menu bar.

F. 'lic0 where you want the control to display.

PowerBuilder places an empty DataWindow control in the window:

>. -7ptional1 3esi5e the DataWindow control by selecting it and dragging one of the handles.

#peciying a DataWindow object

#fter placing the DataWindow control you associate a DataWindow object with the control.

To associate a DataWindow object with the control:

6. 2n the DataWindow Properties view clic0 the Browse button for the Data7bject property.

. +elect the DataWindow object that you want to place in the control and clic0 7C.

The name of the DataWindow object displays in the Data7bject bo/ in the DataWindow Properties

view.

F. -7ptional1 'hange the properties of the DataWindow control as needed.

12


13/58

Allowing users to &oe (ataWindow controls 2f you want users to be able to move a

DataWindow control during e/ecution give it a title and select the Title Bar chec0bo/. Then users

can move the control by dragging the title bar.

Defining reusable DataWindow controls

You might want all the DataWindow controls in your application to have similar appearance and behavior. )or

e/ample you might want all of them to do the same error handling.

To be able to define these behaviors once and reuse them in each window you should create a standard user

object based on the DataWindow control: define the user object=s properties and write scripts that perform the

generic processing you want such as error handling. Then place the user object -instead of a new

DataWindow control1 in the window. The DataWindow user object has all the desired functionality

predefined. You do not need to respecify it.

)or more information about creating and using user objects see the PowerBuilder User's Guide.

*diting the DataWindow object in the control

7nce you have associated a DataWindow object with a DataWindow control in a window you can go directly

to the DataWindow painter to edit the associated DataWindow object.

To edit an associated DataWindow object:

6. +elect 4odify DataWindow from the DataWindow control=s pop$up menu.

PowerBuilder opens the associated DataWindow object in the DataWindow painter.

Specifying the DataWindow object during e+ecutionChanging the DataWindow object

The way to change the DataWindow object depends on the environment:

• PowerBuilder +et the Data7bject property to one of the DataWindow objects built into the

application

• Web Actie! +et the +ource)ile"ame and DataWindow7bject properties to select a new library file

and DataWindow

• Web DataWindow 2f you are not using the Web Target object model you can call the +etDW7bject

method on the ;T4& DataWindow generator component

Setting the transaction ob"ect when #ou change the (ataWindow ob"ect When you change the

DataWindow object during e/ecution you may need to call setTrans or setTrans7bject again.

)or more information see *+etting the transaction object for the DataWindow control*.

Dynamically creating a DataWindow object

13


14/58

You can also create a new DataWindow object during e/ecution and associate it with a control.

)or more information see 'hapter F *Dynamically 'hanging DataWindow 7bjects *.

Changing the DataWindow in PowerBuilder

When you associate a DataWindow object with a control in the window you are setting the initial value of the

DataWindow control=s Data7bject property.

During e/ecution this tells your application to create an instance of the DataWindow object specified in the

control=s Data7bject property and use it in the control.

#etting the Data*bject property in code

2n addition to specifying the DataWindow object in the Window painter you can switch the object that

displays in the control during e/ecution by changing the value of the Data7bject property in code.

)or e/ample: to display the DataWindow object demphist from the library e&p)pbl in the DataWindowcontrol dwemp you can code:

dw,emp-Data.bject / 0d,emp,hist0

The DataWindow object demphist was created in the DataWindow painter and stored in a library on the

application search path. The control dwemp is contained in the window and is saved as part of the window

definition.

Preenting redrawing You can use the +et3edraw method to turn off redrawing in order to avoid flic0er

and reduce redrawing time when you are ma0ing several changes to the properties of an object or control.

Dynamically changing the DataWindow object at e/ecution time implicitly turns redrawing on. To turnredrawing off again call the +et3edraw method every time you change the DataWindow object:

dw,emp-Data.bject / 0d,emp,hist0

dw,emp-Setedraw2$A%S*3

)sing P#0 fles

To put a P+3 file into a DataWindow control at e/ecution time change the control=s Data7bject property to

specify that P+3 file name.

Changing the DataWindow in the Web Actie!

When you associate a DataWindow object with a DataWindow control you are setting the initial value of the

DataWindow control=s +ource)ile"ame and DataWindow7bject properties.

During e/ecution this tells your application to:

6. &oo0 for DataWindow objects in the library -PB& file1 or runtime library -PBD file1 specified in the

control=s +ource)ile"ame property.

1


15/58


16/58

. 'onnect to the database.

F. +et the transaction object for the DataWindow control.

>. 3etrieve and update data.

. Disconnect from the database.

This section provides instructions for setting the transaction object for a DataWindow control and for using

the DataWindow object to retrieve and update data.

To learn more about setting values for the transaction object connecting to the database and disconnecting

from the database see:

• PowerBuilder Application Techniues *,sing Transaction 7bjects*

• Web DataWindow *+pecifying the database connection and retrieving data*

• Web Actie! *,sing the DataWindow Transaction 7bject control*

Setting the transaction object for the DataWindow control

There are two ways to handle database connections and transactions for the DataWindow control. You can

use:

• 2nternal transaction management

• # separate transaction object

The two methods provide different levels of control over database transactions.

I$ #ou are displa#ing a PS! $ile in the control You do not need to use a transaction object or ma0e a

database connection if you are displaying a P+3 file in the DataWindow control.

I$ #ou change the (ataWindow ob"ect 2f you change the DataWindow object associated with a

DataWindow control during e/ecution you may need to call the +etTrans or +etTrans7bject method again.

PowerBuilder You always need to call one of the methods to set the transaction object.

Web Actie! You need to call +etTrans7bject again only when you are using a separate transaction object.

These options are described in this section.

6nternal transaction management

What it does

1&


17/58

When the DataWindow control uses internal transaction management it handles connecting disconnecting

commits and rollbac0s. 2t auto&aticall# performs connects and disconnects as neededA any errors that occur

cause an auto&atic rollbac0.

Whenever the DataWindow needs to access the database -such as when a 3etrieve or ,pdate method is

e/ecuted1 the DataWindow issues an internal '7""'T statement does the appropriate data access then

issues an internal D2+'7""'T.

Whether to use it

When not to use it Do not use internal transaction management when:

• Your application re%uires the best possible performance

2nternal transaction management is slow and uses considerable system resources because it must

connect and disconnect for every database access.

• You want control over when a transaction is committed or rolled bac0

Because internal transaction management must disconnect after a database access any changes arealways committed immediately.

When to use it 2f the number of available connections at your site is limited you might want to use internal

transaction management because connections are not held open.

2nternal transaction management is appropriate in simple situations when you are doing pure retrievals -such

as in reporting1 and do not need to hold database loc0s$$when application control over committing or rolling

bac0 transactions is not an issue.

4ow it wor5s

PowerBuilder To use internal transaction management you specify connection values for a transactionobject which could be the automatically instantiated +9&'#. Then you call the +etTrans method which

copies the values from a specified transaction object to the DataWindow control=s internal transaction object.

S7%CA-DB8S / ProfileString20myapp-ini09 :

0database09 0DB8S09 0 03

--- ## Set more connection parameters

dw,employee-SetTrans2S7%CA3

dw,employee-etriee2 3

*onnecting to the database When you use +etTrans you do not need to e/plicitly code a '7""'T or

D2+'7""'T statement in a script. '7""'T and D2+'7""'T statements are automatically issued

when needed.

)or more information about PowerBuilder transaction objects see PowerBuilder Application Techniues .

Web Actie! To use internal transaction management set the transaction properties for the DataWindow

Web #ctive( control instead of using a DataWindow Transaction 7bject control. You can set the properties

via Param elements or in a script. This e/ample sets the DbParm property and calls 3etrieve in a script:

1'


18/58

dw,employee-DbParm /

0Drier/;com-sybase-jdbc-SybDrier;9

4%/;jdbc'sybase'Tds'www-domain-com'


19/58

• You want to control transaction processing

• You re%uire the improved performance provided by 0eeping database connections open

4ow it wor5s

PowerBuilder The +etTrans7bject method associates a transaction object with the DataWindow control.

PowerBuilder has a default transaction object called +9&'# that is automatically instantiated. You can set its

connection properties connect and assign it to the DataWindow control.

The following statement uses +etTrans7bject to associate the DataWindow control dwemp with the default

transaction object -+9&'#1:

## Set connection parameters in the transaction object

S7%CA-DB8S / ---

S7%CA-database / ---

C.((*CT 4S6(> S7%CA5

dw,emp-SetTrans.bject2S7%CA3

dw,emp-etriee2 3

2nstead of or in addition to using the predefined +9&'# transaction object you can define your own

transaction object in a script. This is necessary if your application needs to connect to more than one database

at the same time.

The following statement uses +etTrans7bject to associate dwcustomer with a programmer$created

transaction object -transcustomer1:

transaction trans,customer

trans,customer / C*AT* transaction

## Set connection parameters in the transaction object

trans,customer-DB8S / ---

trans,customer-database / ---

C.((*CT 4S6(> trans,customer5

dw,customer-SetTrans.bject2trans,customer3

dw,customer-etriee2 3

Web Actie! To use a separate transaction object for the Web #ctive( you add an 7B


20/58

)or more information about database transaction processing:

• PowerBuilder +ee the chapter on using transaction objects in Application Techniues

• Web Actie! +ee'hapter @ *,sing the DataWindow Web 'ontrol for #ctive(*

)or more information about +etTrans and +etTrans7bject methods see the (ataWindow !e$erence .

etrieing and updating data

You call the following two methods to access a database through a DataWindow control:

• 3etrieve

• ,pdate

Basic data retrieal

#fter you have set the transaction object for your DataWindow control you can use the 3etrieve method to

retrieve data from the database into that control:

dw,emp-etriee2 3

The Web DataWindow server component has a second form of the method 3etrieve/ for use when the

method re%uires arguments. )or more information about retrieving data with the Web DataWindow

see *+pecifying the database connection and retrieving data* and*Passing page$specific data to the reloaded

page*.

4sing retrieal argumentsAbout retrie$al arguments

3etrieval arguments %ualify the +&'T statement associated with the DataWindow object reducing the

rows retrieved according to some criteria. )or e/ample in the following +&'T statement +alary is a

retrieval argument defined in the DataWindow painter:

S*%*CT (ame9 emp-sal $.8 *mployee

W?** emp-sal @ 'Salary

When you call the 3etrieve method you supply a value for +alary. 2n PowerBuilder the code loo0s li0e this:

dw,emp-etriee2 3

+pecial considerations for each environment are e/plained below.

When coding 3etrieve with arguments specify them in the order in which they are defined in the

DataWindow object. Your 3etrieve method can provide more arguments than a particular DataWindow object

e/pects. #ny e/tra arguments are ignored. This allows you to write a generic 3etrieve that wor0s with several

different DataWindow objects.

2/


21/58

.mitting retrieal arguments 2f your DataWindow object ta0es retrieval arguments but you do not pass

them in the 3etrieve method the DataWindow control prompts the user for them when 3etrieve is called.

.ore than 1& arguments

The 3etrieve method is limited to 6? arguments in some environments.

PowerBuilder You can specify any number of retrieval arguments.

Web DataWindow You can specify a ma/imum of 6? arguments using the 3etrieve/ method.

Web Actie! You can specify a ma/imum of 6? arguments for 3etrieve. 2f you need to specify more use the

3etrieve/ method for the Web #ctive( and pass an array where each array element is a retrieval argument.

4pdating data

#fter users have made changes to data in a DataWindow control you can use the ,pdate method to save

those changes in the database.

2n PowerBuilder the code loo0s li0e this:

dw,emp-Update23

,pdate sends to the database all inserts changes and deletions made in the DataWindow control since the last

,pdate method. When you are using an e/ternal transaction object you can then commit -or roll bac01 those

database updates. 2n PowerBuilder you use +9& statements. 2n the Web #ctive( you use methods and

properties of the transaction object. 2n the Web DataWindow client control update re%uests call the update

method in the server component which handles the commit or rollbac0.

)or more specifics on how a DataWindow control updates the database -that is which +9& statements are

sent in which situations1 see *,pdating the database*.

amples

The following e/ample shows code that connects retrieves updates commits or rolls bac0 and disconnects

from the database.

#lthough the e/ample shows all database operations in a single script or function most applications separate

these operations. 2n a PowerBuilder application for e/ample an application could connect to the database in

the application 7pen event retrieve and update data in one or more window scripts and disconnect from the

database in the application 'lose event.

PowerBuilder The following statements retrieve and update data using the transaction object mp+9& and

the DataWindow control dwemp:

## Connect to the database specified in the

## transaction object *mpS7%

C.((*CT 4S6(> *mpS7%5

21


22/58

## Set *mpS7% as the transaction object for dw,emp

dw,emp-SetTrans.bject2*mpS7%3

## etriee data from the database specified in

## *mpS7% into dw,emp

dw,emp-etriee23

## 8a)e changes to the data------

## 4pdate the database

6$ dw,emp-4pdate23 @ T?*(

C.886T 4S6(> *mpS7%5

*%S*

.%%BAC 4S6(> *mpS7%5

*(D 6$

## Disconnect from the database

D6SC.((*CT 4S6(> *mpS7%5

Web Actie! The following


23/58

PowerBuilder and Web Actie!

2f the data for a DataWindow is not coming from a database -that is the data source was defined as /ternal

in the DataWindow wi5ard1 you can use these methods to import data into the DataWindow control:

• 2mport'lipboard

• 2mport)ile

• 2mport+tring

All enironments

You can also get data into the DataWindow by using the +et2tem method or by using a DataWindow

e/pression.

)or more information on the +et2tem method and DataWindow e/pressions see *4anipulating data in a

DataWindow control*.

.anipulating data in a DataWindow control

To handle user re%uests to add modify and delete data in a DataWindow you can write code to process that

data but first you need to understand how DataWindow controls manage data.

?ow a DataWindow control manages data

#s users add or change data the data is first handled as te/t in an edit control. 2f the data is accepted it is then

stored as an item in a buffer.

About the DataWindow bu6ers

# DataWindow uses three buffers to store data:

Table $6: DataWindow buffers

Buffer Contents

Primary Data that has not been deleted or filtered out -that is the rows that are viewable1.

)ilter Data that was filtered out.

23


24/58

Delete Data that was deleted by the user or through code.

About the edit control

#s the user moves around the DataWindow control the DataWindow places an edit control over the current

cell -row and column1:

About tet

The contents of the edit control are called te/t. Te/t is data that has not yet been accepted by the DataWindow

control. Data entered in the edit control is not in a DataWindow buffer yetA it is simply te/t in the edit control.

About items

When the user changes the contents of the edit control and presses enter or leaves the cell -by tabbing using

the mouse or pressing up arrow or down arrow1 the DataWindow processes the data and either accepts or

rejects it depending on whether it meets the re%uirements specified for the column. 2f the data is accepted the

te/t is moved to the current row and column in the DataWindow Primary buffer. The data in the Primary

buffer for a particular column is referred to as an item.

$ents or changing tet and items

When data is changed in the edit control several events occur. The names of the events are different in each

environment as shown in the table. This chapter refers to events using PowerBuilder names.

Table $: vent names in different environments

2


25/58

Event Description

PowerBuilder9 Web DataWindow

client controlWeb Actie!

dit'hanged -not available on client

control1ondit'hange

7ccurs for each 0eystro0e the user types in

the edit control.

2tem'hanged before2tem'hange7ccurs when a cell has been modified and

loses focus.

2temrror on2temrror 7ccurs when new data fails the validation

rules for the column.

2tem)ocus'hanged on2tem)ocus'hange

7ccurs when the current item in the controlchanges.

4ow tet is processed in the edit control

When the data in a column in a DataWindow has been changed and the column loses focus -for e/ample

because the user tabs to the ne/t column1 the following se%uence of events occurs:

6. The DataWindow control converts the te/t into the correct data type for the column. )or e/ample if

the user is in a numeric column the DataWindow control converts the string that was entered into anumber. 2f the data cannot be converted the 2temrror event is triggered.

. 2f the data converts successfully to the correct type the DataWindow control applies any validation

rule used by the column. 2f the data fails validation the 2temrror event is triggered.

F. 2f the data passes validation then the 2tem'hanged event is triggered. 2f you set an action!return

code of 6 in the 2tem'hanged event the DataWindow control rejects the data and does not allow thefocus to change. 2n this case the 2temrror event is triggered.

>. 2f the 2tem'hanged event accepts the data the 2tem)ocus'hanged event is triggered ne/t and the

data is stored as an item in a buffer.

2%


26/58

$igure &"&' ?ow te+t is processed in edit controls

Action7return codes or e$ents

You can affect the outcome of events by specifying numeric values in the event=s program code. )or e/ample

step F above describes how you can force data to be rejected with a code of 6 in the 2tem'hanged event.

To specify action!return codes:

• PowerBuilder and Web DataWindow ,se a 3T,3" statement

• Web Actie! 'all the +et#ction'ode or set#ction'ode method

)or information about codes for individual events see the (ataWindow !e$erence .

Accessing the te+t in the edit control

)sing methods

The following methods allow you to access the te/t in the edit control:

• 8etTe/t$$7btains the te/t in the edit control

• +etTe/t$$+ets the te/t in the edit control

8n e$ent code

2n addition to these methods the following events provide access to the te/t in the edit control:

• dit'hanged

2&


27/58

• 2tem'hanged

• 2temrror

,se the Data parameter which is passed into the event to access the te/t of the edit control. 2n your code for

these events you can test the te/t value and perform special processing depending on that value.

)or an e/ample see *'oding the 2tem'hanged event*.

8anipulating the te+t in the edit control

When you want to further manipulate the contents of the edit control within your DataWindow control you

can use any of these methods:

'an,ndo

'lear

'opy

'ut

&ine'ount

Paste

Position

3eplaceTe/t

+croll

+elected&ength

+elected&ine

+elected+tart

+electedTe/t

+electTe/t

Te/t&ine

,ndo

)or more information about these methods see the (ataWindow !e$erence .

Coding the 6temChanged eent

2f data passes conversion and validation the 2tem'hanged event is triggered. By default the 2tem'hanged

event accepts the data value and allows focus to change. You can write code for the 2tem'hanged event to do

some additional processing. )or e/ample you could perform some tests set a code to reject the data have the

column regain focus and trigger the 2temrror event.

ample

The following sample code for the 2tem'hanged event for a DataWindow control called dwmployee sets

the return code in dwmployee to reject data that is less than the employee=s age which is specified in a

+ingle&inedit or te/tbo/ control in the window.

This is the PowerBuilder version of the code:

int a9 age

age / 6nteger2sle,age-te+t3

a / 6nteger2data3

## Set the return code to 1 in the 6temChanged

## eent to tell PowerBuilder to reject the data

## and not change the focus-

2'


28/58

6$ a F age T?*( *T4( 1

Coding the 6tem*rror eent

The 2temrror event is triggered if there is a problem with the data. By default it rejects the data value and

displays a message bo/. You can write code for the 2temrror event to do some other processing. )or

e/ample you can set a code to accept the data value or reject the data value but allow focus to change.

)or more information about the events of the DataWindow control see the (ataWindow !e$erence .

Accessing the items in a DataWindow

You can access data values in a DataWindow by using methods or DataWindow data e/pressions. Both

methods allow you to access data in any buffer and to get original or current values.

The method you use depends on how much data you are accessing and whether you 0now the names of the

DataWindow columns when the script is compiled.

)or guidelines on deciding which method to use see the (ataWindow !e$erence .

)sing methods

There are several methods for manipulating data in a DataWindow control.

These methods obtain the data in a specified row and column in a specified buffer -Web DataWindow

methods have separate methods for overloaded versions1:

• PowerBuilder 8et2temDate 8et2temDateTime 8et2temDecimal 8et2tem"umber 8et2tem+tring

8et2temTime

• Web Actie! 8et2temDate 8et2tem"umber 8et2tem+tring

• Web DataWindow serer component 8et2temDate 8et2temDateBy'ol"um

8et2temDateBy'ol"um/ 8et2temDate/ 8et2temDateTime 8et2temDateTimeBy'ol"um

8et2temDateTimeBy'ol"um/ 8et2temDateTime/ 8et2tem"umber

8et2tem"umberBy'ol"um 8et2tem"umberBy'ol"um/ 8et2tem"umber/ 8et2tem+tatus

8et2tem+tatusBy'ol"um 8et2tem+tring 8et2tem+tringBy'ol"um 8et2tem+tringBy'ol"um/8et2tem+tring/ 8et2temTime 8et2temTimeBy'ol"um 8et2temTimeBy'ol"um/

8et2temTime/

This method sets the value of a specified row and column:

• PowerBuilder and Web Actie! +et2tem

• Web DataWindow serer component +et2temDate +et2temDateBy'ol"um +et2temDateTime

+et2temDateTimeBy'ol"um +et2tem"umber +et2tem"umberBy'ol"um +et2tem+tatus

+et2tem+tatusBy'ol"um +et2tem+tring +et2tem+tringBy'ol"um +et2temTime+et2temTimeBy'ol"um

2(


29/58

)or e/ample the following statement using PowerBuilder synta/ assigns the value from the empname

column of the first row to the variable ls"ame:

ls,(ame / dw,1-GetItemString

219 0empname03

This PowerBuilder statement sets the value of the empname column in the first row to the string Waters:

dw,1- SetItem

219 0empname09 0Waters03

4ses You call the 8et2tem methods to obtain the data that has been accepted into a specific row and column.

You can also use them to chec0 the data in a specific buffer before you update the database. You must use the

method appropriate for the column=s data type.

)or more information about the methods listed above see the (ataWindow !e$erence .

)sing epressions

DataWindow data e/pressions refer to single items columns bloc0s of data selected data or the whole

DataWindow.

The way you construct data e/pressions depends on the environment:

• PowerBuilder ,se dot notation

• Web Actie! Data e/pressions are not supported

*+pressions in PowerBuilder The 7bject property of the DataWindow control lets you specify e/pressionsthat refer directly to the data of the DataWindow object in the control. This direct data manipulation allows

you to access small and large amounts of data in a single statement without calling methods:

dw,1-.bject-jobtitleG=H / 0Programmer0

The ne/t statement sets the value of the first column in the first row in the DataWindow to +mith:

dw,1-.bject-DataG191H / 0Smith0

)or complete instructions on how to construct DataWindow data e/pressions see the (ataWindow !e$erence .

4sing other DataWindow methods

There are many more methods you can use to perform activities in DataWindow controls. ;ere are some of

the more common ones:

2-


30/58

Table $F: 'ommon methods in DataWindow controls

8ethod Purpose

#cceptTe/t#pplies the contents of the edit control to the current item in the DataWindow

control.

Delete3ow3emoves the specified row from the DataWindow control placing it in the Delete

bufferA does not delete the row from the database.

)ilter Displays rows in the DataWindow control based on the current filter.

8et3ow 3eturns the current row number.

2nsert3ow 2nserts a new row.

3eset 'lears all rows in the DataWindow control.

3etrieve 3etrieves rows from the database.

3ows'opy

3ows4ove'opies or moves rows from one DataWindow control to another.

+crollTo3ow +crolls to the specified row.

+elect3ow ;ighlights a specified row.

+hareData +hares data among different DataWindow controls.

,pdate+ends to the database all inserts changes and deletions that have been made in the

DataWindow control.

+ome but not all of these methods are available for the Web DataWindow client control server component

or both. ach development environment provides a reference list of methods. )or a complete list of

DataWindow methods see the PowerBuilder Browser for Power+cript targets or the 'omponents tab of the

+ystem Tree for Web targets.)or complete information on DataWindow methods see the (ataWindow

!e$erence.

3/


31/58

Accessing the properties of a DataWindow object

About DataWindow object properties

DataWindow object properties store the information that controls the behavior of a DataWindow object. They

are not properties of the DataWindow control but of the DataWindow object displayed in the control. TheDataWindow object is itself made up of individual controls$$column te/t graph and drawing controls$$that

have DataWindow object properties.

You establish initial values for DataWindow object properties in the DataWindow painter. You can also get

and set property values during e/ecution in your code.

You can access the properties of a DataWindow object by using the Describe and 4odify methods or

DataWindow property e/pressions. Which you use depends on the type of error chec0ing you want to provide

and on whether you 0now the names of the controls within the DataWindow object and properties you want toaccess when the script is compiled.

"ote that in the Web #ctive( only the Describe and 4odify methods -not property e/pressions1 are

supported.

)or guidelines on deciding which method to use and for lists and descriptions of DataWindow object properties see the (ataWindow !e$erence .

4sing methods to access object properties

You can use the following methods to wor0 with the properties of a DataWindow object:

• Describe$$3eports the values of properties of a DataWindow object and controls within the

DataWindow object

• 4odify$$4odifies a DataWindow object by specifying a list of instructions that change the

DataWindow object=s definition

PowerBuilder )or e/ample the following statements assign the value of the Border property for the

empname column to a string variable:

string ls,border

ls,border / dw,1- Describe

20empname-Border03

The following statement changes the value of the Border property for the empname column to 6:

dw,emp .Modi!

20empname-Border/103

Web Actie! The


32/58

string ls,border

ls,border / dw,1- Describe

20empname-Border035

The following statement changes the value of the Border property for the empname column to 6:

dw,emp .Modi!

20empname-Border/1035

About d#na&ic (ataWindow ob"ects ,sing Describe and 4odify you can provide an interface through

which application users can alter the DataWindow object during e/ecution. )or e/ample you can change the

appearance of a DataWindow object or allow an application user to create ad hoc reports.

)or more information see 'hapter F *Dynamically 'hanging DataWindow 7bjects *.

4sing e+pressions

DataWindow property e/pressions provide access to properties with fewer nested strings. 2n PowerBuilder

you can handle problems with incorrect object and property names in the rror event:

PowerBuilder ,se the 7bject property and dot notation. )or e/ample:

integer li,border

li,border / 6nteger2dw,1-.bject-empname-Border3

dw,1-.bject-empname-Border / 1

)or reference material on the available variations for property e/pressions see the (ataWindow !e$erence.

4andling DataWindow errors

There are several types of errors that can occur during DataWindow processing:

• Data items that are invalid -discussed in *4anipulating data in a DataWindow control*1

• )ailures when retrieving or updating data

• #ttempts to access invalid or none/istent properties or data

This section e/plains how to handle the last two types of errors.

etriee and 4pdate errors and the DB*rror eent

0etrie$e and update testing

When using the 3etrieve or ,pdate method in a DataWindow control you should test the method=s return

code to see whether the activity succeeded.

(o not test the S+,*ode attribute #fter issuing a +9& statement -such as '7""'T '7442T or

D2+'7""'T1 or the e%uivalent method of the transaction object you should always test the success!failure

32


33/58

code -the +9&'ode attribute in the transaction object1. ;owever you should not use this type of error

chec0ing following a retrieval or update made in a DataWindow.

)or more information about error handling after a +9& statement see:

• PowerBuilder The chapter on using transaction objects in Application Techniues

• Web Actie! 'hapter @ *,sing the DataWindow Web 'ontrol for #ctive(*

Table $>: 3eturn codes for the 3etrieve and ,pdate methods

8ethod eturn code 8eaning

3etrieve EG6 3etrieval succeededA returns the number of rows retrieved.

$6 3etrieval failedA DBrror event triggered.

H "o data retrieved.

,pdate 6 ,pdate succeeded.

$6 ,pdate failedA DBrror event triggered.

ample

PowerBuilder 2f you want to commit changes to the database only if an update succeeds you can code:

6$ dw,emp-4pdate23 @ T?*(

C.886T 4S6(> *mpS7%5

*%S*

.%%BAC 4S6(> *mpS7%5

*(D 6$

Web Actie! To commit changes to the database only if an update succeeds you can code:

number rtn5

rtn / dw,emp-4pdate2 35if 2rtn // 13

trans,a-Commit2 35

E else

trans,a-ollbac)2 35

E

)sing the D+rror e$ent

33


34/58

The DataWindow control triggers its DBrror event whenever there is an error following a retrieval or

updateA that is if the 3etrieve or ,pdate methods return $6. )or e/ample if you try to insert a row that does

not have values for all columns that have been defined as not allowing ",&& the DB4+ rejects the row and

the DBrror event is triggered.

By default the DataWindow control displays a message bo/ describing the error message from the DB4+:

2n many cases you may want to code your own processing in the DBrror event and suppress the default

message bo/. ;ere are some tips for doing this:

Table $: Tips for processing messages from DBrror event

To Do this

8et the DB4+=s error code ,se the +9&DB'ode argument of the DBrror event.

8et the DB4+=s message te/t ,se the +9&rrTe/t argument of the DBrror event.

+uppress the default message bo/ +pecify an action!return code of 6.

About (ataWindow action-return codes +ome events for DataWindow controls have codes that you can

set to override the default action that occurs when the event is triggered. The codes and their meaning depend

on the event. 2n PowerBuilder you set the code with a 3T,3" statement. 2n the Web #ctive( you call the

+et#ction'ode or set#ction'ode method.

ample

PowerBuilder ;ere is a sample script for the DBrror event:

## Database error "1I means that some of the

## reJuired alues are missing

3


35/58

6$ sJldbcode / "1I T?*(

8essageBo+208issing 6nformation09 :

0Kou hae not supplied alues for all 0 :

L0the reJuired fields-03

*(D 6$

## eturn code suppresses default message bo+*T4( 1

During e/ecution the user would see the following message bo/ after the error:

Web Actie! 2n


36/58

2f the empname column did not e/ist in the DataWindow or if you had misspelled the property name the

compiler would not detect the error. ;owever at e/ecution time PowerBuilder would trigger the

DataWindow control=s rror event.

)sing a 9ry:Catch bloc5

The rror event is triggered even if you have surrounded an error producing data or property e/pression in a

Try$'atch bloc0. The catch statement is e/ecuted after the rror event is triggered but only if you do not code

the rror event or do not change the default rror event action from /ception)ailJ. The following e/ample

shows a property e/pression in a Try$'atch bloc0:

TK

dw,1-.bject-emp,name-Nisible / 00

CATC? 2dwruntimeerror dw,e3

8essageBo+ 20DWuntime*rror09 dw,e-te+t3

*(D TK

Determining the cause o the error

The rror event has several arguments that provide information about the error condition. You can chec0 the

values of the arguments to determine the cause of the error. )or e/ample you can obtain the internal error

number and error te/t the name of the object whose script caused the error and the full te/t of the script

where the error occurred. The information provided by the rror event=s arguments can be helpful in

debugging e/pressions that are not chec0ed by the compiler.

2f you catch a DW3untimerror error you can use the properties of that class instead of the rror event

arguments to provide information about the error condition. The following table displays the correspondences

between the rror event arguments and the DW3untimerror properties.

Table $?: 'orrespondence between rror event arguments and DW3untimerror properties

*rror eent argument DWuntime*rror property

errornumber number

errorline line

errorte/t te/t

errorwindowmenu objectname

errorobject class

errorscript routinename

Controlling the outcome o the e$ent

3&


37/58

When the rror event is triggered you can have the application ignore the error and continue processing

substitute a different return value or escalate the error by triggering the +ystemrror event. 2n the rror event

you can set two arguments passed by reference to control the outcome of the event.

Table $K: +etting arguments in the rror event

Argument Description

#ction

# value you specify to control the application=s course of action as a result of the error.

Ialues are:

• /ception2gnoreJ

• /ception+ubstitute3eturnIalueJ

• /ception)ailJ -default action1

3eturnIalu

e

# value whose data type matches the e/pected value that the DataWindow would have

returned. This value is used when the value of action is /ception+ubstitute3eturnIalueJ.

)or a complete description of the arguments of the rror event see the (ataWindow !e$erence .

When to substitute a return alue The /ception+ubstitute3eturnIalueJ action allows you to substitute a

return value when the last element of an e/pression causes an error. Do not use

/ception+ubstitute3eturnIalueJ to substitute a return value when an element in the middle of an e/pression

causes an error.

The /ception+ubstitute3eturnIalueJ action is most useful for handling errors in data e/pressions.

)pdating the database

#fter users have made changes to data in a DataWindow control you can use the ,pdate method to save the

changes in the database. ,pdate sends to the database all inserts changes and deletions made in the

DataWindow since the last ,pdate or 3etrieve method was e/ecuted.

?ow the DataWindow control updates the database

When updating the database the DataWindow control determines the type of +9& statements to generate by

loo0ing at the status of each of the rows in the DataWindow buffers.

There are four DataWindow item statuses two of which apply only to rows:

Table $@: DataWindow item status for rows and columns

3'


38/58

Status "pplies to

PowerBuilder name Web DataWindow name (umeric alue

"ewJ "ew 3ows

"ew4odifiedJ "ew4odified F 3ows

"ot4odifiedJ "ot4odified H 3ows and columns

Data4odifiedJ Data4odified 6 3ows and columns

.a&ed or nu&eric constants The constants shown in the table are used differently in each environment:

PowerBuilder The named values are values of the enumerated data type dw2tem+tatus. You must use the

named values which end in an e/clamation point.

Web DataWindow You can use a string value with or without the e/clamation point

Web Actie! "amed values are not definedA use the numeric values.

This discussion uses the PowerBuilder names.

4ow statuses are set

When data is retrieed When data is retrieved into a DataWindow all rows and columns initially have a

status of "ot4odifiedJ.

#fter data has changed in a column in a particular row either because the user changed the data or the data

was changed programmatically such as through the +et2tem method the column status for that column

changes to Data4odifiedJ. 7nce the status for any column in a retrieved row changes to Data4odifiedJ the

row status also changes to Data4odifiedJ.

When rows are inserted When a row is inserted into a DataWindow it initially has a row status of "ewJ and

all columns in that row initially have a column status of "ot4odifiedJ. #fter data has changed in a column in

the row either because the user changed the data or the data was changed programmatically such as through

the +et2tem method the column status changes to Data4odifiedJ. 7nce the status for any column in the

inserted row changes to Data4odifiedJ the row status changes to "ew4odifiedJ.

When a DataWindow column has a default value the column=s status does not change to Data4odifiedJ until

the user ma0es at least one actual change to a column in that row.

When )pdate is called

3(


39/58

$or rows in the Primary and $ilter buffers When the ,pdate method is called the DataWindow control

generates +9& 2"+3T and ,PD#T statements for rows in the Primary and!or )ilter buffers based upon the

following row statuses:

Table $L: 3ow status after 2"+3T and ,PD#T statements

ow status S7% statement generated

"ew4odifiedJ 2"+3T

Data4odifiedJ ,PD#T

# column is included in an ,PD#T statement only if the following two conditions are met:

• The column is on the updatable column list maintained by the DataWindow object)or more information about setting the update characteristics of the DataWindow object see

the PowerBuilder User's Guide.

• The column has a column status of Data4odifiedJ

The DataWindow control includes all columns in 2"+3T statements it generates. 2f a column has no value

the DataWindow attempts to insert a ",&&. This causes a database error if the database does not allow

",&&s in that column.

$or rows in the Delete buffer The DataWindow control generates +9& D&T statements for any rows

that were moved into the Delete buffer using the Delete3ow method. -But if a row has a row status of "ewJ

or "ew4odifiedJ before Delete3ow is called no D&T statement is issued for that row.1

Changing row or column status programmatically

You may need to change the status of a row or column programmatically. Typically you do this to prevent the

default behavior from ta0ing place. )or e/ample you might copy a row from one DataWindow to anotherA

and after the user modifies the row you might want to issue an ,PD#T statement instead of an 2"+3T

statement.

You use the +et2tem+tatus method to programmatically change a DataWindow=s row or column status

information. ,se the 8et2tem+tatus method to determine the status of a specific row or column.

Changing column status

You use +et2tem+tatus to change the column status from Data4odifiedJ to "ot4odifiedJ or vice versa.

*hange colu&n status when #ou change row status 'hanging the row status changes the status of all

columns in that row to "ot4odifiedJ so if the ,pdate method is called no +9& update is produced. You must

change the status of columns to be updated after you change the row status.

3-


40/58

Changing row status

'hanging row status is a little more complicated. The following table illustrates the effect of changing from

one row status to another:

Table $6H: ffects of changing from one row status to another

Original status

Speciied status

(ewO (ew8odifiedO Data8odifiedO (ot8odifiedO

"ewJ $ Yes Yes "o

"ew4odifiedJ "o $ Yes "ewJ

Data4odifiedJ "ew4odifiedJ Yes $ Yes

"ot4odifiedJ Yes Yes Yes $

2n the preceding table /es means the change is valid. )or e/ample issuing +et2tem+tatus on a row that has

the status "ot4odifiedJ to change the status to "ewJ does change the status to "ewJ. .o means that the

change is not valid and the status is not changed.

2ssuing +et2tem+tatus to change a row status from "ew4odifiedJ to "ot4odifiedJ actually changes the status

to "ewJ. 2ssuing +et2tem+tatus to change a row status from Data4odifiedJ to "ewJ actually changes thestatus to "ew4odifiedJ.

'hanging a row=s status to "ot4odifiedJ or "ewJ causes all columns in that row to be assigned a column

status of "ot4odifiedJ. 'hange the column=s status to Data4odifiedJ to ensure that an update results in a

+9& ,pdate.

*hanging status indirectl# When you cannot change to the desired status directly you can usually do it

indirectly. )or e/ample change "ewJ to Data4odifiedJ to "ot4odifiedJ.

Creating reports

You can use DataWindow objects to create standard business reports such as financial statements sales order

reports employee lists or inventory reports.

To create a production report you:

• Determine the type of report you want to produce

/


41/58

• Build a DataWindow object to display data for the report

• Place the DataWindow object in a DataWindow control on a window or form

• Write code to perform the processing re%uired to populate the DataWindow control and print the

contents as a report

*alling In$o%aker $ro& within an application 2f your users have installed 2nfo4a0er -the +ybase

reporting product1 you can invo0e 2nfo4a0er from within an application. This way you can let your users

create and save their own reports. To do this in PowerBuilder use the 3un function.

)or information about invo0ing 2nfo4a0er see the In$o%aker User's Guide .

Planning and building the DataWindow object

To design the report you create a DataWindow object. You select the data source and presentation style and

then:

• +ort the data

• 'reate groups in the DataWindow object to organi5e the data in the report and force page brea0s

when the group values change

• nhance the DataWindow object to loo0 li0e a report -for e/ample you might want to add a title

column headers and a computed field to number the pages1

Using $onts Printer fonts are usually shorter and fatter than screen fonts so te/t may not print in the report

e/actly as it displays in the DataWindow painter. You can pad the te/t fields to compensate for this

discrepancy.

You should test the report format with a small amount of data before you print a large report.

Printing the report

#fter you build the DataWindow object and fill in print specifications you can place it in a DataWindow

control on a window or form as described in *Putting a DataWindow object into a control*.

To allow users to print the report your application needs code that performs the printing logic. )or e/ample

you can place a button on the window or form then write code that is run when the user clic0s the button.

To print the contents of a single DataWindow control or Data+tore call the Print method. )or e/ample thisPowerBuilder statement prints the report in the DataWindow control dw+ales:

dw,Sales- $rint

2T4*3

)or information about the Print method see the (ataWindow !e$erence) )or information about using nested

reports to print multiple DataWindows see *,sing nested reports*.

1


42/58

#eparate DataWindow controls in a single print job

$or PowerBuilder applications only 2f the window has multiple DataWindow controls you can use multiple

PrintDataWindow method calls in a script to print the contents of all the DataWindow controls in one print

job.

These statements print the contents of three DataWindow controls in a single print job:

int job

job / Print.pen20*mployee eports03

## *ach DataWindow starts printing on a new page-

PrintDataWindow2job9 dw,*mp?eader3

PrintDataWindow2job9 dw,*mpDetail3

PrintDataWindow2job9 dw,*mpDptSum3

PrintClose2job3

)or information about PowerBuilder system functions for printing see the PowerScript !e$erence)

4sing nested reports

When designing a DataWindow object for a report you can choose to nest other reports -which are also

DataWindow objects1 within it. The basic steps for using nested reports in an application are the same ones

you follow for the other report types. There are however some additional topics concerning nested reports

that you should 0now about.

Aailabilit# 'omposite and nested reports are not available in the Web DataWindow.

To learn about designing nested reports see the PowerBuilder User's Guide .

Printing multiple updatable DataWindows on a page

#n advantage of composite reports is that you can print multiple reports on a page. # limitation of composite

reports is that they are not updatable so you cannot directl# print several updatable DataWindows on one

page. ;owever there is an indirect way to do that as follows.

You can use the 8et'hild method on named nested reports in a composite report to get a reference to a nestedreport. #fter getting the reference to the nested report you can address the nested report during e/ecution li0e

other DataWindows.

,sing this techni%ue you can call the +hareData method to share data between multiple updatable

DataWindow controls and the nested reports in your composite report. This allows you to print multiple

updatable DataWindows on a page through the composite report.

To print multiple DataWindows on a page using a composite DataWindow:

6. Build a window or form that contains DataWindow controls with the updatable DataWindow objects.

. Define a composite report that has reports corresponding to each of the DataWindows in the windowor form that you want to print. Be sure to name each of the nested reports in the composite report.

2


43/58

.a&ing the nested report To use 8et'hild on a nested report the nested report must have a

name. To name a nested report in the DataWindow painter double$clic0 it in the wor0space and enter

a name in the "ame bo/ on the 8eneral property page.

F. #dd the composite report to the window or form -it can be hidden1.

>. 2n your application do the following:

6. 3etrieve data into the updatable DataWindow controls.

. ,se 8et'hild to get a reference to the nested reports in the composite report.

F. ,se +hareData to share data between the updatable DataWindow objects and the nestedreports.

>. When appropriate print the composite report.

The report contains the information from the updatable DataWindow objects.

!e0retrieing data ach time you retrieve data into the composite report all references -handles1 to nested

reports become invalid and data sharing with the nested reports is terminated. Therefore be sure to call

8et'hild and +hareData each time after retrieving data.

Creating and destroying nested reports during e+ecution

You can create and destroy nested reports in a DataWindow object dynamically during e/ecution using thesame techni%ue you use to create and destroy other controls in a DataWindow object.

Creating nested reports To create a nested report use the '3#T 0eyword with the 4odify method.

+upply the appropriate values for the nested report=s properties.

1iewing s#nta2 $or creating a nested report The easiest way to see the synta/ for creating a nested report

dynamically is to e/port the synta/ of an e/isting DataWindow object that contains a nested report. Thee/port file contains the synta/ you need.

)or more information about e/porting synta/ in the &ibrary painter see the PowerBuilder User's Guide .

When creating a nested report you need to re$retrieve data to see the report. 2n a composite report you caneither retrieve data for the whole report or use 8et'hild to get a reference to the new nested report and

retrieve its data directly. )or nested reports in other reports you need to retrieve data for the base report.

Destroying nested reports To destroy a nested report use the D+T37Y 0eyword with the 4odify method.

The nested report disappears immediately.

)or more about creating and destroying controls in a DataWindow object or report see'hapter F*Dynamically 'hanging DataWindow 7bjects *.

)or a list of properties of nested reports see the (ataWindow !e$erence.

)sing crosstabs

3


44/58

To perform certain 0inds of data analysis you may want to design DataWindow objects in the 'rosstab

presentation style. The basic steps for using crosstabs in an application are the same ones you follow for the

other DataWindow types but there are some additional topics concerning crosstabs that you should 0now

about.

To learn about designing crosstabs see the PowerBuilder User's Guide .

Niewing the underlying data

2f you want users to be able to see the raw data as well as the cross$tabulated data you can do one of two

things:

• Place two DataWindow controls on the window or form: one that is associated with the crosstab and

one that is associated with a DataWindow object that displays the retrieved rows.

• 'reate a composite DataWindow object that contains two reports: one that shows the raw data and

one that shows the crosstab.

(o not share data between the two (ataWindow ob"ects or reports They have the same +9& +&'T

data definition but they have different result sets.

)or more about composite DataWindows see the PowerBuilder User's Guide .

%etting users redefine the crosstab

Aailabilit# This techni%ue is available in PowerBuilder and the Web #ctive(.

With the 'rosstabDialog method you can allow users to redefine which columns in the retrieved data are

associated with the crosstab=s columns rows and values during e/ecution.

The 'rossTabDialog method displays the 'rosstab Definition dialog bo/ for the user to define the data for the

crosstab=s columns rows and values -using the same techni%ues you use in the DataWindow painter1. When

the user clic0s 7C in the dialog bo/ the DataWindow control rebuilds the crosstab with the new

specifications.

Displaying inormational messages

You can display informational messages when a crosstab is rebuilt during e/ecution as a result of the call to

'rosstabDialog. -The messages are the same ones you see when building a crosstab in the DataWindow

painter such as 3etrieving data and Building crosstab.1 You may want to do this if you are wor0ing with a

very large number of rows and rebuilding the crosstab could ta0e a long time.

PowerBuilder 2n PowerBuilder you use a user event to display the crosstab=s informational messages.

To display informational messages when a crosstab is rebuilt:

6. Define a user event for the DataWindow control containing the crosstab. #ssociate it with the event

2D pbmdwnmessagete/t.


45/58

. 2n the script for the user event get the value of the te/t argument -which holds the message that

PowerBuilder would display when building the crosstab in the DataWindow painter1 and display it to

the user.

Web Actie! 2n a Web page you use the DataWindow=s on4essageTe/t event to handle informational

messages.

To display informational messages when a crosstab is rebuilt:

6. dit the code for the on4essageTe/t event of your DataWindow control.

. 2n that event get the value of the Te/t argument and display it to the user.

amples

PowerBuilder 2n the e/ample code for the DataWindow control=s user event for pbmdwnmessagete/t

displays informational messages in a static te/t control in the window containing the crosstab:

st,message-Te+t / te+t

With that script in place after 'rosstabDialog has been called and the user has redefined the crosstab as the

crosstab is being rebuilt your application dynamically displays the informational messages in the static te/t

control stmessage. -You might want to reset stmessage.Te/t to be the empty string in the line following the

'rosstabDialog call.1

2n this e/ample code in the user event for pbmdwnmessagete/t displays informational messages as

4icro;elp in an 4D2 application -wcrosstab is an 4D2 frame window1:

w,crosstab-Set8icro?elp2te+t3

The informational messages are displayed in the 4D2 application=s 4icro;elp as the crosstab is rebuilt.

!or more inormation

)or more about user events in PowerBuilder see the PowerBuilder User's Guide .

)or more about the 'rosstabDialog method and 4essageTe/t event see the (ataWindow !e$erence .

8odifying the crosstab;s properties during e+ecution

#s with other DataWindow objects you can modify the properties of a crosstab during e/ecution using the4odify method. +ome changes re%uire the DataWindow control to dynamically rebuild the crosstabA others

do not. -2f the original crosstab was static it becomes a dynamic crosstab when it is rebuilt.1

Aailabilit# You can use this techni%ue in all DataWindow environments.

Changes that do not orce a rebuild

%


46/58

You can change the following properties without forcing the DataWindow control to rebuild the crosstab:

Table $66: Properties you can change on a crosstab DataWindow without forcing a rebuild

Properties .bjects

#lignment 'olumn 'ompute Te/t

Bac0ground'olumn 'ompute &ine 7val 3ectangle

3ound3ectangle Te/t

Border 'olumn 'ompute Te/t

Brush &ine 7val 3ectangle 3ound3ectangle

'olor 'olumn 'ompute Te/t

dit styles -dddw ddlb chec0bo/ edit editmas0

radiobutton1'olumn

)ont 'olumn 'ompute Te/t

)ormat 'olumn 'ompute

Pen &ine 7val 3ectangle 3ound3ectangle

Pointer 'olumn 'ompute &ine 7val 3ectangle

3ound3ectangle Te/t

Changes that orce a rebuild

2f you change any other properties the DataWindow control rebuilds the structure of the crosstab when

4odify is called. You should combine all needed e/pressions into one 4odify call so that the DataWindow

control has to rebuild the crosstab only once.

Deault $alues or properties

)or computations derived from e/isting columns the DataWindow control by default uses the properties from

the e/isting columns. )or completely new columns properties -such as font color and so on1 default to the

first column of the pree/isting crosstab. Properties for te/t in headers default to the properties of the first te/t

control in the pree/isting crosstab=s first header line.

&


47/58

)or more about the 4odify method see 'hapter F *Dynamically 'hanging DataWindow 7bjects *. )or

details on the DataWindow object properties see the (ataWindow !e$erence.

;enerating 49.<

You can use the data in a DataWindow object to create ;yperTe/t 4ar0up &anguage -;T4&1 synta/. 7ncethe ;T4& has been created you can display it in a Web browser.

Web (ataWindow This section does not describe the Web DataWindow. The Web DataWindow uses

DataWindow object properties that are described in 'hapter ? *,sing the Web DataWindow* and

the (ataWindow !e$erence . 2n particular see the Data.;T4& and ;T4&8en properties.

9echni"ues you can use

You can use any of several techni%ues to generate ;T4& from a DataWindow object.

6n a painter 2n both the DataWindow painter and the 7utput view in the Database painter you can saveretrieved data in ;T4& format. To do this in the DataWindow painter select )ileE+ave 3ows #s from the

menu. 2n the Database painter open the 7utput view then select 3owsE+ave 3ows #s from the menu. 2n both

painters specify ;T4& Table as the format for the file.

6n your application code You can obtain an ;T4& string of the DataWindow presentation and data from the

Data.;T4&Table property. You can save the string in a variable and modify the ;T4& with string

manipulation operations. 2n PowerBuilder you can also use the )ile7pen and )ileWrite functions to save the

;T4& to a file.

The ;T4&Table property has its own properties which you can set to control the ;T4& attributes and style

sheet associated with the Table ;T4& element.

PowerBuilder only 2n PowerBuilder there are two more techni%ues available to you. You can:

• 'all the +ave#s method to save the contents of a DataWindow directly to a file on dis0. To save the

data in ;T4& format you need to specify ;T4&Table as the file type when you call +ave#s.

• 'all the 8enerate;T4&)orm method to create an ;T4& form from data contained in a

DataWindow control or Data+tore whose DataWindow object uses the )reeform or Tabular

presentation style.

Choosing presentation styles

+ome DataWindow presentation styles translate better into ;T4& than others. The following presentation

styles produce good results:

• Tabular

• 8roup

• )reeform

'


48/58

• 'rosstab

• 8rid

The 'omposite 8raph 3ichTe/t and 7& .H presentation styles produce ;T4& output that is based on the

result only and not on the presentation style. DataWindows that have overlapping controls may not produce

the e/pected results. "ested reports are ignoredA they are not included in the generated ;T4&.

ample

This e/ample illustrates how you might use DataWindow$generated ;T4& in an application.

The 0ey line of code gets the ;T4& from the DataWindow by referring to its ;T4&Table property.

Iariations for each environment are shown below. 2n PowerBuilder you can use the Describe method or a

property e/pression. The Web #ctive( has to use Describe.

PowerBuilder

ls,htmlstring / dw,1-.bject-DataWindow-Data-?T8%Table

Web Actie!

str,html / dw,1-Describe20DataWindow-Data-?T8%Table035

The complete e/ample that follows is implemented in PowerBuilder.

The window below displays customer data in a tabular DataWindow object. By pressing the Browse button

the user can translate the contents of the DataWindow object into ;T4& format and invo0e a Web browser to

view the ;T4& output. By pressing the +elect Browser button the user can tell the application which Web

browser to use:

(


49/58

Script for the Select Browser button The script for the +elect Browser button displays a dialog bo/ where

the user can select an e/ecutable file for a Web browser. The path to the e/ecutable is stored in isBrowser

which is an instance variable defined on the window:

String ls,Browser(ame

6nteger li,esult

## .pen the dialog to select a browser-

li,esult / >et$ile.pen(ame20Select Browser09 :

is,Browser9 ls,Browser(ame9 :

0e+e09 0*+ecutable $iles 2-*!*39-*!*03

6$ li,esult / "1 T?*(

8essageBo+20(o Browser09 0(o Browser selected03

*(D 6$

Script for the Browse button The script for the Browse button creates an ;T4& string from the data in the

DataWindow by assigning the Data.;T4&Table property to a string variable. #fter constructing the ;T4&

string the script adds a header to the ;T4& string. Then the script saves the ;T4& to a file and runs the Web

browser to display the output:

String ls,?T8%9 ls,$ile(ame9 ls,BrowserPath

6nteger li,$ile(umber9 li,Bytes9

6nteger li,unesult9 li,esult

## >enerate the ?T8%-

ls,?T8% / dw,1-.bject-DataWindow-Data-?T8%Table

6$ 6s(ull2ls,?T8%3 .r %en2ls,?T8%3 F/ 1 T?*(

8essageBo+ 20*rror09 0*rror generating ?T8%O03

eturn

*%S* ls,?T8% /0F?1@?T8% >enerated $rom a DataWindow0:

L 0F#?1@FP@0 L ls,?T8%

*(D 6$

##Create the file-

ls,$ile(ame / 0custlist-htm0

li,$ile(umber / $ile.pen2ls,$ile(ame9 Stream8odeO9 :

WriteO9 %oc)eadWriteO9 eplaceO 3

6$ 2li,$ile(umber @/ 3 T?*(

li,Bytes / $ileWrite2li,$ile(umber9 ls,?T8%3

$ileClose2li,$ile(umber

Guia Programador Datawindow Cap 1 - 3

Documents