Working with PowerBuilder Web Forms

PowerBuilder®
11.0 CTP
DOCUMENT ID: DC11CTP-01-1100-01

LAST REVISED: March 2006

Copyright © 1991-2006 by Sybase, Inc. All rights reserved.

This publication pertains to Sybase software and to any subsequent release until otherwise indicated in new editions or technical notes.
Information in this document is subject to change without notice. The software described herein is furnished under a license agreement,
and it may be used or copied only in accordance with the terms of that agreement.

To order additional documents, U.S. and Canadian customers should call Customer Fulfillment at (800) 685-8225, fax (617) 229-9845.

Customers in other countries with a U.S. license agreement may contact Customer Fulfillment via the above fax number. All other
international customers should contact their Sybase subsidiary or local distributor. Upgrades are provided only at regularly scheduled
software release dates. No part of this publication may be reproduced, transmitted, or translated in any form or by any means, electronic,
mechanical, manual, optical, or otherwise, without the prior written permission of Sybase, Inc.

Sybase, the Sybase logo, ADA Workbench, Adaptable Windowing Environment, Adaptive Component Architecture, Adaptive Server,
Adaptive Server Anywhere, Adaptive Server Enterprise, Adaptive Server Enterprise Monitor, Adaptive Server Enterprise Replication,
Adaptive Server Everywhere, Adaptive Warehouse, Afaria, Answers Anywhere, Anywhere Studio, Application Manager, AppModeler,
APT Workbench, APT-Build, APT-Edit, APT-Execute, APT-Translator, APT-Library, AvantGo Mobile Delivery, AvantGo Mobile
Inspection, AvantGo Mobile Marketing Channel, AvantGo Mobile Pharma, AvantGo Mobile Sales, AvantGo Pylon, AvantGo Pylon
Application Server, AvantGo Pylon Conduit, AvantGo Pylon PIM Server, AvantGo Pylon Pro, Backup Server, BizTracker,
ClearConnect, Client-Library, Client Services, Convoy/DM, Copernicus, Data Pipeline, Data Workbench, DataArchitect, Database
Analyzer, DataExpress, DataServer, DataWindow, DataWindow .NET, DB-Library, dbQueue, Developers Workbench, DirectConnect,
DirectConnect Anywhere, Distribution Director, e-ADK, E-Anywhere, e-Biz Impact, e-Biz Integrator, E-Whatever, EC Gateway,
ECMAP, ECRTP, eFulfillment Accelerator, Embedded SQL, EMS, Enterprise Application Studio, Enterprise Client/Server, Enterprise
Connect, Enterprise Data Studio, Enterprise Manager, Enterprise SQL Server Manager, Enterprise Work Architecture, Enterprise Work
Designer, Enterprise Work Modeler, eProcurement Accelerator, EWA, Financial Fusion, Financial Fusion Server, Gateway Manager,
GlobalFIX, iAnywhere, iAnywhere Solutions, ImpactNow, Industry Warehouse Studio, InfoMaker, Information Anywhere, Information
Everywhere, InformationConnect, InternetBuilder, iScript, Jaguar CTS, jConnect for JDBC, M2M Anywhere, Mach Desktop, Mail
Anywhere Studio, Mainframe Connect, Maintenance Express, Manage Anywhere Studio, M-Business Anywhere, M-Business Channel,
M-Business Network, M-Business Suite, MDI Access Server, MDI Database Gateway, media.splash, MetaWorks, mFolio, Mirror
Activator, MySupport, Net-Gateway, Net-Library, New Era of Networks, ObjectConnect, ObjectCycle, OmniConnect, OmniSQL
Access Module, OmniSQL Toolkit, Open Biz, Open Client, Open ClientConnect, Open Client/Server, Open Client/Server Interfaces,
Open Gateway, Open Server, Open ServerConnect, Open Solutions, Optima++, PB-Gen, PC APT Execute, PC DB-Net, PC Net Library,
Pharma Anywhere, PocketBuilder, Pocket PowerBuilder, Power++, power.stop, PowerAMC, PowerBuilder, PowerBuilder Foundation
Class Library, PowerDesigner, PowerDimensions, PowerDynamo, PowerScript, PowerSite, PowerSocket, Powersoft, PowerStage,
PowerStudio, PowerTips, Powersoft Portfolio, Powersoft Professional, PowerWare Desktop, PowerWare Enterprise, ProcessAnalyst,
QAnywhere, Rapport, RemoteWare, RepConnector, Replication Agent, Replication Driver, Replication Server, Replication Server
Manager, Replication Toolkit, Report-Execute, Report Workbench, Resource Manager, RFID Anywhere, RW-DisplayLib, RW-Library,
Sales Anywhere, SDF, Search Anywhere, Secure SQL Server, Secure SQL Toolset, Security Guardian, SKILS, smart.partners,
smart.parts, smart.script, SOA Anywhere, SQL Advantage, SQL Anywhere, SQL Anywhere Studio, SQL Code Checker, SQL Debug,
SQL Edit, SQL Edit/TPU, SQL Everywhere, SQL Modeler, SQL Remote, SQL Server, SQL Server Manager, SQL SMART, SQL
Toolset, SQL Server/CFT, SQL Server/DBM, SQL Server SNMP SubAgent, SQL Station, SQLJ, STEP, SupportNow, S.W.I.F.T.
Message Format Libraries, Sybase Central, Sybase Client/Server Interfaces, Sybase Financial Server, Sybase Gateways, Sybase IQ,
Sybase MPP, Sybase SQL Desktop, Sybase SQL Lifecycle, Sybase SQL Workgroup, Sybase User Workbench, SybaseWare, Syber
Financial, SyberAssist, SybFlex, SyBooks, System 10, System 11, System XI (logo), SystemTools, Tabular Data Stream, TradeForce,
Transact-SQL, Translation Toolkit, UltraLite, UltraLite.NET, UNIBOM, Unilib, Uninull, Unisep, Unistring, URK Runtime Kit for
UniCode, VisualWriter, VQL, WarehouseArchitect, Warehouse Control Center, Warehouse Studio, Warehouse WORKS, Watcom,
Watcom SQL, Watcom SQL Server, Web Deployment Kit, Web.PB, Web.SQL, WebSights, WebViewer, WorkGroup SQL Server, XA-
Library, XA-Server, XcelleNet, and XP Server are trademarks of Sybase, Inc. 10/05
Unicode and the Unicode Logo are registered trademarks of Unicode, Inc.

All other company and product names used herein may be trademarks or registered trademarks of their respective companies.

Use, duplication, or disclosure by the government is subject to the restrictions set forth in subparagraph (c)(1)(ii) of DFARS 52.227-7013
for the DOD and as set forth in FAR 52.227-19(a)-(d) for civilian agencies.

Sybase, Inc., One Sybase Drive, Dublin, CA 94568.

Contents

About This Book ............................................................................................................................ v

CHAPTER 1 Moving PowerBuilder Applications to the Web ........................... 1

About PowerBuilder Web Form applications.................................... 1
Advantages of Web Form applications............................................. 2
Creating a PowerBuilder .NET Web Form project............................ 3
Configuring ASP.NET for a PowerBuilder project ............................ 7
Selecting the default ASP.NET version ..................................... 8
Viewing a Web Form’s global properties ................................... 9
Directory structure on the server ............................................. 10
Setting up an ASA database connection ................................. 11
Setting up IE Web Controls on the server ............................... 12
Best practices for C# and .NET coding .......................................... 13
Coding restrictions................................................................... 13
Design-level considerations .................................................... 16
Take advantage of global configuration properties ................. 18
Use client-side events to delay postbacks .............................. 20
Global Web configuration properties .............................................. 22
Sharing data across sessions ........................................................ 26
Troubleshooting tips ....................................................................... 26
Problem with toolbars and tab controls ................................... 27
Failure to connect to database ................................................ 27
DataWindows do not display ................................................... 27
Pictures do not display ............................................................ 27
External DLLs cannot be loaded ............................................. 28
Browser error message ........................................................... 28
Print failure .............................................................................. 28
Log files ................................................................................... 29

CHAPTER 2 Client-Side Events and Default Event Handlers......................... 31

About client-side programming....................................................... 31
Default event handlers ................................................................... 33
Client-side support for the Web DataWindow control..................... 35

Working with PowerBuilder Web Forms iii

Contents

Alphabetical list of Web DataWindow client-side events................ 37

ButtonClicked ................................................................................. 38
ButtonClicking ................................................................................ 39
Clicked ........................................................................................... 40
ItemChanged.................................................................................. 41
ItemError ........................................................................................ 42
ItemFocusChanged ........................................................................ 43
RowFocusChanged........................................................................ 44
RowFocusChanging ....................................................................... 45

CHAPTER 3 Print, File, Mail, and Registry Operations in Web Forms ........... 47
Using the Web Form Print Manager............................................... 47
Print Manager icon display ...................................................... 48
Where printed output is saved................................................. 48
Requirements for saving files in PDF or XSL format............... 49
Installing GNU Ghostscript ...................................................... 50
Where PDF and XSL-FO output is saved ............................... 51
Using the Web Form File Manager ................................................ 52
Using the Web Form Mail Profile Manager .................................... 58
Using the registry functions ............................................................ 61

CHAPTER 4 Unsupported Features in PowerBuilder Web Forms ................. 63

About unsupported features........................................................... 63
Unsupported nonvisual objects ...................................................... 64
Unsupported system functions ....................................................... 65
Restrictions on supported controls ................................................. 66
Unsupported functions ................................................................... 73
Unsupported events ....................................................................... 76
Unsupported properties.................................................................. 77
Run the tutorial in PowerBuilder..................................................... 84
Make changes for a .NET Web Form application .......................... 86
Grant ASP.NET users full control over key directories
and files ............................................................................ 86
Change a relative path to a hard-coded path .......................... 88
Create and deploy a .NET Web Form project ................................ 89
Change a global property for the application ................................. 93
Run the application from a Web browser ....................................... 97

Index ........................................................................................................................................... 101

iv PowerBuilder 11.0 CTP

About This Book

Audience This book is for programmers who plan to convert traditional client-server
PowerBuilder® applications to PowerBuilder .NET Web Form
applications, or to develop new .NET Web Form applications in
PowerBuilder.
How to use this book This book describes the generation of Web Form applications using the
PowerBuilder .NET Web Form Application project wizard. It provides
information on design and coding considerations for converting
PowerBuilder applications to Web Form applications and it describes the
client-side events and event handlers you can use to enhance the
performance of your Web Form applications.
Related documents For a description of books in the PowerBuilder documentation set, see the
preface of PowerBuilder Getting Started.
Other sources of Use the Sybase Getting Started CD, the SyBooks CD, and the Sybase
information Product Manuals Web site to learn more about your product:
• The Getting Started CD contains release bulletins and installation
guides in PDF format, and may also contain other documents or
updated information not included on the SyBooks CD. It is included
with your software. To read or print documents on the Getting Started
CD, you need Adobe Acrobat Reader, which you can download at no
charge from the Adobe Web site using a link provided on the CD.
• The SyBooks CD contains product manuals and is included with your
software. The Eclipse-based SyBooks browser allows you to access
the manuals in an easy-to-use, HTML-based format.
Some documentation may be provided in PDF format, which you can
access through the PDF directory on the SyBooks CD. To read or
print the PDF files, you need Adobe Acrobat Reader.
Refer to the SyBooks Installation Guide on the Getting Started CD, or
the README.txt file on the SyBooks CD for instructions on installing
and starting SyBooks.

Working with PowerBuilder Web Forms v

 • The Sybase Product Manuals Web site is an online version of the SyBooks
CD that you can access using a standard Web browser. In addition to
product manuals, you will find links to EBFs/Maintenance, Technical
Documents, Case Management, Solved Cases, newsgroups, and the
Sybase Developer Network.
To access the Sybase Product Manuals Web site, go to Product Manuals at
http://www.sybase.com/support/manuals/.
Conventions The formatting conventions used in this manual are:
Formatting example Indicates
Retrieve and Update When used in descriptive text, this font indicates:
• Command, function, and method names
• Keywords such as true, false, and null
• Datatypes such as integer and char
• Database column names such as emp_id and
f_name
• User-defined objects such as dw_emp or
w_main
variable or file name When used in descriptive text and syntax
descriptions, oblique font indicates:
• Variables, such as myCounter
• Parts of input text requiring substitution, such as
pblname.pbd
• File and path names
File>Save Menu names and menu items are displayed in plain
text. The greater than symbol (>) shows you how
to navigate menu selections. For example,
File>Save indicates “select Save from the File
menu.”
dw_1.Update() Monospace font indicates:
• Information that you enter in a dialog box or on
a command line
• Sample script fragments
• Sample output fragments

If you need help Each Sybase installation that has purchased a support contract has one or more
designated people who are authorized to contact Sybase Technical Support. If
you cannot resolve a problem using the manuals or online help, please have the
designated person contact Sybase Technical Support or the Sybase subsidiary
in your area.

vi PowerBuilder 11.0 CTP

CH A PTE R 1 Moving PowerBuilder
Applications to the Web

About this chapter This Community Technology Preview (CTP) release of PowerBuilder
11.0 features the .NET Web Form Application wizard which lets you
deploy your PowerBuilder applications as ASP.NET Web applications.
This chapter explains how to generate PowerBuilder applications as Web
Form applications and provides tips on design and coding for the .NET
environment.
Contents
Topic Page
About PowerBuilder Web Form applications 1
Advantages of Web Form applications 2
Creating a PowerBuilder .NET Web Form project 3
Configuring ASP.NET for a PowerBuilder project 7
Best practices for C# and .NET coding 13
Global Web configuration properties 22
Sharing data across sessions 26
Troubleshooting tips 26

About PowerBuilder Web Form applications

The PowerBuilder .NET Web Form solution basically employs the
ASP.NET technology. It has a three-tier architecture, with the browser
client as the front end, and the PowerBuilder components on the IIS server
as the middle tier. The database tier remains unchanged.

Working with PowerBuilder Web Forms 1

CHAPTER 1 Moving PowerBuilder Applications to the Web

Moving an existing application from client-server architecture to three-tier

Web architecture typically requires a significant effort in modifying the
application code and the tolerance of various functionality restrictions due to
constraints of the Web environment. The PowerBuilder .NET Web Form
solution is intended to greatly ease the deployment of existing client-server
applications to the Web and to allow you to use your PowerBuilder skills to
create new Web applications.
The Internet bandwidth available, the rendering capability of client Web
browsers, and IIS server environment factors should be taken into account in
any determination as to whether the .NET Web Form is an optimal solution for
new or existing applications.

Advantages of Web Form applications

Web Form applications have several advantages over traditional client-server
and Windows Form applications. Web Form applications do not require
client-side installation, are easy to upgrade, have no distribution costs, and
offer broad-based user access. Any user with a Web browser and an online
connection can run Web Form applications.
Although PowerBuilder continues to support traditional client-server as well as
distributed applications, PowerBuilder 11.0 will provide you with the ability to
transform these applications into Web Form and Windows Form applications
with relative ease. This CTP release highlights the Web Form transformation
capabilities of PowerBuilder.
The decision to convert an application to use Web Forms instead of Windows
Forms depends upon the type of application you plan to convert. A
text-intensive application is a good candidate for conversion to Web Forms,
especially if text formatting is important.
If an application opens multiple MDI sheets at the same time, however, the user
interface can look crowded and its rendering might be very slow. If the
application requires considerable data entry, or retrieves a large amount of data
(for example, more than 5 MB per request), it might be preferable to convert it
to a Windows Form application. The introduction of client-side events,
however, offsets this disadvantage because it allows users to perform data entry
tasks in Web Form applications while minimizing the performance costs of
postbacks to the server.

2 PowerBuilder 11.0 CTP

 CHAPTER 1 Moving PowerBuilder Applications to the Web

Table 1-1 displays some of the relative advantages and disadvantages of Web
Form and Windows Form applications.
Table 1-1: Relative advantages of Web Form and Windows Form
applications
Application type Advantages Disadvantages
Web • No installation • Slower response
• Easy to upgrade • Must be online
• Broader reach
Windows • Quicker response • Difficult to upgrade
time • Requires client-side
• Availability of installation
client-side resources,
such as 3D animation

Smart client applications

PowerBuilder 11.0 will add a smart-client feature that will make Windows
Form applications easy to upgrade while maintaining the advantages of quick
response times and the ability to use local resources.

For more information on the relative advantages of Web Forms and Windows
Forms, see the Microsoft Web site at http://msdn2.microsoft.com/en-
us/library/5t6z562c(VS.80).aspx.

Creating a PowerBuilder .NET Web Form project

System requirements You must install version 2.0 of the Microsoft .NET Framework on the same
computer as PowerBuilder 11, and you must make sure that the system PATH
environment variable includes the location of the .NET Framework. If you
installed the 1.x and 2.0 versions of the .NET Framework, you must make sure
the PATH variable lists the 2.0 version first.
Some functionality, such as application toolbars, requires the installation of IE
Web Controls on the IIS server where you deploy a .NET Web Form project.
For more information about installation and configuration, see “Configuring
ASP.NET for a PowerBuilder project” on page 7.

Working with PowerBuilder Web Forms 3

CHAPTER 1 Moving PowerBuilder Applications to the Web

About the .NET Web You use the PowerBuilder .NET Web Form project wizard to create a Web
Form project Form project from an existing PowerBuilder application. The project you
create allows you to deploy the PowerBuilder application to an IIS 5.0 or
higher server and allows end users to run the application from a Web browser.
Table 1-2 lists optional and required items in the .NET Web Form project
wizard:
Table 1-2: .NET Web Form Project wizard fields and descriptions
.NET Web Form wizard field Description
Destination library Library where you want to store the .NET Web
Form project.
Project object Name of the .NET Web Form project.
Web application name Name of the .NET Web Form application—by
default, this is the name of the application for the
current PowerBuilder target.
Application URL preview Address for starting the .NET Web Form
application in a browser (minus the default.aspx
or default.htm start-up file name).
Initial current directory in virtual The directory path that you want to use as the
file system current directory in the virtual file system on the
server. By default, this is the full path name for
the PowerBuilder target that will be mirrored on
the server.
Command line parameters Command-line parameters required for running
a PowerBuilder application that you deploy as a
Web Form application. You must use an empty
space as a separation character if an application
requires multiple parameters.
Window style Style for the Web Form application—either
Classic Web Style or Classic Windows Style. For
more information, see “About application style”
on page 6.
Render file manager icon Selecting this check box adds a file manager icon
to the Web Form application. The icon opens the
File Manager for the application’s virtual file
system on the server. The File Manager is not
fully functional for the CTP release.
Render mail manager icon Selecting this check box adds a mail manager
icon to the Web Form application. The icon
opens the Mail Manager for the application on
the server. The Mail Manager is not fully
functional for the CTP release.

4 PowerBuilder 11.0 CTP

 CHAPTER 1 Moving PowerBuilder Applications to the Web

.NET Web Form wizard field Description

PBR file list List PowerBuilder Resource files that you want
to deploy with the project.
Resource file and directory list Specify a list of resource files or directories
containing resource files that you want to deploy
with the project. When you select a directory, the
resource files in all of its subdirectories are also
selected by default. However, if you clear the
check box under the Recursive column, resource
files in the selected directory, but not in any of its
subdirectories, are selected for deployment.
External module list (Not fully functional for CTP.) Specify any
Win32 DLLs or managed assembly DLLs that
you want to include with your project. In
PowerScript® code, references to these modules
must be bounded by #clr and #endclr tags.
Modules in this list are deployed to the bin
directory in the application Web site under the
virtual root folder.
Additional PowerBuilder library Specify PBL and PBD libraries referenced in the
list current target for deployment with your project.
JavaScript file list Specify JavaScript files you want to deploy with
the project.
Generate setup file option and (Not fully functional for CTP.) Select this option
Setup file name and a setup file name if you are not deploying
directly to an IIS server.
Direct deploy to IIS and IIS Select this option to deploy to an IIS server and
server address enter the address of the server where you want to
deploy the .NET Web Form application. Note
that deployment to a remote server is not
completely implemented in the current CTP
release.

Using the Properties After you click Finish in the wizard, PowerBuilder creates a .NET Web Form
dialog box for a .NET project in the target library that you selected and opens the project in the Project
Web Form project
painter. You can use the Edit>Properties menu of the Project painter or the
Properties toolbar icon to open the properties dialog box for the project. This
dialog box displays all the values you entered in the wizard and allows you to
modify them.
Figure 1-1 displays the General page of the Properties dialog box for a .NET
Web Form project.

Working with PowerBuilder Web Forms 5

CHAPTER 1 Moving PowerBuilder Applications to the Web

Figure 1-1: .NET Web Form Project properties dialog box

About application style You can set the application to display in classic Web style or in classic
Windows style. In classic Web style, the application fills the browser frame,
and MDI sheet windows display as tabbed dialog boxes. In classic Windows
style, frame and sheet windows include separate title bars.
For SDI applications using classic Windows style, the main window is centered
in the browser, with its borders offset by the empty browser frame background.
However, the window is resizeable and can be moved.
Deploying and running When a .NET Web Form project is open in the Project painter and no other
the project from the painters are open, you can select Design>Deploy Project from the Project
PowerBuilder UI
painter to deploy the project. When all painters are closed, including the
Project painter, you can right-click a .NET Web Form project in the System
Tree and select Deploy from its pop-up menu.
The Output window displays the progress of the deployment and provides a list
of application functions, events, and properties that are not supported in the
Web Form version of the application. Most of these warnings are benign and
do not prevent users from running the application as a Web Form.

6 PowerBuilder 11.0 CTP

 CHAPTER 1 Moving PowerBuilder Applications to the Web

If the 2.0 version is the only version of the Microsoft .NET Framework
installed on the server, or if you configured the server to use the 2.0 version for
all Web sites by default, you can run the application immediately after you
deploy it. You can run the application from PowerBuilder by selecting
Design>Run Project from the Project painter menu or selecting the Run Project
toolbar icon from the Project painter toolbar. The System Tree pop-up menu for
the .NET Web Form project also has a Run Project menu item.
Running the project When you run the project from PowerBuilder, the Web browser that opens does
from a Web browser not include the browser menu and toolbar. This is because PowerBuilder does
not append the starting page, default.aspx, to the URL listed in the project. You
can see the application in a browser window that includes the browser menu
and toolbar by typing the URL in the browser location window or address bar.
The URL address is not case-sensitive.

Starting an application with command-line parameters

If your application requires command-line parameters, you set the
PBCommandParm parameter at the end of the URL preceded by a question
mark. Multiple parameters are separated by the ASCII character code for an
empty space (%20). For example, the following address, entered on a single
line, uses two start-up parameters for the mypbapp Web Form application
deployed to the www.mysite.com Web site:
http://www.mysite.com/mypbapp/default.aspx?PBCommandPa
rm=p1%20p2

If you do not include the starting page, default.aspx, in a URL that you type in
a browser address bar, or if you append default.htm as the starting page, IIS still
redirects you to the default.aspx page, but the browser menu and toolbar do not
display.

Configuring ASP.NET for a PowerBuilder project

You can configure ASP.NET for a PowerBuilder project before or after you
deploy the project. You must configure most of the global properties for a
specific PowerBuilder project, however, after you deploy the project to IIS.

Working with PowerBuilder Web Forms 7

CHAPTER 1 Moving PowerBuilder Applications to the Web

Selecting the default ASP.NET version

If you installed multiple versions of the .NET Framework on the target Web
server computer, you should make sure that IIS uses the 2.0 version for
PowerBuilder .NET Web Form applications. You can make this change
globally, for all ASP.NET Web site applications, or for individual Web Form
applications that you deploy to IIS.

If you have not installed IIS

You can install IIS from the Control Panel, but you might need a Windows
operating system CD. Select Add and Remove Programs from the Control
Panel, then click Add/Remove Windows Components, select the Internet
Information Services check box, and click Next. You can then follow
instructions to install IIS.

❖ To configure the ASP.NET version for all new Web sites:

1 Select Start>Run from the Windows Start menu.
2 Type “InetMgr” in the Run dialog box drop-down list.
The IIS Manager displays.
3 In the left pane of the IIS Manager, expand the local computer node and
its Web Sites sub-node.
4 Right-click the Default Web Site node and select Properties from its
pop-up menu.
The Default Web Site Properties dialog box displays.
5 Click the ASP.NET tab of the Default Web Site Properties dialog box and
select 2.0.50727 or higher for the ASP.NET version.

8 PowerBuilder 11.0 CTP

 CHAPTER 1 Moving PowerBuilder Applications to the Web

Figure 1-2: Setting the default ASP.NET version

Changing the ASP.NET version for an existing Web Form project

If you have already deployed a PowerBuilder Web Form project, you can
follow the procedure to configure the ASP.NET version for all new Web sites,
but instead of right-clicking on the Default Web Site node in step 4, expand the
node and right-click on the .NET Web Form application that you deployed
from PowerBuilder. Then proceed with step 5.

Viewing a Web Form’s global properties

In the IIS Manager, you can view and modify the global properties for a
PowerBuilder application that you deploy to IIS. For information about global
properties generated with a PowerBuilder .NET Web Form project, see
“Global Web configuration properties” on page 22.

❖ To view a Web Form application’s global properties in the IIS Manager

1 Expand the nodes in the left pane of the IIS Manager until you see the node
for the Web Form application whose properties you want to examine.
2 Right-click on the Web Form application and select Properties from the
pop-up menu.

Working with PowerBuilder Web Forms 9

CHAPTER 1 Moving PowerBuilder Applications to the Web

3 Click the ASP.NET tab and change the ASP.NET version to 2.0.50727 if
necessary.
4 Click Edit Configuration.
The ASP.NET Configuration dialog box displays for the current .NET
Web Form application. You can view its global properties in the list box at
the bottom of the General tab.

Modifying a global property for the application

You modify a global property by selecting that property in the Application
Settings list box and clicking Edit. You can then type in a new value for
that property and click OK. The next time you run the Web Form
application, the new global property value will be used.

Directory structure on the server

When you deploy a PowerBuilder .NET Web Form application, PowerBuilder
creates two top-level directories for the application under the IIS root. One of
the directories takes the name of the application specified in the Web Form
project, and the other appends “_root” to the application name.
The applicationName directory contains the generated cs and aspx files, as
well as subdirectories for any resource files, PowerBuilder libraries, and
external modules that you deploy with your application.
The applicationName_root directory contains directories named File, Mail,
Log, and Print. The File directory contains the Common directory. The
Common directory holds read-only files specified in the Web Form project.
The paths to the read-only files mirror the paths on the development computer,
with the drive letter serving as the name for the top subdirectory under the
Common directory. The subdirectories under the Common directory include
the initial current directory that you assigned in the .NET Web Form project
wizard or in the Project painter.
If you perform write operations on a file in the File directory, a Session ID
folder is created under the Common directory, and the read-only file is copied
there in a mirrored path before a user can save the modified file.

10 PowerBuilder 11.0 CTP

 CHAPTER 1 Moving PowerBuilder Applications to the Web

Setting up an ASA database connection

Before a PowerBuilder .NET Web Form application connects to an Adaptive
Server® Anywhere (ASA) database, you must either start the database
manually or grant the ASPNET user full permissions for the Sybase\Shared
and Sybase SQL Anywhere directories, making sure to replace permissions of
all child objects in those directories.

Starting the database manually

If your database configuration uses a server name, you must provide the
database server name in the start-up options when you start the database
manually, in addition to the name of the database file you are accessing.

If you do not grant the ASPNET user appropriate permissions for Sybase
directories and your database configuration is set to start the database
automatically, your application will fail to connect to the database, because
ASA cannot access files unless the ASPNET user has the right to access them.

❖ To grant an ASPNET user full permissions for Sybase directories

1 In Windows Explorer, right-click the Sybase, Sybase\Shared or Sybase
SQL Anywhere directory and select Properties from the pop-up menu.
The Properties dialog box displays for the selected directory.
2 Select the Security tab of the Properties dialog box for the directory and
click the Add button.
The Select Users, Computers, or Groups dialog box displays.

If the Security tab does not display

To display the Security tab, you might need to modify a setting on the
View tab of the Folder Options dialog box for your current directory. You
open the Folder Options dialog box by selecting the Tools>Folder Options
menu item from Windows Explorer. To display the Security tab, you must
clear the check box labeled “Use simple file sharing (Recommended)”.

3 Click Locations and choose the server computer name from the Locations
dialog box and click OK.
4 Type ASPNET in the list box labeled “Enter the object names to select”
and click OK.
The ASP.NET machine account is created for the current directory.

Working with PowerBuilder Web Forms 11

CHAPTER 1 Moving PowerBuilder Applications to the Web

5 Select the ASP.NET machine account in the top list box on the Security
tab, then select the “Full Control” check box under the Allow column in
the bottom list box.
6 Click the Advanced button.
The Advanced Security Settings dialog box displays for the current
directory.
7 Select the check box labeled “Replace permission entries on all child
objects with entries shown here that apply to child objects” and click OK.
A Security dialog box displays, warns you that it will remove current
permissions on child objects and propagate inheritable permissions to
those objects, and prompts you to respond.
8 Click Yes at the Security dialog box prompt, then click OK to close the
Properties dialog box for the current directory.

Tracing database exceptions

The pbtrace.log file is created in the applicationName_root directory when you
connect to a database from the Web Form application. This file records all
exceptions thrown by the application and can be used to troubleshoot the
application.

Setting up IE Web Controls on the server

PowerBuilder .NET Web Forms use Internet Explorer Web Controls to display
correctly and to provide functionality for the Tab, TreeView, and Toolbar
controls. You can install IE Web Controls (version 1.0) from the PowerBuilder
setup program.
Otherwise, you can download IE Web Controls from the Microsoft Web site at
http://www.asp.net/IEWebControls/Download.aspx. The download comes with a
Readme file that provides instructions for installing the controls.
After you install the IE Web Controls, you must copy them to a
webctrl_client\1_0 directory under the IIS root.

❖ To copy the IE Web Controls:

1 Open a DOS command box.
2 Change directories to the directory where you installed the IE Web
Controls.

12 PowerBuilder 11.0 CTP

 CHAPTER 1 Moving PowerBuilder Applications to the Web

3 Type the following line at the command prompt, modifying the server IIS
root directory if you do not use the default c:\Inetpub\wwwroot directory:
xcopy /s /i .\build\Runtime
c:\Inetpub\wwwroot\webctrl_client\1_0 /y
4 Press Enter.
This creates the following directory structure under the root:
/webctrl_client/1_0
[images]
[treeimages]
The /webctrl_client/1_0 directory should contain the following files:
MultiPage.htc, TabStrip.htc, toolbar.htc, treeview.htc, webservice.htc, and
webserviced.htc

Best practices for C# and .NET coding

The changes required to transform a PowerBuilder application into a Web
Form application depend on the nature of the application, the scripting
practices used to encode the application functionality, and the number of
methods the application uses that are not supported in the .NET environment.

Coding restrictions
Although PowerScript is essentially a compiled language, it is quite tolerant.
For example, PowerScript allows narrow casting without raising warnings at
compile time, even though this might cause a runtime error. On the other hand,
C# and .NET are much more restrictive. If you want to do narrow casting, you
must explicitly express this in the code.
For the sake of performance, the PowerBuilder .NET compiler is not designed
to be as tolerant as the PowerBuilder native compiler. To be able to compile
your applications with .NET, you should avoid certain practices in your
PowerScript code.
The following language-level items apply when you plan to transform a
PowerBuilder application to a Windows Form or Web Form application.

Working with PowerBuilder Web Forms 13

CHAPTER 1 Moving PowerBuilder Applications to the Web

Syntax issues Avoid the GoTo statement Jumping into a branch of a compound statement
is legal in PowerBuilder, because the concept of scope inside a function does
not exist in PowerScript. For example, the following code works well in
PowerBuilder:
if b = 0 then
label: …
else
…
end if
goto label
This PowerScript would translate conceptually into the following C# code:
if (b == 0)
{ // opening a new scope
label: …
}
else
{
…
}
goto label;
Since a GoTo statement is not allowed to jump to a label within a different
scope in .NET, the C# code would not compile. For this reason, you should
avoid using GoTo statements.
Avoid calling an indirect ancestor event in an override event Suppose
that there are three classes, W1, W2, and W3. W1 inherits from Window, W2
inherits from W1, and W3 inherits from W2. Each of these classes handles the
clicked event. In the clicked event of W3, it is legal to code the following in
PowerScript:
call w1::clicked
However, in C#, calling the base method of an indirect base class from an
override method is not allowed. The previous statement translates into the
following C# code, which might produce different behavior:
base.clicked();
Semantic issues Do not use narrow casting PowerScript allows you to caste a class to an
indirect ancestor. Although it does not represent good programming practice,
the following code is legal in PowerBuilder, where n_ds is a subclass of
DataStore:
n_ds ds
ds = create datastore //legal, but to be avoided!

14 PowerBuilder 11.0 CTP

 CHAPTER 1 Moving PowerBuilder Applications to the Web

For this example, .NET would throw an exception.

For another example of casting permitted in PowerBuilder but not in the .NET
environment, suppose a function for opening a window, f_open, is scripted as
follows:
Function void f_open(ref window w)
open(w)
end function
In PowerBuilder, you could call the f_open function as follows:
F_open(w_main)
However, in this CTP release, the compiled C# would not work because the
f_open function has no information about the real type of the window to be
opened.
There are two ways to solve this problem:
• Change the type of the parameter w in the f_open definition to w_main.
• Add one more parameter to the f_open function to specify the type of the
window to be opened:
Function void f_open(ref window w, string
window_type)
open(w, window_type)
end function
You could then call the function in this way:
f_open (ref w_main, "w_main")
Do not use the This keyword in function objects A function object is
essentially a static method of a class. Although the PowerBuilder compiler
does not prevent you from using the This pronoun in a function object, the C#
compiler will not allow this.
Do not change an event's signature The PowerBuilder compiler does not
prevent you from changing the signature of an event defined by its super class,
but .NET does not allow this. For example, suppose the w_main class contains
the following event:
Event type integer ue_update(int e)
The subclasses of the w_main class should not change the parameters or the
return type of the event.

Working with PowerBuilder Web Forms 15

CHAPTER 1 Moving PowerBuilder Applications to the Web

External functions Differences in passing a structure by reference PowerBuilder allows you

to declare an external function that has a parameter of type Structure passed by
reference. For example:
Subroutine CopyMemory(ref structure s, int size)
library "abc.dll"
The s parameter can accept any datatype that is a pointer to something.
A PowerBuilder external function is mapped to the .NET Platform Invoke
functionality. This functionality requires that the structure passed into the
external function be exactly of the type declared. Therefore, when compiling
the following PowerScript code, the PowerBuilder .NET compiler issues an
error, because the parameter, li, references a LogInfo structure, which is
different from the function’s declared structure class.
LogInfo li
CopyMemory(ref li, 20) // error!
To solve this problem, you can declare an additional external function as
follows:
Subroutine CopyMemory(ref LogInfo li, int size) library
"abc.dll"
Allocate space before passing a string by reference Before passing a
string to an external function by reference in PowerBuilder, you should allocate
memory for the string by calling the Space system function. In subsequent calls
to the function, if you pass the same string to the function, PowerBuilder can
continue to work well even if the string had become empty, because memory
allocated for the string is not yet freed by the PowerBuilder VM.
This is not the case in the .NET environment. If the string passed to an external
function by reference is empty, and if the external function writes something to
the string, an exception is thrown. Therefore, you must make sure to allocate
enough space for a string before passing it to an external function by reference.

Design-level considerations
Although stricter compiler enforcement for the .NET environment can catch
coding errors typically tolerated by the PowerScript compiler, the .NET
environment might also require changes in application design that are not
necessarily caught by the compiler.

16 PowerBuilder 11.0 CTP

 CHAPTER 1 Moving PowerBuilder Applications to the Web

Use PowerBuilder For a PowerBuilder .NET Web Form application, you should use
system functions PowerBuilder system functions instead of external functions whenever
possible. Some system functions, such as the functions for file operations, are
implemented differently for Windows Forms and Web Forms. If you always
use PowerBuilder system functions, you do not need to worry about these
differences.
Use GetCurrentDirectory Some applications use external DLL functions to
get the current directory. For PowerBuilder Web Form applications, you must
use the GetCurrentDirectory standard system function instead.
PowerBuilder Web Forms use a virtual file system to emulate a file system on
the server for each client. The virtual file system is actually a folder on the
server computer to which the ASP.NET user has write permission. Calling an
external function to get the current directory from the virtual file system will
fail.
Work around Avoid using Handle Some applications call the Handle function to get the
unsupported features window handle of a control and pass it to an external function. This does not
work in a Web Form application.
Restrict impact of unsupported events Since unsupported events are
never triggered, do not allow the logic in unsupported events to affect the logic
flow of other events or functions. For example, if the code in an unsupported
event changes the value of an instance variable, it can affect the logic flow in
a supported event that uses that variable. You should remove this type of
coding from unsupported events.
Avoid name conflicts PowerBuilder allows two objects to have the same
name if they are of different types. For example, you can use the name
s_address to define a structure and a static text control or a nonvisual object in
the same PowerBuilder application. The .NET environment does not allow two
classes to have the same name. To enable your application to compile in .NET,
you must not give the same name to multiple objects, even if they are of
different types.
AcceptText is redundant In the WebForm deployment version of the
DataWindow®, explicit invocations of AcceptText are redundant but harmless.
Any loss of focus of a DataWindow implicitly invokes AcceptText.
Avoid hindrances to Some functions and features that are fully supported can hinder application
application performance. These functions and features should be used sparingly and
performance
avoided where possible.

Working with PowerBuilder Web Forms 17

CHAPTER 1 Moving PowerBuilder Applications to the Web

Response windows and message boxes Although response windows and

message boxes are supported in Web Forms, use them only when absolutely
necessary. Response windows and message boxes require more server-side
resources than other kinds of windows.
Hiding a response window in a Web Form application does not work properly
and might cause the application to fail. Instead of hiding a response window,
always close it when the user has finished with it.
Yield Although the Yield function works in a Web Form application, avoid it
whenever possible, because it requires additional server-side resources.
Timers Timers are supported in Web Form applications, but they periodically
generate postbacks and might impede data entry. You should use them
sparingly and avoid including them on forms that require data entry. When you
use them, you can delay the postbacks by appropriate scripting of client-side
events.
PFC The DataWindow service in PFC handles many DataWindow events.
Each event causes a postback for each mouse click, which will adversely affect
application performance. You can delay postbacks by scripting client-side
events or you can cache DataWindow data in the client browser by setting the
paging method property for the DataWindow object to XMLClient!.

Take advantage of global configuration properties

Properties have been added to standard PowerBuilder controls to enhance the
application presentation in the .NET environment and to improve application
performance. These properties are listed in “Global Web configuration
properties” on page 22. They are generated in the Web.config file in the main
folder for your PowerBuilder .NET Web Form project under the IIS server root.
You can edit the file directly, or you can modify the global properties using the
IIS Manager.
For information on how to modify global properties in the IIS Manager, see
“Viewing a Web Form’s global properties” on page 9.
Global properties also allow you to share data across application sessions. For
information on sharing DataWindows, see “Sharing data across sessions” on
page 26.

18 PowerBuilder 11.0 CTP

 CHAPTER 1 Moving PowerBuilder Applications to the Web

DataWindow pagination If the HTMLGen.PageSize property

(RowsPerPage property in DataWindow .NET and Rows Per Page in the
DataWindow painter) of a DataWindow object is not set, the Web.config file
property PBDataWindowRowsPerPage limits the number of rows per page for
a Web DataWindow control to 20 rows by default. Because this renders only
the specified number of rows at a time, the PBDataWindowRowsPerPage helps
reduce the size of the HTML response and thereby enhances performance. This
property is global, since it applies to all DataWindows in the application for
which HTMLGen.PageSize is not set.
To disable pagination of Web Form DataWindow objects, set the
PBDataWindowRowsPerPage property to -1. To disable pagination for a
specific DataWindow object, set its HTMLGen.PageSize property to -1.
DataWindow page navigation There are several global properties related to
DataWindow page navigation.You can set the navigation bar at the top or the
bottom of a DataWindow page by modifying the
PBDataWindowNavigationBarPosition property. You can edit labels for
“QuickGo” navigation bar, and the text for the current and total page counts
using the PBDataWindowGoToDescription, the
PBDataWindowGoToButtonText, and the PBDataWindowStatusInfoFormat
properties.
The PBDataWindowPageNavigatorType property lets you select the type of
navigation bar you want to use; NextPrev, Numeric, QuickGo, or combined
types. Figure 1-3 shows the default “NextPrev” navigation bar. It also displays
page status information with the default text for the current and total page
count. You can set the text in the PBDataWindowStatusInfoFormat property.
The NextPrev navigation bar includes the “>” symbol for navigating to the next
page, and the “<“ symbol for navigating to the previous page. Doubled
symbols are controls for navigating to the first page (“<<“) or last page (“>>”).
The navigation bar folds up to display only symbols that are functional when a
user displays the first or last page of a DataWindow. For example, the user
cannot navigate to a previous page from the first page, and navigating to the
first page would be unnecessary, so the “<“ and “<<“ symbols do not display
on the first page.

Working with PowerBuilder Web Forms 19

CHAPTER 1 Moving PowerBuilder Applications to the Web

Figure 1-3: “NextPrev” navigation bar with page count display

Figure 1-4 displays the “NumericWithQuickGo” navigation bar. The numeric

portion of the navigation bar lists each page by its page number. You can set
the PBDataWindowPageNavigatorType to “Numeric” or to “QuickGo” if you
want to use these styles separately. You can also combine the NextPrev style
with the QuickGo style by setting the PBDataWindowPageNavigatorType
property to “NextPrevWithQuickGo”.
Figure 1-4: “NumericWithQuickGo” navigation bar and page count

Although the QuickGo navigation control defaults to a drop-down list, you can
change this to a text box with an associated command button by setting the
PBDataWindowQuickGoPageNavigatorType property to “Button”. You can
edit the button label by setting the PBDataWindowGoToButtonText property.
You set the label for the text box or the drop-down list by modifying the
PBDataWindowGoToDescription property.

Use client-side events to delay postbacks

Before the .NET target is deployed, you can code client-side events in
JavaScript and set properties to reference the JavaScript code that handles
client-side events. You must set the properties in #CLR-#ENDCLR code
blocks. The beginning and end tags for these code blocks signal the
PowerBuilder native compiler to ignore the code contained inside them.

.NET code blocks after this CTP release

The code blocks that begin and end with #CLR and #ENDCLR statements will
need to be modified after the current CTP release. In future releases, #IF,
#ELSE, and #ENDIF statements will be used instead of #CLR and #ENDCLR
to separate .NET code blocks from standard PowerScript code.

The code inside the #CLR-#ENDCLR blocks is passed to the Web browser
client from the server at runtime. You use this code to designate JavaScript
functions that handle events on client-side objects. Most events on client-side
objects cause a postback to controls on the server side, because the events have
server-side analogs that are written originally in PowerScript, then transformed
to run in the .NET environment.

20 PowerBuilder 11.0 CTP

 CHAPTER 1 Moving PowerBuilder Applications to the Web

If you write any JavaScript code for the client-side events, the postback to the
server is interrupted. To resume a postback, you can call the submit method for
a Web Form or one of the postback methods generated in the
PBDataWindow.JS file. The PBDataWindow.JS file is generated in the Scripts
subdirectory of the main project directory under the IIS virtual root.
The postback methods of the PBDataWindow.JS file are described in Chapter
2, “Client-Side Events and Default Event Handlers.”
DataWindow property for setting a customized event handler Properties
of the DataWindow class allow you to handle client-side events in JavaScript
code. The JavaScriptFile property specifies the JS file that contains JavaScript
functions for handling individual client-side events. You must make sure to
deploy the JavaScript file that contains your customized event handling code.
You assign the JavaScriptFile property in a #CLR-#ENDCLR code block:
#clr
dw_1.JavaScriptFile = “D:\Scripts\MyScriptFile.js”
#endclr
DataWindow properties for calling client-side events The following
DataWindow events can be handled on the client side in JavaScript code:
• Clicked
• ButtonClicking
• ButtonClicked
• ItemChanged
• ItemError
• ItemFocusChanged
• RowFocusChanged
• RowFocusChanging
The DoubleClicked and RButtonDown events are not handled on the client
side in the current CTP release.
For more information on client-side events, see Chapter 2, “Client-Side Events
and Default Event Handlers.”
To specify a JavaScript function for handling a client-side event, you must
indicate the function to call in the corresponding Web DataWindow property.
The name of the corresponding property consists of the name of the client-side
event with an “OnClient” prefix. For example, the property corresponding to
the ItemChanged event is OnClientItemChanged.

Working with PowerBuilder Web Forms 21

CHAPTER 1 Moving PowerBuilder Applications to the Web

The following example references a script called MyDwClickedEventHandler

for the client-side DataWindow Clicked event. The script for the
MyDwClickedEventHandler event handler must use the syntax for the
client-side Clicked event described in Chapter 2, “Client-Side Events and
Default Event Handlers.”
#clr
dw_1.JavaScriptFile = “D:\Scripts\MyScriptFile.js”
dw_1.OnClientClicked = “MyDWClickedEventHandler”
#endclr
Client-Side CommandButton property The OnClientClick
CommandButton property specifies a snippet of JavaScript code that executes
when a command button is clicked.
AutoPostBack The AutoPostBack property for SingleLineEdit,
MultiLineEdit, CheckBox, and RadioButton controls allows you to reduce
postbacks and increase performance.
#clr
cb_1.AutoPostBack = true
#endclr
Embedded You can embed a Web page inside a PowerBuilder Web Form
application by assigning the Embedded property to a StaticHyperLink control.
The IFRAME element is used to embed the Web page that you defined in the
URL property of the StaticHyperLink control. The Web page displays inline on
the Web Form page. The following code sets the Embedded property to “true”:
#clr
static_hyperlink.Embedded = true
#endclr

Global Web configuration properties

Table 1-3 displays the global properties of a PowerBuilder .NET Web Form
application. They are defined in the Web.Config file that is generated in the
main application directory under the IIS virtual root directory.

22 PowerBuilder 11.0 CTP

 CHAPTER 1 Moving PowerBuilder Applications to the Web

Table 1-3: Properties of a PowerBuilder .NET Web Form application

Property Default value Description
PBWebFileProcessMode Share Share mode maintains files in a read-only state when a
write file operation is not explicitly coded. If an
application requires multiple file operations, you might
want to change this property setting to Copy mode.
For more information on Share and Copy mode, see
“Using the Web Form File Manager” on page 52.
FileFolder WebAppDir..\appName_ Base directory for the virtual file manager. It contains the
root\file Common directory structure and files that mirror paths for
the application resource files on the development
computer. If you switch to Copy mode, a session ID
directory is created under the File directory that mirrors
the Common directory structure and file contents.
MailFolder WebAppDir..\appName_ Base directory for the mail manager (functionality not
_root\mail completely implemented for the CTP release).
PrintFolder WebAppDir..\appName_ Base directory for files that your application prints in PDF
_root\print format.
LogFolder WebAppDir..\appName_ Folder that contains the PBTrace.log file.
_root\log
PBCurrentDirectory A default value can be The initial current directory for the virtual file manager.
set in PowerBuilder UI
PBDenyDownloadFolders — A comma-delimited string of directory names.
Application users are not able to use the Web Form File
Manager to download files in any of the directories listed
in this string.
PBCommandParm A default value can be Sets command-line parameters for your application.
set in PowerBuilder UI Users can override the default by setting this property in a
URL.
PBYieldTimeout 10000 (milliseconds) Time in milliseconds before the Yield function will cause
a postback to the server. Yield calls are ignored if you set
this value to 0. When you set this value to 0, however, you
must make sure your application does not call Yield inside
a loop, as in the following example:
do while flag
yield()
loop
PBWebWindowStyle Web. This default value Values are web for Classic Web Style, or window for
can be changed in Classic Window Style.
PowerBuilder UI
PBFileManager False. This default value Set to true if you want to render the File Manager icon in
can be changed in a Web Form application.
PowerBuilder UI

Working with PowerBuilder Web Forms 23

CHAPTER 1 Moving PowerBuilder Applications to the Web

Property Default value Description

PBMailManager False. This default value Set to true if you want to render the Mail Manager icon in
can be changed in a Web Form application.
PowerBuilder UI
PBTrace Enabled Indicates whether to log exceptions thrown by the Web
Form application. Values are Enabled or Disabled.
PBTraceTarget File Defines where to log exceptions thrown by the Web Form
application. Values are File or EventLog.
PBTraceFileName PBTrace.log Name of the file that logs exceptions thrown by the
WebForm application.
PBEventLogID 1100 The event ID if exceptions are logged to the EventLog.
AutoTriggerMenuSelected False Indicates whether to trigger the menu Selected event for
Events all menu items before the Web Form is rendered in the
browser. The Selected event can be handled on the server
only for simple tasks related to the appearance of the
menu items. The Selected event is always disabled on the
client side to prevent unnecessary postbacks when a menu
item is highlighted.
PBTimerInterval 1 (second) Sets the interval for the Timer event in the Web Form
application. A value of 0 prevents the Timer event from
being triggered.
PBIdleInterval 1 (second) Sets the interval for the Idle event in the Web Form
application. A value of 0 prevents the Idle event from
being triggered.
PBDeleteTempFileInterval 600 (minutes) Sets the number of minutes before temporary files created
by composite DataWindows are deleted. A value of 0
prevents the temporary files from being deleted.
PBDataWindowRowsPerP 20 Sets the number of DataWindow rows to display in a Web
age Form when the HTMLGen.PageSize property of the
DataWindow object is not set. Note that Group and
Crosstab DataWindows do not support pagination.
PBDataWindowPageNavig NextPrev Values are NextPrev, Numeric, QuickGo,
atorType NextPrevWithQuickGo, or NumericWithQuickGo. For
more information, see “Take advantage of global
configuration properties” on page 18.
PBDataWindowStatusInfo Page {C} of {T} Sets the text to display for the DataWindow page count
Format {C} and the total number of pages {T}. The other
variables you can use are placeholders for the starting
page of a group {S} and for the ending page of a group
{E}.
PBDataWindowGoToDesc Go To: Sets the label for the navigation control that takes a user
ription to a designated DataWindow page.

24 PowerBuilder 11.0 CTP

 CHAPTER 1 Moving PowerBuilder Applications to the Web

Property Default value Description

PBDataWindowGoToButt Go Sets the label for a navigation bar button that takes a user
onText to a designated DataWindow page.
PBDataWindowPageCount 10 Sets a limit to the number of pages that display for the
PerGroup Numeric or NumericWithQuickGo style navigation bars.
PBDataWindowQuickGoP DropDownList Sets the type of control to use for the Quick Go navigation
ageNavigatorType bar. Values are DropDownList or Button.
PBDataWindowNavigatio PBDWBottom Sets the position where the page navigation controls
nBarPosition display. Values are PBDWBottom for display at the
bottom of the DataWindow, PBDWTop for display at the
top of the DataWindow, or PBDWTopAndBottom for
display at the top and bottom of the DataWindow.
PBDataWindowDynamicE True The default value allows you to set client-side events that
ventHook hook into a JavaScript file containing event handlers to
improve performance. Values are true or false.
PBDataWindowEnableDD False Indicates whether to render a DropDownDataWindow
DW (DDDW) or a DropDownListBox control for a column
using the DDDW edit style. Values are true to render the
drop-down object as a DDDW, or false to render it as a list
box. The value you set applies to all DDDW objects in the
application, although if you set this value to true, you can
still render a specific DDDW object as a list box by setting
its HTMLGen.GenerateDDDWFrames property (the
“Generate DDDW Frames” field on the Web Generation
page of the DataWindow painter Properties view) to false.
PBCachedAndSharedDWs — A comma-delimited set of names for DataWindow objects
that you want to share across application sessions. For
more information, see “Sharing data across sessions”
next.
PBCachedAndSharedDDD — A comma-delimited set of names for DataWindow objects
Ws that you want to use in DropDownDataWindow edit style
controls for sharing across application sessions. For more
information, see “Sharing data across sessions” next.

Working with PowerBuilder Web Forms 25

CHAPTER 1 Moving PowerBuilder Applications to the Web

Sharing data across sessions

Sharing DataWindow You can share the data from primary, delete, and filter buffers of read-only
objects DataWindow objects across Web Form application sessions. The Web.config
file global property PBCachedAndSharedDWs is available for this purpose.
You must set its value to the string of comma-delimited names of the
DataWindow objects you want to share across application sessions.
For information on modifying global properties, see “Configuring ASP.NET
for a PowerBuilder project” on page 7.
The following restrictions apply to DataWindow controls that have a
DataWindow object included in the PBCachedAndSharedDWs property
setting:
• Only a single invocation of Retrieve is allowed, and the Retrieve call must
not include parameters.
• No filtering or sorting is allowed.
• No deletions, insertions, data modifications or updates are allowed.
• No invocation of ShareData or ShareDataOff is allowed.
Sharing DDDW It is also possible to share the data of DropDownDataWindow objects across
objects Web Form application sessions. The global property
PBCachedAndSharedDDDWs is used for this purpose. You can set its value to
a string of comma-delimited names of DataWindow objects. Each
DataWindow object that you list can then be shared as the child DataWindow
of a DropDownDataWindow column.
The following restrictions apply to DataWindowChild object references
included in the PBCachedAndSharedDDDWs property setting:
• No invocation of Retrieve is allowed.
• No filtering or sorting is allowed.
• No deletions, insertions, data modifications or updates are allowed.
• No invocation of ShareData or ShareDataOff is allowed.

Troubleshooting tips
After successfully deploying a PowerBuilder .NET Web Form project, you
might encounter some of the following common, easy-to-fix issues at runtime:

26 PowerBuilder 11.0 CTP

 CHAPTER 1 Moving PowerBuilder Applications to the Web

Problem with toolbars and tab controls

If the application toolbar and tab controls are not working properly, this is most
likely due to the improper installation of the Microsoft IE Web controls. For
more information, see “Setting up IE Web Controls on the server” on page 12.

Failure to connect to database

DSN Due to limited access rights of the ASP.NET user, data sources created
as User DSNs cannot be loaded. You must create the data sources for your Web
Form application as System DSNs.
Oracle The ASP.NET user must be granted full control rights to the Oracle
Client directory. For example, if the Oracle client is installed in the
c:\oracle\ora9 directory, the ASP.NET user must have full control rights to this
directory.
Adaptive Server Anywhere The ASP.NET user must be granted full control
rights to the directory indicated by the ASANY9 environment variable. The
ASP.NET user must also have full control rights to the directory that contains
the database.
Database connections using an INI file If your application uses an INI file
to get database connection information, make sure to add the INI file to the
resource file list of your .NET Web Form project before you deploy it.

DataWindows do not display

Make sure the PBL files that contain the DataWindows you want to display are
copied to the File\Common\C subdirectory of the applicationName_root
directory in the server’s virtual file system path.

Pictures do not display

Before you deploy a .NET Web Form project, make sure that you add all
picture files used by the application to the resource file list for the project.

Working with PowerBuilder Web Forms 27

CHAPTER 1 Moving PowerBuilder Applications to the Web

Resource files might not be accessible if you change the default value for the
initial current directory of the virtual file system for the Web Form project. The
default value in the .NET Web Form project wizard is the current target path.
Modifying the PBCurrentDirectory global property in the project’s ASP.NET
configuration settings or directly in the Web.config file might also make the
resource files inaccessible.

External DLLs cannot be loaded

Make sure the DLLs you want to load are copied to the bin subdirectory of the
main Web Form application directory in the server’s virtual file system path.

Browser error message

The “Object reference not set to an instance of an object” error message might
display in a client browser for a Web Form application if the application uses
an unsupported version of the .NET Framework. The error message description
indicates that “an unhandled exception occurred during the execution of the
current web request,” and the exception details display a
“System.NullReferenceException”.
You can resolve this type of error by opening a command window on the server,
changing directories to the Microsoft.NET\Framework\v2.0.50727 directory
in the Windows system path, and typing the following command:
aspnet_regiis -i. This upgrades all IIS scriptmaps to use the 2.0 release
version of ASP.NET. After running this command and restarting the server, the
error message should no longer display.

Print failure
PowerScript print functions are not supported in the current CTP release. If
your applications saves or exports DataWindows as PDF or XSL-FO files,
make sure you read the instructions for installing the appropriate printing
software on the Web Form server.
For more information, see “Requirements for saving files in PDF or XSL
format” on page 49.

28 PowerBuilder 11.0 CTP

 CHAPTER 1 Moving PowerBuilder Applications to the Web

Log files
Log.txt A PowerBuilder application that compiles successfully with the
PowerBuilder native compiler might not compile successfully with the
PowerBuilder to .NET compiler. At deployment time, PowerBuilder logs all
compilation errors and warnings into the application’s log.txt file. The
PowerBuilder to .NET compiler is stricter than the PowerBuilder native
compiler, as described in “Best practices for C# and .NET coding” on page 13.
If deployment fails, or if issues occur at runtime, review the errors and
warnings in the log.txt file.
Pbtrace.log At runtime, a Web application logs all exceptions in the
pbtrace.log file located in the applicationName_root\log directory. You can
look into the call stack when an exception is thrown and map the call stack back
to PowerScript code, from which you might find the root cause of any runtime
errors.

Working with PowerBuilder Web Forms 29

CHAPTER 1 Moving PowerBuilder Applications to the Web

30 PowerBuilder 11.0 CTP

CH A PTE R 2 Client-Side Events and Default
Event Handlers

About this chapter This chapter describes the client-side events available to Web Form
applications and the default JavaScript event handlers that post back to the
server.
Contents
Topic Page
About client-side programming 31
Default event handlers 33
Client-side support for the Web DataWindow control 35
Alphabetical list of Web DataWindow client-side events 37

About client-side programming

Using client-side events to The use of client-side events can improve application performance
interrupt default event because they do not require round trips to the server. In most cases, an
handlers
event that is triggered in a PowerBuilder Web Form application calls a
default JavaScript event handler that posts back to the server and triggers
the same event on the server side control. When you code a client-side
event, however, the call to the default JavaScript event handler for that
event is aborted and the round trip to the server can be avoided.
To code for a client-side event at design time, you must enclose an event
handler assignment in a #CLR-#ENDCLR code block in a PowerBuilder
painter Script view. The event handler assignment is a hook into a
JavaScript file that you also assign in a #CLR-#ENDCLR code block.
Although coding for a client-side event normally interrupts postbacks to
the server, you can explicitly code for a postback in your customized
JavaScript event handler by calling Document.Form.Submit or by calling
a default event handler for the triggered event.

Working with PowerBuilder Web Forms 31

About client-side programming

Example code for an The following is an example of a customized, client-side JavaScript event
event handling script handler for the ItemChanged event of a DataWindow. The event handler
determines whether the item changed is in the first or second column of the
DataWindow. If the item is in one of the first two columns, this event handler
calls the default JavaScript event handler that rejects item changes. In this case,
the default event handler does not cause a postback. If the item changed is not
in the first or second column, no client-side action is taken, and the server-side
action is delayed until a postback is triggered by a different event or function
call:
//Start MyScriptFile.js
function MyItemChanged(sender, rowNumber, columnName,
newValue)
{
if(columnName == “column1” || columnName == “column2”)
{
// The default function is invoked
return PBDataWindow_ItemChangedReject(sender,
rowNumber, columnName, newValue)
}
else
{
//do nothing
}
}
//End MyScriptFile.js
The hook into the customized JavaScript event handler is added at design time
in a #CLR-#ENDCLR code block:
#clr
dw_1.JavaScriptFile = “MyScriptFile.js”
dw_1.OnClientItemChanged = “MyItemChanged”
#endclr
Default event handlers The default event handlers for the ItemChanged and ItemError events do not
and postbacks trigger postbacks. If active, the default ItemChanged event handler returns
immediately to reject the entered value or causes the Web Form application to
wait for a cascade of user events to occur before a postback is allowed. The
cascade of events that must occur before a postback is triggered is:
ItemChanged, Clicked, RowFocusChanging, RowFocusChanged, and
ItemFocusChanged.
Some versions of the default Clicked event handler set a timer for postbacks
because the DHTML DoubleClicked event also triggers the Clicked event.

32 PowerBuilder 11.0 CTP

 CHAPTER 2 Client-Side Events and Default Event Handlers

If a DataWindow object’s HTMLGen.PagingMethod property is set to

XMLClient!, postbacks are not called until an Update is issued, since the data
is stored in its entirety in the client browser cache. Also, if the corresponding
server-side event does not contain any script, the default event handlers do not
cause a postback or cause the client-side Web Form to be re-rendered.
For more information on default event handlers, see “Default event handlers”
next.

Default event handlers

Default event handlers for the Web DataWindow control are contained in the
PBDataWindow.js file that deploys with your application to the
applicationName\Scripts directory under the server’s virtual root. The default
event handlers typically cause a postback or delayed postback to the
corresponding server-side event. Default event handlers can call more than one
server-side event, but each default event handler name includes a reference to
the main event that it handles.
The choice of handlers that attach to each event follows the logic described by
Table 2-1. The table also indicates whether the event handler causes a
postback, a delayed postback, or no postback.
If you call a customized client-side event handler, the default event handler
does not get invoked, postbacks are not made to the server, and the
corresponding server-side event does not get triggered. You can explicitly call
a default event handler from a customized event handler if you want to trigger
the corresponding server-side event. When you call a default event handler
directly in a JavaScript function, you must use the same arguments and return
value that you would for the principal client-side event that it handles.
For information on client-side event signatures, see the event descriptions
under “Alphabetical list of Web DataWindow client-side events” on page 37.

Working with PowerBuilder Web Forms 33

Default event handlers

Table 2-1: List of default event handlers by event type

Default JavaScript handler Used under the following conditions
Client-side Event (postback action) for server-side events:
Clicked PBDataWindow_Clicked (postback) Clicked is handled, but DoubleClicked is
not
Clicked and ButtonClicked are handled, but
DoubleClicked is not
Clicked and ButtonClicking is handled, but
DoubleClicked is not
PBDataWindow_DelayedClicked (delayed Clicked and DoubleClicked are handled
postback) Clicked, DoubleClicked, and
ButtonClicked are handled
Clicked, DoubleClicked, and
ButtonClicking are handled
PBDataWindow_ClickedDifferentRow RowFocusChanging is handled, but
(postback) Clicked and DoubleClicked are not
RowFocusChanged is handled, but Clicked
and DoubleClicked are not
PBDataWindow_DelayedClickedDifferent RowFocusChanging and DoubleClicked
Row (delayed postback) are handled, but Clicked is not
RowFocusChanged and DoubleClicked are
handled, but Clicked is not
DoubleClicked PBDataWindow_DoubleClicked DoubleClicked is handled
(postback)
RButtonDown PBDataWindow_RbuttonDown (postback) RButtonDown is handled
ButtonClicked PBDataWindow_ButtonClicked (postback) ButtonClicked is handled and/or
ButtonClicking is handled
ButtonClicking PBDataWindow_ButtonClicking ButtonClicked is handled and/or
(postback) ButtonClicking is handled
ItemFocusChanged PBDataWindow_ItemFocusChanged ItemFocusChanged is handled
(postback)
PBDataWindow_ItemFocusChanged_AN ItemChanged and ItemError are handled,
D_ItemChanged_OR_ItemError (postback) but ItemFocusChanged is not
PBDataWindow_ItemFocusChanged_AN ItemChanged is handled, but
D_ItemChanged (postback) ItemFocusChanged and ItemError are not
PBDataWindow_ItemFocusChanged_AN ItemError is handled, but ItemChanged and
D_ItemError (postback) ItemFocusChanged are not
ItemError PBDataWindow_ItemError (no postback) ItemChanged is handled and/or ItemError is
handled
ItemChanged PBDataWindow_ItemChangedReject (no ItemChanged is handled
postback)

34 PowerBuilder 11.0 CTP

 CHAPTER 2 Client-Side Events and Default Event Handlers

Default JavaScript handler Used under the following conditions

Client-side Event (postback action) for server-side events:
RowFocusChanged PBDataWindow_RowFocusChanged RowFocusChanging is handled, but
(postback) ItemFocusChanged is not
RowFocusChanged is handled, but
ItemFocusChanged is not

Client-side support for the Web DataWindow control

The Web Form version of the DataWindow is a subclass of the
DataWindow.NET Web DataWindow control. The client-side programming
capabilities of the Web DataWindow enable the use of client-side JavaScript
event handlers.
The PBDataWindowDynamicEventHook global property must be set to true to
enable a Web Form application to handle client-side DataWindow events. This
is the default setting.
The ClientEvent properties of the Web DataWindow have also been exposed,
allowing the creation of customized event handlers that can override the default
event handlers in the PBDataWindow.js file. The names of the ClientEvent
properties consist of the name of a client-side event with an “OnClient” prefix.
For example, the ClientEvent property that corresponds to the Clicked event
would be OnClientClicked. You can circumvent the default event handler for
the Clicked event by setting OnClientClicked to the name of a JavaScript
function that uses the client-side Clicked event arguments.
The Web DataWindow client control supports the events listed in Table 2-2.
The signatures of the client-side events and the effects of their return values are
the same as for the Web DataWindow control in DataWindow .NET. For a
description of each event, see “Alphabetical list of Web DataWindow
client-side events” on page 37.
Table 2-2: Web DataWindow control client-side events
Event Arguments Return Codes
ButtonClicked sender, rowNumber, 0 – Continue processing
buttonName
ButtonClicking sender, rowNumber, 0 – Execute action assigned to button,
buttonName then trigger ButtonClicked
1 – Do not execute action or trigger
ButtonClicked

Working with PowerBuilder Web Forms 35

Client-side support for the Web DataWindow control

Event Arguments Return Codes

Clicked sender, rowNumber, 0 – Continue processing
objectName 1 – Prevent focus change
ItemChanged sender, rowNumber, 0 – Accept data value
columnName, 1 – Reject data value and prevent
newValue focus change
2 – Reject data value but allow focus
change
ItemError sender, rowNumber, 0 – Reject data value and show error
columnName, message
newValue 1 – Reject data value with no error
message
2 – Accept data value
3 – Reject data value but allow focus
change
ItemFocusChanged sender, rowNumber, 0 – Continue processing
columnName
RowFocusChanged sender, 0 – Continue processing
newRowNumber
RowFocusChanging sender, 0 – Continue processing
currentRowNumber, 1 – Prevent focus change
newRowNumber

About return values In client events, you can use a return statement as the last statement in the event
for DataWindow script. The datatype of the value is number.
events
For example, in the ItemChanged event, set the return code to 2 to reject an
empty string as a data value:
if (newValue = "") {
return 2;
}
This example prevents focus from changing if the user tries to go back to an
earlier row:
function dwCustomer_RowFocusChanging(sender,
currentRowNumber, newRowNumber)
{
if (newRowNumber < currentRowNumber)
{ return 1; }
}

36 PowerBuilder 11.0 CTP

 CHAPTER 2 Client-Side Events and Default Event Handlers

This example displays a message box informing the user which column and
row number was clicked:
function dwCustomer_Clicked(sender, rowNumber,
objectName)
{
alert ("You clicked the " + objectName +
" column in row " + rowNumber)
}
Note that displaying an Alert message box for all clicked objects in a
DataWindow could prevent data entry or modification.

Alphabetical list of Web DataWindow client-side events

The list of Web DataWindow control client-side events follows in alphabetical
order.
For information on calling client-side scripts, see “About client-side
programming” on page 31.

Working with PowerBuilder Web Forms 37

ButtonClicked

ButtonClicked
Description Occurs when the user clicks a button inside a DataWindow object.
Argument Description
sender String. Identifier for the button the user clicked.
row Number. The number of the current row when the user
clicked the button.
objectName String. The name of the control within the DataWindow
under the pointer when the user clicked.

Applies to Web DataWindow client control

Return codes There are no special outcomes for this event. The only code is:
0 Continue processing
Usage ButtonClicked fires only for buttons with the UserDefined action. Other
buttons cause the page to be reloaded from the server. The ButtonClicked event
executes code after the action assigned to the button has occurred.

Postback calls to the ButtonClicked server-side event

The corresponding server-side event can be triggered by the following default
event handlers: PBDataWindow_ButtonClicked,
PBDataWindow_ButtonClicking, PBDataWindow_Clicked, and
PBDataWindow_DelayedClicked.

This event is fired only if you have not selected Suppress Event Processing for
the button. If Suppress Event Processing is on, only the Clicked event and the
action assigned to the button are executed when the button is clicked.
If Suppress Event Processing is off, the Clicked event and the ButtonClicked
event are fired. If the return code of the ButtonClicking event is 0, the action
assigned to the button is executed and the ButtonClicked event is fired. If the
return code of the ButtonClicking event is 1, neither the action nor the
ButtonClicked event is executed.
See also ButtonClicking

38 PowerBuilder 11.0 CTP

 CHAPTER 2 Client-Side Events and Default Event Handlers

ButtonClicking
Description Occurs when the user clicks a button. This event occurs before the
ButtonClicked event.
Argument Description
sender String. Identifier for the button the user clicked.
row Number. The number of the current row when the user
clicked the button.
objectName String. The name of the control within the DataWindow
under the pointer when the user clicked.

Applies to Web DataWindow client control

Return codes Set the return code to affect the outcome of the event:
0 Execute the action assigned to the button, then trigger the
ButtonClicked event
1 Prevent the action assigned to the button from executing and the
ButtonClicked event from firing
Usage Use the ButtonClicking event to execute code before the action assigned to the
button occurs. If the return code is 0, the action assigned to the button is then
executed and the ButtonClicked event is fired. If the return code is 1, the action
and the ButtonClicked event are inhibited.

Postback calls to the ButtonClicking server-side event

The corresponding server-side event can be triggered by the following default
event handlers: PBDataWindow_ButtonClicked,
PBDataWindow_ButtonClicking, PBDataWindow_Clicked, and
PBDataWindow_DelayedClicked.

This event is fired only if you have not selected Suppress Event Processing for
the button.
The Clicked event is fired before the ButtonClicking event.
See also ButtonClicked

Working with PowerBuilder Web Forms 39

Clicked

Clicked
Description Occurs when the user clicks anywhere in a DataWindow control.
Argument Description
sender Sting. Identifier for the client-side control.
row Number. The number of the row the user clicked.
objectName String. The name of the control within the DataWindow
under the pointer when the user clicked.

Applies to Web DataWindow client control

Return codes Set the return code to affect the outcome of the event:
0 Continue processing
1 Prevent the focus from changing
Usage When the user clicks on a DataWindow button, the Clicked event occurs before
the ButtonClicking event. When the user clicks anywhere else, the Clicked
event occurs when the mouse button is released.

Postback calls to the Clicked server-side event

The corresponding server-side event can be triggered by the following default
event handlers: PBDataWindow_Clicked and
PBDataWindow_DelayedClicked.

Examples This script in an .aspx file submits the value of the selected row in the
DataWindow to the server:
function objdwCustomers_Clicked(sender, rowNumber,
objectName) {
document.Form1.rownum.value = rowNumber;
document.Form1.submit();
}
See also ButtonClicked
ButtonClicking
ItemFocusChanged
RowFocusChanged
RowFocusChanging

40 PowerBuilder 11.0 CTP

 CHAPTER 2 Client-Side Events and Default Event Handlers

ItemChanged
Description Occurs when a field in a DataWindow control has been modified and loses
focus (for example, the user presses Enter, the Tab key, or an arrow key or
clicks the mouse on another field within the DataWindow). It occurs before the
change is applied to the item. ItemChanged can also occur when the Update
function is called.
Argument Description
sender String. Identifier for the client-side control.
row Number. The number of the row containing the item whose
value is being changed.
columnName String. The name of the column containing the item.
newValue String. The new data the user has specified for the item.

Applies to Web DataWindow client control

Return codes Set the return code to affect the outcome of the event:
0 (Default) Accept the data value
1 Reject the data value and do not allow focus to change
2 Reject the data value but allow the focus to change
Usage The ItemChanged event does not occur when the DataWindow control itself
loses focus.

Postback calls to the server-side ItemChanged event

The corresponding server-side event is triggered by default event handlers only
after a cascade of events occurs: ItemChanged, Clicked, RowFocusChanging,
RowFocusChanged, and ItemFocusChanged. Default postback scripts for this
event are PBDataWindow_ItemFocusChanged_AND_ItemChanged and
PBDataWindow_ItemFocusChanged_AND_ItemChanged_OR_ItemError.
The default event handler PBDataWindow_ItemChangedReject does not cause
a postback, but instead rejects the changed value entered by the user.

See also ItemError

Working with PowerBuilder Web Forms 41

ItemError

ItemError
Description Occurs when a field has been modified, the field loses focus (for example, the
user presses Enter, Tab, or an arrow key or clicks the mouse on another field in
the DataWindow), and the data in the field does not pass the validation rules
for its column.
Argument Description
sender String. Identifier for the client-side control.
row Number. The number of the row containing the item whose
new value has failed validation.
columnName String. The name of the column containing the item.
newValue String. The new data the user has specified for the item.

Applies to Web DataWindow client control

Return codes Set the return code to affect the outcome of the event:
0 (Default) Reject the data value and show an error message box
1 Reject the data value with no message box
2 Accept the data value
3 Reject the data value but allow focus to change
Usage If the Return code is 0 or 1 (rejecting the data), the field with the incorrect data
regains the focus.
The ItemError event occurs instead of the ItemChanged event when the new
data value fails a validation rule. You can force the ItemError event to occur by
rejecting the value in the ItemChanged event.

Postback calls to the server-side ItemError event

Default postback scripts for this event are called only after an
ItemFocusChanged event occurs on the client side. The default event handlers
that invoke the server-side ItemError event are
PBDataWindow_ItemFocusChanged_AND_ItemError and
PBDataWindow_ItemFocusChanged_AND_ItemChanged_OR_ItemError.
The default event handler PBDataWindow_ItemError does not cause a
postback, but instead rejects the value entered by the user.

Examples This script in the .aspx file displays an alert message:

function objwdw_ItemError(sender, rowNumber,
columnName, newValue) {
alert("ItemError: " + rowNumber + columnName +
newValue);
}

42 PowerBuilder 11.0 CTP

 CHAPTER 2 Client-Side Events and Default Event Handlers

See also ItemChanged

ItemFocusChanged
Description Occurs when the current item in the control changes.
Argument Description
sender String. Identifier for the client-side control.
row Number. The number of the row containing the item that has just
gained focus.
columnName String. The name of the column containing the item.

Applies to Web DataWindow client control

Return codes There are no special outcomes for this event. The only code is:
0 Continue processing
Usage ItemFocusChanged occurs when focus is set to another column in the
DataWindow, including when the DataWindow is first displayed.
The row and column together uniquely identify an item in the DataWindow.

Postback calls to the server-side ItemFocusChanged event

The corresponding server-side event can be triggered by the following event
handler: PBDataWindow_ItemFocusChanged.

See also RowFocusChanged

RowFocusChanging

Working with PowerBuilder Web Forms 43

RowFocusChanged

RowFocusChanged
Description Occurs when the current row changes in the DataWindow.
Argument Description
sender String. Identifier for the client-side control.
newRow Number. The number of the row that has just become
current.

Applies to Web DataWindow client control

Return codes There are no special outcomes for this event. The only code is:
0 Continue processing
Usage The SetRow function, as well as user actions, can trigger the
RowFocusChanged and ItemFocusChanged events.

Postback calls to the server-side RowFocusChanged event

The corresponding server-side event can be triggered by the following default
event handlers: PBDataWindow_RowFocusChanged,
PBDataWindow_ClickedDifferentRow, and
PBDataWindow_DelayedClickedDifferentRow.

Examples This script in the .aspx file displays an alert message when the row focus
changes:
function objdw_RowFocusChanged(sender, newRowNumber) {
alert("Focus changed to row” " + newRowNumber);
}
See also ItemFocusChanged
RowFocusChanging

44 PowerBuilder 11.0 CTP

 CHAPTER 2 Client-Side Events and Default Event Handlers

RowFocusChanging
Description Occurs when the current row is about to change in the DataWindow. (The
current row of the DataWindow is not necessarily the same as the current row
in the database.)
The RowFocusChanging event occurs just before the RowFocusChanged
event.
Argument Description
sender String. Identifier for the client-side control.
currentRow Number. The number of the row that is current (before the
row is deleted or its number changes). If the DataWindow
object is empty, currentrow is 0 to indicate there is no current
row.
newRow Number. The number of the row that is about to become
current. If the new row is going to be an inserted row,
newrow is 0 to indicate that it does not yet exist.

Applies to Web DataWindow client control

Return codes Set the return code to affect the outcome of the event:
0 Continue processing (setting the current row)
1 Prevent the current row from changing
Usage Typically the RowFocusChanging event is coded to respond to a mouse click
or keyboard action that would change the current row in the DataWindow
object.

Postback calls to the server-side RowFocusChanging event

The corresponding server-side event can be triggered by the following default
event handlers: PBDataWindow_RowFocusChanged,
PBDataWindow_ClickedDifferentRow, and
PBDataWindow_DelayedClickedDifferentRow.

See also ItemFocusChanged

RowFocusChanged

Working with PowerBuilder Web Forms 45

RowFocusChanging

46 PowerBuilder 11.0 CTP

CH A PTE R 3 Print, File, Mail, and Registry
Operations in Web Forms

About this chapter This chapter describes the print, mail profile, and file managers that you
can use with a PowerBuilder .NET Web Form application.
Contents
Topic Page
Using the Web Form Print Manager 47
Using the Web Form File Manager 52
Using the Web Form Mail Profile Manager 58
Using the registry functions 61

Using the Web Form Print Manager

In Web Form applications, output from supported PowerScript print
functions is published as PDF files on the server side. These PDF files are
visible in the client-side Web browser through links in the Web Form Print
Manager, and they can be printed on the client side.

Print function support

The following system print functions are supported in .NET Web Form
applications: Print, PrintCancel, PrintClose, PrintDefineFontDefine,
PrintLine, PrintOpen, PrintOval, PrintPage, PrintRect, PrintRoundRect,
PrintSetSpacing, PrintText, PrintWidth, PrintX, PrintY. PrintSetFont is also
supported, but its return value is not the same as in a PowerBuilder native
application.

You can also use the PowerScript SaveAs method to print DataWindows
and their data as PDF or XSL files. These files are not visible in the Web
Form Print Manager and cannot be printed on the client side without the
intervention of the IIS administrator.

Working with PowerBuilder Web Forms 47

Using the Web Form Print Manager

Print Manager icon display

When supported print functions are used to print text in a Web Form
application, a printer icon displays in the right-bottom corner of the main
browser window. The application user can double-click the icon to open the
Web Form application Print Manager. The Print Manager lets the application
user open a window to view the printed output as PDF files.
Figure 3-1 shows the Print Manager with hyperlinks to two printed files.
Figure 3-1: Print Manager for a Web Form application

The Print Manager icon automatically disappears on browser refresh after all
the printed files are removed from the Print Manager window.

Where printed output is saved

Printed output is saved to files in the applicationName_root\Print\SessionID
directory under the virtual root for IIS Web sites. The
applicationName_root\Print\ directory is created when you deploy your
application. The SessionID directory is created by the ASP.NET runtime
engine after a PrintOpen call.

48 PowerBuilder 11.0 CTP

 CHAPTER 3 Print, File, Mail, and Registry Operations in Web Forms

The SessionID directory created under the Print directory uses the same session
ID number as the subdirectory created under the applicationName_root\File
directory when the user saves a DataWindow as a PDF or writes to a file from
the current application session, or when the PBWebFileProcessMode global
property has been set to Copy mode. The actual SessionID directory name is a
long 24-character string with letters and numbers such as
cdxgel554rkxxsbn1221uh55. The SessionID directories are deleted when the
Web Form session is ended.

Requirements for saving files in PDF or XSL format

The default PDF printing feature uses the Sybase DataWindow PS printer to
print output to a postscript (PS) file, and then convert it to a PDF file format.
Alternatively, you could use the Apache Formatting Objects (FO) processor to
save a DataWindow and its data in the PDF or XSL-FO format.
PostScript printing The Sybase DataWindow PS printer profile is added automatically to a
method computer’s printer list when you save a DataWindow to a PDF file from a
PowerBuilder application. This does not occur automatically with a Web Form
application, however Web Form users can use the Sybase DataWindow PS
printer that you create on the server computer from a standard client-server
application at design-time or runtime.
You can also add the Sybase DataWindow PS profile manually to the server
computer using the Windows Add Printer wizard. In the wizard, click the Have
Disk button and browse to the Adist5.inf file installed in the
Shared\PowerBuilder\drivers directory, or to another PostScript driver file.
To enable PDF printing from a Web Form application using the postscript
processing method, you must also install GNU Ghostscript on the IIS server
computer.
For more information about installing Ghostscript, see “Installing GNU
Ghostscript” next.
Apache FO If a Web Form application uses the Apache processor to save a DataWindow
processing method and its data in PDF or XSL-FO format, you must include the fop-0.20.4
(Apache processor) directory and the Java Runtime Environment (JRE) on the
server computer.

Working with PowerBuilder Web Forms 49

Using the Web Form Print Manager

The processor directory and the JRE must be in the same path as the
PowerBuilder runtime files. For example, if pbvm110.dll and the other
PowerBuilder runtime files are included in a server computer directory called
ServerPB, the Apache processor and the JRE must be copied to
ServerPB/fop-0.20.4 and ServerPB/jre. However, you do not need to place a
copy of the JRE in this location if the full JDK is installed on the server
computer and is in its classpath.
The following JAR files must be in the server computer’s classpath:
• fop-0.20.4\build\fop.jar
• fop-0.20.4\lib\batik.jar
• fop-0.20.4\lib\xalan-2.3.1.jar
• fop-0.20.4\lib\xercesImpl-2.1.0.jar
• fop-0.20.4\lib\xml-apis.jar
• fop-0.20.4\lib\avalon-framework-cvs-20020315.jar

DBCS platforms
If the Web Form server computer is a DBCS platform, you also need to include
a file that supports DBCS characters in the Windows font directory, for
example, C:\WINDOWS\fonts. For more information about configuring fonts,
see the Apache Web site at http://xml.apache.org/fop/fonts.html.

Installing GNU Ghostscript

To enable Web Form users save data in the PDF format using the postscript
processing method, you must download and install GNU Ghostscript on the IIS
server computer as described in the procedure that follows. Ghostscript is not
required on the client for Web Form applications.
The use of GNU Ghostscript is subject to the terms and conditions of the GNU
General Public License (GPL). A copy of the GPL is available on the GNU
Project Web server at http://www.gnu.org/licenses/gpl.html.

❖ To install GNU Ghostscript:

1 Download the self-extracting executable file for the Ghostscript version
you want from one of the mirrored sites listed on the Ghostscript Web site
at http://www.ghostscript.com/doc/GPL.

2 Run the executable file to install Ghostscript on the server computer.

50 PowerBuilder 11.0 CTP

 CHAPTER 3 Print, File, Mail, and Registry Operations in Web Forms

The default installation directory is C:\program files\gs. You can select a

different directory and/or choose to install shortcuts to the Ghostscript
console and readme file.
Location of files When a Web Form application user saves a DataWindow
object as a PDF, the Web Form server searches in the following locations for
an installation of GNU Ghostscript:
• The Windows registry
• The relative path of the pbdwe110.dll file (typically in the
Sybase\Shared\PowerBuilder directory)
• The system PATH environment variable
If GNU Ghostscript is installed using the Ghostscript executable file, the path
is added to the Windows registry.
If the Ghostscript files are in the relative path of the pbdwe110.dll file, they
must be installed in this directory structure:
dirname\pbdwe110.dll
dirname\gs\gsN.NN
dirname\gs\fonts
where dirname is the directory that contains the runtime DLLs and N.NN
represents the release version number for Ghostscript.
For information about fonts supplied with Ghostscript, see the APFL
Ghostscript Web site at http://www.ghostscript.com/doc/gnu/7.05/Fonts.htm.

You must also make sure the default PostScript printer driver and related files
in Sybase\Shared\PowerBuilder\drivers are included in the IIS server path.

Where PDF and XSL-FO output is saved

If a full path is not provided in the SaveAs command, the PDF and XSL-FO
files that users generate from Web Form DataWindow objects are saved by
default in the virtual root path for IIS Web sites under the
applicationName_root\File\SessionID\currentInitialDirectory directory,
where currentInitialDirectory is a directory that you assign at design time for
the Web Form application.

Working with PowerBuilder Web Forms 51

Using the Web Form File Manager

IIS server administrator role

The IIS server administrator can change the default current initial directory by
modifying the PBCurrentDirectory global property in the ASP.NET
Configuration Settings dialog box or in the Web.Config file for the Web Form
application.

Using the Web Form File Manager

Virtual file system When you deploy a PowerBuilder application as a .NET Web Form
application, PowerBuilder creates a virtual file system that Web Form users can
access from client-side Web browsers. The virtual file system is maintained on
the server. Application users can read from and write to files in the virtual file
system as long as user permissions for file operations are not restricted.
The virtual file system for a PowerBuilder .NET Web Form application is
contained in the applicationName_root\File\Common directory under the
virtual root of the IIS server, where applicationName is the name of the current
Web Form application.
Subdirectories of the Common directory store read-only files that are shared by
all users of a Web Form application. PowerBuilder creates these subdirectories
at deployment time. A top-level subdirectory is created for each development
computer drive containing a file deployed with the PowerBuilder application.
The entire path to each application file is mirrored in the virtual file system to
reflect the path to the application files on the desktop file system. The name of
each top-level subdirectory in the virtual file system consists only of a drive
letter that mirrors the desktop drive from where an application file was copied.
Figure 3-2 shows the Common directory and its subdirectories for the
FilmCatalog Web Form application. It also shows a SessionID subdirectory
with a single subdirectory where a PDF file was written in Share mode. At
runtime, the Web Form application creates a SessionID folder in the File
directory for each user for storing files uploaded or created by that user. The
exact name of the SessionID directory is generated by the ASP.NET runtime
engine.

52 PowerBuilder 11.0 CTP

 CHAPTER 3 Print, File, Mail, and Registry Operations in Web Forms

Figure 3-2: Virtual file system under the IIS root directory

File process mode There are two file process modes: Share mode and Copy mode. The
PBWebFileProcessMode global property defines the mode for the current Web
Form application. It is set to Share mode by default.
Share mode: Files are copied from the Common directory to the SessionID
directory only as needed.
Copy mode: In Copy mode, the first time a file operation is called, all folders
and files under the Common directory are copied to the SessionID directory. In
Copy mode, all file operations are handled in subdirectories of the SessionID
directory.
The File Manager presents a merged view of the files under the Common and
SessionID directories. If a read-only file in the Common directory has the same
name as a read-write file in the SessionID directory, only the SessionID file is
displayed.

Working with PowerBuilder Web Forms 53

Using the Web Form File Manager

Although users can delete and move folders or files that they create under the
SessionID directory, files and folders that are copied from the Common
directory to the SessionID directory cannot be deleted because the File
Manager presents a merged view of these virtual file paths, and removing a file
or folder from the SessionID directory does not cause its removal from the
Common directory.
The common dialog boxes for all file operations are supported regardless of
file process mode. You can display these dialog boxes with the
GetOpenFileName, GetSaveFileName and GetFolder functions.
Using the File Users can open the File Manager only if you choose to render the File Manager
Manager icon in your Web Form applications. Although you can choose to render the
File Manager icon at design time, you can change your selection after
deployment by modifying the application’s PBFileManager global property.
The File Manager icon displays in the upper right corner of the Web Form, just
to the right of the Mail Profile Manager icon when that icon is also rendered.
The File Manager opens in the current browser window when a user clicks the
File Manager icon.
Figure 3-3 shows the File Manager for a Web Form application.

54 PowerBuilder 11.0 CTP

 CHAPTER 3 Print, File, Mail, and Registry Operations in Web Forms

Figure 3-3: File Manager displaying an uploaded text file

Creating a directory The File Manager allows users to create directories, rename and delete selected
files or directories, and to upload and download selected files. It allows users
to view all files in the virtual file system for the Web Form application—unless
those files are located in a directory or subdirectory listed in the
PBDenyDownloadFolders global property.

❖ To create a folder using the File Manager

1 Select the directory in the left pane under which you want to create a
folder.
2 Type the name you want for the new folder in the New text box.
3 Click Create Folder.

Working with PowerBuilder Web Forms 55

Using the Web Form File Manager

The new directory is created in the SessionID path under the directory you
selected in Step 1. No other application user can use the Web Form File
Manager to see the new directory. When you leave the current session, the
directory and any files you uploaded to it are removed.

Renaming and deleting a directory

You can rename a directory by selecting it in the left pane, entering a new
name in the New text box, and clicking Rename Folder. You delete a
directory by selecting it in the left pane and clicking Delete Folder.
You cannot rename or delete a directory if it was not created in the current
Web Form session. The Rename Folder and Delete Folder buttons are
disabled when a directory under the Common path of the virtual file
directory is selected in the left pane of the File Manager.

Closing the File Users can close the File Manager and return to the current Web Form window
Manager by selecting Frame from the Windows drop-down menu that displays in the
upper right corner of the manager frame. The close (x) button at the upper right
corner of the manager frame also has the same effect. This is a separate close
button from the one in the browser title bar. (The close button in the browser
title bar closes the browser and ends the current Web Form session.)
Figure 3-4 displays the Frame Manager’s drop-down menu.
Figure 3-4: Drop-down menu in the Frame Manager

Uploading files The files that a user uploads through the Web Form File Manager are saved
under the SessionID path. The uploaded files are copied from the client-side
computer. They are deleted from the server-side SessionID path at the end of
the Web Form session.
Figure 3-5 shows the PowerBuilder Upload File dialog box for a Web Form
application.

56 PowerBuilder 11.0 CTP

 CHAPTER 3 Print, File, Mail, and Registry Operations in Web Forms

Figure 3-5: Upload dialog box

❖ To upload a file using the File Manager:

1 Select the directory in the left pane of the File Manager where you want to
copy a file.
The Upload File link displays to the right of the New text box after you
select a directory for the file you want to upload.
2 Click the Upload File link.
The PowerBuilder Upload File dialog box displays.
3 Type the file name or browse to the file you want to upload.
4 Click Upload.
A message displays in the dialog box to indicate whether the upload is
successful.
5 Click Close & Refresh to close the dialog box and refresh the file listings
in the right pane of the File Manager.
Downloading a file Users can download any file listed in the right pane of the File Manager. The
files are downloaded to the client-side computer from either the SessionID or
Common path on the server. (The actual server path is never displayed in the
virtual file directory.)

❖ To download a file using the File Manager

1 Select the file you want to download from the right pane of the File
Manager.
The Download File link displays near the bottom right corner of the File
Manager, just above the Upload File link.

Working with PowerBuilder Web Forms 57

Using the Web Form Mail Profile Manager

2 Click Download File.

The File Download dialog box lists the file name and file type and the
name of the server from which the file can be downloaded. It prompts you
to save the file or cancel the download. (On some operating systems, the
File Download dialog box can also include Open and More Info buttons.)
3 Click Save.
The Save As dialog box displays.
4 Browse to the path on the local computer where you want to save the file
and click Save.
The Download Complete dialog box displays. Its appearance depends on
the client operating system. It typically prompts you to open the
downloaded file, open the folder where you saved the file, or close the
dialog box.
5 Click Close to close the Download Complete dialog box and return to the
File Manager.

Using the Web Form Mail Profile Manager

Sending and receiving If you do not include a user ID and password in the optional arguments of the
mail MailLogon call for a MailSession object, a dialog box displays prompting the
application user for these mail server login parameters. When the user ID and
password from this dialog box do not match the user ID and password from an
existing server-side mail profile, the Web Form Mail Profile Manager displays.
(The Mail Profile Manager also displays when the MailLogon call includes user
ID and password arguments that do not match the user ID and password from
an existing server-side mail profile.)
The Mail Profile Manager creates server-side mail profiles that include user
IDs, passwords, outgoing mail server information, and incoming mail server
information.
Modifications required MailLogon You cannot use client-side mail profiles in a Web Form
for Web Form application MailLogon call, although you can include a user ID and password in
applications
the optional arguments for this method. The only login option supported is
mailNewSession!. The mailDownload! and mailNewSessionWithDownload!
options cannot be used with a Web Form application.

58 PowerBuilder 11.0 CTP

 CHAPTER 3 Print, File, Mail, and Registry Operations in Web Forms

MailSend For a standard PowerBuilder client-server application, you can use

a MailSend call without arguments to open a new message window in the
client’s default mail application. Because you cannot do this from a Web Form
application, you can use a MailSend call only if you include a mailmessage
argument. The properties of the MailMessage object include the text, subject
line, and recipient information for the message that the application user sends.
Unsupported mail functions The MailResolveRecipient,
MailRecipientDetails, and MailSaveMessage functions are not supported int he
current CTP release.
Using the Mail Profile Users can open the Mail Profile Manager at any time from a Web Form
Manager application when you choose to render the Mail Manager icon for that
application. Although you can choose to render the Mail Manager icon at
design time, the IIS server administrator can change your selection after
deployment by modifying the application’s PBMailManager global property.
The Mail Manager icon displays in the upper right corner of the Web Form, just
to the left of the File Manager icon when that icon is also rendered. The Mail
Profile Manager opens in the current browser window when a user clicks the
Mail Manager icon.
Figure 3-6 shows the Mail Profile Manager for a Web Form application.
Figure 3-6: Mail Profile Manager for Web Form applications

Working with PowerBuilder Web Forms 59

Using the Web Form Mail Profile Manager

The Mail Profile Manager is divided into sections for user profile information,
outgoing mail parameters, incoming mail parameters, and account type.
Information that the application user enters in the Mail Profile Manager can be
saved in a profile that is available to the Web Form application.
Table 3-1 lists and describes the fields in the Web Form Mail Profile Manager.
Table 3-1: Mail Profile Manager fields
Section Field Description
User Profile Name Display name for the user.
User ID Alias used to log onto the e-mail server.
E-mail address E-mail address the Web Form user wants to use.
Password Password for the user ID. The password a user
enters is encoded using an MD5 algorithm.
Outgoing Mail Server address Address for the outgoing mail server, such as
smtp.sybase.com.
Port The default outgoing mail port is 25.
Requires Select this check box if the outgoing mail server
authentication requires authentication or a certificate file.
Requires SSL Select this check box if the outgoing mail
requires a secure sockets layer connection.
Incoming Mail Server type Select POP3 or IMAP for the incoming server
type. POP3 is the default.
Server address Address for the incoming mail server, such as
pop3.sybase.com.
Port The default incoming mail port is 110.
Requires SSL Select this check box if the incoming mail
requires a secure sockets layer connection.
Account Type Permanent Select this radio button to keep the mail profile
across Web Form sessions.
Temporary Select this radio button to delete the mail profile
when the current Web Form session is
terminated.

After entering all the Mail Profile Manager fields, the user should click Create
Profile to save the entries to a profile file in the applicationName_root\Mail
virtual file directory.

60 PowerBuilder 11.0 CTP

 CHAPTER 3 Print, File, Mail, and Registry Operations in Web Forms

Using the registry functions

Searching and setting PowerBuilder Web Form applications can read registry entries at the server
registry entries side and can write registry entries to a registry.xml file.
The RegistryGet, RegistryKeys, or RegistryValues calls can search the server
registry for registry entries if a registry.xml file does not exist in the
applicationName/File/SessionID directory under the IIS virtual root, where
applicationName is the name of the application and SessionID is the current
session identifier. The registry search functions also search the server registry
when the registry.xml file exists but the entries you are searching for are not
contained in the current session’s registry.xml file.
The RegistrySet function creates the registry.xml file—if one does not already
exist—in the applicationName/File/SessionID directory for the current Web
Form session. If a registry.xml file already exists, the arguments of the
RegistrySet function are added to the contents of the existing registry.xml file.
The RegistrySet function can also copy a registry.xml file from
applicationName/File/Common to applicationName/File/SessionID, but it
writes to the registry.xml file in the SessionID directory only.
Rules for registry The following rules obtain for registry search and setting operations:
searching and setting
• Searches for registry entries, keys, or values are conducted first in the
registry.xml file. The search uses the server registry only if the registry
entry, key, or value cannot be found in the registry.xml file.
• Application users can set or write registry entries only in the registry.xml
file in the applicationName/File/SessionID folder for the current session.
• Application users can delete registry keys or values only from the
registry.xml file in the sessionID folder for the current session.
Adding a registry.xml The IIS server administrator can add a registry.xml file to the
file applicationName_root\File\Common directory under the virtual root for IIS
Web sites. If the Web Form application searches for a registry entry, key, or
value, the registry.xml file is copied to the applicationName/File/SessionID
folder for the current session.
The following is sample content of a registry.xml file:
<?xml version="1.0"?>
<RegistryRoot>
<k name="HKEY_LOCAL_MACHINE">
<k name="Software">
<k name="MyApp">
<k name="Fonts">
<v name="Title">MyTrueType</v>

Working with PowerBuilder Web Forms 61

Using the registry functions

</k>
</k>
</k>
</k>
</RegistryRoot>
The first time the registry function is called, the system copies registry.xml
from the Common directory to the SessionID directory; after that, the system
uses the registry.xml copy under the SessionID directory.

62 PowerBuilder 11.0 CTP

CH A PTE R 4 Unsupported Features in
PowerBuilder Web Forms

About this chapter In this PowerBuilder 11.0 Community Technology Preview release, you
can use the .NET Web Form Application wizard to deploy PowerBuilder
applications that are suitable for use as Web applications to ASP.NET 2.0.
This chapter lists features of PowerBuilder and PowerScript that are not
supported in the current release.
Contents
Topic Page
About unsupported features 63
Unsupported nonvisual objects 64
Unsupported system functions 65
Restrictions on supported controls 66
Unsupported functions 73
Unsupported events 76
Unsupported properties 77

About unsupported features

When you deploy a PowerBuilder application as a Web Form application
to an IIS server, PowerBuilder lists any unsupported features in the Output
window. For the most part, unsupported features just fail silently in the
Web Form application, but unexpected results can also occur. A few
unsupported features, such as rich text edit controls, can prevent the
PowerBuilder to .NET compiler from compiling your application. In this
case, the failure and its cause are noted in the Output window in
PowerBuilder.
DataWindow support Currently all DataWindow presentation styles
are supported except RichText, OLE, and TreeView. All DataWindow
dialog boxes (Specify Retrieval Arguments, Specify Retrieval Criteria,
Import File, Save As, Print, Sort, Filter, and Crosstab) are supported, as
are all built-in functions for DataWindow expressions.

Working with PowerBuilder Web Forms 63

Unsupported nonvisual objects

The Web DataWindow control uses a simplified version of DataWindow

pagination rules, and provides a choice of page navigation bars instead of scroll
bars to support page navigation. It also renders buttons to accommodate drag-
and-drop actions that cannot be used in the Web browser.
Although the current CTP release does not support the PrintDataWindow or
PrintScreen print functions, users can save DataWindow objects and their data
as PDF files, and can print the current Web Form page using a browser’s print
menu when those are available. (Browser menus are available only when the
default.aspx page name is included in the URL used to start the Web Form
application.)

Unsupported nonvisual objects

The nonvisual objects listed in Table 4-1 cannot be used in applications
deployed to ASP.NET.
Table 4-1: Unsupported nonvisual objects
Category Objects
ClassDefinition ArrayBounds
ClassDefinition
ClassDefinitionObject
EnumerationDefinition
EnumerationItemDefinition
ScriptDefinition
SimpleTypeDefinition
TypeDefinition
VariableCardinalityDefinition
VariableDefinition
Profiling and tracing ProfileCall
ProfileClass
ProfileLine
ProfileRoutine
Profiling
TraceFile
TraceTree
TraceTreeNode and descendants
TraceActivityNode and descendants

64 PowerBuilder 11.0 CTP

 CHAPTER 4 Unsupported Features in PowerBuilder Web Forms

Category Objects
OLE OleStorage
OleStream
OmStorage
OmStream
EAServer integration RemoteObject

Unsupported system functions

Table 4-2 lists categories of system functions that are not supported or are
deferred until a future release:
Table 4-2: Unsupported system functions by category
Category Functions
Clipboard functions Clipboard, also any object function that
uses the clipboard, such as Copy, Paste,
Clear, and so on
DDE functions CloseChannel, ExecRemote,
GetCommandDDE,
GetCommandDDEOrigin, GetDataDDE,
GetDataDDEOrigin, GetRemote,
OpenChannel, RespondRemote,
SetDataDDE, SetRemote, StartHotLink,
StartServerDDE, StopHotLink,
StopServerDDE
Debugging functions DebugBreak
Garbage collection functions GarbageCollect,
GarbageCollectGetTimeLimit,
GarbageCollectSetTimeLimit
Help functions ShowHelp, ShowPopupHelp
Input method functions IMEGetCompositionText, IMEGetMode,
IMESetMode
Messaging functions Post, Send
Miscellaneous functions DoScript, DraggedObject, Handle, Run,
Restart, Timer
Print functions PrintBitmap, PrintDataWindow,
PrintScreen, PrintSend, PrintSetPrinter,
PrintSetup, PrintSetupPrinter

Working with PowerBuilder Web Forms 65

Restrictions on supported controls

Category Functions
Profiling and tracing functions TraceBegin, TraceClose,
TraceDisableActivity, TraceDump,
TraceEnableActivity, TraceEnd,
TraceError, TraceOpen, TraceUser
Reflection functions FindClassDefinition,
FindFunctionDefinition,
FindTypeDefinition

System registry functions can read and write registry entries, keys, and values
on the server side, but do not perform these operations on the server computer’s
registry in the same way as they do on a client computer’s registry in a standard
PowerBuilder application.
For more information on system registry functions, see “Using the registry
functions” on page 61.

Restrictions on supported controls

Almost all PowerBuilder controls are supported in .NET Web Form
applications, however some of the methods and properties on supported
controls will not work in Web Form applications. Table 4-3 lists functions,
events, and properties that are not supported on any control.
Table 4-3: Unsupported functions, events, and properties
Category Unsupported feature
Control Functions Cut, Copy, Paste
CanUndo, Undo
Drag
Print (supported for DataWindows and DataStores)
SetActionCode
SetPosition
SetRedraw

66 PowerBuilder 11.0 CTP

 CHAPTER 4 Unsupported Features in PowerBuilder Web Forms

Category Unsupported feature

Events Drag and drop events
GetFocus, LoseFocus events
Help event
MouseMove event
Other event
Hot keys, shortcut keys, and accelerator keys
Properties Accelerator
AccessibleDescription
AccessibleName
AccessibleRole
BringToTop
DragAuto
DragIcon
IMEMode
Pointer (for most controls)

Table 4-4 lists the functions, events, and properties that are not supported on
some individual controls. Table 4-4 does not include the items listed in Table
4-3. The entry “No additional” in Table 4-4 indicates that all items except those
listed in Table 4-3 are supported for that control.
Table 4-4: Unsupported functions, events, and properties by control
Supported control Unsupported functions Unsupported events Unsupported properties
Animation Seek No additional OriginalSize
CommandButton SetFocus No additional No additional
CheckBox SetFocus No additional No additional
DataStore Same as DataWindow No additional No additional

Working with PowerBuilder Web Forms 67

Restrictions on supported controls

Supported control Unsupported functions Unsupported events Unsupported properties

DataWindow CanUndo, Undo DragDrop ControlMenu
Collapse functions DragEnter HSplitScroll, LiveScroll
CopyRTF, PasteRTF DragLeave Icon
Cut, Clear, Copy, Paste DragWithin MaxBox, MinBox
DBErrorCode EditChanged Resizable
DBErrorMessage GetFocus RightToLeft
Drag Help Title, TitleBar
Expand functions LoseFocus
FindNext Other
GenerateHTMLForm ScrollHorizontal
GenerateResultSet ScrollVertical
GetMessageText
GetMessageStatus
GetStateStatus
GetUpdateStatus
ImportClipboard
InsertDocument
IsExpanded
LineCount
OLEActivate
Position
PrintCancel
ReplaceText
ResetInk
SaveInk functions
Scroll
Selected functions
SelectText functions
SetActionCode
SetDetailHeight
SetFocus
SetRedraw
ShowHeadFoot
TextLine
DataWindowChild Same as DataWindow Has no events No additional
DatePicker GetCalendar Clicked AllowEdit
CloseUp DropDownRight
DropDown RightToLeft
DoubleClicked ShowUpDown
UserString TodayCircle
ValueChanged TodaySection
WeekNumbers

68 PowerBuilder 11.0 CTP

 CHAPTER 4 Unsupported Features in PowerBuilder Web Forms

Supported control Unsupported functions Unsupported events Unsupported properties

DropDownListBox, Position DoubleClicked AllowEdit
DropDownPictureList ReplaceText AutoHScroll
Box SelectedLength HScrollBar
SelectedStart Limit
SelectedText RightToLeft
SelectText ShowList
EditMask LineCount No additional AutoHScroll
LineLength AutoSkip
ReplaceText AutoVScroll
Scroll CalendarBackColor
SelectedLength CalendarTextColor
SelectedStart CalendarTitleBackColor
SelectedText CalendarTitleTextColor
SelectText CalendarTrailingTextColor
TextLine DisplayData
HScrollBar
HideSelection
IgnoreDefaultButton
Increment
Limit
MinMax
RightToLeft
Spin
TabStop
UseCodeTable
VScrollbar
Graph (For AddData, No additional No additional
GetDataValue,
InsertData, ModifyData,
string values only—
other datatypes
supported.)
Clipboard
ImportClipboard
ImportFile
SaveAs
SetFocus
GroupBox No additional No additional No additional
HProgressBar No additional DoubleClicked No additional
RButtonDown
HScrollBar No additional RButtonDown No additional

Working with PowerBuilder Web Forms 69

Restrictions on supported controls

Supported control Unsupported functions Unsupported events Unsupported properties

HTrackBar SelectionRange RButtonDown LineSize
SliderSize
TickFrequency
TickMarks
ListBox SetTop DoubleClicked DisableNoScroll
Top ExtendedSelect
RightToLeft
TabStop
ListView Arrange BeginDrag AutoArrange
EditLabel BeginLabelEdit ButtonHeader
GetItemAtPointer BeginRightDrag DeleteItems
GetOrigin DeleteAllItems ExtendedSelect
SetOverlayPicture EndLabelEdit FixedLocations
ItemActivate GridLines
RightClicked HeaderDragDrop
RightDoubleClicked HideSelection
Sort LabelWrap
LargePictureMaskColor
LayoutRTL
OneClickActivate
RightToLeft
ShowHeader
SmallPictureMaskColor
StatePictureMaskColor
TrackSelect
TwoClickActivate
UnderlineCold
UnderlineHot
ListViewItem No additional No additional CutHighlighted
DropHighlighted
ItemX
ItemY
MailRecipient No additional No additional EntryID
MailSession MailHandle No additional No additional
mailRecipientDetails
MailResolveRecipient
MailSaveMessage
MailSend (without a
parameter—you must
use MailSend with a
mailMessage argument)

70 PowerBuilder 11.0 CTP

 CHAPTER 4 Unsupported Features in PowerBuilder Web Forms

Supported control Unsupported functions Unsupported events Unsupported properties

Menu No additional Selected (If you set the BitmapBackColor
AutoTriggerMenuSele BitmapGradient
ctedEvents global MenuAnimation
property to true, the MenuBitmaps
Selected event is MenuImage
supported for simple MenuTitles
tasks that can be run MenuTitleText
prior to the rendering MergeOption
of the Web Form in a MicroHelp
client browser) TitleBackColor
TitleGradient
ToolbarAnimation
ToolbarItemDown
ToolbarItemDownName
ToolbarItemSpace
MonthCalendar NoAdditional Clicked AutoSize
DoubleClicked ScrollRate
TodayCircle
TodaySection
WeekNumbers
MultiLineEdit LineCount RButtonDown AutoHScroll
LineLength AutoVScroll
Position HideSelection
Scroll TabStop
SelectedLine
SelectedStart
TextLine
Picture No additional No additional FocusRectangle
Invert
Map3DColors
PictureButton No additional No additional FlatStyle
Map3DColors
PictureHyperLink No additional No additional FocusRectangle
Invert
Map3DColors
PictureListBox SetTop DoubleClicked DisableNoScroll
Top ExtendedSelect
PictureMaskColor
RightToLeft
TabStop
RadioButton SetFocus No additional BorderStyle
RightToLeft

Working with PowerBuilder Web Forms 71

Restrictions on supported controls

Supported control Unsupported functions Unsupported events Unsupported properties

SingleLineEdit No additional RButtonDown AutoHScroll
HideSelection
StaticHyperLink No additional No additional FillPattern
FocusRectangle
RightToLeft
StaticText No additional No additional FillPattern
FocusRectangle
RightToLeft
Tab SetFocus DoubleClicked BorderStyle
RightClicked FixedWidth
RightDoubleClicked FocusOnButtonDown
RaggedRight
RightToLeft
TabPosition (Only enum
values for TabsOnTop and
TabsOnLeft supported)
TreeView AddStatePicture BeginDrag DeleteItems
DeleteStatePicture BeginLabelEdit DisableDragDrop
DeleteStatePictures BeginRightDrag EditLabels
EditLabel EndLabelEdit FullRowSelect
GetItemAtPointer Notify HideSelection
SetDropHighlight RightDoubleClicked LayoutRTL
SetFirstVisible LinesAtRoot
SetLevelPictures PictureHeight
SetOverlayPicture PictureMaskColor
PictureWidth
RightToLeft
SingleExpand
StatePictureHeight
StatePictureMaskColor
StatePictureWidth
TrackSelect
TreeViewItem No additional No additional Bold
CutHighlighted
DropHighlighted
ExpandOnce

72 PowerBuilder 11.0 CTP

 CHAPTER 4 Unsupported Features in PowerBuilder Web Forms

Supported control Unsupported functions Unsupported events Unsupported properties

UserObject AddItem No additional Border
DeleteItem ColumnsPerPage
EventParmDouble HScrollBar
EventParmString LinesPerPage
InsertItem PictureName
PictureMaskColor
PowerTipText
UnitsPerColumn
UnitsPerPage
VScrollBar
VProgressBar No additional DoubleClicked No additional
RButtonDown
VScrollBar No additional RButtonDown No additional
VTrackBar SelectionRange RButtonDown LineSize
SliderSize
TickFrequency
TickMarks
Window DDE functions DDE events Border
InputField functions Deactivate ClientEdge
InsertPicture DoubleClicked ColumnsPerPage
IsPreview Hide ContextHelp
LineCount Mouse events ControlMenu
LineLength SystemKey KeyboardIcon
PageCount ToolbarMoved LinesPerPage
PasteRTF PaletteWindow
Preview Resizable
ReplaceText RightToLeft
Scroll functions TitleBar
Select functions Toolbar properties
Selected functions UnitsPerColumn
SetMicroHelp UnitsPerLine
SetRedraw
ShowHeadFoot
TextLine

Unsupported functions
Table 4-5 lists unsupported functions, the controls on which they are not
supported, and any notes that apply to specific controls. If your application
uses these functions, you should rework your application to avoid their use.

Working with PowerBuilder Web Forms 73

Unsupported functions

Table 4-5: Unsupported functions for Web Form deployment

Function Controls Notes
AddData Graph Unsupported for string values, other
datatypes are supported.
AddStatePicture TreeView
Arrange ListView
CanUndo SingleLineEdit, MultiLineEdit
ChangeMenu Window Throws an exception.
Check Menu, MenuCascade Working, but appearance is different.
Clear All controls except EditMask
Clipboard Graph
CloseChannel Window
Copy All controls
Cut All controls
DeleteStatePicture TreeView
DeleteStatePictures TreeView
Drag All controls Supported only in list boxes.
EditLabel ListView
TreeView
ExecRemote Window
GetCommandDDE Window
GetCommandDDEOrigin Window
GetContextService MenuCascade, Window Not working correctly.
GetDataDDE Window
GetDataDDEOrigin Window
GetDataValue Graph
GetNextSheet Window Working, but returns sheet instead of
frame.
GetItemAtPointer TreeView
GetOrigin ListView
GetRemote Window
GetToolbar Window
GetToolbarPos Window
ImportClipboard Graph
ImportFile Graph
InsertData Graph Unsupported for string values, other
datatypes are supported.
LineCount MultiLineEdit

74 PowerBuilder 11.0 CTP

 CHAPTER 4 Unsupported Features in PowerBuilder Web Forms

Function Controls Notes

LineLength MultiLineEdit
Move GroupBox Not working.
OpenChannel Window
Paste All controls
PopMenu MenuCascade Works for Menu objects, but not for
MenuCascade objects.
Print All controls
Resize GroupBox Not working.
RespondRemote Window
SaveAs Graph
Scroll MultiLineEdit Not working.
SelectedLine MultiLineEdit
SelectedStart MultiLineEdit Not working.
SelectionRange HTrackbar, VTrackbar Not working.
SetActionCode All controls
SetDataDDE Window
SetDragHighLight TreeView
SetFirstVisible TreeView
SetFocus Most controls Works for Picture, PictureHyperLink,
and Window. Not currently supported
on other controls.
SetLevelPictures TreeView
SetMicroHelp Window
SetOverlayPicture ListView
TreeView
SetPosition All controls
SetRedraw All controls
SetRemote Window
SetToolbar Window
SetToolbarPos Window
SetTop ListBox, PictureListBox
StartHotLink Window
StartServerDDE Window
StopHotLink Window
StopServerDDE Window
TextLine MultiLineEdit
Top ListBox, PictureListBox

Working with PowerBuilder Web Forms 75

Unsupported events

Function Controls Notes

Undo MultiLineEdit, SingleLineEdit

Unsupported events
Table 4-6 lists unsupported events, the controls on which they are not
supported, and any notes that apply to specific controls. If your application
uses these events, you should rework your application to avoid their use.
Table 4-6: Unsupported events for Web Form deployment
Event Controls Notes
BeginDrag ListView, TreeView
BeginLabelEdit ListView, TreeView
BeginRightDrag ListView, TreeView
Clicked PictureHyperLink, StaticHyperLink, Not working for PictureHyperLink,
TreeView, Window StaticHyperLink, and TreeView, not
supported for Window.
Deactivate Window
DeleteAllItems ListView
DoubleClicked HProgressBar, Picture, Not working for PictureHyperLink and
PictureHyperLink, StaticHyperLink, StaticHyperLink. Not currently
StaticText, Tab, TreeView, supported for client-side Web
VProgressBar, Window DataWindow control. Not supported for
progress bars. Working for other
controls, but the Clicked event is not
triggered on a double click in a Picture
or StaticText control.
DragDrop All controls
DragEnter All controls
DragLeave All controls
DragWithin All controls
EndLabelEdit ListView, TreeView
GetFocus All controls
Help All controls
Hide Window
HotLinkAlarm Window
ItemActivate ListView
Key All controls

76 PowerBuilder 11.0 CTP

 CHAPTER 4 Unsupported Features in PowerBuilder Web Forms

Event Controls Notes

LoseFocus All controls
MouseDown Window
MouseMove Window
MouseUp Window
Notify TreeView
Other All controls
RButtonDown HScrollBar, HTrackbar, MultiLineEdit, Not currently supported for client-side
SingleLineEdit, VScrollBar, VTrackbar Web DataWindow control.
RemoteExec Window
RemoteHotLinkStart Window
RemoteHotLinkStop Window
RemoteRequest Window
RemoteSend Window
Resize Window
RightClicked All controls
RightDoubleClicked All controls
Selected Menu, MenuCascade
Show Window
Sort ListView
SystemKey Window
ToolbarMoved Window

Unsupported properties
Table 4-7 lists unsupported properties, the controls on which they are not
supported, and any notes that apply to specific controls. If your application
uses these properties, you should rework your application to avoid their use.
Table 4-7: Unsupported properties for Web Form deployment
Property Controls Notes
Accelerator All controls
AccessibleDescription All controls Works on some controls.
AccessibleName All controls Works on some controls.
AccessibleRole All controls
Alignment StaticHyperLink Not working.
AutoArrange ListView

Working with PowerBuilder Web Forms 77

Unsupported properties

Property Controls Notes

AutoHScroll SingleLineEdit
BorderColor StaticHyperLink Color is always blue.
BorderStyle MultiLineEdit, Picture, Working, but Raised and ShadowBox
PictureHyperLink, RadioButton, styles are the same for most controls.
SingleLineEdit, StaticHyperLink, Not working correctly for Picture. Not
StaticText supported for RadioButton.
BringToTop All controls
ButtonHeader ListView
Cancel CommandButton, PictureButton Not working.
ClientEdge Window
ColumnsPerPage Window
ContextHelp Window
ControlMenu Window
Default CommandButton, PictureButton Not working.
DeleteItems ListView
TreeView
DisableDragDrop TreeView
DisableNoScroll ListBox
DisplayOnly MultiLineEdit Working, but control cannot get focus
when set to true.
DragAuto All controls
DragIcon All controls
EditLabels TreeView
ExtendedSelect ListBox, ListView
FaceName CommandButton
FlatStyle CommandButton, PictureButton Not working.
FillPattern StaticHyperLink, StaticText
FixedLocations ListView
FocusButtonDown SingleLineEdit,Tab Not working.
FocusRectangle Picture, StaticText Not working.
FontCharSet MultiLineEdit, SingleLineEdit, Tab Not working.
FontFamily MultiLineEdit, SingleLineEdit, Tab Not working.
FontPitch MultiLineEdit, SingleLineEdit, Tab Not working.
FullRowSelect ListView, TreeView
GridLines ListView
HeaderDragDrop ListView

78 PowerBuilder 11.0 CTP

 CHAPTER 4 Unsupported Features in PowerBuilder Web Forms

Property Controls Notes

Height HTrackBar, RoundRectangle For RoundRectangle, does not change
height if width is changed first. For
HTrackBar, this property has no effect
in a Windows application, but it does
have an effect in a Web application.
HideSelection ListView, MultiLineEdit, TreeView
HScrollbar ListBox, Window Not working in Window.
IgnoreDefaultButton MultiLineEdit Not working in response windows.
Invert Picture, PictureHyperLink
IMEMode All controls
KeyboardIcon Window
LabelWrap ListView
LargePictureMaskColor ListView
LayoutRTL ListView, TreeView
LinesAtRoot TreeView
LineSize HTrackBar, VTrackBar
LinesPerPage Window
Map3DColors Picture, PictureButton,
PictureHyperLink
MaxBox Window
MenuAnimation Menu Not working.
MenuBitmaps Menu Not working.
MenuTitles Menu Not working.
MenuTitleText Menu Not working.
MergeOption Menu
MicroHelp Menu
MinBox Window
OneClickActivate ListView
PaletteWindow Window
PictureHeight TreeView
PictureMaskColor TreeView
PictureWidth TreeView
Pointer GroupBox, HProgressBar, HScrollbar, Not supported for SingleLineEdit and
SingleLineEdit, Tab, VProgressBar, Tab. Not working for GroupBox,
VScrollbar, Window Window, progress bars, scroll bars.
Resizable Window

Working with PowerBuilder Web Forms 79

Unsupported properties

Property Controls Notes

RightToLeft GroupBox, ListBox, ListView, Cannot align RadioButton to right. Not
RadioButton, TreeView, Window working correctly for GroupBox. Not
supported for other listed controls.
Scrolling ListView
ShowHeader ListView
SingleExpand TreeView
SliderSize HTrackBar, VTrackBar
SmallPictureMaskColor ListView
SmoothScroll HProgressBar, VProgressBar Only smooth scrolling is supported.
StatePictureHeight TreeView
StatePictureMaskColor ListView
TreeView
StatePictureWidth TreeView
ShowToolbarText Window Working, but width of text is changed.
TabStop MultiLineEdit
TextSize CommandButton Not working.
TickFrequency HTrackBar, VTrackBar
TickMarks HTrackBar, VTrackBar
TitleBackColor Menu Not working.
TitleBar Window
TitleGradient Menu Not working.
ToolbarAlignment Window
ToolbarAnimation Menu Not working.
ToolBarFrameTitle Application Not working.
ToolBarHeight Window
ToolbarItemDown Menu
ToolbarItemDownName Menu
ToolbarItemSpace Menu
ToolBarPopMenuText Application Not working.
ToolBarSheetTitle Application Not working.
ToolBarUserControl Window Not working.
ToolBarVisible Window
ToolBarWidth Window
ToolBarX Window
ToolBarY Window
TrackSelect ListView
TreeView

80 PowerBuilder 11.0 CTP

 CHAPTER 4 Unsupported Features in PowerBuilder Web Forms

Property Controls Notes

TwoClickActivate ListView
UnderlineCold ListView
UnderlineHot ListView
UnitsPerColumn Window
UnitsPerLine Window
Url PictureHyperLink, StaticHyperLink Not working.
VScrollbar Window Not working.
Weight CommandButton Not working.
Width VTrackBar This property has no effect in a
Windows application, but it does have
an effect in a Web application.

Working with PowerBuilder Web Forms 81

Unsupported properties

82 PowerBuilder 11.0 CTP

T U TO R IA L Converting the Tutorial to a Web
Form Application

This tutorial provides the information you need to convert the

PowerBuilder tutorial application to an ASP .NET Web Form application.
It assumes you have installed the Microsoft .NET Framework 2.0 and an
IIS server on your development computer. You can use a different
computer to run the Web Form application from a standard Web browser.
In this tutorial, you:
• Run the tutorial in PowerBuilder
• Make changes for a .NET Web Form application
• Create and deploy a .NET Web Form project
• Change a global property for the application
• Run the application from a Web browser

How long does it take?

About 35 minutes.

Working with PowerBuilder Web Forms 83

Run the tutorial in PowerBuilder

Run the tutorial in PowerBuilder

Where you are
> Run the tutorial in PowerBuilder
Make changes for a .NET Web Form application
Create and deploy a .NET Web Form project
Change a global property for the application
Run the application from a Web browser

Before you deploy the PowerBuilder tutorial application as an ASP.NET Web

application, you must make sure that the application runs successfully from the
PowerBuilder environment. The complete tutorial application is included in
the PowerBuilder installation folder.
To run the tutorial application successfully, you must have installed Adaptive
Server Anywhere software and you must be able to connect to the "EAS Demo
DB V110" database.

1 Select Programs>Sybase>PowerBuilder 11.0>PowerBuilder 11.0 from

the Windows Start menu.
The PowerBuilder development environment displays.

2 Select Open Workspace from the File menu.

The Open Workspace dialog box displays.

3 Navigate to the Tutorial\Solutions folder under the PowerBuilder 11.0

installation folder, select MyWorkspace.pbw, and click Open.
The workspace containing the pbtutor.pbt PowerScript target file opens in
the PowerBuilder IDE. This target contains two library files (pbtutor.pbl
and tutor_pb.pbl) with all the objects of the tutorial application.

4 Click the Run button in the PowerBar.

The Login window displays for the tutorial application.

84 PowerBuilder 11.0 CTP

 Lesson TUTORIAL Converting the Tutorial to a Web Form Application

5 Enter dba as the value for the user ID and sql as the password.
Upon successful login, an MDI frame window with a menu and toolbar
displays.

6 Test available menu options to make sure they are working, then
terminate the application.

Working with PowerBuilder Web Forms 85

Make changes for a .NET Web Form application

Make changes for a .NET Web Form application

Where you are
Run the tutorial in PowerBuilder
> Make changes for a .NET Web Form application
Create and deploy a .NET Web Form project
Change a global property for the application
Run the application from a Web browser

Unless you plan to always start the tutorial database manually before your Web
Form application connects to the database, you must grant all ASP.NET users
full control of the directories containing the database and the ASA database
engine, and extend that permission to all the files in those directories.
If you want resource files to display in the browsers of Web Form clients, you
must make sure that the resource files use fully named paths rather than relative
paths. In this lesson you:
• Grant ASP.NET users full control over key directories and files
• Change a relative path to a hard-coded path

Grant ASP.NET users full control over key directories and files
You can grant ASP.NET users full control over the database and database
engine directories to enable the Web Form application to automatically start the
tutorial database. You must also propagate the directory permissions to all files
in these directories.

1 In Windows Explorer, browse to the Sybase\Shared\PowerBuilder

directory.
This directory contains the tutorial database.

2 Right-click the directory and select Properties from the pop-up menu.

3 Select the Security tab of the Properties dialog box for the directory
and click the Add button.
The Select Users, Computers, or Groups dialog box displays.

86 PowerBuilder 11.0 CTP

 Lesson TUTORIAL Converting the Tutorial to a Web Form Application

If the Security tab does not display

To display the Security tab, you might need to modify a setting on the
View tab of the Folder Options dialog box for your current directory. You
open the Folder Options dialog box by selecting the Tools>Folder Options
menu item from Windows Explorer. To display the Security tab, you must
clear the check box labeled “Use simple file sharing (Recommended)”.

4 Click Locations and choose the server computer name from the
Locations dialog box and click OK.

5 Type ASPNET in the list box labeled “Enter the object names to
select” and click OK.
The ASP.NET machine account is created for the current directory.

If you click the Check Names button, a message will be displayed if the
system does not recognize the ASPNET user name. If the name is not
recognized, you might have to reinstall the Microsoft 2.0 .NET
Framework.
The Select Users, Computers, or Groups dialog box closes after you click
OK and you return to the Security tab of the Properties dialog box for the
current directory.

6 Select the ASP.NET machine account in the top list box on the
Security tab, then select the “Full Control” check box under the Allow
column in the bottom list box.

Working with PowerBuilder Web Forms 87

Make changes for a .NET Web Form application

7 Click the Advanced button.

The Advanced Security Settings dialog box displays for the current
directory.

8 Select the check box labeled “Replace permission entries on all child
objects with entries shown here that apply to child objects” and click
OK.
A Security dialog box displays, warns you that it will remove current
permissions on child objects and propagate inheritable permissions to
those objects, and prompts you to respond.

9 Click Yes at the Security dialog box prompt, then click OK to close the
Properties dialog box for the current directory.

10 Repeat steps 1-9 for the Sybase\SQL Anywhere 9\win32 directory.

Change a relative path to a hard-coded path

The tutorial application includes a picture on its welcome window that uses a
relative path. The picture will not display in a Web Form application unless the
path is converted to include the entire file path.

1 Open the w_welcome window in the Window painter.

The w_welcome window is in the pbtutor.pbl library.

2 Click the p_sports picture control in the w_welcome window.

3 Click the browse (...) button next to the PictureName text box on the
General tab of the Properties view for the picture control.
The Select Picture dialog box displays.

4 Browse to the tutsport.bmp file in the PowerBuilder Tutorial

directory and click Open.
The PictureName field should now display the full path to the tutsport.bmp
picture file. The full path will be recreated in a virtual file directory when
you deploy the application as a .NET Web Form project to the IIS server.

88 PowerBuilder 11.0 CTP

 Lesson TUTORIAL Converting the Tutorial to a Web Form Application

Create and deploy a .NET Web Form project

Where you are
Run the tutorial in PowerBuilder
Make changes for a .NET Web Form application
> Create and deploy a .NET Web Form project
Change a global property for the application
Run the application from a Web browser

You use the PowerBuilder .NET Web Form project wizard to convert an
existing PowerBuilder application to a Web Form application.

1 Right-click on the pbtutor target entry in the System Tree, select

New from the pop-up menu, and click the Project tab.
The Project page of the New dialog box displays.

2 Select the .NET Web Form Application Wizard icon and click OK.
The first page of the wizard displays about what the wizard is used for.

3 Click Next until the Specify Settings for .NET Web Form Application
page displays.
You accept the default values for the application library (pbtutor.pbl) and
the .NET Web Form project name (p_pbtutor_webform). The following
table shows default values for the fields on the .NET Web Form
Application page:
.NET Web Form parameter Default value
Web application name pbtutor
Application URL preview http://<ServerName>/pbtutor, where
<ServerName> is a placeholder for the name
of the IIS server
Initial current directory in virtual The path of the current directory, typically:
file system drive:\Program Files\Sybase\PowerBuilder
11.0\Tutorial\Solutions
Command line parameters — (blank)
Window style Classic Web style
Render file manager icon Not selected
Render mail manager icon Not selected

Working with PowerBuilder Web Forms 89

Create and deploy a .NET Web Form project

4 Accept the default values and click Next.

The Select PBR Files page of the wizard displays. The tutorial does not use
PBR files.

5 Click Next to display the Specify Resource Files / Directories page of

the wizard, then click the Add Files button.
The ini file, image files (bmp, gif, or jpeg) or icon files used by the
application are mentioned here. The PowerBuilder Tutorial application
uses some image files and hence they need to be added in this page.
This opens the “Choose Resource Files” page.

6 Select All Files from the Files of Type drop-down list and navigate
to the parent Tutorial directory.

7 Hold down the Ctrl key and select the tshirtw.jpg, tutsport.bmp,
and tutorial.ico files and click Open.
The selected resources are added to the page as shown below:

8 Click Next to include the selected resource files for deployment with
the tutorial Web Form application.

90 PowerBuilder 11.0 CTP

 Lesson TUTORIAL Converting the Tutorial to a Web Form Application

The “Specify External Modules” page of the wizard displays. The tutorial
application does not use any external modules.

9 Click Next to display the Specify PowerBuilder Library Files page of

the wizard.
Make sure the check boxes for the PBTutor.PBL and Tutor_PB.PBL
libraries are selected.
The tutorial application uses DataWindow objects in both libraries. The
application library (PBTutor.PBL) is transformed by the PowerBuilder
.NET compiler to a .NET application. If this PBL did not contain
DataWindow objects that you use in the application, deploying the PBL
would not be required because a PBD and DLL file are deployed
automatically to the IIS application bin directory.

10 Click Next twice to display the Specify Deployment Options page of

the wizard.
You do not include any extra JavaScript files on the Specify JavaScript
Files page of the wizard, because none are needed for the tutorial
application.
The Specify Deployment Options page displays:

Working with PowerBuilder Web Forms 91

Create and deploy a .NET Web Form project

11 Accept Localhost for the IIS server address or change this to the
formal name for the local IIS server, then click Next.
In this tutorial, you deploy the Web Form project directly to the local IIS
server. After you click Next, the Summary page of the wizard displays.

12 Click the Finish button.

The .NET Web Form Application wizard creates the p_pbtutor_webform
project and add it to the pbtutor.pbl library. The .NET Web Form project
opens in the Project painter.

13 Select Design>Deploy Project from the Project painter menu or click

the deploy icon in the PainterBar.
You build and deploy the project to the local IIS server. A success message
displays and asks if you want to run the project now. It also prompts you
to look in the PowerBuilder Output window for a list of the project’s
features that are not supported in the .NET Web Form environment. You
can ignore this list, because the unsupported features do not affect the main
functionality of the tutorial application.

14 Click No in the Deployment Succeeded message box and close the

Project painter.
You will run the Web Form project after you modify one of its global
properties.

92 PowerBuilder 11.0 CTP

 Lesson TUTORIAL Converting the Tutorial to a Web Form Application

Change a global property for the application

Where you are
Run the tutorial in PowerBuilder
Make changes for a .NET Web Form application
Create and deploy a .NET Web Form project
> Change a global property for the application
Run the application from a Web browser

After you deploy the tutorial application to an IIS server, the pbtutor and
pbtutor_root directories are created under the IIS root directory. The IIS root
directory is c:\Inetpub\wwwroot by default.
In this lesson you change a global property for page navigation in the
DataWindow controls on tutorial application sheet windows.

1 Select Start>Run from your computer, type Inetmgr in the Open

drop-down list, and click OK.
The Internet Information Services Manager displays.

2 Expand the nodes for your local computer, as well as those for Web
Sites and Default Web Sites.
You should see nodes labeled pbtutor and pbtutor_root.

3 Right-click the pbtutor node, select Properties from the pop-up

menu and click the ASP.NET tab.

Working with PowerBuilder Web Forms 93

Change a global property for the application

The ASP.NET tab of the Properties dialog box displays, as shown below:

4 Make sure that the ASP.NET version is 2.0.50727 or higher.

5 Select Edit Configuration.

The ASP.NET Edit Configuration dialog box opens to the General page.

6 Scroll down in the Application Settings list box to display the

PBDataWindowPageNavigatorType property in the Key column.
The default page navigator control for DataWindow controls is NextPrev.
The NextPrev navigator control includes four direction buttons for the first
page, next page, previous page, and last page. You will change the
navigator control to the Numeric type.
Note also that the PBDataWindowRowsPerPage property is listed directly
above the PBDataWindowPageNavigatorType property. Its default value
is 20, and it limits the number of rows in a DataWindow page to 20. You
do not change this value in the current tutorial.

94 PowerBuilder 11.0 CTP

 The ASP.NET Configuration Settings dialog box displays default settings
for the application’s global properties, as shown below:

7 Click the PBDataWindowPageNavigatorType property, then click the

Edit button.
The Edit/Add Application Settings dialog box displays.

8 Type Numeric in the Value text box.

You change the navigator control type from NextPrev to Numeric.

9 Click OK to close the Edit / Add Application Settings dialog box.

Note that the PBDataWindowPageNavigatorType property value has
changed to Numeric in the Application Settings list box of the ASP.NET
Edit Configurations dialog box.

Working with PowerBuilder Web Forms 95

Change a global property for the application

10 Click OK twice to close the remaining dialog boxes.

The Internet Information Services manager displays again.

11 Expand the pbtutor and pbtutor_root nodes to view their directory

structures.
The Web Form application virtual file directory displays under the
pbtutor_root\file\common directory. The virtual file directory mirrors the
physical directory structure of the development computer for directories
that contain files needed by the application. Drive letters in the physical
directory structure are rendered as directory names for the top-level
directories in the virtual file system. Note that the resource files you
selected for deployment are listed in the virtual file system.

12 Select File>Exit to close the IIS manager.

96 PowerBuilder 11.0 CTP

Run the application from a Web browser
Where you are
Run the tutorial in PowerBuilder
Make changes for a .NET Web Form application
Create and deploy a .NET Web Form project
Change a global property for the application
> Run the application from a Web browser

You are now ready to run the tutorial as a Web Form application. In this lesson
you start one application session from PowerBuilder and another session by
typing the application URL in a Web browser Address box.

1 Start the EAS Demo DB V110 database manually if necessary.

You do not need to start the database manually if you set full control
permissions for the ASP.NET user for the database and database engine
directories, as described in “Grant ASP.NET users full control over key
directories and files” on page 86.

Starting the database manually

You can start the database manually by selecting
Programs>Sybase>PowerBuilder 11.0>Demo Database from the
Windows Start menu.

2 Right-click the p_pbtutor_webform project in the PowerBuilder

System Tree and select Run Project from the pop-up menu.
If you left the p_pbtutor_webform project open in the Project painter, you
can select Design>Run from the Project painter menu or you can click the
Run Project icon in the PainterBar instead of using the System Tree
pop-up menu. You cannot run the project from the System Tree pop-up
menu while a PowerBuilder painter is open for any of the project objects.

Working with PowerBuilder Web Forms 97

Run the application from a Web browser

The .NET Web Form Application dialog box opens to the Run in Browser
page.

3 Click the Run in Browser button.

The welcome window (login screen) for the tutorial application displays
in the Web browser. When you run the application from the PowerBuilder
design-time environment, you do not see the browser menus and toolbars.

4 Open an Internet Explorer (IE) browser from the Windows Start menu
or task bar.
You can open a browser on a different computer if you have one available.
You will next start a second session for the tutorial application.

5 Type http://serverName/pbtutor/default.aspx in the IE Address box,

where serverName is the name of the IIS server where you deployed
the tutorial application.
If you open a Web browser on the IIS server machine, and you deployed
the application to “localhost”, you can use localhost for the server name in
the browser’s Address box. When you start the application from a Web
browser and include the default.aspx start page, the browser menus and
toolbars remain visible when the Web Form application displays in the
browser window.

6 Enter dba for the user ID and sql for the password.
After a successful login, the tutorial application’s Frame window displays
in the Web browser.

98 PowerBuilder 11.0 CTP

 7 Select Report>Customer Maintenance from the Frame window menu.
The Maintain Customers sheet window displays. The master DataWindow
on this page uses the Numeric style page navigation control. You can click
on a number to navigate to a different page. Because you did not change
the PBDataWindowRowsPerPage property in the IIS manager, the number
of DataWindow rows per page is 20.
Frame window and the sheet window toolbars display separately.

8 Select Report>Product Maintenance from the Frame window menu.

The Maintain Products sheet window displays. Because you used the
classic Web style for the application’s window presentation, the sheet
windows display in a tab page format rather than as detached, cascading
windows.
You do not see any page navigation controls on the Maintain Products
page because its DataWindow controls do not have more than 20 rows (the
value set by the global PBDataWindowRowsPerPage property) and are
therefore completely visible in a single page.

Working with PowerBuilder Web Forms 99

Run the application from a Web browser

The following picture displays the tab page format used in the classic Web
style presentation.

9 Continue testing the tutorial or select File>Exit from the application

Frame window menu.
You should be able to insert, update, and delete database entries from the
tutorial Web Form application, just as you were able to do from the
PowerBuilder native tutorial application.
After you finish with the current Web Form session, you might want to
experiment with changing some of the other global properties. To examine
the File Manager and the Mail Profile Manager, you can set the
PBFileManager and PBMailManager global properties to true.

Advanced topics
For more information on the File Manager and Mail Profile Manager, as
well as for information on printing to a PDF file and on using registry
functions, see Chapter 3, “Print, File, Mail, and Registry Operations in
Web Forms.” For information on coding client-side events, see Chapter 2,
“Client-Side Events and Default Event Handlers.”

100 PowerBuilder 11.0 CTP

Index

A E
ASA database connection, setting up 11 Embedded, StaticHyperLink property 22
ASP.NET event handlers
configuring 7 and postback events 32
setting user permissions 11, 86 client-side 32
version 8 default 33
AutoPostBack property 22 events
ClientEvent properties 35
Web DataWindow client control 35

B
ButtonClicked event 38
ButtonClicking event 39 F
File Manager
creating a folder 55
downloading a file 57
C uploading a file 56
Clicked event 40 virtual file system 52
client-side, event handlers 32 file process mode 53
command-line parameters 7
Configuring
ASP.NET 7
IE Web Controls 12 G
conventions vi Ghostscript, installing 50
copy mode, global property 53 global properties 18, 22

D H
DataWindow HTMLGen.PagingMethod property 33
page navigation 19
pagination 19
saving as PDF 49
saving as XSL 49 I
deploy, Web Form project 6 IE Web Controls
downloading files 57 configuring 12
problem with toolbars and tab controls 27
IIS, directory structure 10
ItemChanged event 41

Working with PowerBuilder Web Forms 101

Index

ItemError event 42 avoiding 33

ItemFocusChanged event 43 from default event handlers 33
PowerScript
registry functions 61
unsupported events 76
L unsupported functions 73
Log file, pbtrace 12 unsupported properties 77
printing
Apache FO software processing 49
DataWindow as PDF 49
M DataWindow as XSL 49
Mail Profile Manager GNU Ghostscript software processing 50
opening from icon 59 output location 48, 51
opening in MailLogon call 58 properties, global 9
mail, sending and receiving 58
MailLogon function 58
MailSend function 59
MailSession object 58 R
registry functions, in Web Form applications 61
requirements, system 3
RowFocusChanged event 44
N RowFocusChanging event 45
navigation controls 19
.NET compiler 1
.NET Web Forms
application wizard 3 S
code block 31 script
coding restrictions 13 .NET code block 31
configuring for 7 client-side events 31
global properties 9 share mode, global property 53
sharing data
across sessions 26
DropDownDataWindows 26
O system requirements 3
OnClient event prefix 35

T
P Troubleshooting tips 26
PBDataWindow.JS file 33 typographical conventions vi
PBTrace.Log file 12
PDF
Apache FO printing method 49
postscript printing method 49 U
postback uploading files 56
and client-side events 20

102 PowerBuilder 11.0 CTP

 Index

W
Web browser
command-line parameters 7
default start page 7
Web DataWindow
client-side scripts 35
events for client control 35
Web Form applications
advantages 2
directory structure 10
global properties 9
sending and receiviing mail 58
start page 7
supported controls 67
unsupported features 63
using registry functions 61
virtual file system 52

Working with PowerBuilder Web Forms 103

Index

104 PowerBuilder 11.0 CTP