PowerBuilder .

NET Features Guide

DOCUMENT ID: Not Yet Available

LAST REVISED: June 2009
Copyright 2009 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 trademarks can be viewed at the Sybase trademarks page at http://www.sybase.com/detail?id=1011207. Sybase and the marks listed are trademarks of
Sybase, Inc. A indicates registration in the United States of America.
Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.
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
What is PowerBuilder .NET

............................................................1

PowerBuilder .NET Architecture ...................................................................1

Overview of the WPF Control Classes .............................................................2
Semantic Differences

................................................................................3

Runtime Requirements for PowerBuilder .NET

..................................................4
Advantages of WPF Applications ...................................................................4
Unsupported Features in PowerBuilder .NET
....................................................5
Conditional Compilation in PowerBuilder .NET Targets ........................................6

Graphic User Interface

..................................................................7

System Tree in PowerBuilder .NET

................................................................8
WPF Visual Controls in PowerBuilder
.............................................................9
PowerBuilder .NET Toolbox ........................................................................10
PB Object Outline ...................................................................................12
New Dialog in PowerBuilder .NET
................................................................14
Skin Selection for Applications and Controls ...................................................15
PowerBuilder .NET Painters .......................................................................16
About the Enumeration Painter ...........................................................16
About the Interface Painter ...............................................................16
Window Painter in PowerBuilder .NET
..................................................16
Building a New WPF Window ..............................................................17
MDI Applications in PowerBuilder .NET
.................................................18
Menus and Toolbars in PowerBuilder .NET
.............................................19
User Objects .................................................................................29

PowerBuilder .NET Targets and Projects

..........................................33

Deployment Requirements for .NET Component Targets .....................................33

Creating a WPF Window Target ...................................................................33
WPF Window Target Properties ...................................................................34
Creating a .NET Assembly Target .................................................................36
.NET Assembly Target Properties .................................................................36
Creating a .NET Web Service Target .............................................................38
.NET Web Service Target Properties ..............................................................38
Project Painter User Interface ....................................................................40
WCF Client Project Overview .....................................................................40
Creating a WCF Client ......................................................................41

Scripts and Code Fundamentals

.....................................................43

Script View in PowerBuilder .NET

...............................................................43
Opening the Script View ...........................................................................43
Modifying Script View Properties .................................................................44
Editing Scripts .......................................................................................44
Code Snippets .......................................................................................44
IntelliSense ...........................................................................................44

PowerBuilder .NET Features Guide

iii

Contents

Compiling the Script ................................................................................45

Handling Problems with Script Compilation ............................................45
Declaring Variables and External Functions .....................................................45
GoTo Definition ......................................................................................46
Accelerator Characters in Control Labels .......................................................46
Unsupported Properties, Functions, and Events ...............................................46

CLS Compliance in PowerBuilder

...................................................49

Runtime Array Bounds Creation ...................................................................50

Jagged Array Support ...............................................................................50
.NET System.Array Support ........................................................................50
Returning an Array for a Function or Event .....................................................50
Support for BitRight and BitLeft Operators .....................................................51
Defining an Interface ...............................................................................52
System Interface Syntax ...........................................................................52
Implementing an Interface ........................................................................53
Deleting a Declared Interface .....................................................................54
Consuming a .NET Delegate .......................................................................54
Syntax for Consuming .NET Delegates
..................................................54
Syntax for Consuming Generic Classes ...........................................................56
Inheriting from a .NET Class .......................................................................57
Syntax Supporting Inheritance from a .NET Class ......................................57
Creating a Global User-Defined Enumeration ..................................................58
Syntax for User-Defined Enumerations ..................................................58
Creating a Local User-Defined Enumeration ....................................................59
Declaring a Namespace ............................................................................59
Adding a Parameterized Constructor ............................................................60
Inheritance from .NET System.Object ...........................................................60
StringBuilder System Class .........................................................................60
Defining a Custom Attribute .......................................................................61
Syntax for a Custom Attribute ............................................................61
Including XML Documentation Comments .......................................................62
Enhancements to .NET Component Projects ....................................................62

Graphs in PowerBuilder .NET

........................................................63

Parts of a Graph .....................................................................................63

Types of Graphs in PowerBuilder .NET
..........................................................64
Area, Bar, Column, and Line Graphs .....................................................64
Pie and Donut Graphs ......................................................................64
Scatter and Bubble Graphs ................................................................65
Three-Dimensional Graphs ................................................................68
Radar Graphs ................................................................................68
Stacked Graphs ..............................................................................69
Cone Graphs .................................................................................69

DataWindows

............................................................................71

DataWindows in PowerBuilder .NET

.............................................................71
Using DataWindow Objects in PowerBuilder .NET
....................................71

iv

Contents

Presentation Styles for DataWindow Objects ...................................................71

Tabular Presentation Style .................................................................72
Freeform Presentation Style for DataWindow Objects ................................72
Grid Presentation Style in DataWindow Objects .......................................72
Label Presentation Style for DataWindow Objects ....................................72
N-Up Presentation Style for DataWindow Objects .....................................72
Group Presentation Style for DataWindow Objects ....................................73
Composite Presentation Style for DataWindow Objects ..............................73
Graph and Crosstab Presentation Styles for DataWindow Objects ..................73
RichText Presentation Style for DataWindow Objects .................................73
TreeView Presentation Style ..............................................................73
Cascading Presentation Style for DataWindow Objects ...............................73
Using SQL Select ....................................................................................74
Defining the Data Using SQL Select ......................................................74
Selecting Tables and Views Using SQL Select ...........................................74
Table Layout View in SQL Select ..........................................................75
Selecting Columns Using SQL Select .....................................................75
Including Computed Columns Using SQL Select ........................................75
Defining Queries .....................................................................................76
Previewing the Query ......................................................................76
Saving the Query ............................................................................76
Modifying the Query ........................................................................76
DataWindow Object Enhancements ..............................................................77
DataWindow Painter ........................................................................77
Adding Controls to a DataWindow Object
......................................................79
Adding Columns to a DataWindow Object
..............................................80
Adding Text to a DataWindow Object
...................................................80
Adding Drawing Controls to a DataWindow Object
...................................80
Adding a Group Box to a DataWindow Object
.........................................80
Adding Pictures to a DataWindow Object
..............................................81
Adding Computed Fields to a DataWindow Object
....................................81
Adding Buttons to a DataWindow Object
...............................................84
Add Graphs to DataWindow Objects .....................................................86
Adding Reports to a DataWindow Object
...............................................86
Adding WPF Controls to a DataWindow Object
........................................86
Tooltips in DataWindow Objects ..........................................................86

Database Management in PowerBuilder .NET

....................................87

Defining Database Profiles .........................................................................87

The Database Painter in PowerBuilder .NET
...................................................87
Manipulating Data in Database Painter ..........................................................87
SQL Statements in Database Painter .............................................................87
DSI Database Trace Tool ............................................................................88

WCF Client Proxy Reference

.........................................................91

WCFConnection Object ............................................................................91

Classes Supporting WCF Client Connections ....................................................93

PowerBuilder .NET Features Guide

Contents

BasicHttpMessageSecurity Class ..........................................................93

BasicHttpSecurity Class ....................................................................94
ClientCertificateCredential Class ........................................................94
HttpTransportSecurity Class ...............................................................95
HttpDigestCredential Class ................................................................95
MessageSecurityOverTcp Class ............................................................95
NetTcpSecurity Class .......................................................................96
NoDualHttpMessageSecurity Class ........................................................96
ServiceCertificateCredential Class .......................................................97
TcpTransportSecurity Class ................................................................98
UserNameCredential Class .................................................................98
WCFBasicHttpBinding Class ................................................................98
WCFClientCredential Class ................................................................99
WCFConnection Class .......................................................................99
WCFEndpointAddress Class ...............................................................101
WCFEndpointIdentity Class .............................................................. 101
WCFnetTCPBinding Class ................................................................. 102
WCFProxyServer Class .................................................................... 102
WCFReaderQuotas Class .................................................................. 103
WCFReliableSession Class ................................................................ 103
WCFWebHttpBinding Class ............................................................... 104
WCFwsHttpBinding Class ................................................................. 104
WebHttpSecurity Class ....................................................................105
WindowsCredential Class .................................................................105
wsHttpSecurity Class ......................................................................105
WCF Client System Constants ....................................................................106
BasicHttpMessageCredentialType Enumeration .......................................106
BasicHttpSecurityMode Enumeration ...................................................106
CertStoreLocation Enumeration .........................................................107
CertStoreName Enumeration ............................................................ 107
HttpClientCredentialType Enumeration ................................................107
HttpProxyCredentialType Enumeration ................................................ 108
ImpersonationLevel Enumeration ....................................................... 108
MessageCredentialType Enumeration .................................................. 108
ProtectionLevel Enumeration ............................................................109
TcpClientCredentialType Enumeration ................................................. 109
WCFBindingType Enumeration ...........................................................109
WCFEndpointIdentity Enumeration ..................................................... 110
WebHttpSecurityMode Enumeration ....................................................111
wsSecurityMode Enumeration ........................................................... 111
WSTransferMode Enumeration ...........................................................111

vi

What is PowerBuilder .NET

What is PowerBuilder .NET

Beginning with the 12.0 release, the PowerBuilder setup program allows you to install two separate IDEs. The familiar
PowerBuilder IDE is rebranded as PowerBuilder Classic. The new IDE is named PowerBuilder .NET.
In the PowerBuilder .NET IDE, you use the WPF Window Application Target wizard in the New dialog box to create
Windows Presentation Foundation (WPF) applications. The wizard can create WPF applications from scratch or by
converting standard PowerBuilder client-server or .NET Windows Forms targets.
In addition to WPF application targets, the PowerBuilder .NET IDE allows you to create .NET Web Services and .NET
Assembly components from nonvisual user objects. You can take advantage of language enhancements for fuller .NET
compliance when you build these components in PowerBuilder .NET rather than in PowerBuilder Classic.
Note: For beta1, .NET Web Services and .NET Assembly targets are nonfunctional in the PowerBuilder .NET IDE.

PowerBuilder .NET Architecture

PowerBuilder .NET applications are built on top of the PowerBuilder WPF runtime library, including system classes and
system functions.
The WPF runtime library reuses the existing nonvisual part of the PowerBuilder Classic .NET runtime library, enhanced
for extended Common Language Specification (CLS) compliance. The major difference with PowerBuilder Classic is in
the presentation layer.
A .NET assembly, Sybase.PowerBuilder.WPF.controls.dll, contains PowerBuilder versions of all WPF
controls available in the presentation layer. (Implementations for the DataWindow, EditMask, and RichText controls
depend on additional assemblies.) WPF application development reuses the existing PowerBuilder to .NET compiler
(pb2cs) for application compilation.
Although PowerBuilder Classic and PowerBuilder .NET share the same compiler, the compiler has been modified so that
it can generate WPF applications correctly. For example, the WPF runtime library needs to link binary application markup
language (BAML) to WPF controls. The currrent version of the compiler accomplishes this linkage for
PowerBuilder .NET applications, even though the .NET Windows Forms or Web Forms applications you develop in
PowerBuilder Classic do not use BAML or WPF controls.
The diagram below shows the process used by PowerBuilder to create a new WPF application. In this diagram, once you
drag and drop a control or change something in the layout of the WPF painter, a corresponding XAML file is generated.

PowerBuilder .NET Features Guide

What is PowerBuilder .NET

The WPF painter also generates PowerScript code to work as the code behind file to the XAML files. However, before
it can be used as a code behind file, it is translated and processed by the pb2cs compiler. The generated files are then
compiled to a WPF application that contains embedded BAML. The WPF application also references the PowerBuilder
WPF runtime engine that enables users to run the deployed application.

Overview of the WPF Control Classes

The runtime classes in a PowerBuilder .NET application maintain the traditional PowerBuilder control hierarchy, but
inherit from the Microsoft WPF control hierarchy.
When the runtime engine loads the application, the PowerBuilder .NET control classes (that are actually .NET wrappers
around standard PowerScript controls) marshal data and connect to PowerBuilder versions of WPF controls in the
presentation layer.
The following diagram shows the dual dependency structure of controls in the PowerBuilder presentation layer. However,
only a minimal set of control classes is displayed in this diagram.

What is PowerBuilder .NET

The PowerBuilder .NET controls use a "PB" prefix internally. This set of controls enables you to use PowerScript code
to access control properties, methods, and events. They marshal the data and pass it to the PowerBuilder version of WPF
controls in the presentation layer.
The controls that you add to window objects in the PowerBuilder WPF painter, and that display in the runtime presentation
layer, are derived from control classes in the WPF Framework (System.Windows.Controls namespace). They are
referenced at design time in XAML using the default pbwpf alias for the Sybase.PowerBuilder.WPF.Controls
namespace, and at runtime, in binary application markup language (BAML).

Semantic Differences
Semantic differences between PowerBuilder and Visual Studio can lead to confusion.

PowerBuilder .NET Features Guide

What is PowerBuilder .NET

The main semantic differences (equivalencies) are listed below:

PowerBuilder "Workspace" is equivalent to a Visual Studio "Solution"

In PowerBuilder .NET, the workspace file is saved with a PBWX extension, rather than the PBW extension used in
PowerBuilder Classic.
PowerBuilder "Target" is equivalent to a Visual Studio "Project"
In PowerBuilder .NET, target files are saved with PBTX extensions, rather than the PBT extensions used in
PowerBuilder Classic.
PowerBuilder "Library" or "PBL" is equivalent to a Visual Studio "file"
In PowerBuilder .NET, the PBL is a folder containing files for all objects in the PBL, although in PowerBuilder
Classic, the PBL is a binary file that includes version metadata and compiled code for all objects in the PBL.
The PBL directory in PowerBuilder .NET must have a PBL extension. It must contain a PBLX file, and subdirectories
for all build configurations. Although you can add other files to the library directories, the PowerBuilder System Tree
only recognizes PowerBuilder source files. However, you can include other types of files in a PowerBuilder .NET
target.
PowerBuilder "System Tree" is equivalent to the Visual Studio "Solution Explorer"

Runtime Requirements for PowerBuilder .NET

The applications you create in PowerBuilder .NET automatically reference several .NET assemblies that must be present
in the global assembly cache (GAC) on the design time and runtime computers.
The PowerBuilder setup program installs the required assemblies in the GAC of the design time computer, but they also
must be deployed or installed in the GAC of each runtime computer.
The following list shows the Microsoft assemblies (and their .NET Framework version numbers) that are installed with
PowerBuilder and can be redistributed to runtime computers with the PowerBuilder Runtime Packager:

System.dll (v 2.0)
PresentationCore.dll (v 3.0)
PresentationFramework.dll (v 3.0)
WindowsBase.dll (v 3.0)
System.Xml.Linq.dll (v 3.5)
Sybase.PowerBuilder.WPF.dll
Sybase.PowerBuilder.Common.dll
Sybase.PowerBuilder.Interop.dll
Sybase.PowerBuilder.Core.dl

Advantages of WPF Applications

PowerBuilder WPF applications allow you to take advantage of the diverse systems that WPF uses internally, such as
DirectX (3D and hardware acceleration), Adobe Flash (animation support), and HTML (declarative markup and easy
deployment).
The advantages of WPF applications include:

Tight multimedia integration

To use 3D, video, speech, and rich document viewing in Windows 32 or Windows Forms applications, you would need
to learn several independent technologies and blend them together without much built-in support. WPF applications
allow you to use all these features with a consistent programming model.
Resolution independence
WPF makes it easy to shrink or enlarge elements on the screen independent of the screens resolution. It uses vector
graphics to make your applications resolution independent.

What is PowerBuilder .NET

Hardware acceleration
WPF is built on top of Direct3D, which offloads work to graphics processing units (GPUs) instead of central processor
units (CPUs). This provides WPF applications with the benefit of hardware acceleration, permitting smoother
graphics and enhanced performance.
Declarative programming
WPF uses Extensible Application Markup Language (XAML) declarative programming to define the layout of
application objects and to represent 3D models, among other things. This allows graphic designers to directly
contribute to the look and feel of WPF applications.
Rich composition and customization
WPF controls are easily customizable. You do not have to write lines of code, or for that matter, any code, to customize
controls in very unique ways. WPF also makes it easy to create skins for applications that have radically different
looks.
Easy deployment
WPF provides options for deploying traditional Windows applications (using Windows Installer or ClickOnce) or for
hosting applications in a Web browser. Although this feature is not unique to WPF, it is still an important component
of the technology.

WPF is also more suitable for applications with rich media content than Windows Forms applications. This includes
applications using:

Multimedia and animation with DirectX technology

HD video playback
XPS documentation for high quality printing
Control rotation (Windows Forms applications support text rotation only.)

Unsupported Features in PowerBuilder .NET

Some features available in PowerBuilder Classic are not supported in PowerBuilder .NET. Other features are partially
supported.
The following features are not currently supported or are only partially supported in PowerBuilder .NET:

User-defined custom events

PowerBuilder .NET uses a different event model than PowerBuilder Classic.
MDI windows
Tabbed documents are used in place of MDI sheet windows. This is similar to the tabbed document implementation
in Web Forms applications in PowerBuilder Classic.
Control handles
In PowerBuilder Classic applications, each control has its own window handle, and many operations depend on the
window handle. In PowerBuilder .NET, there is only a single "big" handle for a window, but the controls nested in a
window do not have their own handles. Migrated applications that use API calls that rely on control handles must be
refactored before being imported to PowerBuilder .NET.
OLE controls
OLE controls are only partially supported in PowerBuilder .NET.
PBNI, including PBDOM objects
Profile and Trace related objects
EAServer components

Other differences in functionality relate to the WYSIWYG designer in PowerBuilder .NET and the sequence in which
events are handled.

Look and feel differences

The size of WPF controls is determined by the controls' contents. Some legacy properties of these controls, such as
BorderStyle, are not supported.

PowerBuilder .NET Features Guide

What is PowerBuilder .NET

Event sequence
The difference in event sequence in WPF applications should not affect new applications. However, applications that
you migrate from PowerBuilder Classic require manual refactoring when they rely on the order of triggered events.
Although Web Forms applications also use a different event sequence than Windows 32 or Windows Forms
applications, in Web Forms applications, the events can be saved to a queue and executed during a postback operation.
For WPF applications, the events must be handled immediately after they are fired

Conditional Compilation in PowerBuilder .NET Targets

Although you do not need to use conditional code blocks in PowerBuilder .NET to reference .NET classes as in
PowerBuilder Classic, you can still use the PBDOTNET, PBWEBSERVICE, and DEBUG preprocessor symbols for
conditional compilation in PowerBuilder .NET targets.
PowerBuilder .NET also recognizes the PBWPF preprocessor symbol. This preprocessor symbol allows you to
conditionally code blocks of script for WPF Window Application targets exclusively. The code in these blocks is not
parsed for other target types that share objects with the WPF Window Application targets.
PowerBuilder .NET processes code inside PBDOTNET code blocks for WPF Window Application, Web Service,
and .NET Assembly targets. When the Enable Debug Symbol check box is selected in the Project painter,
PowerBuilder .NET also processes code bracketed by the DEBUG preprocessor symbol.
PowerBuilder .NET ignores all code in PBNATIVE, PBWINFORM, and PBWEBFORM code blocks in the targets that
you migrate from PowerBuilder Classic. The conditional code blocks in targets that you migrate are kept in place, and are
enabled only for those symbols that are valid in PowerBuilder .NET.
Code in blocks with the NOT operator can be processed in PowerBuilder .NET, even if the preprocessor symbol used is
not normally valid in PowerBuilder .NET targets. You can also enable invalid code blocks in migrated applications by
changing the preprocessor symbols to symbols that are valid for your current target.
For more information on conditional compilation, see Referencing .NET Classes in PowerScript in the PowerBuilder
Classic HTML Help.
The following are some preprocessor use cases in PowerBuilder .NET:

#if Defined NOT PBNATIVE then

/// code will be executed
#end if
#if Defined PBWINFORM
/// code will be ignored
#elseif defined PBWEBFORM then
/// code will be ignored
#else
/// code will be executed
#end if
#if Defined PBWPF then
/// code will be executed
#end if

Graphic User Interface

Graphic User Interface

Although PowerBuilder .NET and PowerBuilder Classic share many GUI elements, there are also a number of
differences. Many of the differences are the result of the isolated Visual Studio shell that is integrated into PowerBuilder .NET.
The features in the following table are supplied with the Microsoft Visual Studio shell. You can use the F1 key from a
Visual Studio shell feature to open the H2 Help, and in Visual Studio shell dialog boxes you can click the question mark
icon in the title bar for the H2 Help. The Help for these features is also supplied by Microsoft.
Visual Studio shell feature

Comment

XAML editor

The eXtensible Application Markup Language (XAML) allows you to code the presentation aspects of your applications separate from the business logic that you code in the
PowerBuilder .NET painter Script views. Changes that you make in the painter designer
views are reflected in the XAML editor code, and changes you make in the XAML editor
can be seen in the designer views. You can only view the XAML editor for a painter when
the Layout view is also visible.

Object Browser

The Object Browser allows you to view all .NET Framework classes. It is accessible from
the View menu and is separate from the classic PowerBuilder Object Browser that is also
available from the View menu.

Source control

Source control functionality is available from the File>Source Control menu of PowerBuilder .NET. PBG files are no longer required, because exported objects are not compiled into a binary PBL file as in PowerBuilder Classic. The Visual Studio shell source
control functionality also does not use PBC files.

Code Snippets Manager

The Code Snippets Manager replaces the PowerBuilder Classic Clip window, and allows
you to add XML snippets as well as PowerScript snippets. You can insert snippets from
the pop-up menu in painter Script views. The Code Snippet Manager is available from the
Tools menu.

Command window

You open the Command window from the View>Other Windows menu. It allows you to
execute commands from the design time environment. Intellisense is active in the Command window to assist you in scripting valid commands for your targets.

Document outline

The Document Outline view enables you to see a list of controls available in the current
painter. It replaces the Control List and Non-Visual Object List in PowerBuilder Classic,
but it also shows the control hierarchy. You can open the Document Outline view from the
View>Other Windows cascading menu.

Toolbox

Replaces the tool selection facility in the painter toolbars and Insert menu in PowerBuilder Classic. You open the toolbox from the PowerBuilder .NET View menu. You can
add or remove toolbox items from the Tools>Choose Toolbox Items menu.

Intellisense

Replaces PowerBuilder Classic autoscript, but also provides selections for classes, methods, and members of all assemblies included in target references. Intellisense is available
in painter Script views, in the XAML editor, from the Edit menu, and in the Command
window.

Properties window

The Properties window replaces the Properties view in PowerBuilder Classic painters. It
allows you to sort properties by category or alphabetically, and when opened from the
View>Properties Window menu, has a status line to describe a selected property.

Configuration

You open the Configruration Manager from the Properties pages dialog box for each
PowerBuilder .NET workspace/solution. Release and Debug configurations are provided
by default, although you can add and edit configurations from the Configuration Manager.
You can change the deployment platform for a particular configuration, and you can open
the Edit Project Configurations dialog box from the Configuration Manager to rename or
remove a configuration that you added.

PowerBuilder .NET Features Guide

Graphic User Interface

Visual Studio shell feature

Comment

Bookmark window

You can enable and toggle bookmarks in painter Script views or in the XAML editor from
the Edit>Bookmarks cascading menu. You open the Bookmark window from the
View>Other Windows cascading menu.

Find and Replace

The PowerBuilder .NET Find and Replace dialog box has tabs for Quick Find and Quick
Replace. It is available from the Edit>Find and Replace menu, and it allows you to
bookmark all items that match the Find string.

Layout view

The painter Layout views use the Visual Studio designer and are closely associated with
the XAML editor. A magnifier bar in the upper left corner of each Layout view allows you
to change the magnification of objects and controls at design time without changing their
size at runtime. The close (x) icon at top right corner closes only the current tab of the
painter. If you click this icon while the Layout view is current, the Layout tab closes and
the Script (code-behind) view becomes current.

File editor

The Open With dialog box replaces the File Editor in PowerBuilder Classic. It allows you
to select an editor for text in the Script views or XAML editor, or for current items in the
System Tree. It also allows you to add editors that you want to use to view these files, and
set a different editor as the default file viewing selection. You can open this dialog box
from the View>Open With menu item.

Text formatting

In PowerBuilder .NET, you can format text in painter Script views, in the XAML editor,
and in the Command window with the Edit>Advanced cascading menu items.

Task list

Replaces the PowerBuilder Classic To-Do List. You can open the Task list by selecting the
View>Other Windows>Task List menu item.

System Tree in PowerBuilder .NET

The System Tree in PowerBuilder .NET functions in many ways like the System Tree in PowerBuilder Classic, although
for some functionality it appears more like the Solution Explorer in Microsoft Visual Studio.
The System Tree is typically the central point of action in PowerBuilder programming. It provides access to all the objects
in a PowerBuilder workspace.
The System Tree inPowerBuilder Classic displays objects in PowerBuilder libraries (PBLs), whereas in
PowerBuilder .NET, the PBLs have been converted to directories, and the System Tree displays the contents of the PBL
directories only as separate files. The implementation of the PowerBuilder .NET System Tree as a Solution Explorer
extension has or enables several enhancements:

Integration with the Solution Explorer "Find" subsystem

Provision of a more natural framework for opening editors
Replacement of an ad-hoc framework for source control
Provision of a more natural framework for workspace and project persistence
Enabling extensions for things like code refactoring
Ability to drag and drop files from the Windows Explorer to targets and libraries
Listing of all assemblies used by a target in a single References folder
Ability to select a set of nodes to perform a common action, such as applying a comment or changing a common
writeable property
Ability to host targets with multiple application objects and to set one of those objects as the current application
object.

However, there is also System Tree functionality that is no longer available with the file orientation of the
PowerBuilder .NET System Tree. This includes:

Dragging and dropping objects to the PowerScript editor or painters

Using the System Tree to navigate directly to nested controls or specific methods and properties

Graphic User Interface

Displaying of the source control status of objects in the System Tree

Some functionality operates similarly in the PowerBuilder Classic System Tree and in the PowerBuilder .NET System
Tree. Double-clicking an item in the System Tree executes the default action for that item. Right-clicking an item opens
the pop-up menu for that item.
The following pop-up menu items on a PowerBuilder Classic System Tree object are not available in the System Tree in
PowerBuilder .NET:

PBNI Extensions
PowerBuilder .NET library nodes do not have the Import PowerBuilder Extension pop-up menu item for importing
PBNI extensions.
Optimize
In PowerBuilder Classic, the Optimize menu item provides a way to clean up deleted objects and items that have been
accumulated in target PBLs. This is not necessary in PowerBuilder .NET.
Migrate
The PowerBuilder Classic migrate capability assumes you can view a target in the System Tree that does not list
objects in an expanded PBL format. In PowerBuilder .NET, objects are always listed in an expanded format, so the
Migrate pop-up menu item is not necessary.
The other use of the Migrate pop-up menu is to regenerate PCode from the sources for an object, and this is also not
needed in PowerBuilder .NET.
Separate Library List and .NET Assemblies
Separate pop-up menu items for the library list and .NET assemblies are not needed inPowerBuilder .NETbecause of
their functional equivalence. Instead, a single pop-up menu item, "Library List", lists all PBLs and .NET assemblies
in PowerBuilder .NET targets.
Regenerate
Like the Optimize and Migrate pop-up menu items, the Regenerate menu item is not needed in the PowerBuilder .NET
System Tree because objects are always listed in an expanded format.

WPF Visual Controls in PowerBuilder

The system defined visual controls that you include in PowerBuilder .NET applications maintain the class hierarchy of
traditional PowerBuilder runtime controls, but the WPF controls are referenced in Extensible Application Markup
Language (XAML) files.
The following table maps PowerBuilder visual controls with their WPF equivalents:
Windows 32 Control

WPF Control Equivalent

CommandButton and PictureButton

Button

CheckBox

CheckBox

DataWindow

DataWindow WPF control

DropDownListBox and DropDownPictureListBox

ComboBox

EditMask

EditMask WPF control

Graph

Graph WPF control

GroupBox

GroupBox

HProgressBar and VProgressBar

ProgressBar

HScrollBar and VScrollBar

ScrollBar

HTrackBar and VTrackBar

Slider

InkPicture

InkCanvas

PowerBuilder .NET Features Guide

Graphic User Interface

Windows 32 Control

WPF Control Equivalent

ListBox and PictureListBox

ListBox

ListView

ListView

Menu

Menu/Toolbar

MenuCascade

Menu

MultilineEdit and SingleLineEdit

TextBox

Picture and PictureHyperLink

Image

RadioButton

RadioButton

RichTextEdit

RichTextBox

StaticHyperLink

HyperLink

StaticText

Label

Tab

TabControl

TreeView

TreeView

Window

Window/Grid

The following visual controls have no current WPF control equivalents: Animation, DateTimePicker, DragObject,
InkEdit, and MonthCalendar.

PowerBuilder .NET Toolbox

The Toolbox displays icons for controls that you can add to applications.
The Toolbox is available from the View menu. You can dock the Toolbox and either leave it pinned open or set it to Auto
Hide.
You can drag and drop an item onto a design surface (such as a window painter) or copy and paste it into a code editor
within PowerBuilder .NET. Either action adds the fundamental code to create an instance of the Toolbox item in the active
project file.
In PowerBuilder .NET, the Toolbar is initially provided with two tabs:
WPF
Workshop
Controls

Preloaded with PowerBuilder .NET-specific controls.

General

Initially, the General tab is empty, but you can add items that you want to store for later reuse, including
these kinds:

The list of controls depends on the object that has focus. For example, when a Window painter is active,
the controls that can be added to that painter become available in the Toolbar. If you change focus to a
different object, the items available in the Toolbar might change.

Controls
.NET Framework components
Your own or third-party components
Reusable text or code snippets

For example, you can highlight some code in a script window and drag it to the General tab to create a
reusable item. Or, you can copy an EventLog component and paste it in the toolbox. These items are
ready to be dragged from the General tab and dropped into the code editor or onto the active design
surface.
See the Toolbox topics in Visual Studio Help for details about basic Toolbox usage and customization.

10

Graphic User Interface

Toolbar WPF Controls
The WPF Controls tab contains the following PowerBuilder items:

Pointer
CommandButton
PictureButton
CheckBox
RadioButton
StaticText
StaticHyperlink
Picture
PictureHyperLink
GroupBox
Line
Oval
Rectangle
RoundRectangle
SingleLineEdit
EditMask
MultiLineEdit
RichTextEdit
HScrollBar
VScrollBar
HTrackBar
VTrackBar
HProgressBar
VProgressBar
DropDownListBox
DropDownPictureListBox
ListBox
PictureListBox
ListView
Treeview
Tab
DataWindow
Graph
MonthCalendar
DatePicker
Animation
InkEdit
InkPicture
OLE
UserObject

PowerBuilder Objects
The Toolbar PowerBuilder Objects tab contains the following non-visual items:

Name
AdoResultSet
Connection

PowerBuilder .NET Features Guide

11

Graphic User Interface

DataStore
DynamicDescriptionArea
DynamicStagingArea
Error
InternetResult
JaguarORB
MailSession
Message
MlSync
OleObject
OleStorage
OleStream
OleTxnObject
Pipeline
Profiling
SslCallback
Timing
TraceFile
TraceTree
Transaction
UlSync
UserObject

PB Object Outline
The PB Object Outline provides a convenient, single view for navigating and manipulating all the elements of a selected
object.
The view is available whenever a PowerBuilder object is open in the Designer.
To open the PB Object Outline, select an object in a PowerBuilder design window, then click View > OtherWindows
> PB Object Outline .
The PB Object Outline shows the elements of the currently selected object, which can be organized into groups such as
events, controls, and functions.
If you select a different object, an open PB Object Outline changes to show the new object's elements. If no PowerBuild
object is selected, the window is empty except for a message that an outline is not available for the active object.
If the object represented in the outline is under source control, it has a source control icon just as in the System Tree.
Element Icons
Each element in the PB Outline Tool has a static icon. For example, there are control, structure, and event icons. Some
elements, such as events, functions, .NET properties, and indexers, have an additional state icon.
.NET properties and indexer state icons have the same meaning as state icons in Event and Function lists. They reflect the
state of both get and set combined, because an element can represent both methods.
Navigating the Outline
You can navigate the PB Outline by expanding and collapsing groups of elements. Individual elements expand to show
any attributes and subcomponents. For example, you can expand a control to list its events. Non-visual objects expand to
events and functions, and custom user objects can expand to controls.

12

Graphic User Interface

You can also customize the way the outline displays and sorts items. The following navigation functions are available in
the PB Object Outline tool bar and menu, and in the view's context menu:
Sort Alphabetically (either ascending or descending)
Sort by Category
Sort by Type (element class or type)
Group by Category
Expand All
Collapse All
Changing sort and group settings in any PB Outline Tool view affects only the current view.
You can apply grouping and sorting independently. For example, if you disable Group by Category, the entire tree is
sorted. With Group by Category enabled, elements are sorted within each group.
Context menus vary for each element type. In addition to navigation functions, typical context menus also include
shortcuts for copying, pasting, deleting, adding, and editing items. For example, to edit a control, you can right-click it
in the outline and choose Go To Script. The control code opens in the Script view.
Sort and Display Options for Events and Functions
You can set the following sort and display options for events and functions:
Group by Category When enabled, (default), displays a heirarchical tree of elements. Sorting works within each
categeory. When disabled, displays a flat list of elements.
Show Ancestors

When enabled, includes ancestors for events, functions, indexers, and NET properties. When
disabled (the default) only locally scripted events or functions will be displayed for any of the
order schemes below.

Show Unscripted
WPF Events and
Functions

When enabled, includes events and functions for which no script has been created. When disabled
(default), only scripted events and functions are shown.

Problem Scripts
Rise to Top

When enabled (default), lists elements first whose scripts contain errors or warnings. When you
correct the propblem, the element reverts to its appropriate position in the list.
Choose one of the following order schemes:

Alphabetically
Scripted Local First
Lists local scripts first, followed by the remaining elements in alphabetical order.
Scripted Local, Scripted Ancestor, Unscripted (default)
Lists local scripts first, followed by ancestor scripts, and finally unscripted events or functions.
Scripted Anywhere, Unscripted

You can control these settings either globally or for the current PB Object Outline:

Set the options globally in the PowerBuilder Options page. The global settings apply to the System Tree, PB Object
Outline, and the Event and Function List views.
Within a PB Object Outline, right-click an event or function element and set the options in the context menu. Your
settings override those in the Options page.

Interface Outlines
The PB Object Outline for interface objects shows indexers, events, functions, and .NET properties.
Interfaces can inherit from other interfaces. When an object implements other interfaces, those interfaces expand to the
same information as the interface object. You can expand each level recursively until there are no more implemented
interfaces.

PowerBuilder .NET Features Guide

13

Graphic User Interface

Menu and Global Structure Outlines
For menu and global structure objects, items appear in the PB Object Outline in the same order as they are defined in the
menu, unless you sort them alphabetically.

New Dialog in PowerBuilder .NET

Use the New dialog box to create new PowerBuilder .NET workspaces, targets, and most of the objects you need for your
application.

Just as in PowerBuilder Classic, you click File > New to open the New dialog box. The New dialog box is changed in
PowerBuilder .NET: instead of tabbed pages, it has a single page where you can browse all the available objects. The New
dialog box includes these main areas:
Target

Allows you to choose the target in which a selected object will be created.

Filter

Lets you simplify the list by entering a filter expression that displays only a subset of available objects.
A simple filter expression is a string of characters. For advanced filtering, you can include any of the special
Match function characters. Expressions are not case-sensitive.
Examples:

wpf matches WPF and wpf.

listbox matches include DropDownListBox and DropDownPictureListBox.
^listbox matches only Listbox.
Button$ matches CommandButton, RadioButton, and PictureButton.
...x finds any three characters that are followed by x.

See Help on the Match function for details about special characters.
Object
view

The main part of the window contains a list of all the PowerBuilder object types that you can create, organized
into a hierarchy of folders. When you select an object, a brief description of it is displayed below the view.

New Object Creation

You double-click an object entry in the New dialog to create a new instance of the object.
For some objects, PowerBuilder .NET opens a wizard in which you can configure the object properties before creating
it. Other objects have no associated wizard. For these objects, PowerBuilder .NET creates an untitled instance
immediately. It then opens the object's associated editor, where you can specify the title and other properties.
The Previous and Next buttons let you navigate and step through the pages in the wizard. The Finish button is enabled
when you have entered enough information to create the selected object. This makes it possible to create some objects
quickly with minimal information: you can open an object in its editor later to add or modify properties.
New Dialog Customization
You can change which items the New dialog displays.

14

To remove an item, right-click its entry in the object view and choose Remove .
To restore items that have been removed, right-click a category folder and choose one of these actions:
Reset PB Object Category

Restores the removed objects in the category

Reset All

Restores all previously removed objects to the view.

Graphic User Interface

Skin Selection for Applications and Controls

At design time, you can select predefined and custom skins for PowerBuilder .NET applications and individual visual
controls. You can also allow customers to change skins on applications and controls at runtime.
The ability to apply different skins to PowerBuilder .NET controls allows you to create visually compelling applications
that can also be customized by application users. PowerBuilder provides predefined skins, but also allows you to select
custom skin files that use the XAML extension.
Predefined skins
"PBDefault" and "Metal" are predefined skins provided by PowerBuilder. The PBDefault skin defines the behavior and
simulates the appearance of visual controls in PowerBuilder classic. It also supports display themes that depend on system
selections for the design time or runtime computers. These include the standard Microsoft Windows themes, such as Aero
on Windows Vista, Luna on Windows XP, Royale on the Tablet PC, and Classic on all Windows operating systems.
Customized themes are also supported.
The Metal skin inherits from the PBDefault skin, which enables it to retain the behavior of all PowerBuilder controls.
However, it displays control surfaces with a metallic color, and its styles are not affected by the theme setting of the host
computer.
The Application object in all WPF Windows applications always has a skin, whether the application is migrated from a
PowerBuilder Classic target or created from scratch. By default, the skin of the Application object is set to PBDefault.
Visual controls are not assigned a skin by default. However, if you do not assign a skin to them, they inherit a skin setting
from their immediate parent. For example, if there is no skin defined for a CommandButton, it takes its parent control's
skin. The parent could be a GroupBox, TabPage, Window, or other container control. If the container controls do not have
assigned skins, the CommandButton uses the skin set in the Application object.
Note: Skin inheritance works only at runtime. If the Skin property is not set on a control, the skin of its container or the
Application object is not applied at design time.
Custom skins
You can create and select custom skins to affect the styles (colors, fonts, borders, and so on) of the visual controls in
PowerBuilder .NET applications. However, if you use a custom skin that you do not base on the predefined PBDefault
skin, you are likely to lose some of the controls' more complex behaviors that are embedded in the PBDefault skin's
XAML definitions.
Custom skin files must be added to the directory containing the application executable, or to a subdirectory of that
directory. You can select the custom skin for a control by assigning it to the Skin property for the control.
To use the custom skin at runtime, you must add the XAML file to a folder that you create under the target containing the
control. If the compile time Build Action property for the XAML file is set to "Content" (default), the XAML file is
deployed as a standalone file. If you set the Build Action property to "Embedded Resource", the XAML file is compiled
into the target assembly. Custom skins do not get applied at runtime if the Build Action property for the XAML file is set
to "None" when the project is deployed.
Skin property
The Skin property is available for all visual controls and for the Application object in a WPF Window target. You can set
the value of the Skin property in PowerScript code, or by entering it in the Properties view for a visual control or the
Application object. The Skin property is under the General category in the Properties view when you display properties
by category.
The datatype of the Skin property is string. You can set this property to a predefined system skin, or to a custom skin file
with a XAML extension.
This example sets an application-level skin to the predefined Metal skin:
PowerBuilder .NET Features Guide

15

Graphic User Interface

applicationName.Skin = Metal
The following example sets a window-level skin to an external file:
w_main.Skin = skin1.xaml

PowerBuilder .NET Painters

In PowerBuilder .NET as in PowerBuilder Classic, you edit objects, such as applications, windows, and menus, in
painters. However, because of its full support for the Common Language Specification, PowerBuilder .NET also includes
painters that are not available in PowerBuilder Classic.

About the Enumeration Painter

The Enumeration painter is similar to Structure painter. You can use the painter to define global enumerations for your
applications or components, and to define local enumerations for objects in your applications or components.
Each row in the Enumeration painter represents an item in the enumeration you are defining. The rows contain editable
text cells under three columns: Name, Value, and Comments. You must specify a name for each item you want to include
in the enumeration. If you do not enter a value for an item, PowerBuilder enters it for you by adding one to the previous
value.
If you select the Flags check box in the Enumeration painter, the values for each item in the enumeration are treated as
bit fields.
When the Enumeration painter is active, the PowerBuilder .NET Edit menu includes two additional items: Insert Row and
Delete Row. The Insert Row item adds an empty row before the current row and the sequential values in the rows after the
empty row are automatically adjusted upwards. The Delete Row item removes the current row and the values in the rows
following the deleted row are adjusted downwards sequentially.
You can change the order of rows in the Enumeration painter by cutting and pasting rows, or by dragging and dropping
the current row to another position. When you reorder the rows, all rows affected by these actions are modified to maintain
sequential values.
The Enumeration painter for local enumerations has one additional field that is not present in the painter for global
enumerations. This is the Enumeration Name field where you enter the name you want for the local enumeration. The
global enumeration is saved as a file when you select the File>Save menu. The extension for a global user-defined
enumeration that you save in the Enumeration painter is .sre.

About the Interface Painter

You can create interfaces in the Interface painter. It is similar to the Custom Class (nonvisual object) painer, with a few
notable differences.
You can define functions, events, indexers, and .NET properties for interfaces using the prototype pane of the Interface
painter. However, the scripting area of the painter is noneditable, since scripting is not allowed for the members of an
interface. The scripting must be done in the objects that implement the interface.
The fields of the prototype pane are the same as those for other painters. However, for functions that you create in the
Interface painter, the Access and Throw fields are grayed. Access is always public for interfaces. Also, you cannot select
Enumerations or Structures for interfaces.
When you select Declare in the upper left drop-down list of the Interface painter, you can select only Namespace and
Interfaces in the second drop-down list. You cannot declare global, instance, or shared variables for an interface.

Window Painter in PowerBuilder .NET

You design windows in the Window painter. The Window painter has several views where you specify how a window
looks and how it behaves.

16

Graphic User Interface

The default layout for the Window painter workspace has two tabs:

The Layout view, where you design the appearance of the window and edit the XAML
The Script view, where you modify behavior by coding window and control scripts

Building a New WPF Window

You can build a window from scratch. You would use this technique to create windows that are not based on existing
windows.
When you build a window, you:

Specify the appearance and behavior of the window by settings its properties
Add controls to the window
Build scripts that determine how to respond to events in the window and its controls
To support these scripts, you can define new events for the window and its controls, and declare functions, structures,
and variables for the window.

Creating a New WPF Window

You can create a WPF Window from scratch.
Note: At any point during the creation process, you can click the Finish button (if it is enabled) to create the window by
accepting the default settings for the later steps.
To create a new WPF window:
1. Open the New dialog box.
2. In the PB Object node, select WPF Window.
3. Click the Next button.
The WPF Window wizard opens.
4. Enter a title and a name for the window. Select the library in which to save the window. Click the Next button.
5. Select the layout for the window and then click the Next button.
Options

Description

Canvas

A canvas defines an area within which you can explicitly position child elements by coordinates relative
to the canvas area.

Dock Panel

A dockpanel defines an area within which you can arrange child elements either horizontally or
vertically, relative to each other.

Grid

A grid defines a flexible grid area consisting of columns and rows. Child elements of a Grid can be
positioned precisely using the Margin property.

Stack Panel

A stackpanel arranges child elements into a single line that can be oriented horizontally or vertically.

Virtualizing Stack
Panel

This is the same layout as StackPanel, but data bound to controls, like listboxes, are only created as
needed when visible.

Wrap Panel

A wrappanel positions child elements in sequential position from left to right, breaking content to the
next line at the edge of the containing box.

6. You can specify the Namespace, Using, and Interface, then click the Next button.
7. Review the WPF window characteristics and then click Finish.
The Window painter opens. The new window displays in the Window painter's Layout view and the XAML defining the
Window are shown in the XAML view.
Defining the WPF Window Propeties
Every window and control has a style that determines how it appears to the user. You define a window's style by choosing
settings in the Window painter's Properties view.

PowerBuilder .NET Features Guide

17

Graphic User Interface

A window's style encompasses its:

Type
Basic appearance
Initial position on the screen
Icon when minimized
Pointer

Note: You can also edit the properties in the XAML view.
1. Click the window's background to display the window's properties in the Properties view.
2. Choose the category appropriate to the property you want to specify.
To specify the window's

Choose this category

Name, type, state, color, and whether a menu is associated with it

PBGeneral

Icon to represent the window when you minimize it

PBGeneral

Transparency

PBGeneral

Opening and closing animation styles

PBGeneral

Position and size when it displays at runtime

PBOther

Default cursor whenever the mouse moves over the window

PBOther

Horizontal and vertical scroll bar placement

PBScroll

Toolbar placement

PBToolbar

Adding Controls to WPF Windows

You can add controls to a WPF Window by using the Toolbox or editing the XAML.
When you build a window, you place controls in the window to request and receive information from the user and to
present information to the user.
After you place a control in the window, you can define its style, move and resize it, and write scripts to determine how
the control responds to events.
1. Select the control you want to insert from the Toolbox.
2. In the Layout view, click where you want the control.
After you insert the control, you can size it, move it, define its appearance and behavior, and create scripts for its events.

MDI Applications in PowerBuilder .NET

Multiple Document Interface (MDI) is an application style you can use to open multiple windows (called sheets) in a
single window and move among the sheets.
To build an MDI application, you define a window whose type is MDI Frame and open other windows as sheets within
the frame. In a WPF application, these sheets open as tabbed documents.
Some topics are covered here. For more information, see Application Techniques.
MDI frame windows
An MDI frame window is a window with several parts: a menu bar, a frame, a client area, sheets, and (usually) a status
area, which can display MicroHelp (a short description of the current menu item or current activity).

18

Graphic User Interface

Client area
In a standard frame window, PowerBuilder sizes the client area automatically and the open sheets display within the client
area. In custom frame windows containing objects in the client area, you must size the client area yourself. If you do not
size the client area, the sheets will open, but may not be visible.
When you build an MDI frame window, PowerBuilder creates a control named MDI_1, which it uses to identify the client
area of the frame window. In standard frames, PowerBuilder manages MDI_1 automatically. In custom frames, you write
a script for the frame's Resize event to size MDI_1 appropriately. Code is also added to the XAML for the window.
Tabbed interface
Sheets open as tabs in the client area of a WPF frame window. You can use any type of window except an MDI frame as
a sheet in an MDI application. To open a sheet, use either the OpenSheet or OpenSheetWithParm function.
Building an MDI Frame Window
When you create a new window in PowerBuilder, its default window type is Main. Select Mdi! or MdiHelp! in the
PBGeneral property category to change the window to an MDI frame window.
When you change the window type to MDI, you must associate a menu with the frame. Menus usually provide a way to
open sheets in the frame and to close the frame if the user has closed all the sheets.
Note: A sheet can have its own menu but is not required to. When a sheet without a menu is opened, it uses the frame's
menu.
1.
2.
3.
4.
5.
6.
7.
8.

Click the New button in the PowerBar.

Select WPF Window and click Next.
Enter a window title and name, then click Next (or Finish).
(Optional) Select the layout and click Next (or Finish).
(Optional) Select a namespace and click Next (or Finish).
Click Finish.
When the window object is selected, open the Properties view.
In the PBGeneral category, set the WindowType property to Mdi! or MdiHelp!

Using Sheets in a PowerBuilder .NET Application

In an MDI frame window, users can open sheets to perform activities. All sheets can be open at the same time and the user
can move among the sheets, performing different activities in each sheet.
Note: A sheet can have its own menu but is not required to. When a sheet without a menu is opened, it uses the frame's
menu.
To open a sheet in the client area of an MDI frame, use the OpenSheet function in a script for an event in a menu item,
an event in another sheet, or an event in any object in the frame.
For more information about OpenSheet, see the PowerScript Reference.

Menus and Toolbars in PowerBuilder .NET

By adding customized menus and toolbars to your applications, you can make it easy and intuitive for your users to select
commands and options.
Menus and Menu Items
Usually, all windows in an application have menus except child and response windows. Menus are lists of related
commands or options (menu items) that a user can select in the currently active window. Each choice in a menu is called
a menu item. Menu items display in a menu bar or in drop-down or cascading menus.
Each item in a menu is defined as a Menu object in PowerBuilder.
PowerBuilder .NET Features Guide

19

Graphic User Interface

Using menus
You can use menus you build in PowerBuilder in two ways:

In the menu bar of windows: Menu bar menus are associated with a window in the Window painter and display
whenever the window is opened.
As pop-up menus: Pop-up menus display only when a script executes the PopMenu function.

Designing menus
PowerBuilder gives you complete freedom in designing menus, but you should follow conventions to make your
applications easy to use. For example, you should keep menus simple and consistent; group related items in a drop-down
menu; make sparing use of cascading menus and restrict them to one or two levels.
A full discussion of menu design is beyond the scope of this documentation. You should acquire information that
specifically addresses design guidelines for graphical applications and apply the rules when you use PowerBuilder to
create your menus.
Building menus
When you build a menu, you:

Specify the appearance of the menu items by setting their properties.

Build scripts that determine how to respond to events in the menu items. To support these scripts, you can declare
functions, structures, and variables for the menu.

There are two ways to build a menu. You can:

Build a new menu from scratch. See the topic Building a New Menu.
Build a menu that inherits its style, functions, structures, variables, and scripts from an existing menu. You use
inheritance to create menus that are derived from existing menus, thereby saving yourself coding and time. See the
topic Using Inheritance to Build a Menu.

Menu Painter in PowerBuilder .NET

The Menu painter has several views where you can specify menu items and how they look and behave.
In addition to customizing the style of a menu in the Menu painter, you can also customize the style of a toolbar associated
with a menu. For information, see the Providing Toolbars in PowerBuilder .NET topic.
Menu Painter Views
There are several views that you use to create a menu.
You use two views to specify menu items that display in the menu bar and under menu bar items:
This view

Displays

Tree Menu view

All the menu items at the same time when the tree is fully expanded.
Note: In-place text editing is not enabled for Beta. Edit menu names using the Properties view.

WYSIWYG Menu view

The menu as you will see it and use it in your application, with the exception of invisible menu
items that do display.

The Tree Menu view and the WYSIWYG Menu view are equivalent. You can use either view to insert new menu items
on the menu bar or on drop-down or cascading menus, or to modify existing menu items. The menus in both views change
when you make a change in either view.
The two views are separated by a grid splitter. You can resize the views as needed, or hide one view entirely.
You specify menu properties in two views:

20

Graphic User Interface

This view

Displays

Properties view (for the top-level

menu object)

General, Appearance and Toolbar categories for setting menu-wide properties

Properties view (for menu items)

Name, Menu Item, and Toolbar Item categories for setting properties for submenu items and
toolbars

Views for the Top Level Menu Object

When you select the top-level menu item in the Tree Menu view, you can set its properties.
This Menu painter layout is for the top level menu object, m_pbapp_frame. The Tree Menu view is on the left and the
WYSIWYG Menu view is in the middle. The Properties view displays the General, Appearance and Toolbar categories
on the right.

Views for Submenu Items

When you select the menu items in the Tree Menu view, you can set their properties.
This Menu painter layout is for a menu item under the top level, in this case the Open menu item. The Tree Menu view
is on the left and the WYSIWYG Menu view is in the middle. The Name, Menu Item, and Toolbar Item categories display
in the Properties view on the right.

PowerBuilder .NET Features Guide

21

Graphic User Interface

Menu Styles in PowerBuilder .NET

A menu can have a contemporary or traditional style.
Menus that you import or migrate from earlier versions of PowerBuilder have the traditional style, and new menus use the
traditional menu style by default.
Menu style

Description

Contemporary

A 3D-style menu similar to Microsoft Office 2003 and Visual Studio 2005 menus

Traditional

Window default menu style which has a flat appearance

The contemporary menu style has a three-dimensional menu appearance that can include images and menu title bands.
With a contemporary menu, you can set the MenuAnimation, MenuImage, and MenuTitleText at runtime using scripts.
You select a menu style in the Appearance category of the Properties view for the top-level menu object in the Menu
painter. You must select the top-level menu object in the Tree Menu view of the Menu painter to display its Properties
view.
If you select contemporarymenu! in the Menu Style drop-down list, you can customize the display properties for that
style and have them apply to all menu items in the current menu. If you select traditionalmenu! the rest of the menu
style properties do not apply.
For more about using images for menus and toolbars, please refer to the PowerBuilder Users Guide.
Building a New Menu in PowerBuilder .NET
You can build menus that are not based on existing menus.

22

Graphic User Interface

Creating a New Menu

You build a new menu by creating a new Menu object and then working on it in the Menu painter.
To create a new menu:
1. Click the New button in the PowerBar.
2. In the PB Object category, select Menu.
3. Click Finish.
The Menu painter opens and displays the Tree Menu view and the WYSIWYG view for defining the menu, the General,
Appearance and Toolbar catgeories for setting menu and toolbar properties.
Because you are creating a new menu and have not added menu items yet, the only content is an untitled top-level tree view
item in the TreeMenu view.
Working with Menu Items in PowerBuilder .NET
A menu consists of at least one menu item on the menu bar and menu items in a drop-down menu.
You can add menu items in three places:

To the menu bar

To a drop-down menu
To a cascading menu

How menu items are named

When you add a menu item, PowerBuilder gives it a default name, which displays in the Name box in the Properties view.
This is the name by which you refer to a menu item in a script.
The default name is m_itemn , where n is the lowest number that can be combined with the prefix to create a unique
name.
Menu items in the Tree Menu view and WYSIWYG Menu view can have the same names, but they cannot have the same
name in the Properties view.
Inserting Menu Items
There are three Insert choices in the context menu: Insert Menu Item, Insert Menu Item At End, and Insert Submenu Item.
Use the first two to insert menu items in the same menu as the selected item, and use Insert Submenu Item to create a new
drop-down or cascading menu for the selected item.
Suppose you have created a File menu on the menu bar with two menu items: Open and Exit. Here are the results of
some insert operations:

Select File and select Insert Menu Item At End from the pop-up menu
A new item is added to the menu bar after the File menu.
Select Open and select Insert Menu Item from the pop-up menu
A new item is added to the File menu above Open.
Select Open and select Insert Menu Item At End from the pop-up menu
A new item is added to the File menu after Exit.
Select Open and select Insert Submenu Item from the pop-up menu
A new cascading menu is added to the Open menu item.

The first thing you do with a new menu item is add the first item to the menu bar. After doing so, you can continue adding
new items to the menu bar or to the menu bar item you just created. As you work, the changes you make display in both
the WYSIWYG and Tree Menu views.
Inserting the First Menu Bar Item in a New Menu
PowerBuilder .NET Features Guide

23

Graphic User Interface

You can add a menu bar item and work on its drop-down menu.
This procedure describes how to add a single first item to the menu bar. Use this procedure if you want to add the menu
bar item and then work on its drop-down menu.
1. Select the first menu item, and then select Insert Submenu Item from the context menu.
PowerBuilder displays the text none in the menu bar in the WYSIWYG Menu view and as a sub-item in the Tree
Menu view.
2. In the Properties view, enter the text you want for the menu item in the Name category Text box and then press Enter.
Inserting Additional Menu Items on the Menu Bar
You can insert additional menu items to the end of the menu or before the selected item.
Use this procedure to insert additional menu items on the menu bar.
1. Do one of the following

With any menu bar item selected, select Insert Menu Item At End from the context menu to add an item to the end
of the menu bar.
Select a menu bar item and select Insert Menu Item from the context menu to add a menu bar item before the
selected menu bar item.
2. In the Properties view, enter the text you want for the menu item in the Name category Text box and then press Enter.
Adding an Item to the End of a Menu
You can add items to the end of menus.
Use this procedure to add an item to the end of any menu.
1. Select any item on the menu.
2. Select Insert Menu Item At End from the context menu.
PowerBuilder displays the text none.
3. In the Properties view, enter the text you want for the menu item in the Name category Text box and then press Enter.
Inserting an Item in an Existing Menu
You can insert an item in a menu.
Use this procedure to insert an item in any existing menu:
1. Select the item that should follow the new menu item.
2. Select Insert Menu Item from the context menu.
The word none displays above the item you selected.
3. In the Properties view, enter the text you want for the menu item in the Name category Text box and then press Enter.
Creating Separation Lines in Menus
Use separation lines to separate groups of related menu items with lines.
You should use lines to separate groups of related items.

24

Graphic User Interface

1. Insert a new menu item where you want the separation line to display.
2. Type a single dash (-) as the menu item text and press Enter.
A separation line displays.
Changing Menu Item Text
It is often necessary to change the text of a menu item.
To change the text of a menu item:
1. Select the item and open the Name category in the Properties view.
2. Type the new text for the menu item in the Text box in the Properties view.
Navigating in the Menu
You can select items in the Tree Menu or WYSIWYG view using the mouse or keyboard.
As you work in a menu, you can move to another menu item by selecting it. You can also use the Right Arrow, Left Arrow,
Up Arrow, and Down Arrow keys on the keyboard to navigate.
Deleting Menu Items
You can delete menu items.
To delete a menu item:
1. Select the menu item you want to delete.
2. Select Delete from the pop-up menu.
Saving the Menu in PowerBuilder .NET
You can save the menu you are working on at any time. When you save a menu, PowerBuilder saves the compiled menu
items and scripts in the library you specify.
The menu name can be any valid PowerBuilder identifier. For information about PowerBuilder identifiers, see the
PowerScript Reference.
A common convention is to use m_ as a standard prefix, and a suffix that helps you identify the particular menu. For
example, you might name a menu used in a sales application m_sales.
To save a menu:
1. Select File>Save from the menu bar.
If you have previously saved the menu, PowerBuilder the new version in the same library and returns you to the Menu
painter. If you have not previously saved the menu, PowerBuilder displays the Save Menu dialog box.
2. Name the menu in the Menus box (if you are saving a new menu).
3. Write comments to describe the menu.
These comments display in the Select Menu dialog box and in the Library painter. It is a good idea to use comments
so you and others can easily remember the purpose of the menu later.
4. Specify the library in which to save the menu and click OK.
Menu Item Appearance and Behavior in PowerBuilder .NET
By setting menu properties, you can customize the display of menus in applications that you create with PowerBuilder.
You use the Menu painter to change the appearance and behavior of your menu and menu items by choosing different
settings in the Properties view categories. For a list of all menu item properties, see Objects and Controls.
General Properties for Menu Items in PowerBuilder .NET
There are properties you can set when you select a menu item and then select the Menu Item category in the Properties
view.
PowerBuilder .NET Features Guide

25

Graphic User Interface

For information on using the menu properties, refer to the PowerBuilder Users Guide.
Shortcut Keys in Menus in PowerBuilder .NET
You can define shortcut keys for menu items.
Note: Accelerator keys are not enabled in Beta.
You can define shortcut keys, which are combinations of keys that a user can press to select a menu item whether or not
the menu is displayed.
You should adopt conventions for using shortcut keys in your applications. All commonly used menu items should have
shortcut keys.
Assigning a Shortcut Key to Menu Items
You can assign shortcut keys to menu items.
If you specify the same shortcut for more than one MenuItem, the command that occurs later in the menu hierarchy is
executed.
Some shortcut key combinations, such as Ctrl+C, Ctrl+V, and Ctrl+X, are commonly used by many applications. Avoid
using these combinations when you assign shortcut keys for your application.

1. Select the menu item to which you want to assign a shortcut key.
2. In the Menu Item category in the Properties view, select a key from the ShortcutKey drop-down list.
3. Change ShortcutAlt, ShortcutCtrl, and/or Shortcut Shift to True to create a key combination.
PowerBuilder displays the shortcut key next to the menu item name.
Providing Toolbars in PowerBuilder .NET
To make your application easier to use, you can add toolbars with buttons that users can click as a shortcut for choosing
an item from a menu.
For information on setting the toolbar properties, see the PowerBuilder Users Guide.
Adding Toolbars to a Window
To define toolbars for windows, select pictures for menu commands and then PowerBuilder generates toolbars.
PowerBuilder provides an easy way to add toolbars to a window: when you are defining an item in the Menu painter for
a menu that will be associated with a frame window, sheet, or a main window, you simply specify that you want the menu
item to display in the toolbar with a specific picture. At runtime, PowerBuilder automatically generates a toolbar for the
window containing the menu.
1. In the Menu painter, specify the display characteristics of the menu items you want to display in the toolbar.
For details see Toolbar item display characteristics in the PowerBuilder Users Guide.
2. (Optional) In the Menu painter, specify drop-down toolbars for menu items.
3. In the Window painter, associate the menu with the window and turn on the display of the toolbar.
4. (Optional) In the Window painter, specify other properties, such as the size and location of a floating toolbar, on the
Toolbar property page.
Selecting a Toolbar Style
You select a toolbar style in the Toolbar category of the Properties view for the top-level menu object in the Menu painter.
Toolbars can have a contemporary or traditional style.
26

Graphic User Interface

Toolbar style

Description

Contemporary

A 3D-style toolbar similar to Microsoft Office 2003 and Visual Studio 2005

Traditional

A more traditional and older toolbar style

Toolbars that you import or migrate from earlier versions of PowerBuilder have the traditional style, and new toolbars use
the traditional toolbar style by default.
1. Select the top-level menu object.
2. In the Toolbar category of the Properties view, select the toolbar style you want, traditionaltoolbar! or
contemporarytoolbar!

PowerBuilder .NET Features Guide

27

Graphic User Interface

If you select traditionaltoolbar! in the ToolbarStyle drop-down list, the rest of the toolbar style properties are
grayed. If you select contemporarytoolbar! style, you can customize the display properties for that style and have
them apply to all menu items with associated toolbar buttons in the current menu.
Unless you are using the traditional toolbar style for the current menu object, you can set the ToolbarAnimation property
in the Properties view for each menu item. If you do not select an image for the ToolbarItemName property of a menu item,
the selection you make for the ToolbarAnimation property is ignored.
Writing Scripts for Menu Items in PowerBuilder .NET
You write scripts for menu items in the Script view. The scripts specify what happens when users select a menu item.
To write a script for a menu item, select Script from the menu item's pop-up menu. The Script view displays for the clicked
event, which is the default event for a menu item.
For information on writing scripts for menu item events, using functions and variables, and referring to objects in your
application, see the PowerBuilder Users Guide.
Using Inheritance to Build a Menu
When you build a menu that inherits its style, events, functions, structures, variables, and scripts from an existing menu,
you save coding time. All you have to do is modify the descendent object to meet the requirements of the current situation.
To use inheritance to build a descendent menu:
1. In the System Tree, select the menu from which you want to inherit.
2. From the context menu, select Inherit from.
The new menu opens in the Menu painter.
3. Make the changes you want to the descedent menu.
See the section on using inherited information in the PowerBuilder Users Guide.
4. Save the menu under a new name.
For information on working with inherited menus, see the PowerBuilder Users Guide.
Using Menus in Your PowerBuilder .NET Applications
You can use menus as the window menu bar or as pop-up menus.
Adding a Menu Bar to a Window
To have a menu bar display when a window is opened by a user, you associate a menu with the window in the Window
painter.
To associate a menu with a window:
1. Click the Open button in the PowerBar, select the window with which you want to associate the menu, and open the
window.
2. Do one of the following:

In the Properties view for the window, enter the name of the menu in the MenuName text box in the PBGeneral
category.
Click the Browse button and select the menu from the Select Menu dialog box, which lists all menus available to
the application.

In the Select Object dialog box, you can search for a menu by clicking the Browse button.
3. Click Save to associate the selected menu with the window.
Add and Change Menu Bars Using Scripts
You can use PowerScript to assign and change menu bars in Windows.

28

Graphic User Interface

Identifying menu items in window scripts
You reference menu items in scripts in windows and controls using the following syntax:
menu.menu item
You must always fully qualify the menu item with the name of the menu.
When referring to a menu item in a drop-down or cascading menu, you must specify each menu item on the path to the
menu item you are referencing, separating the names with periods.
For example, to refer to the Enabled property of menu item m_open, which is under the menu bar item m_file in the
menu saved in the library as m_menu, use:
m_menu.m_file.m_open.Enabled
Changing a window's menu at runtime
You can use the ChangeMenu function in a script to change the menu associated with a window at runtime.
Displaying Pop-up Menus in Windows
To display a pop-up menu in a window, use the PopMenu function to identify the menu and the location at which you want
to display the menu.
If the menu is currently associated with the window, you can simply call the PopMenu function.
The following statement in a CommandButton script displays m_appl.m_help as a pop-up menu at the current pointer
position, assuming m_appl is already associated with the window:
m_appl.m_help.PopMenu(PointerX(), PointerY())
If the menu is not already associated with the window, you must create an instance of the menu before you can display
it as a pop-up menu.
The following statements create an instance of the menu m_new, then pop up the menu my_menu.m_file at the pointer
location, assuming m_new is not associated with the window containing the script:
m_new mymenu
mymenu = create m_new
mymenu.m_file.PopMenu(PointerX(), PointerY())

User Objects
Applications often have features in common. If you find youself using the same application feature repeatedly, you should
define a user object; you define the user object once in the User Object painter and use it as many times as you need.
For example, you might often reuse features like the following:

A processing package that calculates commissions or performs statistical analysis

A Close button that performs a certain set of operations and then closes the window
DataWindow controls that perform standard error checking
A list that includes all departments
A predefined file viewer that you plug into a window

Third-Party and Custom Controls in PowerBuilder .NET

You can use custom WPF controls, third-party WPF controls, and Windows Form controls in PowerBuilder .NET.
You can use custom and third-party controls in WPF Windows and DataWindow objects. Using custom and third-party
controls allows you to extend the software system to support a wider range of applications and meet varied requirements.
WPF Controls in DataWindow objects
In DataWindow objects, you insert custom and third-party WPF controls using the CustomControl component.
PowerBuilder .NET Features Guide

29

Graphic User Interface

The third-party control encapsulated in the CustomControl may have different capabilities of presenting and processing
data. If the third-party control is able to present data (e.g., a TextBlock), CustomControl feeds data to this third-party
control; if the third-party control is able to modify data (e.g., a TextBox) CustomControl will retrieve modified data from
the third-party control.
WPF Controls in Windows
If the custom control defines some public events, public events will be dynamically added into the event list of the custom
control. You can define your own event handler source code to any event of a WPF control.
WinForm Controls in Windows
You can also add custom or third-party controls to windows.
Adding WPF Controls to the PowerBuilder .NET Toolbox
You can choose which components appear in the Toolbox. This also allows you to use third-party and custom WPF
controls.
The contents of the Toolbox are related to the object that has focus. For example, the Toolbox controls for the DataWindow
painter are different from those for the Window painter. Be sure that the appropriate object is selected before adding a
WPF control to the Toolbox.
1.
2.
3.
4.
5.

In the Toolbox, select the group to which you want to add the WPF control.
Right-click in the Toolbox group and select Choose Items.
Select the WPF Components tab.
You can select a standard WPF control in the tab, or use the Browse button to select your own WPF control.
Click OK.
The WPF control is added to the Toolbox.

Adding Third-Party and Custom WPF Controls to PowerBuilder .NET Windows

You can add third-party and custom WPF controls to objects.
Using the Toolbox, you can add WPF controls to the window.
1. If you have not already done so, add the WPF control to the toolbox.
See Adding WPF Controls to the PowerBuilder .NET Toolbox.
2. Select the control in the toolbox, and then click in the window where you want to place the control.
The control is added to the window, and the XAML code for the control is added to the code for the window.
Adding Third-Party and Custom WinForm Controls in PowerBuilder .NET Windows
You can add third-party and custom WinForm controls to objects.

1. Open the File menu and select New.

You can also click the New button on the PowerBar.
2. External Visual Control and click the Next button.
The wizard opens.
3. Select the library to which you want to add the control and click Next.
4. Select the assembly file that contains the third-party or custom WinForm control you want. Click the Next button.
5. Select the control and click the Finish button.
Adding Custom and Third-Party Controls to DataWindow Objects
You can add custom and third-party controls to DataWindow objects using the CustomControl. You can also add controls
that are in the Toolbox directly.
30

Graphic User Interface

In PowerBuilder .NET, you can add built-in WPF controls and user-developed controls.
1. Select Custom Control in the Toolbox (found in the DataWindow Controls group).
2. Click on the location in the DataWindow where you want to place the custom control.
The Select Custom Control dialog box opens.
3. Do one of the following:

Click the ellipsis button next to the From File field and then navigate to the location of the XAML file defining the
custom control.
Click the ellipsis button next to the From Assembly field and then select the control.

PowerBuilder .NET Features Guide

31

Graphic User Interface

32

PowerBuilder .NET Targets and Projects

PowerBuilder .NET Targets and Projects

In PowerBuilder .NET, as in PowerBuilder Classic, you can work with one or more targets in a workspace. Each target
can contain multiple projects that can be separately configured for different runtime platforms or build types (such as
debug or release builds)
A PowerBuilder .NET workspace can have the following target types:

WPF Window Application

.NET Assembly (Not enabled in beta1)
.NET Web Service (Not enabled in beta1)

A WPF Window Application target can support WPF Window Application projects and WCF Client Proxy projects.
The only project type available for .NET Assembly targets is the .NET Assembly project type. The only project type
available for .NET Web Service targets is the .NET Web Service project type.

Deployment Requirements for .NET Component Targets

At runtime, the .NET assemblies and Web Services that you generate from .NET component target types execute using
the .NET Common Language Runtime (CLR).
Note: .NET component targets are not enabled in PowerBuilder .NET for the beta1 release. They will be ported from
PowerBuilder Classic to PowerBuilder .NET after the beta.
For deployment of .NET target types, production servers or target computers must have the following:

Windows XP SP2, Windows 2003, Windows Vista, or Windows 2008 operating system
.NET Framework 2.0 or later
The Microsoft Visual C++ runtime libraries msvcr71.dll and msvcp71.dll and the Microsoft .NET Active
Template Library (ATL) module, atl71.dll
PowerBuilder .NET assemblies in the global assembly cache (GAC)
PowerBuilder runtime dynamic link libraries in the system path
For more information on the required runtime files, see Deploying PowerBuilder runtime files in the Deploying
Applications to .NET book for PowerBuilder Classic.

For .NET Web Service targets, production servers must also have:

IIS 5, IIS 6, or IIS 7

ASP.NET
ASP.NET permissions for all files and directories used by your components

For information on configuring IIS, selecting the default ASP.NET version, and examples of how to grant ASP.NET user
permissions, see the first chapter in the Deploying Applications to .NET book for PowerBuilder Classic.

Creating a WPF Window Target

Use the New WPF Target wizard to create a WPF Window application target.
You can create a WPF Window application target from scratch, or by converting a PowerBuilder Classic Win32 or
Winform target.
1. Click File > New in the menu or the New button in the toolbar.
2. In the New wizard, expand the Target folder. Select the WPF Window Application target and click Next.

PowerBuilder .NET Features Guide

33

PowerBuilder .NET Targets and Projects

3. In the Create the application page, select one of these options and click Next:

Create a new application and target

Convert an existing PowerBuilder Classic Win32 or Winform target to WPF
Note: If the existing target was created in an earlier version of PowerBuilder, upgrade it in PowerBuilder Classic
by following the guidelines in the Migration information section of the current Release Bulletin. You can then
convert the upgraded version in PowerBuilder .NET using this procedure.

4. Follow the remaining instructions of the New WPF Target wizard and click Finish.
The New WPF Target wizard creates a project object and a target and a that allows you to deploy the application.
Tip: When the Finish button is enabled at any point in this procedure, you can click it to skip the remaining steps and
create a target with just the values you have provided. You can add or change values in the target painter later.

WPF Window Target Properties

You can enter properties for WPF Window targets in the New WPF Target wizard or in the Target painter.
Creating a WPF Window target from scratch
For WPF Window targets that you create from scratch, provide the information described in the following table:
Table 1. Wizard fields for a WPF Window target created from scratch
Wizard field

Description

Application name

Name of the application object to be created. By default, the

application name is also used for the library and target.
Example: wpfapp

Library

Name and location of the PowerBuilder library to be created. By

default, this includes the current Workspace path, the application
name you chose, and a PBL extension.
Example: C:\Documents and Settings\jane-

doe\My Documents\pbnet\wpfapp.pbl
Target

Name and location of the target to be created. By default, this

includes the current Workspace path, the application name you
chose, and a PBTX extension.
Example: C:\Documents and Settings\jane-

doe\My Documents\pbnet\wpfapp.pbtx
Project name

Name of the project object to be created.

Example: p_wpfapp_wpf

Product name

Product name to be associated with this target. Example: My

WPF Application

Product executable filename

Name of the runnable file for this target.

Product version

Major, Minor, Build, and Revision version numbers to be associated with this target.

Resource files and directories

Optionally, identify resource files and folders that are not compiled with the target but need to be delivered with the application.
Use the browser buttons to select individual files, directories, or
contents in PBR resource files.

34

PowerBuilder .NET Targets and Projects

Wizard field

Description

Resource dictionaries

Optionally, identify WPF resource dictionaries that the application will use.

Publish as smart client application?

Select this option to configure smart client publishing properties

in subsequent Wizard pages. For example, select this option if
you want to publish the application to an FTP site.

Application running mode (for smart client only)

Choose one of these options:

Yes The application can be run either locally (on the user's
computer) or from a remote site.
No

Install options (for smart client only)

The application will installed on a web site or shared

path; not locally.

Choose one of these options:

From web site

Specify the Web site URL. Example: http://

localhost/wpfapp

From shared
path

Specify the path where a user can find and

install the application.

Specify this option the application will be

From CDROM or DVD- provided on one of these media.
ROM
Update options (for smart client only)

How does the application check for the latest version and update?
Choose one of these options:

Update frequency (for smart client only)

Never check for updates

Check for updates before application starts
Check for updates after application starts
If you choose this option, also specify the update frequency.

Choose one of these options:

Every time application starts

At least n interval from last update. Enter a positive number
for the frequency n. Choose days, hours, or weeks as the
interval.

Creating a WPF Window target from an existing target

When you create a WPF Window target from an existing target, most of the wizard fields are the same as those for creating
a target from scratch, but a few few fields are added or changed. The following table describes only the new or changed
fields.
Table 2. Wizard fields for a WPF Window target from an existing target
Wizard field

Description

Target

Location of the existing Win32 or Windows Forms target

(PBT) file.
Example: C:\pb12apps\myapp.pbt
When you enter the target, the Library list displays the names and
locations of its library (PBL) files.

PowerBuilder .NET Features Guide

35

PowerBuilder .NET Targets and Projects

Wizard field

Description

New location and target file

By default, the wizard specifies a target with the same name as

the existing target but with a PBTX extension. The default location is a wpf subfolder within the existing target's folder.
Example: C:\pb12apps\wpf\myapp.pbtx
If you prefer a different target, change the default value.

Creating a .NET Assembly Target

You can create .NET assembly targets from scratch or from an existing target that contains at least one nonvisual custom
class object.
Note: The .NET Assembly wizard is not enabled for the beta1 release in the PowerBuilder .NET IDE.
You use the .NET Assembly wizard in the New dialog box to create a .NET Assembly target.
1. Open the New dialog box from the File menu or the toolbar.
2. Select .NET Assembly under the Target category and click Next.
3. Select the radio button option that corresponds to how you want to create the .NET assembly:
From scratch
From an existing target
By converting a PowerBuilder Classic .NET Assembly target
4. Follow the remaining instructions of the .NET Assembly wizard and click Finish.
If you prefer to enter values for the .NET Assembly target in the target painter, you can click Finish as soon as it is
enabled.
When you use the .NET Assembly target wizard to create a target from scratch, the wizard also creates an Application
object, a project object that allows you to deploy the assembly, and a nonvisual object (NVO). However, you must add and
implement at least one public method in the wizard-created NVO before it can be used to create a .NET assembly.
If you selected the option to use an existing target, the wizard creates only the .NET Assembly target and a .NET Assembly
project. The target you select must include at least one NVO having at least one public method. The public method must
be implemented by the NVO or inherited from a parent. The AutoInstantiate property of the NVO must be set to false.

.NET Assembly Target Properties

You can enter properties for .NET Assembly targets in the .NET Assembly wizard or in the Target painter.
Creating a .NET Assembly target from scratch
For .NET Assembly targets that you create from scratch, you must provide the information described in the following
table:
Table 3. Wizard fields for a .NET Assembly target created from scratch

36

Wizard field

Description

Project name

Name of the project object the wizard creates.

Library

Name of the library directory the wizard creates. By default, this

includes the current Workspace path and takes the name you
enter for the project object with a PBL extension.

PowerBuilder .NET Targets and Projects

Wizard field

Description

Target

Name of the target the wizard creates. By default, this includes

the current Workspace path and takes the name you enter for the
project object with a PBT extension.

Library search path

Lets you add PBLs and PBDs to the search path for the new
target.

PowerBuilder object name

Name of the nonvisual object the wizard creates. By default this

takes the name that you entered for a project object with an
n_ prefix.

Description

Lets you add a description for the project object the wizard creates.

Namespace

Provides a globally unique name to assembly elements and attributes, distinguishing them from elements and attributes of the
same name but in different assemblies.

Assembly file name

Name of the assembly created by the wizard. By default, the

assembly file name takes the namespace name with a DLL suffix.

Resource file and directory list

List of resource files, or directories containing resource files, that

you want to deploy with the project.
You can use the Add Files, Add Directories, or Search PBR Files
buttons to add files and directories to the list box. You can select
a file or directory in the list and click the Delete button to remove
that file or directory from the list. When you select a directory, the
resource files in all of its subdirectories are also selected by
default. However, you can use the Resource Files tab in the
Project painter to prevent deployment of subdirectory files.

Win32 dynamic library file list

Specifies any Win32 DLLs you want to include with your

project. Click the Add button to open a file selection dialog box
and add a DLL to the list. Select a DLL in the list and click Delete
to remove the DLL from the list.

Setup file name

Name of the setup file the wizard creates. You can copy this MSI
file to client computers, then double-click the files to install
the .NET assembly on those computers.

Creating a .NET Assembly target from an existing target

When you use the wizard to create a .NET Assembly target from an existing target, the wizard prompts you for the same
information as when you create a target from scratch, except that it omits the PowerBuilder object name and library search
path fields. These fields are unnecessary because the existing target must have a usable nonvisual object and the library
search path for the target is already set. The wizard does, however, present the following fields that are not available when
you create a target from scratch:
Table 4. Additional fields for the existing target wizard selection
Wizard field

Description

Choose a target

Select a target from the list of targets in the current workspace.

Specify a project name

Select a name for the project you want to create. You must create
a project object to deploy nonvisual objects as .NET components.

PowerBuilder .NET Features Guide

37

PowerBuilder .NET Targets and Projects

Wizard field

Description

Choose a project library

Specify a library from the list of target libraries where you want
to store the new project object.

Choose NVO objects to be deployed

Expand the library node or nodes in the list box and select check
boxes next to the nonvisual objects that you want to deploy.

Use .NET nullable types

Select this check box to map PowerScript standard datatypes

to .NET nullable datatypes. Nullable datatypes are not Common
Type System (CTS) compliant, but they can be used with .NET
Generic classes if a component accepts or returns null arguments
or if reference arguments are set to null.

Creating a .NET Web Service Target

You can create .NET Web Service targets from scratch or from an existing target that contains at least one nonvisual
custom class object.
Note: The .NET Web Service wizard is not enabled for the beta1 release in thePowerBuilder .NET IDE.
You use the .NET Web Service wizard in the New dialog box to create a .NET Assembly target.
1. Open the New dialog box from the File menu or the toolbar.
2. Select .NET Web Service under the Target category and click Next.
3. Select the radio button option that corresponds to how you want to create the .NET Web Service:
From scratch
From an existing target
By converting a PowerBuilder Classic .NET Web Service target
4. Follow the remaining instructions of the .NET Web Service wizard and click Finish.
If you prefer to enter values for the .NET Web Service target in the target painter, you can click Finish as soon as it
is enabled.
When you use the .NET Web Service target wizard to create a target from scratch, the wizard also creates an Application
object, a project object that allows you to deploy the Web Service assembly, and a nonvisual object (NVO). However, you
must add and implement at least one public method in the wizard-created NVO before you can deploy it as a .NET Web
Service.
If you selected the option to use an existing target, the wizard creates only the .NET Web Service target and a .NET Web
Service project. The target you select must include at least one NVO having at least one public method. The public method
must be implemented by the NVO or inherited from a parent. The AutoInstantiate property of the NVO must be set to
false.

.NET Web Service Target Properties

You can enter properties for .NET Web Service targets in the .NET Web Service wizard or in the Target painter.
Creating a .NET Web Service target from scratch
For .NET Web Service targets that you create from scratch, you must provide the information described in the following
table:

38

PowerBuilder .NET Targets and Projects

Table 5. Wizard fields specific to .NET Web Service targets and projects
Wizard field

Description

Project name

Name of the project object the wizard creates.

Library

Name of the library directory the wizard creates. By default, this

includes the current Workspace path and takes the name you
enter for the project object with a PBL extension.

Target

Name of the target the wizard creates. By default, this includes

the current Workspace path and takes the name you enter for the
project object with a PBT extension.

Library search path

Lets you add PBLs and PBDs to the search path for the new
target.

PowerBuilder object name

Name of the nonvisual object the wizard creates. By default this

takes the name that you entered for a project object with an
n_ prefix.

Description

Lets you add a description for the project object the wizard creates.

Web service virtual directory name

The directory path you want to use as the current directory in the
virtual file system on the server. By default, this is the full path
name for the current target.

Web service URL preview

Address for accessing the .NET Web service from an application.

Resource file and directory list

List of resource files, or directories containing resource files, that

you want to deploy with the project.
You can use the Add Files, Add Directories, or Search PBR Files
buttons to add files and directories to the list box. You can select
a file or directory in the list and click the Delete button to remove
that file or directory from the list. When you select a directory, the
resource files in all of its subdirectories are also selected by
default. However, you can use the Resource Files tab in the
Project painter to prevent deployment of subdirectory files.

Win32 dynamic library file list

Specifies any Win32 DLLs you want to include with your

project. Click the Add button to open a file selection dialog box
and add a DLL to the list. Select a DLL in the list and click Delete
to remove the DLL from the list.

Generate setup file

Select this option to deploy the Web service in an MSI file. When
you select this option, you must provide a name for the setup
file.

Setup file name

This field is enabled only if you select the Generate Setup File
option. You use it to name the setup file the wizard creates. You
can copy this MSI file to client computers, then double-click the
files to install the .NET Web Service on those computers.

Directly deploy to IIS

Select this option to deploy the Web service directly to an IIS

server. When you select this option, you must provide an IIS
server address. By default, the server address is localhost.

Creating a .NET Web Service target from an existing target

When you use the wizard to create a .NET Web Service target from an existing target, the wizard prompts you for the same
information as when you create a target from scratch, except that it omits the PowerBuilder object name and library search
PowerBuilder .NET Features Guide

39

PowerBuilder .NET Targets and Projects

path fields. These fields are unnecessary because the existing target must have a usable nonvisual object and the library
search path for the target is already set. The wizard does, however, present the following fields that are not available when
you create a target from scratch:
Table 6. Additional fields for the existing target wizard selection
Wizard field

Description

Choose a target

Select a target from the list of targets in the current workspace.

Specify a project name

Select a name for the project you want to create. You must create
a project object to deploy nonvisual objects as .NET components.

Choose a project library

Specify a library from the list of target libraries where you want
to store the new project object.

Choose NVO objects to be deployed

Expand the library node or nodes in the list box and select check
boxes next to the nonvisual objects that you want to deploy.

Use .NET nullable types

Select this check box to map PowerBuilder standard datatypes

to .NET nullable datatypes. Nullable datatypes are not Common
Type System (CTS) compliant, but they can be used with .NET
Generic classes if a component accepts or returns null arguments
or if reference arguments are set to null.

Project Painter User Interface

Use the Project painter to generate compiled resources, such as EXE, PBD, and .NET assembly files, for runtime
applications and components.
You can also locally execute the generated files from the design time environment by selecting the Run item from the main
menu of the Project painter, or by selecting one of the Build menu items from pop-up menus in the System Tree.
The PowerBuilder .NET Project painter uses the Visual Studio style to display horizantally stacked tabs separating
functional areas of a Project object rather than the classic PowerBuilder painter style that uses top row tabs.
The options for full and incremental builds are not included on the General tab of the Project painter as they are in
PowerBuilder Classic. Instead, you specify the build scope by selections from the target and project pop-up menus in the
System Tree, or by selections from the Design and Build menus of the Project painter.
The Resources tab in the Project painter for PowerBuilder Classic is not available in PowerBuilder .NET. Instead, you add
resources to a target from a pop-up menu in the System Tree, or from the Project menu. The build process copies resource
files to the project output directory.
Note: Although you can save information that you enter on the Security, Sign, Publish, Install/Update, Notify, and
Prerequisites tabs, these tabs are not yet fully functional in the beta1 release.
The PowerBuilder Library Files listbox on the Library Files tab is also not functional in the current beta. However, the
Win32 Dynamic Library Files listbox on this tab is functional, and the DLLs you include in the listbox are copied to the
project output directory during the build process.

WCF Client Project Overview

Windows Communication Foundation (WCF) is a runtime engine and set of APIs that allow you to send messages
between services and clients over the Internet. Use the Project painter to build WCF client proxy objects that consume
Web services from a PowerBuilder .NET application.
Note: WCF Client Proxy projects in the current beta1 release can consume Web services with the following restrictions:

40

PowerBuilder .NET Targets and Projects

ASMX services that use arrays of simple datatypes are not supported. (Simple datatypes are supported.)
ASMX services that use user-defined datatypes inheriting from .NET datatypes are not supported. (User-defined
datatypes defined in a WSDL file, and arrays of these datatypes are supported.)
WCF services that use bindings other than BasicHttpBinding, WSHttpBinding, or netTCPBinding are not supported.
Connection to a service through a proxy server is not supported.

.
Note: You must install the .NET Framework SDK 3.5 to use the WCF feature. The WCF Client Proxy project uses a tool
from the SDK to access a service contract (svc or wsdl). This tool (SvcUtil.exe) parses the service contract and
generates C# files. The C# compiler (CSC.exe from .NET 3.5 runtime) then builds the newly generated C# code into a
private assembly, which is automatically referenced by the project.
The nonvisual user object (NVO) proxy generated by the WCF Client Proxy project allows PowerBuilder .NET
application users to consume a Web service. The proxy NVO represents the service class defined by the Web service
contract, which is also incorporated in a private assembly generated by the WCF client project.
The generated proxy layer uses PowerScript and .NET interoperability to pass the call to the assembly and get a return
value from the Web service. This is different from the approach used in PowerBuilder Classic, where the generated proxy
uses the PowerBuilder Native Interface (PBNI) for data exchange. For this reason, you cannot migrate existing Web
service clients from PowerBuilder Classic to the WCF engine.
The WCF client engine allows PowerBuilder .NET application users to consume WSE (Web Service Enhancement)
extensions in addition to other Web services. The WSE extensions cannot be accessed by the EasySoap and .NET SOAP
engines available in PowerBuilder Classic.

Creating a WCF Client

Create a WCF client by building a WCF Client Proxy project.
You can add a WCF Client Proxy project to any WPF Window Application target.
1. Under the Project node in the New dialog box, select the WCF Client Proxy item.
2. Click:

Next and complete the wizard, entering or selecting values for the Web Service Definition Language (WSDL) file,
the proxy name prefix and assembly, services and ports, the project name and library, and the library for the
proxy.
Finish and complete project property selections in the Project painter.

For the WSDL File Name, you can enter or choose files with the WSDL or ASMX extension.
You can click Finish at any time in the wizard and edit any default values in the Project painter.
3. Build the project.
PowerBuilder creates an assembly that can connect to the Web service.
4. Create an instance of the generated assembly in a PowerBuilder .NET target.
5. (Optional) Create an instance of WCFConnection, and set its binding and related properties.
6. Call a method of the instance of the generated assembly.

PowerBuilder .NET Features Guide

41

PowerBuilder .NET Targets and Projects

42

Scripts and Code Fundamentals

Scripts and Code Fundamentals

PowerBuilder applications are event driven. You specify the processing that takes place when an event occurs by writing
a script.
PowerScript in PowerBuilder .NET is a productive .NET language.

Script View in PowerBuilder .NET

You use the Script view to code functions and events, define your own funtions and events, and declare variables and
external functions.
Script views are part of the default layout in the Application, Window, User Object, Menu, and Function painters. You can
open as many Script views as you need, or perform all coding tasks in a single Script view.
Drop-down lists
There are three drop-down lists at the top of the Script view.
In the first list, you can select the object, control, or menu item for which you want to write a script. You can also select
Functions to edit function scripts or Declare to declare variables and external functions.
The second list lets you select the event or function you want to edit or the kind of declaration you want to make. A script
icon next to an event name indicates there is a script for that event, and the icon's appearance tells you more about the
script:
If there is a script

The script icon displays

For the current object or control

With text

In an ancestor object or control only

In color

In an ancestor as well as in the object or control you are working Half in color
with

The same script icons display in the Event List view.

The third list is available in descendent objects. It lists the current object and all its ancestors so that you can view scripts
in the ancestor objects.

Opening the Script View

You can open the Script view by double-clicking a control, function, or event.
If there is no open Script view, selecting a menu or PainterBar item that requires a Script view opens one automatically.
If you want to edit more than one script at a time, you can open additional Script views.
To open the Script view:
Options

Description

From the menu

Not enabled in CTP

For a control

Double-click a scriptable control, or select Script from the PainterBar or a pop-up menu.

For a function or event Double-click an item in the Event list or Function list views, or select the function or event from the
second drop-down list in an open Script view.

PowerBuilder .NET Features Guide

43

Scripts and Code Fundamentals

If you double-click a control, function, or list, the Script view shows the script for the selected item. If the Script view is
in a tabbed pane and is hidden, it pops to the front. If there is no open Script view, PowerBuilder creates a new one.

Modifying Script View Properties

The Script view automatically color-codes scripts to identify datatypes, system-level functions, flow-of-control
statements, comments, and literals. It also indents the script based on flow-of-control statements. You can modify these
and other properties.
You can modify Script view properties.
1. Select Tools > Options to display the options dialog box for the painter.
The Options dialog box includes pages that affect the Script view.
2. Choose the page appropriate to the property you want to specify:
Options

Description

To specify

Choose this page

Font family, size, and color

Environment > Fonts and Colors

Text and background coloring for PowerScript syntax elements

Environment > Fonts and Colors

Tab size, automatic indenting, whether dashes are allowed in

identifiers??, and which compiler and database messages to display??

Text Editor > PowerScript > General

Whether Intellisense is enabled and what kind of assistance it provides

Text Editor > PowerScript > Formatting

Editing Scripts
You can perform standard editing tasks in the Script view using the Edit menu, the pop-up menu in the Script view, or the
PainterBars. There are shortcuts for many editing actions.
Tip: You can set up your own shortcuts. Select Tools > Options, then Environment > Keyboard in the Options dialog
box.
For more information, see the PowerBuilder Users Guide.

Code Snippets
You can store short code snippets and reuse them in scripts.
Code snippets enable you to store and reuse pieces of code in multiple scripts or files. Snippets are similar to clips in the
PowerBuilder Classic environment.
PowerBuilder .NET provides a library of PowerBuilder-specific snippets that are ready to use. These are available with
the Insert Snippet and Surround Snippet functions when you are editing code in the PowerScript editor.
For information about adding, using, and managing Intellisense Code Snippets, refer to the Visual Studio Help.

IntelliSense
IntelliSense is a tool that helps you write PowerScript code more quickly by providing a lookup and paste service inside
the Script view.
IntelliSense is a feature of Visual Studio similar to Autoscript in PowerBuilder Classic.

44

Scripts and Code Fundamentals

Where you use IntelliSense
You can use IntelliSense in three different contexts:

When you can remember part of the name and you want IntelliSense to finish typing it for you or show you a list of
alternatives.
When you cannot remember the name or you just want a list. IntelliSense options can help you narrow the list if you
do not know the name but you do know the type you are looking for.
When you want a list of the properties and/or functions and events that apply to an identifier followed by a dot.

Compiling the Script

Before you can execute a script, you must compile it.
Click the Compile button, or select Edit > Compile from the menu bar.
Note: When you attempt to open a different script in a Script view, PowerBuilder compiles the current script. When you
save the object, such as the window containing a control you wrote a script for, PowerBuilder recompiles all scripts in the
object to make sure they are still valid. For example, PowerBuilder checks that all objects that were referenced when you
wrote the script will exist.

Handling Problems with Script Compilation

If problems occur when a script is compiled, PowerBuilder displays messages in the Error List tab of the Output view.

There are three kinds of messages:

Errors
Warnings
Information messages

For more information about messages, see the PowerBuilder Users Guide.

Declaring Variables and External Functions

The default layout in the Application, Window, and User Object painters includes a Script view set up to declare variables.
Keeping a separate Script view open makes it easy to declare any variables or external functions you need to use in your
code without closing and compiling the script.
To declare variables and external functions
1. Select [Declare] from the first list in the Script view.

PowerBuilder .NET Features Guide

45

Scripts and Code Fundamentals

2. Select the variable type (instance, shared, or global) or the function type (namespace, local, or global) from the second
list.
3. Type the declaration in the Script view.
Next
For more information about declaring variables, see the PowerScript Reference. For more information about declaring
and using external functions, see the PowerScript Reference and Application Techniques.

GoTo Definition
Not enabled in CTP

Accelerator Characters in Control Labels

Unlike PowerScript, which uses an ampersand to signal an accelerator character for the default action defined by a control,
XAML uses the first single underscore character in a control label to define the character that follows the underscore as
an accelerator character.
When you migrate PowerBuilder Classic targets to PowerBuilder .NET, the ampersand signaling an accelerator character
is converted to an underscore. If the control label has an underscore in it, the migration adds an extra underscore as an
escape character, and XAML displays the control label with a single underscore that is a regular part of the label text.
XAML does not allow you to use the underscore character itself as an accelerator.
Note: In the beta1 release, migration does not change the accelartor character to an underscore or add an extra underscore
as an escape character.
However, as in PowerBuilder Classic, accelerator characters in PowerBuilder .NET control labels display with an
underscore in the label.
Although migration handles conversion of the accelerator characters for PowerBuilder Classic targets, any new
accelerator characters you want to use in Script views or in the XAML editor must follow the XAML accelerator character
rules. The rules for accelerator characters apply to CommandButton, PictureButton, CheckBox, RadioButton, StaticText,
StaticHyperlink, and GroupBox controls.
In XAML, the control label myCommandButton__1_x will cause the control to display with the character x as the
accelerator: myCommandButton_1 x. In this example, x is the first character after a single underscore, which marks it as
an accelerator character.

Unsupported Properties, Functions, and Events

Several PowerScript properties, functions, and events are not supported in PowerBuilder .NET.

Unsupported PowerScript properties

The following table lists PowerBuilder .NET objects and controls with unsupported PowerScript properties:

46

Object or control

Unsupported properties

Application object

ToolbarUserControl

CheckBox

Automatic

DataWindow

ControlMenu, HSplitScroll, Icon, MaxBox, MinBox, Title, and

TitleBar

Scripts and Code Fundamentals

Object or control

Unsupported properties

DatePicker

AllowEdit

DropDownListBox

HScrollBar. IMEMode

DropDownPictureListBox

HScrollBar. IMEMode

EditMask

AutoHScroll, AutoVScroll. IgnoreDefaultButton, IMEMode,

TabStop, and VScrollBar

ListBox

TabStop

ListView

IMEMode

Menu

MenuItemType, MergeOption, and ToolbarItemSpace

MenuCascade

Columns, CurrentItem, DropDown, MenuItemType, MergeOption, and ToolbarItemSpace

MultiLineEdit

AutoVScroll, HideSelection. IgnoreDefaultButton. IMEMode,

and TabStop

Picture

Map3DColors (Use PictureMaskColor instead)

PictureButton

Map3DColors (Use PictureMaskColor instead)

PictureHyperLink

Map3DColors (Use PictureMaskColor instead)

PictureListBox

TabStop

RadioButton

Automatic

RichTextEdit

Accelerator, ControlCharsVisible, DisplayOnly, ImeMode, PicturesAsFrame, Resizable, ReturnsVisible, RulerBar, SpacesVisible, TabBar, TabsVisible, Underline, UndoDepth, and WordWrap

SingleLineEdit

HideSelection, IMEMode

UserObject

Style

Window

MdiClientColor

Note: Several properties are renamed with a "PB" prefix. For example, Height and Width properties are set as PBHeight
and PBWidth; the Tag and FontFamily properties are set as PBTag and PBFontFamily. TabOrder is included as a property
in the Property view for an object or control.
Unsupported PowerScript events
The following table lists PowerBuilder .NET controls with unsupported PowerScript events:
Control

Unsupported events

All controls

Other

DatePicker

DoubleClicked and UserString

MonthCalendar

DoubleClicked

RichTextEdit

DragDrop, DragEnter, DragLeave, and DragWithin

Unsupported PowerScript functions

The following table lists PowerBuilder .NET objects and controls with unsupported PowerScript functions:

PowerBuilder .NET Features Guide

47

Scripts and Code Fundamentals

Object or control

Unsupported functions

Application object

SetTransPool
Obsolete method: SetLibraryList

DataStore

CopyRTF, CreateFromm GenerateResultSet, GetStateStatus, InsertDocument, and PasteRTF

Obsolete method: GenerateHTMLForm

DataWindow

GenerateResultSet, GetStateStatus, GetUpdateStatus, and OleActivate

Obsolete methods: DBErrorCode, DBErrorMessage, GenerateHTMLForm, and GetMessageText

DataWindowChild

GetUpdateStatus and OleActivate

Obsolete methods: DBErrorCode and DBErrorMessage

48

EditMask

Scroll, SelectedLine, and Undo

RichTextEdit

Scroll, PageCount, and PrintEx

UserObject

AddItem, DeleteItem, EventParmDouble, EventParmString, and

InsertItem

Window

CloseChannel, ExecRemote, GetCommandDDE, GetDataDDE,

GetDataDDEOrigin, GetRemote, OpenChannel, RespondRemote, SetDataDDE, SetRemote, StartHotLink, StartServerDDE,
StopHotLink, and StopServerDDE

CLS Compliance in PowerBuilder

CLS Compliance in PowerBuilder

PowerScript supports full compliance with Common Language Specification (CLS) rules and restrictions.
The CLS ensures that components developed in one language can be fully accessible to any other .NET language. It
describes a set of commonly used features that serve as the minimum language requirement for any .NET language.
The CLS defines three separte roles for CLS compliant applications: framework, consumer, and extender.
CLS role

Requirements

Framework

Guarantees interoperability across different .NET languages. A CLS compliant .NET library is called a framework.

Consumer

A CLS consumer must be able to use CLS compliant libraries, but cannot extend the CLS framework. The CLS
compliant consumer must be able to:

Extender

Call any CLS compliant method

Have a mechanism for calling methods whose names are keywords in the language
Create an instance of any CLS compliant type
Read and modify any CLS compliant field
Access any CLS compliant property and event
Have a mechanism to use generic types and methods, and to access nested types

A CLS extender must allow users to consume and extend the CLS Framework. Everything that applies to CLS
consumers also applies to CLS extenders, but extenders must also be able to:

Define new nongeneric CLS compliant types that extend CLS compliant base types
Implement any CLS compliant interface
Place CLS compliant custom attributes on appropriate elements

With PowerBuilder .NET, you can create extensions to other CLS compliant languages and deploy components that can
be consumed by any CLS compliant application.
Several enhancements to the PowerScript language enable PowerBuilder .NET to support its CLS-extender role:

Ability to call .NET classes and methods without using preprocessor symbols (such as PBDOTNET) in #IF DEFINED
code blocks
Ability to define and implement interfaces
Support for array enhancements
Ability to consume .NET delegates
Ability to inherit from .NET Classes
Support for parameterized constructor events
Ability to define and consume custom attributes (UI not available in beta1)
Ability to consume generic types
Support for defining namespaces
Support for indexers
Support for user-defined enumerations
Support for additional bitwise operators
Support for StringBuilder system class (Not available in beta1)
Support for methods of .NET system.object in PowerObject class
Support for XML documentation comments (UI not available in beta1)
Support for language enhancements in .NET assembly and Web Service targets (Not available in beta1)

The .NET component targets in the PowerBuilder .NET IDE support a framework role for CLS compliance, since the
components generated from these targets can be consumed by any other .NET language. The WPF Window Application
targets in PowerBuilder .NET are CLS extenders because they allow you to consume and extend the CLS framework.
PowerBuilder .NET Features Guide

49

CLS Compliance in PowerBuilder

Runtime Array Bounds Creation

For PowerBuilder 12.0 .NET targets, the PowerScript language allows you to declare an unbounded array at design time,
and to dynamically create the array bounds at runtime.
Note: Although you could create and use an unbounded one-dimensional array in previous releases of PowerBuilder, you
could not previously set a bounds for these arrays at runtime.
PowerScript lets you specify array bounds for one-dimensional or multidimensional unbounded arrays. The array bounds
are created at runtime.
In this example, the indexes for an unbounded one-dimensional array are set to 2, 3, 4, and 5:
int arr[] //one-dimensional unbounded integer array
arr = create int[2 to 5]
This example sets the indexes of an unbounded two-dimensional array to 4 for one dimension, and 2, 3, 4, and 5 for the
other dimension:
int arr[,] //two-dimensional unbounded integer array
arr = create int[4, 2 to 5]

Jagged Array Support

For PowerBuilder 12.0 .NET targets, the PowerScript array syntax allows you to declare a jagged array.
Jagged arrays have elements of different dimensions and sizes. They are sometimes called "arrays of arrays".
In this example, the first line creates an array with three elements, each of type int[ ] . The subsequent lines initialize the
three elements of the first array dimension with references to individual array instances of varying lengths in the second
array dimension:
int arr[][]
arr = create int[3][]
arr[1] = create int[5]
arr[2] = create int[20]
arr[3] = create int[10]

.NET System.Array Support

PowerScript arrays include all the functionality of the .NET System.Array type.
All the public properties, and public static and instance methods, of the .NET System.Array type can be accessed by any
PowerBuilder .NET application or component
This allows you to get the number of dimensions in an array. You can continue to use PowerScript methods to determine
the lower bounds and upper bounds of a particular dimension or to get and set values of array items, but you can also
use .NET array object methods. The System.Array methods and properties are visible in the System Tree .

Returning an Array for a Function or Event

PowerBuilder .NET allows you to return an array datatype from a function or event.

50

CLS Compliance in PowerBuilder

PowerScript previously required you to map an ANY datatype whenever a function or event returned an array datatype.
You must still do this in PowerBuilder Classic. Although you can also map an ANY datatype for an array datatype in
PowerBuilder .NET, this is not type-safe or efficient.
Set an array datatype for a return value in the IDE as follows:
1. Open a painter for a PowerBuilder object, and:

to return an array on a new event, select the object name in the upper left drop-down list and New Event in the
second drop-down list.
to return an array on a new function, select Functions in the upper left drop-down list.

Note: You can also add an array datatype on a new function object that you define from the New dialog box.
2. Type the datatype followed by brackets in the Return Type drop-down list.
Note: You can add commas inside the brackets for multidimensional arrays.
3. Complete the remaining prototype fields available for the event or function, and add script for the new method in the
scripting area.
For a function script, you must include a return value that matches the array datatype you entered in the previous
step.
This example shows PowerScript syntax for a function that returns an array of type integer:
public function integer[] ut_test_array ()
integer ret[]
ret = {1, 2}
return ret
end function

Support for BitRight and BitLeft Operators

PowerBuilder 12.0 includes support for right shift and left shift bitwise operators.

BitRight operator
The right-shift operator shifts its first operand to the right by the number of bits specified in its second operand. This works
the same as the C# >> operator.
The shift to the right can be arithmetic or logical, depending on the datatype of the first operand:

Arithmetic - If the first operand is an integer or a long, high-order empty bits are set to the sign bit.
Logical - If the first operand is an unsigned integer (uint) or unsigned long (ulong), high-order bits are filled with
zeros.

BitLeft operator
The left-shift operator shifts its first operand to the left by the number of bits specified in its second operand. This works
the same as the C# << operator. The datatype of the second operand must be an integer.
The high-order bits of the first operand are discarded and the low-order empty bits are filled with zeros. Shift operations
never cause overflows. The shift amount to the left depends on the bit quantity of the first operand datatype:

32-bit quantity - If the first operand is a long or ulong, the shift amount is given by the low-order five bits of
the second operand. The maximum left shift is 0x1f or 31 bits.
64-bit quantity - If the first operand is a longlong or ulonglong, the shift amount is given by the low-order six
bits of the second operand. The maximum left shift is 0x3f or 63 bits.

PowerBuilder .NET Features Guide

51

CLS Compliance in PowerBuilder

Operator precedence
Bitwise shift operations are performed before relational (=, >, <, <=, >=, <>), negation (NOT), and logical (AND, OR)
operations. They are performed after grouping, unary, exponentiation, arithmetic (multiplication, division, addition,
subtraction), and string concatenation operations.

Defining an Interface
An interface specifies the members of a class that must be supplied by any class that implements the interface. In
PowerBuilder .NET, you can create interfaces from the New dialog box.
Because PowerScript has no concept of abstract classes, all methods, properties, events, and indexers defined in
PowerBuilder .NET interfaces (including ancestor interfaces) must be implemented by a PowerBuilder object class.
1. In the New dialog box, select PBObject>Interface, and

Click Next to open the wizard.

In the wizard, you can provide a name for the interface, select the library where you want to save the interface, and
select an interface that you want the new interface to inherit from. Click Finish at any time to open the Interface
painter.
Click Finish to open the Interface painter.
If you click Finish without providing a name for the interface, the interface name displays as Untitled.

2. Select New Event in the second drop-down list of the Interface painter to add events to the interface, and enter values
and parameters for each new event that you add.
If you added functions, indexers, or properties, or made declarations as described in the next step (step 3), you must
select the interface name (or Untitled if you did not provide a name for the interface) from the first drop-down list
before you can select New Event in the second drop-down list.
3. Select Functions, Indexers, Properties, or Declare in the first drop-down list of the Interface painter to
add functions, indexers, or properties to the interface, or to declare a namespace or another interface.
A new painter window displays for the item you select. For new functions, indexers, and properties, or to switch
between declarations for namespaces and other interfaces, you might need to select an appropriate item from the
second drop-down list in the painter window.
Add as many functions, indexers, properties or declarations as required for the interface.
4. Save the interface.
If you did not provide a name for the interface in the Interface wizard, the Save Interface dialog box prompts you for
an interface name and the library where you want to save the interface.

System Interface Syntax

PowerBuilder .NET provides pre-implemented system interfaces that you can use in your WPF applications or
components. The system interfaces include implementations for all the methods of DataWindow controls and DataStores.
You can work with system interfaces in place of DataWindow, DataStore, or Picture controls. These controls
automatically implement system interfaces, allowing you to pass around the interface rather than the control, and directly
call control methods on the interface.
You do not declare the system interfaces or add implementations for their methods.
IDataWindowBase and its children
The IDataWindowBase system interface includes all the methods common to DataWindows and DataStores. It also is the
base interface of three other system interfaces: IDataWindowControl, IDataWindowChild, and IDataWindowStore.

52

CLS Compliance in PowerBuilder

Any variable with a DataWindow, DataStore, or DataWindowChild datatype can be assigned to the IDataWindowBase
system interface. This allow you to take advantage of the interface's built-in polymorphism, so you do not need to
duplicate code or check whether the assigned variable is a DataWindow or DataStore. The inherited interfaces are slightly
more restrictive, but can be assigned any variable with the datatype indicated in the following table:
Variable datatype

System interface to which it can be assigned (in addition to IDataWindowBase)

DataWindow

IDataWindowControl

DataWindowChild

IDataWindowChild

DataStore

IDataWindowStore

The following syntax defines a function that determines the number of rows in a DataWindow or DataStore after a filter
is applied:
public function long f_filter (IDataWindowBase idw_base,
string as_filter);
long ll_rows
idw_base.SetFilter (as_filter)
idw_base.Filter ()
return idw_base.RowCount ()
end function
You can then call this function in a script, passing in a valid DataWindow or DataStore and the value you want to use as
a filter. The following script filters a DataStore on a department ID of 100:
DataStore ldw_emps
ldw_emps = Create DataStore
ldw_emps.DataObject = "d_myDWO"
ldw_emps.SetTransObject (SQLCA)

// Assumes a connected

transaction
ldw_emps.Retrieve ()
this.f_Filter (ldw_emps, "dept_id = 100")
IPicture
PowerBuilder .NET also provides an IPicture interface that exposes all the common methods of the PowerBuilder picture
control. The following example calls the SetPicture and Draw methods on an object that inherits from the IPicture
interface:
IPicture ip = p_1
ip.SetPicture (myPictureBlob)
ip.Draw (x, y)
The IDataWindowControl and IDataWindowChild interfaces also use the IPicture system interface to set the picturename
parameter in the SetRowFocusIndicator method of a DataWindow or DataWindowChild control.

Implementing an Interface
To use the functionality of an interface, you must create a class that implements the interface, or derive a class from one
of the .NET Framework classes that implements the interface.
The following types of PowerBuilder .NET objects can implement interfaces: Custom Class, Standard Class, Custom
Visual, External Visual, Standard Visual, Window, and Menu objects.

PowerBuilder .NET Features Guide

53

CLS Compliance in PowerBuilder

If an object class implements two interfaces that contain a member with the same signature, implementing that member
in the class implements that member for both interfaces. Naming or identity conflicts are resolved by including the name
of the interface with the name of the class member, separated by a dot (.)
1. Open the painter for an object that can implement interfaces.
2. In the Script view of the object painter, select Declare in the first drop-down list and Interfaces in the second drop-down
list.
3. Right-click inside the Script view and select Add Interface from the pop-up menu.
4. In the Select Interface dialog box, select the interface you want to implement and click OK.
5. Write scripts for all interface events, functions, .NET properties, and indexers.
6. Save the object with its interface implementations.
You can view the object and the interfaces it implements in the the PB Object Outline view.

Deleting a Declared Interface

Delete a declared interface from the object painter for the object implementing the interface.
When you delete an interface that you declare for an object or control, you can decide to keep or delete the interface
functions, indexers, and properties.
1.
2.
3.
4.
5.

Open the painter for the object with a declared interface that you want to delete.
Select Declare in the first drop-down list and Interfaces in the second drop-down list.
Right-click the interface you want to delete and select Delete from the pop-up menu.
In the Delete Interface dialog box, clear any checked functions, indexers, or properties that you want to keep.
Click OK.
The Delete Interface dialog box closes. If you open the PB Object Outline view, you still see any functions, indexers,
or properties that you chose to keep.

Consuming a .NET Delegate

In PowerBuilder .NET you can invoke .NET delegates from PowerScript code. Delegates make it possible to treat
functions as entities that can be assigned to variables and passed as parameters.
A delegate type represents references to methods with a particular parameter list and return datatype.
The PowerBuilder .NET IDE exposes all the visible delegates in the .NET assemblies referenced by the current target in
the System Tree or object browser.
1. Import an assembly containing a .NET delegate to a PowerBuilder .NET target.
2. Deternine whether to invoke the .NET delegate synchronously or asynchronously.
3. Write PowerScript code to assign a function or functions to a variable that has the .NET delegate type.
Next
If you invoke the delegate asynchronously, you must also determine whether to join the results immediately after the
invoked thread completes its execution, after a callback function is triggered, or as the result of polling that allows other
processing to complete even after the child thread has finished running.
You can also decide whether to use multicasting. Multicasting makes use of a function chain that passes arguments by
value or reference from one function to another in a single invocation of the .NET delegate.

Syntax for Consuming .NET Delegates

In PowerBuilder .NET, you can use PowerScript to invoke delegates in imported assemblies either synchronously or
asynchronously.
54

CLS Compliance in PowerBuilder

Delegate declaration
The following C# syntax declares delegate types named Func and FuncAsync in a .NET assembly that you import to
your PowerBuilder .NET target.
.NET class declaration in C# (in an external assembly):
using System;
delegate double Func(double x);
delegate double FuncAsync(double[] a);
The example for the synchronous use case that follows consumes the Func delegate, and the example for the
asynchronous use case consumes the FuncAsync delegate.
Synchronous use case
The following PowerScript syntax uses the delegate type Func from the external DLL that you import to your target. The
delegate signature requires a function that takes a double and returns a double value.
public function double[] of_apply (double a_v[], Func a_f)
double result[]
for i = 0 to i < a_v.Length step 1
result[i] = a_f (a_v[i])
next
return result
end function

public function double of_multiply(double a_x)

return a_x * factor;
end function
public subroutine of_test()
double a[] = {1.0,2.0,3.0,4.0,5.0}
double doubles[] = of_apply(a, of_multiply)
end subroutine
In the above example, the of_test method has a vector of double values. The vector is passed to the function
of_apply which calls the function of_multiply for each value in the vector using the delegate variable a_f. This is
possible since of_apply takes a delegate as an argument (a_f).
You could use the above method to apply different algorithms to the same data. So besides of_multiply, you could
include additional functions with of_apply and the delegate variable, as long as the additional functions process a
single value of the double datatype and return a value of the double datatype.
Asynchronous use case
The following PowerScript syntax uses the delegate type FuncAsyc from the external DLL that you import to your
target.
public function double of_sum( double a_v[] )
double sum
for i = 0 to i < a_v.Length step 1
sum = sum + a_v[i]
next
return sum
end function

PowerBuilder .NET Features Guide

55

CLS Compliance in PowerBuilder

public subroutine test()

double a[] = {1.0,2.0,3.0,4.0,5.0}
FuncAsync D = of_sum
System.AsyncCallback nullValue
integer stateValue
System.IAsyncResult ar = D.BeginInvoke( a, nullValue,
stateValue )
//background thread starts
...
double result = D.EndInvoke( ar ) // wait for thread to
return
result (join)
end subroutine
The above example corresponds to a "wait-until-done pattern". You could also use asynchronous processing in a "polling
pattern", where the invoked thread is polled to determine it is finished, or in a "callback pattern", where a callback function
is called when the thread has finished executing.
The code between the BeginInvoke and EndInvoke runs in the main thread, but the computation of the sum has its own
thread from the .NET thread pool. When EndInvoke is called, it acts as a Join operation and completes when the sum is
returned by the child thread.
Note: To maintain thread safety, .NET prevents child threads from directly getting or setting property values in a form or
its child controls. You can read from and write to the user interface only from the main UI thread.

Syntax for Consuming Generic Classes

Generics are classes, structures, interfaces, and methods with placeholders for the datatypes that they store or use.
A generic collection class can use a datatype parameter as a placeholder for the types of objects that it stores or returns.
A generic method can also use its datatype parameter as a type for any of its formal parameters (arguments).
In PowerBuilder .NET, you can consume .NET generic classes and methods that conform to CLS generic rules. However,
you cannot define a generic type or override generic methods.
The following example calls the generic SortedList method:
System.Collections.Generic.SortedList<string, integer> teams
teams = create System.Collections.Generic.SortedList<string, integer>
teams["DEV"] = 30
teams["QA"] = 25
The generic parameter type can be any type, including a primitive type, .NET class type, PowerBuilder user-defined type,
or a nested generic type. Inner generic types are also supported. For example:
MyDll.GenericClass2<MyDll.Class1>.GenericClass2_1<System.String> o1
o1 = CREATE MyDll.GenericClass2<MyDll.Class1>.GenericClass2_1
<System.String>
The syntax for calling functions and events of .NET classes is also available for the .NET generic type. For example:
c21 = o0_temp.Dynamic GenericTest11(c21, c1)
c21 = o0_temp.Dynamic GenericTest11<MyDll.MyClass2>(c21, c1)
o0_temp.Dynamic GenericTest11(c21, c1)
o0_temp.Dynamic GenericTest11<MyDll.MyClass2>(c21, c1)
o0_temp.Dynamic POST GenericTest11<MyDll.MyClass2>(c21, c1)
o0_temp.POST Dynamic GenericTest11<MyDll.MyClass2>(c21, c1)

56

CLS Compliance in PowerBuilder

Inheriting from a .NET Class

You must add a .NET class to a target before you can create an object to inherit from that class in a PowerBuilder .NET
application.
Use the following procedure to inherit from a .NET class:
1. Click Custom under the PBObject>Non-Visual Class node of the New dialog box, then click Finish.
2. Choose a base .NET class that you want to inherit from.
3. Choose the interface or interfaces that you want to implement.
4. In the Object painter, implement all abstract and virtual functions, events, indexers, and properties defined in the base
class and the interfaces that the object implements.
5. Add any new functions, events, indexers, and properties you want to include in the new object.

Syntax Supporting Inheritance from a .NET Class

PowerScript allows you to create nonvisual objects that override all virtual and abstract methods, properties, indexers and
events defined in .NET base classes and interfaces.
The following example defines a PowerScript nonvisual object that inherits from a .NET class:
global type NVO from DotNetClass1, ISub1
end type
The syntax for calling PowerScript functions and events can also be used to call the functions and events of a .NET
class.
{ objectname.} { type } { calltype } { when } name ( { argumentlist } )
The following table describes the arguments used in the function or event calls. All arguments except the function or event
name are optional.
Argument

Description

objectname

The name of the object where the function or event is defined

followed by a period or the descendant of that object, or the name
of the ancestor class of the object followed by two colons.

type

A keyword specifying whether you are calling a function or

event. Values are:

calltype

A keyword specifying when PowerBuilder looks for the function/event. Values are:

PowerBuilder .NET Features Guide

FUNCTION (Default)
EVENT

STATIC (Default)
DYNAMIC

57

CLS Compliance in PowerBuilder

Argument

Description

when

A keyword specifying whether the function or event should execute immediately or only after the current script is finished.
Values are:

TRIGGER (Default) Execute immediately

POST Put in the object's queue and execute after other
pending messages have been handled

name

The name of the function or event you want to call.

argumentlist

The values you want to pass to the function or event. Each value
in the list must have a datatype that corresponds to the declared
datatype in the function or event definition or declaration.

Creating a Global User-Defined Enumeration

In PowerBuilder .NET, you can create global enumerations in the Enumeration painter or in script.
Global enumerations can be used by all objects in your application or component target. The following procedure uses the
Enumeration painter to define global enumerations for your applications.
Note: The Flags check box mentioned in step 2 is not available in the beta1 release.
1. In the New dialog box, select the PB Object>Enumeration item and click Finish.
The Enumeration painter displays.
2. If you want the values for each item in the enumeration to be bit fields, select the Flags check box.
3. Enter a name in the Name column for each item you want to add to the enumeration.
4. Optionally add values to the Values column and comments to the Comments column for each item in the painter.
5. Select File>Save, provide a name for your global enumeration, and click OK.

Syntax for User-Defined Enumerations

PowerScript allows you to create custom enumerations for PowerBuilder .NET targets.
The following example creates a user-defined enumeration named MyEnum:
global type MyEnum enumerated
item1,
item2 = 3
end type
The syntax to access an enumeration constant is:
[[namespacename.]enumerationType.]enumerationEntryName!
The items of user-defined enumerations must be accessed using the enumeration type. For example:
Enum me
me = MyEnum.item2!
This syntax helps make the code readable and avoids naming conflicts.
If you do not provide an enumeration type, the enumeration is assumed to be a system-defined type and
PowerBuilder .NET tries to find it in PowerBuilder system-defined enumerations. If the enumeration type exists,
PowerBuilder .NET tries to find the enumeration type first and then find the enumeration entry for that enumeration
type.
58

CLS Compliance in PowerBuilder

Creating a Local User-Defined Enumeration

In PowerBuilder .NET you can create local enumerations for an object in an Enumeration painter that you open from the
object painter.
To define a local enumeration using the PowerBuilder .NET user interface, you must first open an object painter that has
a local Enumeration painter attached. You can define local enumerations for the following kinds of objects: Custom and
Standard Class objects, Custom, Standard and External Visual objects, and Windows and Menus.
In the Enumeration painter, you can specify entry name, value, and comments for each item that you enter for an
enumeration type.
1. In the System Tree, right-click the object for which you want to add a local enumeration and select Open from the
pop-up menu.
2. In the Script view of the object painter, select Enumerations from the first drop-down list in the upper left corner of
the view.
3. If it is not already selected, select New Enumeration in the second drop-down list of the Script view.
4. Enter a name for the new enumeration in the Enumeration text box.
5. Enter a name in the Name column for each item you want to add to the enumeration.
6. Optionally add values to the Values column and comments to the Comments column for each item in the painter.
7. Save the object with its new enumeration.

Declaring a Namespace
You can specify a namespace for the following kinds of PowerBuilder objects: Custom and Standard Class objects,
Custom, Standard, and External Visual objects, windows and menus, structures and functions, and interfaces and
enumerations.
You declare a namespace in the Declare Namespace window of an object painter that supports namespace declarations.
You can also add Using (namespace) directives in the Declare Namespace window. Using directives allow you to refer to
a named type by its simple name rather than its compound name that includes a namespace prefix.
1. Open a painter for a PowerBuilder object for which you want to declare a namespace.
The painter opens automatically when you create a new object.
2. Select Declare in the upper left drop-down list in the painter and Namespace in the second drop-down list.
Note: You could click the Namespace tab at the bottom of the object painter rather than selecting the drop-down list
items mentioned in this step.
3. If the current object has an ancestor object, and you want the namespace to apply to the ancestor object as well as the
current object, select the ancestor in the third drop-down list.
Note: This feature is not implemented in the current beta release.
4. Type your namespace declaration in the Namespace text box.
The namespace declaration applies only to the selected object and any objects that inherit from the selected object.
Skip the next step if you do not want to include a Using directive in the source code for the current object.
5. Click the Add button to open the Select Namespaces dialog box and include a Using directive.
a) Select an assembly or other item from the Assemblies list box.
The list of namespaces declared for the selected item displays in the top list box.
b) Select a namespace from the top list box and click OK.
The dialog box closes and the namespace you selected displays in the Using list box of the object painter.

PowerBuilder .NET Features Guide

59

CLS Compliance in PowerBuilder

c) Click the Add button again to include as many Using directives as you need.
6. Save the object with its declared namespaces.
The following is an example of a namespace declaration that you can enter in the Namespace tab of an object painter:
namespace sybase.pb.ns
using directive1
using directive2

Adding a Parameterized Constructor

In PowerBuilder .NET, you can define parameterized constructor events that overload the default constructor event and
instantiate the object with the arguments that you assign in the overriding event prototypes.
Parameterized constructor events are supported on all custom and standard class nonvisual user objects. If no arguments
are passed in the call to instantiate a user object, the object's default constructor event is triggered instead of the
parameterized constructor.
Create and invoke a parameterized constructor as follows:
1. Open the object painter for an object whose type supports parameterized constructor events.
Selecting an object in the New dialog box opens its painter automatically.
2. Select New Constructor in the second drop-down list in the object prototype area.
3. Define an overloaded constructor event with the arguments that you want to include.
Arguments must be added to the new constructor event.
4. Create an object by passing in values for the arguments in the overloaded constructor event.
The following example creates an object with two arguments:
Obj obj = CREATE obj(1, 2)

Inheritance from .NET System.Object

In PowerBuilder 12, the .NET System.Object type is the ancestor type of the PowerObject datatype.
Because the PowerObject datatype is the base class of all PowerScript object types, you can invoke the public members
of the .NET System.Object type from any PowerBuilder object.
The following example calls the ToString method that a PowerObject inherits from System.Object:
PowerObject po
String str
Po = create PowerObject
Str = Po.Tostring()

StringBuilder System Class

PowerBuilder includes a StringBuilder system class that maintains a buffer to accommodate new string data.
Use the StringBuilder class to avoid redundant operations and fragmented memory when you concatenate a variable
number of strings.
Note: The StringBuilder class is not available in the beta1 release.
60

CLS Compliance in PowerBuilder

The following example builds a string that concatenates the numbers from 1 to 100:
StringBuilder sb = create StringBuilder()
Int i
FOR i = 1 to 100
Sb.append(mystr)
NEXT

Defining a Custom Attribute

A custom attribute is a class that you can use to represent customized metadata.
Note: Custom attribute support is not available in the beta1 release.
You can define custom attributes and place any of them on any of the following PowerScript elements:
Assembly = 1
Class = 4
Enumeration = 16
Constructor = 32
Method = 64
Property = 128
Field = 256
Event = 512
Interface = 1024
Parameter = 2048
ReturnValue = 8192
All = 32767
The Select Attribute Usage Type wizard lets you choose which elements an attribute can be applied to, and opens the
Custom Attribute painter.
1.
2.
3.
4.
5.

Open the New dialog box.

Select the Custom Attribute icon and start the Custom Attribute wizard.
Choose the type of element that you want the custom attribute to apply to and click Finish.
Create a new custom attribute in Custom Attribute painter.
Apply the custom attribute to an element of the type selected in step 3.

Syntax for a Custom Attribute

You can define and apply custom attributes in PowerScript syntax as well as through the UI.
Note: Syntax supporting custom attributes is not enabled in the beta1 release.
The following examples show how to define a custom attribute for an event using PowerScript syntax:
global type EventPrototype from System.Attribute usage [event]
event clicked
end type
type variables
public string prototype
end variables
forward prototypes
subroutine EventPrototype(string prototype)
PowerBuilder .NET Features Guide

61

CLS Compliance in PowerBuilder

end prototypes
subroutine EventPrototype(string pt)
prototype = pt
end subroutine
The following code places tje custom attribute on the Clicked event:
[EventPrototype(pbm_lbndblclk)]
event clicked
end event

Including XML Documentation Comments

You can create documentation for your code by including XML tags in special comment fields in the source code.
Typically, you add the XML comment fields before the code block they refer to.
The elements that support XML documentation comments are: constructors and destructors, enumerations, events,
functions, interfaces, object, properties, and variables.
1. Open a Script view for the item or element for which you want to add an XML comment.
2. Type three forward slashes before each line that you want to contain an XML comment, and enter your comment.
/// <Summary>
/// The function performs an important task.
/// </Summary>
subroutine MyFunction(string s)

Enhancements to .NET Component Projects

When you generate .NET Web Service and .NET Assembly components from PowerBuilder .NET projects, you can take
advantage of CLS compliant features of PowerBuilder .NET that are not available in PowerBuilder Classic.
PowerBuilder .NET enables you to include user-defined enumerations and user-defined interface types as parameter types
of public methods in .NET assembly and Web service component projects.
If you set the CLSCompliant value of a .NET component project to <codeph>true</codeph>, the PowerBuilder to .NET
compiler (pb2cs) generates the CLSCompliantAttribute(true) attribute for the component, and the C# compiler applies the
CLS rules to the public methods of the component. If you do this and the component is not CLS compliant, the compiler
issues the appropriate warnings or errors.

62

Graphs in PowerBuilder .NET

Graphs in PowerBuilder .NET

Often the best way to display information is graphically. Instead of showing users a series of rows and columns of data,
you can present information as a graph in a DataWindow object or window.
PowerBuilder .NET provides many types of graphs and allows you to customize your graphs in many ways. Probably
most of your use of graphs will be in a DataWindow object. The source of the data for your graphs will be the database.
You can also use graphs and standalone controls in windows (and user objects) and populate the graphs with data through
scripts.
The way you define graphs is the same whether you are using them in a DataWindow object or directly in a window.
However, the way you manipulate graphs in a DataWindow object is different from the way you manipulate them in a
window.

Parts of a Graph
Before using graphs in an application, you need to understand the parts of a graph.
Here is a column graph created in PowerBuilder that contains most major parts of a graph. It shows quarterly sales of three
products: Stellar, Cosmic, and Galactic printers.

How data is represented

Graphs display data points. To define graphs, you need to know how the data is represented. PowerBuilder organizes data
into three components.
Table 7. Components of a graph
Component

Meaning

Series

A set of data points Each set of related data points makes up one series. Each series in a graph is
distinguished by color, pattern, or symbol.

Categories

The major divisions of the data Series data are divided into categories, which are often non-numeric.
Categories represent values of the independent variable(s).

Values

The values for the data points (dependent variables).

PowerBuilder .NET Features Guide

63

Graphs in PowerBuilder .NET

Organization of a graph
Table 8. Parts of a typical graph
Part of graph

What it is

Title

An optional title for the graph. The title appears at the top of the graph.

Value axis

The axis of the graph along which the values of the dependent variable(s) are plotted. In a column graph,
for example, the Value axis corresponds to the y axis in an XY presentation. In other types of graphs, such
as a bar graph, the Value axis can be along the x dimension.

Category axis

The axis along which are plotted the major divisions of the data, representing the independent variable(s).
In column graphs, the Category axis corresponds to the x axis in an XY presentation. These form the major
divisions of data in the graph.

Series

A set of data points. In bar and column charts, each series is represented by bars or columns of one color
or pattern.

Series axis

The axis along which the series are plotted in three-dimensional (3D) graphs.

Legend

An optional listing of the series. The preceding graph contains a legend that shows how each series is
represented in the graph.

Types of Graphs in PowerBuilder .NET

PowerBuilder provides many types of graphs for you to choose from.
You choose the type on the Define Graph Style page in the DataWindow wizard or in the General category in the Properties
view for the graph.

Area, Bar, Column, and Line Graphs

Area, bar, column, and line graphs are conceptually very similar. They differ only in how they physically represent the data
valueswhether they use areas, bars, columns, or lines to represent the values. All other properties are the same.
For more information on graphs, see the PowerBuilder Users Guide.

Pie and Donut Graphs

Pie and donut graphs typically show one series of data points with each data point shown as a percentage of a whole.
You can see the relative values in a series of data.

64

Graphs in PowerBuilder .NET

Figure 1: Donut graph

You can have pie and donut graphs with more than one series if you want; the series are shown in concentric circles.
Multiseries pie and donut graphs can be useful in comparing series of data.

Scatter and Bubble Graphs

Scatter graphs show xy data points. Typically you use scatter graphs to show the relationship between two sets of numeric
values.
Non-numeric values, such as string and DateTime datatypes, do not display correctly.
Scatter graphs do not use categories. Instead, numeric values are plotted along both axesas opposed to other graphs,
which have values along one axis and categories along the other axis.
Bubble graphs enable you to chart three data values in two dimensions, using one x data point and two y data points for
each bubble.
For example, the following data shows the effect of speed on the mileage of a sedan, and the number of minutes required
to travel a mile at that speed:
Speed

Mileage

Minutes per mile

10

12

6.00

20

18

3.00

30

21

2.00

40

23

1.50

50

26

1.20

60

26

1.00

70

24

0.86

80

20

0.75

This scatter graph shows the data from the first two columns:

PowerBuilder .NET Features Guide

65

Graphs in PowerBuilder .NET

Figure 2: Scatter graph of the effect of speed on mileage:

This bubble graph shows the data from all three columns:
Figure 3: Bubble graph of the effect of speed on mileage and distance traveled:

SetBubbleSize Function
The SetBubbleSize function is used to define the size of the bubbles in a bubble graph.

66

Graphs in PowerBuilder .NET

Syntax
integer controlName.SetBubbleSize({string graphControl,} integer seriesNumber,
integer itemNumber, double size)
Argument

Description

controlName

The name of the graph in which you want to set the bubble size, or the name of the DataWindow
control containing the graph.

graphControl (DataWindow control only)

(Optional) A string whose value is the name of the graph in the DataWindow control.

seriesNumber

The number of the series in which you want to set the bubble size.

itemNumber

The number of the data point for which you want to set the bubble size.

size

A double that defines the size of the bubble.

Return value
Returns 0 if successful, 1 for no action. If an error occurs, SetBubbleSize returns a negative integer. Values are:

-1 The row number provided is not valid

-2 The column number provided is not valid
-3 Request requires currency but no current
-4 Data type of request doesn't match column
-5 Argument passed is invalid
-6 Result is null
-7 Expression is bad
-8 Error occured during file i/o processing
-9 Used cancelled action
-13 The DataWindow is invalid
-14 The graph object specified is invalid
-15 Code table index is invalid
-16 Invalid tree
-17 Runtime error
-18 Skip this request and execute the next one

Usage
In bubble graphs, you can plot three data values on two axes, one x and two y. The size of the bubble is proportional to
the value it represents. Use SetBubbleSize to define the size of the bubbles.
Example
This statement changes the size of the first bubble in the first series of graph gr_1 in the DataWindow control dw_1 to
25.
dw_1.SetBubbleSize("gr_1", 1, 1, 25)
BubbleSize Property
The size of a bubble in a bubble graph.

Syntax
PowerBuilder dot notation:
controlName.Object.graphname.BubbleSize

PowerBuilder .NET Features Guide

67

Graphs in PowerBuilder .NET

Argument

Description

controlName

The name of the graph in which you want to set the bubble size, or the name of the DataWindow control
containing the graph.

graphName

A string whose value is the name of the graph in the DataWindow control.

size

A double that defines the size of the bubble.

Usage
In the painter, select the graph control and set the value in the Properties view, Graph group.

Three-Dimensional Graphs
You can create three-dimensional (3D) graphs of area, bar, column, line, pie, and donut graphs.
For more on generating 3D graphs, see the PowerBuilder Users Guide.
The Render3D property is supported in PowerBuilder .NET for backward compatibility, but it will work only for
Column3D and Bar3D graphs.

Radar Graphs
Radar graphs graphically display multivariate data (with three or more quantitative variables) in a two-dimensional chart
represented on axes starting from the same point.
Radar graphs display data points on radii, displaying the data in a way that allows you to see patterns such as dominant
variables, outliers, and other patterns in the data.

68

Graphs in PowerBuilder .NET

Stacked Graphs
In bar and column graphs, you can choose to stack the bars and columns.
In stacked graphs, each category is represented as one bar or column instead of as separate bars or columns for each
series.

Cone Graphs
The cone graph style shows the percentage of every value in a series of data.
A cone graph represents one series of data. Different colors represent different data items in the series, and the heights
represent the percentage it takes from the sum of the series.

PowerBuilder .NET Features Guide

69

Graphs in PowerBuilder .NET

70

DataWindows

DataWindows
You build DataWindow objects to retrieve, present, and manipulate data in your applications.

DataWindows in PowerBuilder .NET

A DataWindow object is an object you use to retrieve, present, and manipulate data from a relational database or other data
source. In PowerBuilder .NET, the WPF DataWindows use fully managed code.
DataWindow objects have knowledge about the data they are retrieving. You can specify display formats, presentation
styles, and other data properties so that users can make the most meaningful use of the data.

Using DataWindow Objects in PowerBuilder .NET

You can use DataWindow objects in WPF Window applications.
Before you can use a DataWindow object, you need to build it. To do that you can go to the DataWindow painter, which
lets you create and edit DataWindow objects.
This procedure describes the overall process for creating using DataWindow objects. To read about the concepts of using
DataWindow objects in different kinds of applications and writing code that interacts with DataWindow objects, see the
DataWindow Programmers Guide.
1. Create the DataWindow object by using one of the DataWindow wizards in the DataWindow group of the New dialog
box.
The wizard helps you define the data source, presentation style, and other basic properties of the object, and the
DataWindow object displays in the DataWindow painter. In this painter, you define additional properties for the
DataWindow object, such as display formats, validation rules, and sorting and filtering criteria.
2. Place a DataWindow control in a window or user object.
It is through this control that your application communicates with the DataWindow object you created in the
DataWindow painter.
3. Associated the DataWindow control with the DataWindow object.
4. Write scripts in the Window painter to manipulate the DataWindow control and its contents.
For example, you use the PowerScript Retrieve method to retrieve data into the DataWindow control.
You can write scripts for the DataWindow control to deal with error handling, sharing data between DataWindow
controls, and so on.

Presentation Styles for DataWindow Objects

The presentation style you select for a DataWindow object determines the format PowerBuilder uses to display the
DataWindow object in the Design view. You can use the format as displayed or modify it to meet your needs.
When you create a DataWindow object, you can choose from the presentation styles listed in the following table.
Table 9. DataWindow presentation styles
Using this DataWindow wizard

You create a new DataWindow object

Composite

That includes other DataWindow objects

Crosstab

With summary data in a spreadsheet-like grid

PowerBuilder .NET Features Guide

71

DataWindows
Using this DataWindow wizard

You create a new DataWindow object

Freeform

With the data columns going down the page and labels next to each column

Graph

With data displayed in a graph

Grid

With data in row and column format with grid lines separating rows and columns

Group

With data in rows that are divided into groups

Label

That presents data as labels

N-Up

With two or more rows of data next to each other

RichText

That combines input fields that repesent database columns with formatted text

Tabular

With data columns going across the page and headers above each column

TreeView

With data grouped in rows in a TreeView; the TreeView displays the data hierarchically in a way that allows you to expand and collapse it

Tabular Presentation Style

The Tabular presentation style presents data with the data columns going across the page and headers above each column.
As many rows from the database will display at one time as can fit in the DataWindow object. You can reorganize the
default layout any way you want by moving columns and text.

Freeform Presentation Style for DataWindow Objects

The Freeform presentation style presents data with the data columns going down the page and labels next to each column.
You can reorganize the default layout any way you want by moving columns and text.

Grid Presentation Style in DataWindow Objects

The Grid presentation style shows data in row-and-column format with grid lines separating rows and columns.
With other styles, you can move text, values, and other objects around freely in designing the report. With the grid style,
the grid lines create a rigid structure of cells.

Label Presentation Style for DataWindow Objects

The Label presentation style shows data as labels.
With this style you can create mailing labels, business cards, name tags, index cards, diskette labels, file folder labels, and
many other types of label

N-Up Presentation Style for DataWindow Objects

The N-Up style presents two or more rows of data next to each other.
It is similar to the Label style in that you can have information from several rows in the database across the page. However,
the information is not meant to be printed on labels. The N-Up presentation style is useful if you have periodic data; you
can set it up so that each period repeats in a row.
After you select a data source, you are asked how many rows to display across the page. For each column in the data
source, PowerBuilder defines n columns in the report (column_1 to column_n), where n is the number of rows you
specified.

72

DataWindows
Note: In an n-up report, the data is displayed across and then down. If you want your data to go down the page and then
across in multiple columns, as in a phone list, you should create a standard tabular report, then specify newspaper
columns.

Group Presentation Style for DataWindow Objects

This style generates a tabular report that has grouping properties defined.
The Group presentation style provides an easy way to create grouped reports, where the rows are divided into groups, each
of which can have statistics calculated for it.

Composite Presentation Style for DataWindow Objects

The Composite presentation style allows you to combine multiple reports in the same object.
It is particularly handy if you want to print more than one report on a page. For more information, see the PowerBuilder
Users Guide.

Graph and Crosstab Presentation Styles for DataWindow Objects

In addition to the text-based presentation styles, PowerBuilder provides two styles that allow you to display information
graphically: Graph and Crosstab.
Note: These styles are not supported in the CTP.
Graphs can be inserted into DataWindows as controls, or you can create DataWindows using the Graph presentation
style.
Cross tabulation is a useful technique for analyzing data. By presenting data in a spreadsheet-like grid, a crosstab lets you
view summary data instead of a long series of rows and columns.

RichText Presentation Style for DataWindow Objects

The RichText presentation style lets you combine input fields that represent database columns with formatted text.
Note: This style is not supported in the CTP.
This presentation style is useful for display-only reports, especially mail-merge documents.

TreeView Presentation Style

The TreeView presentation style provides an easy way to create reports that display hierarchical data in a TreeView.
Rows are divided into groups that can be expanded and collapsed. Icons (+ or ) show whether the state of a group in the
TreeView is expanded or collapsed, and lines connect parents and their children.

Cascading Presentation Style for DataWindow Objects

Cascading presentation style consists of multiple component DataWindows in multiple hierarchical levels.
Note: This style is not available for Beta.
Logically, the Cascading DataWindow conveys the hierarchical relationship between multiple database tables. In the user
interface, Cascading DataWindows organize component DataWindows in a tree-like view, in which each node is a
component DataWindow, and component DataWindows in different levels of this tree have a parent-children relationship.

PowerBuilder .NET Features Guide

73

DataWindows

Using SQL Select

In specifying data for a DataWindow object, you have more options for specifying complex SQL statements when you
use SQL Select as the data source.
When you choose SQL Select, you go to the SQL Select painter, where you can paint a SELECT statement that includes
the following:

More than one table

Selection criteria (WHERE clause)
Sorting criteria (ORDER BY clause)
Grouping criteria (GROUP BY and HAVING clauses)
Computed columns
One or more arguments to be supplied at runtime

Note: While in the SQL Select painter, you can save the current SELECT statement as a query by selecting File > Save
As from the menu bar. Doing so allows you to easily use this data specification again in other DataWindows.

Defining the Data Using SQL Select

In the SQL Select painter, you paint a SQL statement to retrieve data for the DataWindow object.
To define the data using SQL Select:
1. Click SQL Select in the Choose Data Source dialog box in the wizard and click Next.
The Select Tables dialog box opens.
2. Select the tables and/or views that you will use in the DataWindow object.
3. Select the columns to be retrieved from the database.
4. Join the tables if you have selected more than one.
5. Select retrieval arguments if appropriate.
6. Limit the retrieved rows with WHERE, ORDER BY, GROUP BY, and HAVING criteria, if appropriate.
7. If you want to eliminate duplicate rows, select Distinct from the Design menu.
This adds the DISTINCT keyword to the SELECT statement.
8. Click OK in the Query painter.

Selecting Tables and Views Using SQL Select

Select the tables and views that you want to include in the query. The tables and views that are available for you to select
depend on the DBMS.
After you have chosen SQL Select, the Select Tables dialog box displays in front of the Table Layout view of the SQL
Select painter. What tables and views display in the dialog box depends on the DBMS. For some DBMSs, all tables and
views display, whether or not you have authorization. Then, if you select a table or view you are not authorized to access,
the DBMS issues a message.
For ODBC databases, the tables and views that display depend on the driver for the data source. SQL Anywhere does not
restrict the display, so all tables and views display, whether or not you have authorization.
To select the tables and views, do one of the following:

74

Options

Description

Click the name of each table or view

you want to open

Each table you select is highlighted. (To deselect a table, click it again.) Click
the Open button to close the Select Tables dialog box.

DataWindows
Options

Description

Double-click the name of each table or Each object opens immediately behind the Select Tables dialog box. Click the
Cancel button to close the Select Tables dialog box.
view you want to open

Representations of the selected tables and views display. You can move or size each table to fit the space as needed.

Table Layout View in SQL Select

In Table Layout View, representations of any selected tables and views appear in the SQL Select dialog. Below this view
are other tabbed views, which you can use to specify the SQL SELECT statement in more detail.
Below the Table Layout view, several tabbed views also display by default.

Selecting Columns Using SQL Select

In the Table Layout view, you can click each column you want to include from the table representations in the Table Layout
view.
PowerBuilder highlights selected columns and places them in the Selection List at the top of the SQL Select painter.
To select a column, click on it once in the Table Layout view.
Options

Description

To select all columns from a

table:

Move the pointer to the table name and select Select All from the pop-up menu.

To reorder the selected

columns:

Drag a column in the Selection List with the mouse. Release the mouse button when the
column is in the proper position in the list.

To see a preview of the query results, click the Execute button in the Painter bar. A table displaying the query results appear
in the Results tab.
Click the OK button to open the DataWindow painter.

Including Computed Columns Using SQL Select

Computed columns you define in the SQL Select painter are added to the SQL statement and used by the DBMS to retrieve
the data. The expression you define here follows your DBMS's rules.
Note: You can also choose to define computed fields, which are created and processed dynamically by PowerBuilder after
the data has been retrieved from the DBMS. There are advantages to doing this. For example, work is offloaded from the
database server, and the computed fields update dynamically as data changes in the DataWindow object. (If you have
many rows, however, this updating can result in slower performance.)
To include computed columns:
1. Click the Compute tab to make the Compute view available (or select View > Compute if the Compute view is not
currently displayed).
Each row in the Compute view is a place for entering an expression that defines a computed column.
2. Enter one of the following:
Options

Description

An expression for the computed

column

For example: salary/12

A function supported by your

DBMS

For example, the following is a SQL Anywhere function:

substr("employee"."emp_fname",1,2)

3. You can display the pop-up menu for any row in the Compute view. Using the pop-up menu, you can select and paste
the following into the expression:

PowerBuilder .NET Features Guide

75

DataWindows

Names of columns in the tables used in the DataWindow or pipeline

Any retrieval arguments you have specified
Functions supported by the DBMS

The functions listed here are provided by your DBMS. They are not PowerBuilder functions. This is so because you
are now defining a SELECT statement that will be sent to your DBMS for processing.
4. Press the Tab key to get to the next row to define another computed column, or click another tab to make additional
specifications.
PowerBuilder adds the computed columns to the list of columns you have selected.

Defining Queries
This feature is not supported in CTP.

Previewing the Query

While creating a query, you can preview it to make sure it is retrieving the correct rows and columns.
To preview a query:
1. Select Design>Execute from the menu bar.
PowerBuilder retrieves the rows satisfying the currently defined query in the Results view.
2. Manipulate the retrieved data as you do in the Database painter in the results view.
You can sort and filter the data, but you cannot insert or delete a row or apply changes to the database. For more about
manipulating data, see Managing the Database in the PowerBuilder Users Guide.

Saving the Query

While working on a query, you can save it at any time.
To save the query:
1. Select File>Save As Query from the menu bar.
If you have previously saved the query, PowerBuilder allows you to save the query as-is or save a new version in the
same library. If you have not saved the query, PowerBuilder displays the Save Query dialog box.
2. Enter a name for the query in the Query box.
The query name can be any valid PowerBuilder identifier up to 255 characters. When you name queries, use a unique
name to identify each one. A common convention is to use a two-part name to identify each one. A common
convention is to use a two-partt name: a standard prefix that identifies the object as a query (such as q_) and a unique
suffix. For example, you might name a query that displays employee data q_emp_data. For information about
PowerBuilder identifiers, see the Powerscript Reference.
3. (Optional) Enter comments to describe the query.
These comments display in the Library painter. It is a good idea to use comments to remind yourself and others of the
purpose of the query.
4. Specify the library in which to save the query, and click OK.

Modifying the Query

76

DataWindows

DataWindow Object Enhancements

Before you put a DataWindow object into production, you can enhance it to make it easier to use and interpret data.
You make DataWindow object enhancements in the DataWindow painter.

DataWindow Painter
The DataWindow painter provides views related to the DataWindow object you are working on.
The following picture shows a DataWindow object in the DataWindow painter.

DataWindow Painter Design View

For most presentation styles, the DataWindow painter Design view is divided into areas called bands. Each band
corresponds to a section of the displayed DataWindow object.
DataWindow objects with these presentation styles are divided into four bands: header, detail, summary, and footer. Each
band is identified by a bar containing the name of the band above the bar.
These bands can contain any information you want, including text, drawing controls, graphs, and computed fields
containing aggregate totals.
The following picture shows the Design view for a tabular DataWindow object.

PowerBuilder .NET Features Guide

77

DataWindows

Band

Used to Display

Header

Information at the top of every screen, such as the name of the

report or current date

Detail

Data from the database or other data source

Summary

Summary information that displays after all the data, such as

totals and counts

Footer

Information displayed at the bottom of every page or screen, such

as page number and page count

Header Band in DataWindows

The header band contains heading information that is displayed at the top of every screen or page.
The presentation style determines the contents of the header band:

If the presentation style is Tabular, Grid, or N-Up, the headings defined for the columns in the Database painter display
in the header band and the columns display on a single line across the detail band
If the presentation style is Freeform, the header band is empty and labels display in the detail band next to each
column

You can specify additional heading information (such as a date) in the header band and you can include pictures, graphic
controls, and color to enhance the appearance of the band.
Note: To include the current date in the header, you place a computed field that uses the Today DataWindow expression
function in the header band.
Detail Band in DataWindows
The detail band displays the retrieved data. It is also where the user enters new data and updates existing data.
The number of rows of data that display in the PowerBuilder at one time is determined by the following expression:
(Height of the DataWindow object - Height of headers and footers) / Height of the detail band
The presentation style is Tabular, Grid, N-Up, or Label, the detail band displays column names, representing the columns
If the presentation style is Freeform, the labels defined for the columns in the Database painter display in the detail band
with boxes for the data to the right.
When you design the detail band of a DataWindow object, you can specify display and validation information for each
column of the DataWindow object and add other controls, such as text, pictures, graphs, and drawing controls.

78

DataWindows
How PowerBuilder names the columns in the Design view
If the DataWindow object uses one table, the names of the columns in the Design view are the same as the names in the
table.
If the DataWindow object uses more than one table, the names of the columns in the Design view are
tablename_columnname. PowerBuilder prefaces the name of the column with the table name to prevent ambiguity, since
different tables can have columns with the same name.
Summary and Footer Bands
The summary and footer bands are similar to the summaries and footers in a printed report.
You use the summary and footer bands of the DataWindow object the same way you use summary pages and page footers
in a printed report:

The contents of the summary band display at the end, after all the detail rows; this band often summarizes information
in the DataWindow object
The contents of the footer band display at the bottom of each screen or page of the DataWindow object; this band often
displays the page number and name of the report

DataWindow Painter Toolbars

The DataWindow painter contains two customizable PainterBars.
The PainterBars include buttons for standard operations (such as Save, Print, and Undo on PainterBar1) and for common
formatting operations (such as Currency, Percent, and layout in PainterBar2).
Properties View in the DataWindow Painter
Each part of the DataWindow object (such as text, columns, computed fields, bands, graphs, even the DataWindow object
itself) has a set of properties appropriate to the part. The properties display in the Properties view.
You can use the Properties view to modify the parts of the DataWindow object.
For example, the Properties view for a column has categories of information that you access by selecting the appropriate
category. If you want to choose an edit style for the column, you select the Edit Style category.
Using the Preview View of a DataWindow Object
You use the Preview view of a DataWindow object to view it as it will appear with data and test the processing that takes
place in it.
To display the Preview view of a DataWindow object open in the DataWindow painter:
1. If the Preview view is not already displayed, select View>DataWindow Painter Views>Preview from the menu bar.
(If the menu option is not available, make sure the DataWindow painter is active.)
In the Preview view, the bars that indicate the bands do not display. You are prompted to supply arguments if you
defined retrieval arguments.
2. Test your DataWindow object.
For example, modify some data, update the database, re-retrieve rows, and so on.
Note: Insertrow and Deleterow are not enabled for CTP.

Adding Controls to a DataWindow Object

One of the ways you can enhance a DataWindow object is to add controls.
Using the Toolbox, you can add controls such as columns, drawing objects, buttons, and computed fields. You can also
change the layout of the DataWindow object by reorganizing, positioning, and rotating controls.

PowerBuilder .NET Features Guide

79

DataWindows

Adding Columns to a DataWindow Object

You can add columns that are included in the data source to a DataWindow object.
When you first create a DataWindow object, each of the columns in the data source is automatically placed in the
DataWindow object. Typically, you would add a column to restore one that you had deleted from the DataWindow object,
or to display the column more than once in the DataWindow object.
Note: If you want to add a column from the DataWindow definition to a DataWindow, always insert it from the Toolbox.
You might see unexpected results if you copy a column from one DataWindow object to another if they both reference the
same column but the column order is different. This is because copying a column copies a reference to the column's ID
in the DataWindow definition.
Suppose d_first and d_second both have first_name and last_name columns, but first_name is in column 1 in d_first
and column 2 in d_second. If you delete the first_name column in d_second and paste column 1 from d_first in its place,
both columns in d_second display the last_name column in the Preview view, because both columns now have a column
ID of 1.
1. Click the Column control in the Toolbox.
2. Click where you want to place the column.
The Select Column dialog box displays, listing all columns included in the data source of the DataWindow object.
3. Select the column.

Adding Text to a DataWindow Object

You can add text anywhere in a DataWindow object.
When PowerBuilder generates a basic DataWindow object from a presentation style and data source, it places columns
and their headings in the DataWindow painter. You can add text anywhere you want to make the DataWindow object easier
to understand.
1. Click the Text control in the Toolbox.
2. Click where you want the text.
PowerBuilder places the text control in the Design view and displays the word text.
3. Type the text you want.
4. (Optional) Change the font size, style, and alignment for the text using the Properties View.

Adding Drawing Controls to a DataWindow Object

You can add drawing controls to a DataWindow object.
You can add the following drawing controls to a DataWindow object to enhance its appearance:

Rectangle
RoundRectangle
Line
Oval

1.
2.
3.
4.

Select the drawing control in the Toolbox.

Click where you want the control to display.
Reize or move the drawing control as needed.
Use the drawing control's Properties view to change its properties as needed.
For example, you might want to specify a fill color for a rectangle or thickness for a line.

Adding a Group Box to a DataWindow Object

Use group boxes to organize controls in a DataWindow object.
80

DataWindows

To visually enhance the layout of a DataWindow object you can add a group box. A group box is a static frame used to
group and label a set of controls in a DataWindow object.
1. Select GroupBox in the Toolbox.
2. Click where you want the control to display
3. With the group box selected, edit the Text property in the General category in the Properties view. This changes the
text to display in the frame.
4. Move and resize the group box as appropriate.

Adding Pictures to a DataWindow Object

You can place pictures, such as your company logo, in a DataWindow object to enhance its appearance.
If you place a picture in the header, summary, or footer band of the DataWindow object, the picture displays each time the
content of that band displays. If you place the picture in the detail band of the DataWindow object, it displays on each
row.
1. Select the Bitmap control in the Toolbox.
2. In the Design view, click where you want the picture to display.
The Open dialog box displays.
3. Locate the image file you want to use and select it, then click Open.
The picture must be a bitmap (BMP), runlength-encoded (RLE), Windows metafile (WMF), Graphics Interchange
Format (GIF), Joint Photographic Experts Group (JPG) file, or Portable Network Graphics (PNG) file.
4. You can use the mouse to change the size of the image in the DataWindow painter, or set its Height and Width
properties in the Properties View.

Adding Computed Fields to a DataWindow Object

You can use computed fields in any band of the DataWindow object.
You can enter any valid DataWindow expression when defining a computed field. You can paste operators, columns, and
DataWindow expression functions into the expression from information in the Modify Expression dialog box. Use the +
operator to concatenate strings.
You can use any built-in or user-defined global function in an expression. You cannot use object-level functions.
Note: You are entering a DataWindow expression, not a SQL expression processed by the DBMS, so the expression
follows the rules for DataWindow expressions.
1. Select the Compute control in the Toolbox.
2. In the Design view, click where you want to place the computed field.
If the calculation is to be based on column data that changes for each row, make sure you place the computed field in
the detail band.
The Modify Expression dialog box displays, listing:
DataWindow expression functions you can use in the computed field
The columns in the DataWindow object
Operators and parentheses
3. Enter the expression that defines the computed field.
4. (Optional) Click Verify to test the expression.
PowerBuilder analyzes the expression.
5. Click OK.
These are some examples of computed fields.

PowerBuilder .NET Features Guide

81

DataWindows
To display

Enter this expression

In this band

Current date at top of each page

Today()

Header

Current time at top of each page

Now()

Header

Current page at bottom of each page

Page()

Footer

Total page count at bottom of each page

PageCount()

Footer

Concatenation of Fname and Lname columns for Fname + " " + Lname
each row

Detail

Monthly salary if Salary column contains annual

salary

Salary / 12

Detail

Four asterisks if the value of the Salary column is

greater than $50,000

IF(Salary > 50000, "****", "")

Detail

Average salary of all retrieved rows

Avg(Salary)

Summary

Count of retrieved rows, assuming each row contains a value for EmpID

Count(EmpID)

Summary

You can refer to other rows in a computed field. This is particularly useful in N-Up DataWindow objects when you want
to refer to another row in the detail band. Use this syntax:
ColumnName[x]
where x is an integer. 0 refers to the current row (or first row in the detail band), 1 refers to the next row, -1 refers to the
previous row, and so on.
For complete information about the functions you can use in computed fields in the DataWindow painter, see the
DataWindow Reference.
Computed Columns Versus Computed Fields
You define computed columns in the SQL Select painter, and the value is calculated by the DBMS when the data is
retrieved. You define computed fields in the DataWindow painter, and the value is calculated after the data has been
retrieved.
When creating a DataWindow object, you can define computed columns and computed fields as follows:

In the SQL Select painter, you can define computed columns when you are defining the SELECT statement that will
be used to retrieve data into the DataWindow object.
In the DataWindow painter, you can define computed fields after you have defined the SELECT statement (or other
data source).

When you define the computed column in the SQL Select painter, the value is calculated by the DBMS when the data is
retrieved. The computed column's value does not change until data has been updated and retrieved again.
When you define the computed field in the DataWindow painter, the value of the column is calculated in the DataWindow
object after the data has been retrieved. The value changes dynamically as the DataWindow object changes.
Tip: If you want your DBMS to do the calculations on the server before bringing data down and you do not need the
computed values to be updated dynamically, define the computed column as part of the SELECT statement.
If you need computed values to change dynamically, define computed fields in the DataWindow painter Design view.
Consider a DataWindow object with four columns: Part number, Quantity, Price, and Cost. Cost is computed as
Quantity * Price.

82

DataWindows
Part#

Quantity

Price

Cost

101

100

1.25

125.00

If Cost is defined as a computed column in the SQL Select painter, the SELECT statement is as follows:
SELECT part.part_num,
part.part_qty
part.part_price
part.part_qty * part.part_price
FROM part;
If the user changes the price of a part in the DataWindow object in this scenario, the cost does not change in the
DataWindow object until the database is updated and the data is retrieved again. The user sees a display with the changed
price but the unchanged, incorrect cost.
Part#

Quantity

Price

Cost

101

100

2.50

125.00

If Cost is defined as a computed field in the DataWindow object, the SELECT statement is as follows, with no computed
column:
SELECT part.part_num
part.part_qty
part.part_price
FROM part;
The computed field is defined in the DataWindow object as Quantity * Price.
In this scenario, if the user changes the price of a part in the DataWindow object, the cost changes immediately.
Part#

Quantity

Price

Cost

101

100

2.50

250.00

Menu Options and Buttons for Common Functions

You can define computed fields in the DataWindow painter.
PowerBuilder provides a quick way to create computed fields that summarize values in the detail band, display the current
date, or show the current page number.
Insert a Computed Field for the Current Date or Page Number
The functions for the current date and page number are available in the Modify Expression dialog box.
To insert a computed field for the current date or page number:
1. Click the Compute control in the Toolbox.
2. Select today() or page() from the function list in the Modify Expression dialog box.
3. Click in the DataWindow object where you want the field to appear.
If you want to display Page n of n, create the expression: 'Page ' + page() + ' of ' + pageCount()
Adding Custom Buttons that Place Computed Fields
Not supported in Beta

1. Place the mouse pointer over the PainterBar and select Customize from the pop-up menu.
The Customize dialog box displays.
2.

PowerBuilder .NET Features Guide

83

DataWindows

Adding Buttons to a DataWindow Object

Buttons make it easy to provide command button actions in a DataWindow object. No coding is required.
The use of Button controls in the DataWindow object, instead of CommandButton controls in a window, ensures that
actions appropriate to the DataWindow object are included in the object itself.
The Button control is a command or picture button that can be placed in a DataWindow object. When clicked at runtime,
the button activates either a built-in or user-supplied action.
For example, you can place a button in a report and specify that clicking it opens the Filter dialog box, where users can
specify a filter to be applied to the currently retrieved data.
Note: Do not use a message box in the Clicked event. If you call the MessageBox function in the Clicked event, the action
assigned to the button is executed, but the ButtonClicking and ButtonClicked events are not executed.
1. Click the Button control in the Toolbox.
2. Click where you want the button to display.
You may find it useful to put a Delete button or an Insert button in the detail band. Clicking a Delete button in the detail
band will delete the row next to the button clicked. Clicking an Insert button in the detail band will insert a row
following the current row.
Note: Buttons in the detail band repeat for every row of data, which is not always desirable. Buttons in the detail band
are not visible during retrieval, so a Cancel button in the detail band would be unavailable when needed.
3. With the button still selected, type the text to display on the button or in the Properties view.
4. Select the action you want to assign to the button from the Action drop-down list in the General section of the
Properties view.
Actions Assignable to Buttons in DataWindow Objects
There are actions available for you to assign to a Button control, or you can define an event script.
The table shows the actions you can assign to a button in a DataWindow object. Each action is associated with a numeric
value (the Action DataWindow object property) and a return code (the actionreturncode event argument).
The following code in the ButtonClicked event displays the value returned by the action:
MessageBox("Action return code", actionreturncode)
Action

Effect

NoAction (default)

Allows the developer to program the But0

tonClicked event with no intervening action
occurring.

The return code from the user's coded

event script.

RetrieveYield

Retrieves rows from the database. Before

1
retrieval occurs, the option to yield is turned
on; this will allow the Cancel action to take
effect during a long retrieve.

Number of rows retrieved.

Retrieves rows from the database. The option to yield is not automatically turned on.

Number of rows retrieved.

Retrieve

Cancel

84

Value

Cancels a retrieval that has been started with 3

the option to yield.

Action return code

-1 if retrieve fails

-1 if retrieve fails
0

DataWindows
Action

Effect

Value

Action return code

PageNext

Scrolls to the next page.

The row displayed at the top of the DataWindow control when the scrolling is
complete or attempts to go past the first
row.
-1 if an error occurs.

PagePrior

Scrolls to the prior page.

The row displayed at the top of the DataWindow control when the scrolling is
complete or attempts to go past the first
row.
-1 if an error occurs.

PageFirst

Scrolls to the first page.

1 if successful.
-1 if an error occurs.

PageLast

Scrolls to the last page.

The row displayed at the top of the DataWindow control when the scrolling is
complete or attempts to go past the first
row.
-1 if an error occurs.

Sort

Filter

DeleteRow

Displays Sort dialog box and sorts as speci- 8

fied.

1 if successful.

Displays Filter dialog box and filters as

specified.

Number of rows filtered.

-1 if an error occurs.

Number < 0 if an error occurs.

If button is in detail band, deletes row asso- 10

ciated with button; otherwise, deletes the
current row

1 if successful.

AppendRow

Inserts row at the end.

11

Row number of newly inserted row.

InsertRow

If button is in detail band, inserts row using 12

row number associated with the button; otherwise, inserts row using the current row.

Row number of newly inserted row.

Update

Saves changes to the database. If the update 13

is successful, a Commit will be issued; if
the update fails, a Rollback will be issued.

1 if successful.

Displays Save As dialog box and saves rows 14

in the format specified.

Number of rows filtered.

Print

Prints one copy of the DataWindow object.

15

Preview

Toggles between preview and print preview 16

PreviewWithRulers

Toggles between rulers on and off.

17

QueryMode

Toggles between query mode on and off.

18

QuerySort

Allows user to specify sorting criteria

(forces query mode on).

19

SaveRowAs

PowerBuilder .NET Features Guide

-1 if an error occurs

-1 if an error occurs

Number < 0 if an error occurs.

85

DataWindows
Action

Effect

Value

Action return code

QueryClear

Removes the WHERE clause from a query

(if one was defined).

20

Add Graphs to DataWindow Objects

PowerBuilder offers many types of graphs and provides you with the ability to control the appearance of a graph to best
meet your application's needs.
Graphs are one of the best ways to present information. For example, if your application displays sales information over
the course of a year, you can easily build a graph in a DataWindow object to display the information visually.
See the Graphs in PowerBuilder .NET topics.

Adding Reports to a DataWindow Object

You can nest reports (nonupdatable DataWindow objects) in a DataWindow object.
Nesting reports works the same in PowerBuilder .NET as in PowerBuilder Classic, except that you select the Report
control from the Toolbox. For more information, see the PowerBuilder Users Guide.

Adding WPF Controls to a DataWindow Object

You can add WPF controls from the Toolbox to the DataWindow object.
You can add built-in, third-party, and custom WPF controls to DataWindow objects using the toolbox.
Tip: If the control you want to use is not in the toolbox, add it using Choose Items in the context menu.
1. Click the WPF control in the Toolbox.
2. Click where you want the control to display.
3. Set the properties as appropriate.

Tooltips in DataWindow Objects

Tooltips display text when the pointer pauses over a DataWindow column or control.
Tooltip text can be used to explain the purpose of the column or control. To use this feature, select the column or control
for which you want to create a tooltip and use the Tooltips properties in the Properties view.

86

Text for the tooltip

Title for the tooltip
Color of the background and text
Icon for the tooltip
Delay before the tooltip appears and disappears
Whether the tooltip appears as a rectangle or callout bubble
Whether the tooltip has a close button

Database Management in PowerBuilder .NET

Database Management in PowerBuilder .NET

You can manage a database from within PowerBuilder.
For the most part, the Database painter works the same in PowerBuilder .NET as in PowerBuilder Classic.
PowerBuilder 12 provides enhanced support for connecting to any .NET provider through a managed ADO.NET
interface. You can use the built-in ADO.NET drivers for Oracle, ASE, and SQL Server from PowerBuilder Classic or
PowerBuilder .NET applications. These drivers enable you to access most of the current database features of those
providers.
For more information, see the New Features in PowerBuilder 12 topic in the online Help.

Defining Database Profiles

You can edit an existing database profile or create a new one.
Database profiles defined in either PowerBuilder Classic or PowerBuilder .NET are available to both.
Select Tools>Database Profiles and then click the Edit button or the New button.
For more information about how to edit or define a database profile, see Connecting to Your Database.

The Database Painter in PowerBuilder .NET

To open the Database painter, select the View>Database Painter from the menu bar.
Like the other PowerBuilder tool windows, the Database painter contains a menu bar, customizable PainterBars, and
several views. All database-related tasks that you can do in PowerBuilder can be done in the Database painter.
Because it is a tool window, you can dock it, auto-hide it, float it, or view it as a tabbed document.
To open views in the Database painter, select the view from View>Database Painter Views in the main menu bar.

Manipulating Data in Database Painter

As you work on the database, you often want to look at existing data or create some data for testing purposes. You might
also want to test display formats, validation rules, and edit styles on real data.
PowerBuilder provides data manipulation for such purposes. With data manipulation, you can:

Retrieve and manipulate database information

Save the contents of the database in a variety of formats (such as Excel, PDF, or XML)

These functions work the same as in PowerBuilder Classic; for more information see thePowerBuilder Users Guide.

SQL Statements in Database Painter

The Database painter's Interactive SQL view is a SQL editor in which you can enter and execute SQL statements. The view
provides all editing capabilities needed for writing and modifying SQL statements.
You can cut, copy, and paste text; search for and replace text; and create SQL statements. You can also set editing
properties to make reading your SQL files easier.

PowerBuilder .NET Features Guide

87

Database Management in PowerBuilder .NET

For the most part, the Database painter works the same in PowerBuilder .NET as in PowerBuilder Classic; for more
information see the PowerBuilder Users Guide.

DSI Database Trace Tool

The DSI Database Trace tool is a managed database interface that records the internal commands PowerBuilder executes
while accessing a database.
Use the DSI Database Trace tool in PowerBuilder .NET WPF applications to trace DSI database connections at runtime.
Unless you use the PBADO driver, the DSI data source interface calls the DBI database interface to connect to a database.
This, in turn, activates the DBI Database Trace tool to trace the DBI database connections, although you can disable DBI
tracing through a DSI parameter setting.
Enabling the DSI Database Trace tool
You enable DSI tracing in WPF applications by adding "tra" followed by a blank space before the assignment of the
transaction object DBMS. For example:
SQLCA.DBMS = "TRA ODBC"
The DSI Database Trace tool writes the output of the DSI trace to a log file that you specify in a DSI parameter setting.
When you enable DSI or DBI database tracing for the first time, PowerBuilder creates the log file on your computer.
Tracing continues until you disconnect from the database.
At design time, you can only use DBI tracing. For information about DBI tracing, see the PowerBuilder Classic Users
Guide.
Parameters of the DSI database trace
You set parameters for the DSI Database Trace tool in a "DSITrace" section of the configuration file for your application.
The DSITrace section must also include a type parameter set to "Sybase.PowerBuilder.DataSource.DSITraceConfig,
Sybase.PowerBuilder.DataSource,Version=12.0.0.0, Culture=neutral, PublicKeyToken=598c7456a83d557a".
Note: The DSITrace section with the required type parameter is generated automatically in the application configuration
file on deployment, but it is commented out. You can uncomment this section when you set parameters for DSI tracing
in the configuration file .
The following table describes parameters you can set for DSI tracing in a DSITrace element after the configSections tag
in the application configuration file.
Parameter

Description

fileName

Name and location of the trace log file. If you do not specify a full path name, the log file is saved in the
current directory. If you do not use this parameter, the DSI trace will not be generated.

disableDBITrace
(optional)

Use to set or cancel DBI tracing when DSI tracing is enabled. This parameter is not valid for PBADO drivers.
Values are:

0 - (default) DBI tracing is enabled

1 - DBI tracing is disabled
showParameters (op- Use to include or exclude SQL command parameters in the DSI trace log file. Values are:
tional)

0 - (default) SQL command parameters are not included in the

log file
1 - SQL command parameters are included in the log file

88

Database Management in PowerBuilder .NET

Parameter

Description

showFetchData (optional)

Use to include or exclude data from fetch buffers in the DSI trace log file. Values are:

0 - (default) Fetch data are not included in the log file

1 - Fetch data are included in the log file

Configuration file example:

The following settings in an application configuration file disable DBI tracing, cause the DSI trace to include SQL
command parameters and fetch data in its log file, and save the log file to the current directory with the default
DSITRACE.LOG file name:
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<configSections>
<section name="DSITrace"
type="Sybase.PowerBuilder.
DataSource.DSITraceConfig, Sybase.
PowerBuilder.DataSource,Version=12.0.0.0,
Culture=neutral, PublicKeyToken=598c7456a83d557a"

>
</configSections>
...
<DSITrace fileName="c:\dsitrace.log" disableDBITrace="1"
showParameters="1"
showFetchData="1" /
>
...
</configuration>

Trace file contents

The log file that you generate with the DSI Database Trace tool lists information from commands of three object types:
DSConnection, DSCommand, and DSReader. The log file also lists SQL commands and data from fetch buffers if you
enabled those options in the configuration file.
The format for the DSI command information is as follows, where tID is the thread ID, objID is a random 8-digit number
for the DSObject, DSObject is either DSConnection, DSCommand, or DSReader, and commandIssued is the name of the
command. The starting time for the command is given to the second, and the duration of the command is given in
milliseconds (MS):
(tID.objID) DSObject.commandIssued() MM/DD/YYYY HR:MIN:SEC / #### MS

PowerBuilder .NET Features Guide

89

Database Management in PowerBuilder .NET

90

WCF Client Proxy Reference

WCF Client Proxy Reference

The WCF Client Proxy project relies on a series of classes and enumerations to connect to a variety of Web services.
When you build a WCF client proxy project, the Project painter creates a WCFConnection object that it automatically
instantiates with information obtained from the WSDL file for the services you want to access.
The WCFConnection object has the WCFConnection class type, and it invokes a number of other classes that can store
information about binding types, transport and message security protocols, and other properties of the services you want
to access for your client applications. The WCFConnection object allows you to create a Web service client without
worrying about these connection details.
If you are accessing Web services through a firewall, building a WCF Client Proxy project can instantiate an object of the
WCFProxyServer class to include values from the Firewall page of the Options dialog box that you open from the
PowerBuilder .NET Tools>Options menu. When you use the Project painter, it is not necessary to invoke this or other
WCF project reference classes in script.
Although you do not need to call the WCF reference classes or select enumerated values for service binding parameters
and proxy server settings, you can do this to override default values. You can also query class properties to view the
parameters that the proxy object will use to connect to Web services. The reference topics that follow provide information
about the WCFConnection object, and the classes and enumerations it uses to access Web services.

WCFConnection Object
The WCFConnection object includes all options for calling WCF services. You create a WCFConnection object
automatically when you build a WCF Client Proxy project.
The WCFConnection object is an instance of the WCFConnection class.
Properties
WCFConnection property

Type

Description

BindingType

WCFBindingType (enumeration)

Specifies the binding type and communciation

format to use when accessing a WCF service.
The default value is generated from the service
contract. If you delete this value, the
connection is attempted using
BasicHttpBindiing as the default binding type.
Values are: BasicHttpBinding,
WSHttpBinding,
WS2007HttpBinding,
WSFederationHttpBinding,
WS2007FederationHttpBinding,
NetTcPBinding,
NetNamedPipeBinding,
NetMsmqBinding, and
WebHttpBinding.
WCF connection bindings are described on the
MSDN Web site.

ClientCredential

PowerBuilder .NET Features Guide

WCFClientCredential (class)

Specifies the WCF credential to use for

communication with the Web service.

91

WCF Client Proxy Reference

WCFConnection property

Type

Description

EndpointAddress

WCFEndpointAddress (class)

Specifies a URL for the remote Web service,

and tells the Web service engine where the
Web service resides. If the endpoint is not
explicitly set, the Web service engine uses the
default endpoint embedded in the service
contract file and in the generated Web service
assembly.

ProxyServer

WCFProxyServer (class)

Allows you to specify credentials for a proxy

server if the client machine is behind a firewall.
If the client machine is directly connected to
the Internet, you need not set this property.

Timeout

String

Specifies how long the WCF engine waits

before timing out while invoking the Web
service. The default value is 10 minutes
("00:10:00"). The format for the time is
"hh:mm:ss".
The Web service might have a different
timeout value on the server side.

BasicHttpBinding

WCFBasicHttpBinding (class)

Defines binding settings for

BasicHttpBinding. This property is used only
when the BindingType property is
BasicHttpBinding.

wsHttpBinding

WCFwsHttpBinding (class)

Defines binding settings for

WCFwsHttpBinding. This property is used
only when the BindingType property is
WCFwsHttpBinding.

NetTcpBinding

WCFNetTcpBinding (class)

Defines binding settings for NetTcpBinding.

This property is used only when the
BindingType property is NetTcpBinding.

WebHttpBinding

WCFWebHttpBinding (class)

Defines binding settings for WebHttpBinding.

This property is used only when the
BindingType property is WebHttpBinding.

ws2007HttpBinding

WCFws2007HttpBinding (class)

Defines binding settings for

ws2007HttpBinding. This property is used
only when the BindingType property is
ws2007HttpBinding.

wsFederationHttpBinding

WCFwsFederationHttpBinding
(class)

Defines binding settings for

ws2007HttpBinding. This property is used
only when the BindingType property is
ws2007HttpBinding.

ws2007FederationHttpBinding WCFws2007FererationHttpBinding Defines binding settings for

(class)
ws2007FererationHttpBinding. This property
is used only when the BindingType property is
ws2007FererationHttpBinding.
NetNamedPipeBinding

92

WCFNetNamedPipeBinding (class) Defines binding settings for

NetNamedPipeBinding. This property is used
only when the BindingType property is
NetNamedPipeBinding.

WCF Client Proxy Reference

WCFConnection property

Type

Description

NetMSMQBinding

WCFNetMSMQBinding (class)

Defines binding settings for

NetMSMQBinding. This property is used only
when the BindingType property is
NetMSMQBinding.

Events
WCFConnection event

Occurs

Constructor

Immediately before the Open event occurs in the window

Destructor

Immediately after the Close event occurs in the window

Functions
WCFConnection
function

Datatype
returned

Description

ClassName

String

Returns the name assigned to the control

GetContextService

Integer

Creates a reference to a context-specific instance of the specified

service

GetParent

PowerObject

Returns a reference to the name of the parent object

PostEvent

Boolean

Adds an event to the end of the message queue for the control

TriggerEvent

Integer

Triggers a specified event in the control and executes the script for
the event

TypeOf

Object

Returns the type of the control

Classes Supporting WCF Client Connections

Several PowerScript system classes provide all the support required for WCF client connections from PowerBuilder .NET
applications.
The objects you create by instantiating these classes enable you to select the binding types, transport modes, and message
security settings for WCF Web service connections.

BasicHttpMessageSecurity Class
The BasicHttpMessageSecurity class enables you to get and configure the message security settings of a
BasicHttpBinding binding for a WCF client.

Properties
BasicHttpMessageSecurity
property

Type

Description

SecurityAlgorithm

SecurityAlgorithmType
(enumeration)

Specifies the algorithm suite to use for Http

message security. Values are: DEFAULT,
BASIC128, BASIC128RSA15,

PowerBuilder .NET Features Guide

93

WCF Client Proxy Reference

BasicHttpMessageSecurity
property

Type

Description
BASIC128HA256,
BASIC128SHA256RSA15A15, BASIC192,
BASIC192RSA15, BASIC192HA256,
BASIC192SHA256RSA15, BASIC256
(default), BASIC256RSA15,
BASIC256HA256,
BASIC256SHA256RSA15, TRIPLEDES,
TRIPLEDESRSA15, TRIPLEDESSHA256,
and TRIPLEDESSHA256RSA15.

ClientCredentialType

BasicHttpMessageCredentialType
(enumeration)

Specifies the credential type the client uses for

authentication. Values are: UserName (default)
and Certificate.

BasicHttpSecurity Class
The BasicHttpSecurity class configures the security settings of a BasicHttpBinding binding for a WCF client.

Properties
BasicHttpSecurity
property

Type

Description

SecurityMode

BasicHttpSecurityMode
(enumeration)

Gets or sets the security mode for a BasicHttpBinding binding.

Values are: None (default), Transport, Message,
TransportCredentialOnly, and
TransportWithMessageCredential.

Transport

HttpTransportSecurity (class) Gets the transport level security settings for a

BasicHttpBinding binding.

Message

BasicHttpMessageSecurity
(class)

Gets the message level security settings for a

BasicHttpBinding binding.

ClientCertificateCredential Class
The ClientCertificateCredential class enables you to select a client certificate for a secure connection to a Web service.

Properties

94

ClientCertificateCredential
property

Type

Description

SubjectName

string

Specifies the full path file name or the distinguished

subject name of the certificate you want to use. If you use
a full path file name, the StoreLocation and StoreName
properties are ignored.

StoreLocation

CertStoreLocation
(enumeration)

Specifies the location of the X.509 certificate store where

the certificate you want to use resides.

StoreName

CertStoreName
(enumeration)

Specifies the name of the X.509 certificate store where the

certificate you want to use resides.

WCF Client Proxy Reference

Note: The distinguished subject name of a certificate that you can specify for the SubjectName property is a commaseparated textual representation of the certificate details in the format "E=mailAddress, CN=commonName,
OU=orgUnit, O=organization, L=locality, S=stateOrProvince,C=countryCode". Determine the distinguished subject
name by double-clicking the certificate you want to use in the Certificate Manager (accessible from the Content tab of the
Internet Explorer Internet Options dialog box), switching to the Details tab, and selecting Subject in the Field column of
the list view on the Details tab.

HttpTransportSecurity Class
The HttpTransportSecurity class enables you to get and configure transport security settings for a WCF Web service that
uses BasicHttpBinding, WebHttpBinding, or wsHttpBinding bindings.

Properties
HttpTransportSecurity
property

Type

Description

Realm

string

Gets or sets the authentication realm for digest or basic

authentication. The authentication realm string must
include the name of the host performing the
authentication, and can also list the collection of users
with access permissions.

ClientCredentialType

HttpClientCredentialType
(enumeration)

Specifies the credential type for HTTP client

authentication. Values are: None (default), Basic,
Digest, NTLM, Windows, and Certificate.

HttpDigestCredential Class
The HttpDigestCredential class provides credential information that allows a WCF client to use a proxy server, or connect
to a Web service that requires digest authentication.
Invoke objects of the HttpDigestCredential class from the HttpDigest property of WCFClientCredential class objects.
Properties
HttpDigestCredential
property

Type

Description

UserName

UserNameCredential
(class)

Specifies the user name, password, and domain of the

client.

AllowImpersonationLevel

ImpersonationLevel
(enumeration)

Determines the impersonation level of the WCF client.

Values are: None (default), Anonymous,
Identification, Impersonation, and
Delegation.

MessageSecurityOverTcp Class
The MessageSecurity class configures message-level security settings for a message sent using TCP transport.

PowerBuilder .NET Features Guide

95

WCF Client Proxy Reference

Properties
MessageSecurityOverTcp
property

Type

Description

AlgorithmSuite

SecurityAlgorithmType
(enumeration)

Specifies the algorithm suite used for message-level

security. Valid values are: DEFAULT, BASIC128,
BASIC128RSA15, BASIC128HA256,
BASIC128SHA256RSA15A15, BASIC192,
BASIC192RSA15, BASIC192HA256,
BASIC192SHA256RSA15, BASIC256 (default),
BASIC256RSA15, BASIC256HA256,
BASIC256SHA256RSA15, TRIPLEDES,
TRIPLEDESRSA15, TRIPLEDESSHA256,
TRIPLEDESSHA256RSA15, and
TRANSPORTWITHMESSAGECREDENTIAL.

ClientCredentialType

MessageCredentialType
(enumeration)

Specifies the credential type used for client authentication.

Values are: NONE, WINDOWS (default), USERNAME,
CERTIFICATE, and ISSUEDTOKENS.

NetTcpSecurity Class
The NetTcpSecurity class configures the security settings of a NetTcpBinding binding for a WCF client and WCF
service.

Properties
NetTcpSecurity
property

Type

Description

SecurityMode

wsSecurityMode
(enumeration)

Gets or sets the security mode for the binding. Values are: None,
Transport (default), Message, and
TransportWithMessageCredential.

Transport

TcpTransportSecurity (class) Provides properties to control authentication parameters and the

protection level for TCP transport.

Message

MessageSecurityOverTcp
(class)

Provides properties that control authentication parameters and the

protection level for TCP messages.

NoDualHttpMessageSecurity Class
The NoDualHttpMessageSecurity class represents message-level security settings over an HTTP protocol where security
is not set for two-way communication.

Properties

96

NoDualHttpMessageSecurity Type
property

Description

SecurityAlgorithm

Specifies the algorithm suite to use with

NoDualHttpMessageSecurity. Values are: DEFAULT,
BASIC128, BASIC128RSA15, BASIC128HA256,
BASIC128SHA256RSA15A15, BASIC192,
BASIC192RSA15, BASIC192HA256,

SecurityAlgorithmType
(enumeration)

WCF Client Proxy Reference

NoDualHttpMessageSecurity Type
property

Description
BASIC192SHA256RSA15, BASIC256 (default),
BASIC256RSA15, BASIC256HA256,
BASIC256SHA256RSA15, TRIPLEDES,
TRIPLEDESRSA15, TRIPLEDESSHA256,
TRIPLEDESSHA256RSA15, and
TRANSPORTWITHMESSAGECREDENTIAL.

ClientCredentialType

MessageCredentialType Specifies the credential type to use for client

(enumeration)
authentication. Values are: NONE, WINDOWS (default),
USERNAME, CERTIFICATE, and ISSUEDTOKENS.

EstablishSecurityContext

boolean

Controls whether a security context token is established

through a WS-SecureConversation exchange between a
client and Web service. Values are:

NegotiateServiceCredential

boolean

true (default) requires the remote party to support

the WS-SecureConversation protocol.
false the WS-SecureConversation protocol is not
used for the communication.

Specifies whether the service credential is supplied by the

Web service through a negotiated process. Values are:

true (default) service credential is obtained

through a negotiated process.
false service credential is supplied by the client
out of band.

ServiceCertificateCredential Class
The ServiceCertificateCredential class provides a client certificate for a secure connection to a Web service. Use this class
instead of the ClientCredentialService class when message-level security is enabled for the service.
Properties
ServiceCertificateCredential
property

Type

Description

SubjectName

string

Specifies the full path file name or the distinguished

subject name of the certificate you want to use. If you use
a full path file name, the StoreLocation and StoreName
properties are ignored.

StoreLocation

CertStoreLocation
(enumeration)

Specifies the location of the X.509 certificate store where

the certificate you want to use resides.

StoreName

CertStoreName
(enumeration)

Specifies the name of the X.509 certificate store where the

certificate you want to use resides.

Note: The distinguished subject name of a certificate that you can specify for the SubjectName property is a commaseparated textual representation of the certificate details in the format "E=mailAddress, CN=commonName,
OU=orgUnit, O=organization, L=locality, S=stateOrProvince,C=countryCode". Determine the distinguished subject
name by double-clicking the certificate you want to use in the Certificate Manager (accessible from the Content tab of the
Internet Explorer Internet Options dialog box), switching to the Details tab, and selecting Subject in the Field column of
the list view on the Details tab.
PowerBuilder .NET Features Guide

97

WCF Client Proxy Reference

TcpTransportSecurity Class
The TcpTransportSecurity class provides properties to control authentication parameters and the protection level for TCP
transport. Use it, instead of the HttpTransportSecurity class, to set the transport-level security for Web service bindings
that use TCP for message delivery.

Properties
TcpTransportSecurity
property

Type

Description

ClientCredentialType

TcpClientCredentialType
(enumeration)

Specifies the credential type for TCP client

authentication. Values are: NONE, WINDOWS (default),
and CERTIFICATE.

ProtectionLevel

ProtectionLevel (enumeration) Gets or sets the protection level for the TCP stream.
Values are: NONE, SIGN, and ENCRYPTANDSIGN
(default).

UserNameCredential Class
The UserNameCredential class provides a user name, password, and domain name that enable you to authenticate a client
to a Web service or proxy server.
Invoke objects of the UserNameCredential class from the UserName property of WCFClientCredential,
HTTPDigestCredential, or WindowsCredential class objects.
Properties
UserNameCredential property

Type

Description

UserName

string

Specifies a user name

Password

string

Specifies a password

Domain

string

Specifies a domain that the user belongs to

WCFBasicHttpBinding Class
Use the WCFBasicHttpBinding class for communication between a WCF client and ASMX-based Web services or other
services that conform to the WS-I Basic Profile 1.1.

Properties

98

WCFBasicHttpBinding
property

Type

Description

TransferMode

WSTransferMode(enumeration)

Gets or sets a value to indicate whether messages

are buffered or streamed. Values are: BUFFERED
(default), STREAMED, STREAMEDREQUEST, and
STREAMEDRESPONSE.

MessageEncoding

WSMessageEncoding
(enumeration)

Specifies encoding for SOAP messages. Values

are: Text (default), and MTOM (Message
Transmission Optimization Mechanism).

WCF Client Proxy Reference

WCFBasicHttpBinding
property

Type

Description

TextEncoding

WSTextEncoding (enumeration)

Specifies character encoding for SOAP message

text. Values are: ASCII, BIGENDIANUNICODE,
UNICODE, UTF32, UTF7, and UTF8 (default).

Security

BasicHttpSecurity (class)

Gets or configures the security settings of a

BasicHttpBinding connection.

ReaderQuotas

WCFReaderQuotas (class)

Gets or sets processing constraints based on the

SOAP message complexity for endpoints with this
binding type.

WCFClientCredential Class
The WCFClientCredential class provides client credentials for a Web service or a proxy server that is behind a firewall.

Properties
WCFClientCredential
property

Type

Description

UserName

UserNameCredential (class)

Gets a credential object you can use to set the user

name and password for a Web service or proxy server

HTTPDigest

HttpDigestCredential (class)

Gets the current HTTP digest credential

Windows

WindowsCredential (class)

Gets an object with the Windows credential you want

to use to authenticate a client to a Web service

ClientCertificate

ClientCertificateCredential
(class)

Specifies an object that provides an X.509 certificate

that the client can use for authentication to a Web
service

ServiceCertificate

ServiceCertificateCredential
(class)

Specifies an object that provides an X.509 certificate

when the message security mode is set for messagelevel encryption

WCFConnection Class
The WCFConnection class specifies the properties required for a WCF client to connect to a Web service.
WCFConnection is the base class for the WCFConnection object generated by the WCF Client project wizard.

Properties
WCFConnection property

Type

Description

BindingType

WCFBindingType (enumeration)

Specifies the binding type and communciation

format to use when accessing a WCF service.
The default value is generated from the service
contract. If you delete this value, the
connection is attempted using
BasicHttpBindiing as the default binding type.
Values are: BasicHttpBinding,
WSHttpBinding,
WS2007HttpBinding,

PowerBuilder .NET Features Guide

99

WCF Client Proxy Reference

WCFConnection property

Type

Description
WSFederationHttpBinding,
WS2007FederationHttpBinding,
NetTcPBinding,
NetNamedPipeBinding,
NetMsmqBinding, and
WebHttpBinding.
WCF connection bindings are described on the
MSDN Web site.

ClientCredential

WCFClientCredential (class)

Specifies the WCF credential to use for

communication with the Web service.

EndpointAddress

WCFEndpointAddress (class)

Specifies a URL for the remote Web service,

and tells the Web service engine where the
Web service resides. If the endpoint is not
explicitly set, the Web service engine uses the
default endpoint embedded in the service
contract file and in the generated Web service
assembly.

ProxyServer

WCFProxyServer (class)

Allows you to specify credentials for a proxy

server if the client machine is behind a firewall.
If the client machine is directly connected to
the Internet, you need not set this property.

Timeout

String

Specifies how long the WCF engine waits

before timing out while invoking the Web
service. The default value is 10 minutes
("00:10:00"). The format for the time is
"hh:mm:ss".
The Web service might have a different
timeout value on the server side.

100

BasicHttpBinding

WCFBasicHttpBinding (class)

Defines binding settings for

BasicHttpBinding. This property is used only
when the BindingType property is
BasicHttpBinding.

wsHttpBinding

WCFwsHttpBinding (class)

Defines binding settings for

WCFwsHttpBinding. This property is used
only when the BindingType property is
WCFwsHttpBinding.

NetTcpBinding

WCFNetTcpBinding (class)

Defines binding settings for NetTcpBinding.

This property is used only when the
BindingType property is NetTcpBinding.

WebHttpBinding

WCFWebHttpBinding (class)

Defines binding settings for WebHttpBinding.

This property is used only when the
BindingType property is WebHttpBinding.

ws2007HttpBinding

WCFws2007HttpBinding (class)

Defines binding settings for

ws2007HttpBinding. This property is used
only when the BindingType property is
ws2007HttpBinding.

WCF Client Proxy Reference

WCFConnection property

Type

Description

wsFederationHttpBinding

WCFwsFederationHttpBinding
(class)

Defines binding settings for

ws2007HttpBinding. This property is used
only when the BindingType property is
ws2007HttpBinding.

ws2007FederationHttpBinding WCFws2007FererationHttpBinding Defines binding settings for

(class)
ws2007FererationHttpBinding. This property
is used only when the BindingType property is
ws2007FererationHttpBinding.
NetNamedPipeBinding

WCFNetNamedPipeBinding (class) Defines binding settings for

NetNamedPipeBinding. This property is used
only when the BindingType property is
NetNamedPipeBinding.

NetMSMQBinding

WCFNetMSMQBinding (class)

Defines binding settings for

NetMSMQBinding. This property is used only
when the BindingType property is
NetMSMQBinding.

The following binding types are not supported: WSDualHttpBinding, NetPeerBinding, and
MsmqIntegrationBinding.

WCFEndpointAddress Class
The WCFEndpointAddress class provides a unique network address that a client uses to communicate with a service
endpoint.

Properties
WCFEndpointAddress property Type

Description

URL

string

Specifies the URI that identifies the endpoint

location.

Identity

WCFEndpointIdentity (class) Specifies the identity for the endpoint.

WCFEndpointIdentity Class
The WCFEndpointIdentity class defines the identity type and value of an endpoint, enabling authentication by clients
exchanging messages with it.

Properties
WCFEndpointIdentity
property

Type

Description

Type

WCFEndpointIdentityType
(enumeration)

Specifies the type of identity. Values are: NONE

(default), UPN, SPN, DNS, RSA, and
CERTIFICATE.

IdentityValue

string

Specifies the identity value.

PowerBuilder .NET Features Guide

101

WCF Client Proxy Reference

WCFnetTCPBinding Class
The WCFnetTCPBinding class enables you to communicate with WCF Web services from a WCF client using
NetTcpBinding. This binding is intended for WCF-to-WCF communication only.

Properties
WCFnetTCPBinding
property

Type

Description

MaxConnections

System.Int32

Specifies a value for the maximum number of connections to be

pooled for subsequent reuse on the client. The default for
netTcpBinding is 10.

ReliableSession

WCFReliableSession
(class)

Specifies whether to enable reliable sessions (using the WSReliableMessaging protocol) and defines settings for these
sessions when enabled.

TransactionFlow

boolean

Specifies whether transaction flowing is supported. Values are:

true supported.
false (default) not supported.

TransactionProtocol

TransactionProtocolType
(enumeration)

Specifies the transaction protocol to use in flowing transactions.

Values are: DEFAULT (default), OLETRANSACTIONS,
WSATOMICTRANSACTION11, and
WSATOMICTRANSACTION_OCTOBER2004.

TransferMode

WSTransferMode
(enumeration)

Gets or sets a value to indicate whether messages are buffered or

streamed. Values are: BUFFERED (default), STREAMED,
STREAMEDREQUEST, and STREAMEDRESPONSE.

Security

NetTcpSecurity (class)

Specifies the type of security to use with services configured for

NetTcpBinding. The default security mode is TRANSPORT.

ReaderQuotas

WCFReaderQuotas (class) Gets or sets processing constraints based on the SOAP message
complexity for endpoints with this binding type.

WCFProxyServer Class
If you connect to a Web service from behind a proxy server, you must first instantiate an object of the WCFProxyServer
class. This class provides credential information to the proxy server.

Properties

102

WCFProxyServer
property

Type

Description

ProxyAddress

string

Specifies a URL for the proxy server or firewall.

CredentialType

HttpProxyCredentialType
(enumeration)

Specifies the credential type to use for the firewall.

Values are: None (default), Basic, Digest, NTLM,
Certificate, and Windows.

ClientCredential

WCFClientCredential (class)

Specifies the WCF credentials to be used for the firewall.

WCF Client Proxy Reference

WCFProxyServer
property

Type

Description

UseDefaultWebProxy

Boolean

Determines whether to use the default Web proxy

settings, as defined for Internet Explorer. The default
value is "true".

WCFReaderQuotas Class
The WCFReaderQuotas class defines restrictions (quotas) for the complexity of message exchanges with service
endpoints that you can set differently according to the binding type used.

Properties
WCFReaderQuotas
property

Type

Description

MaxDepth

Int (System.Int32) Gets or sets a maximum node depth. The default value is 32.

MaxStringContentLength

Int (System.Int32) Gets or sets a maximum length for message strings returned
from the service. The default value is 8192.

MaxArrayLength

Int (System.Int32) Gets or sets the maximum length for arrays returned from the
service. The default value is 16384.

MaxBytesPerRead

Int (System.Int32) Gets or sets the maximum number of bytes returned from the
service during a single call. The default value is 4096.

MaxNameTableCharCount

Int (System.Int32) Gets or sets the maximum number of characters permitted in

a table name. Setting this value can help prevent buildup of
large amounts of character data. The default value is 16384.

WCFReliableSession Class
The WCFReliableSession class allows you to use reliable messaging for your Web service connections, as long as the
binding type you are using supports the WS-ReliableMessaging protocol. WCFReliableSession also lets you get and set
message ordering and duration.

Properties
WCFReliableSession
property

Type

Description

Enabled

boolean Specifies whether the connection uses the WS-ReliableMessaging protocol. The
default for this property depends on the binding type used for the Web service
connection. Values are:

Ordered

boolean Specifies whether messages are delivered in the order they are sent. Values are:

Duration

true reliable messaging is enabled.

false reliable messaging is not enabled.

long

PowerBuilder .NET Features Guide

true (default) messages are delivered in the order sent.

false message order is not specified.

Specifies the duration, in seconds, of a reliable messaging sequence. The default

value is 600 seconds (10 minutes).

103

WCF Client Proxy Reference

WCFWebHttpBinding Class
The WCFWebHttpBinding class enables you to communicate with WCF Web services through HTTP requests using
Plain Old XML (POX) messaging instead of SOAP messaging. This binding is intended only for WCF-to-WCF
communication.

Properties
WCFWebHttpBinding
property

Type

Description

TransferMode

WSTransferMode
(enumeration)

Gets or sets a value to indicate whether messages are buffered or

streamed. Values are: BUFFERED (default), STREAMED,
STREAMEDREQUEST, and STREAMEDRESPONSE.

WriteEncoding

WSTextEncoding
(enumeration)

Gets or set the character encoding used for the message text.
Values are: ASCII, BIGENDIANUNICODE, UNICODE,
UTF32, UTF7, and UTF8 (default).

Security

WebHttpSecurity
(class)

Specifies the type of security to use with services configured for

WebHttpBinding.

ReaderQuotas

ReaderQuotas (class)

Gets or sets processing constraints based on the SOAP message

complexity for endpoints with this binding type.

WCFwsHttpBinding Class
The WCFwsHttpBinding class enables you to communicate with Web services using the WSHttpBinding binding. This
binding provides transaction capability, reliable messaging, WS-Addressing, and message security.

Properties
WCFwsHttpBinding
property

Type

Description

MessageEncoding

WSMessageEncoding(enumeration) Specifies encoding for SOAP messages. Values are:

TEXT (default) and MTOM (Message Transmission
Optimization Mechanism).

TextEncoding

WSTextEncoding (class)

Specifies character encoding for SOAP message text.

Values are: ASCII, BIGENDIANUNICODE,
UNICODE, UTF32, UTF7, and UTF8 (default).

ReliableSession

WCFReliableSession (class)

Specifies whether to enable reliable sessions (using

the WS-ReliableMessaging protocol), and defines
settings for these sessions when enabled.

TransactionFlow

boolean

Specifies whether transaction flowing is supported.

Values are:

Security

104

wsHttpSecurity (class)

true supported.
false (default) not supported.

Gets or configures the security settings of a

wsHttpBinding connection.

WCF Client Proxy Reference

WCFwsHttpBinding
property

Type

Description

ReaderQuotas

WCFReaderQuotas (class)

Gets or sets processing constraints based on the

SOAP message complexity for endpoints with this
binding type.

WebHttpSecurity Class
The WebHttpSecurity class provides the security settings for the WebHttpBinding of a WCF client to a WCF Web
service.

Properties
WebHttpSecurity
property

Type

Description

SecurityMode

WebHttpSecurityMode
(enumeration)

Specifies the security mode used to configure a service endpoint

for receipt of HTTP requests. Values are: None (default),
Transport, and TransportCredentialOnly

Transport

HttpTransportSecurity
(class)

Specifies the transport-level security for the binding.

WindowsCredential Class
The WindowsCredential class provides credential information that allows a WCF client to use a proxy server or connect
to a Web service that requires integrated Windows authentication.
The WindowsCredential class can be invoked by the Windows property of the WCFClientCredential class.
Properties
WindowsCredential
property

Type

Description

UserName

UserNameCredential
(class)

Specifies the user name, password, and domain of the

client.

AllowsImpersonationLevel

ImpersonationLevel
(enumeration)

Determines the impersonation level of the WCF client.

Values are: None (default), Anonymous,
Identification, Impersonation, and
Delegation.

AllowNtlm

boolean

Indicates whether NT LAN Manager (NTLM)

authentication is allowed as Windows Security Support
Provider Interface (SSPI) Negotiate authentication. Values
are:

true (default) authentication is allowed.

false authentication is not allowed.

wsHttpSecurity Class
The wsHttpSecurity class provides the security settings for the wsHttpBinding of a WCF client to a Web service.

PowerBuilder .NET Features Guide

105

WCF Client Proxy Reference

Properties
wsHttpSecurity
property

Type

Description

SecurityMode

wsSecurityMode (enumeration)

Gets or sets the security mode for the binding. Values are:
None, Transport, Message (default), and
TransportWithMessageCredential.

Transport

HttpTransportSecurity (class)

Specifies the transport-level security for the binding.

Message

NoDualHttpMessageSecurity
(class)

Specifies the message-level security for the binding.

WCF Client System Constants

PowerBuilder .NET system enumerations enable you to get and set values for connecting a WCF client to a proxy server
or a Web service.

BasicHttpMessageCredentialType Enumeration
The BasicHttpMessageCredentialType enumeration specifies the credential type required by a binding for authentication.
It is used only for BasicHttpBinding bindings.

Enumerated values
BasicHttpMessageCredentialType value

Meaning

UserName

Specifies client authentication using UserName

Certificate

Specifies client authentication using a certificate

BasicHttpSecurityMode Enumeration
The BasicHttpSecurityMode enumeration stores or supplies security mode settings for a WCF client using
BasicHttpBinding to bind to a Web service.

Enumerated values
BasicHttpSecurityMode value

Meaning

None

The SOAP message is not secured during transfer. This is the default behavior for
WCF client binding.

Transport

HTTPS provides security for the SOAP message and the client authenticates the
service using the service's SSL certificate. The ClientCredentialType property of
the BasicHttpBinding class controls client authentication to the service.

Message

SOAP message security provides client authentication. The server SSL certificate
must be provided to the client separately.

TransportWithMessageCredential HTTPS provides for message integrity, confidentiality, and server authentication.
SOAP message security assures client authentication. The service must be
configured with an SSL certificate.

106

WCF Client Proxy Reference

BasicHttpSecurityMode value

Meaning

TransportCredentialOnly

Client authentication is provided by HTTP, but message integrity and

confidentiality are not provided. Use this mode only when other means of transfer
security (such as IPSec) are available.

CertStoreLocation Enumeration
The CertStoreLocation enumeration specifies the location of the X.509 certificate store containing a certificate you want
to use for secure communication from a WCF client.

Enumerated values
CertStoreLocation value

Meaning

CurrentUser

Specifies the X.509 certificate store assigned to the current user.

LocalMachine

Specifies the X.509 certificate store assigned to the local machine.

CertStoreName Enumeration
The CertStoreName enumeration specifies the name of the X.509 certificate store containing a certificate you want to use
for secure communication from a WCF client.

Enumerated values
CertStoreName value

Meaning

AddressBook

Specifies the X.509 certificate store for other users

AuthRoot

Specifies the X.509 certificate store for third-party certificate authorities

CertificateAuthority

Specifies the X.509 certificate store for intermediate certificate authorities

Disallowed

Specifies the X.509 certificate store for revoked certificates

My

Specifies the X.509 certificate store for personal certificates

Root

Specifies the X.509 certificate store for trusted root certificates

TrustedPeople

Specifies the X.509 certificate store for directly trusted people and resources

TrustedPublisher

Specifies the X.509 certificate store for directly trusted publishers

HttpClientCredentialType Enumeration
The HttpClientCredentialType enumeration provides the type of credential to use for transport-level security when
connecting to a Web service that uses the BasicHttpBinding binding.

Enumerated values
HttpClientCredentialType value

Meaning

None

Specifies anonymous authentication

Basic

Specifies Basic authentication

Digest

Specifies Digest authentication

PowerBuilder .NET Features Guide

107

WCF Client Proxy Reference

HttpClientCredentialType value

Meaning

NTLM

Specifies client authentication using NTLM (NT LAN Manager)

Windows

Specifies client authentication using Windows

Certificate

Specifies client authentication using a certificate

HttpProxyCredentialType Enumeration
The HttpProxyCredentialType enumeration provides the type of credential required by a proxy server for clients that
connect to a Web service from behind a firewall.

Enumerated values
HttpProxyCredentialType value Meaning
None

No credentials are presented or used

Basic

Client uses basic authentication to connect to the proxy server

Digest

Client uses digest authentication to connect to the proxy server

NTLM

Client uses NTLM (NT LAN Manager) authentication to connect to the proxy
server

Windows

Client uses integrated Windows authentication to connect to the proxy server

ImpersonationLevel Enumeration
The ImpersonationLevel enumeration supplies identification values to a proxy server or a Web service for a WCF client
using integrated Windows or digest authentication.

Enumerated values
ImpersonationLevel value Meaning
None

An impersonation level is not assigned.

Anonymous

The server process cannot impersonate the client and cannot obtain identification
information about the client.

Identification

The server process cannot impersonate the client, but can obtain identification and
privileges information about the client. This allows other services available on the server
to use the client security context for access and validation decisions.

Impersonation

The server process can impersonate the client security context on its local system, but not
on remote systems.

Delegation

The server process can impersonate the client security context on local and remote
systems.

MessageCredentialType Enumeration
The MessageCredentialType enumeration specifies the credential type required by a binding for authentication. It is used
by all standard binding types except BasicHttpBinding.

108

WCF Client Proxy Reference

Enumerated values
MessageCredentialType value

Meaning

None

Specifies anonymous authentication

Windows

Specifies client authentication using Windows

UserName

Specifies client authentication using UserName

Certificate

Specifies client authentication using a certificate

IssuedToken

Specifies client authentication using an issued token

ProtectionLevel Enumeration
The ProtectionLevel enumeration provides the security service requested for an authenticated stream. This enumeration
is used by the TcpTransportSecurity class for NetTcpBinding bindings.

Enumerated values
ProtectionLevel value

Meaning

None

Specifies authentication only

Sign

Signs data to ensure integrity of transmitted data

EncryptAndSign

Encrypts and signs data to ensure confidentiality and integrity of transmitted data

TcpClientCredentialType Enumeration
The TcpClientCredentialType enumeration provides the type of credential to use for transport-level security when
connecting to a Web service that uses the NetTcpBinding binding.

Enumerated values
TcpClientCredentialType value

Meaning

None

Specifies anonymous authentication

Windows

Specifies client authentication using Windows

Certificate

Specifies client authentication using a certificate

WCFBindingType Enumeration
The WCFBindingType enumeration defines the binding and communication formats to use when accessing a WCF
service.

Enumerated values
WCFBindingType value

Description

BasicHttpBinding

Suitable for communication with services, such as ASP.NET (ASMX-based) Web

services, that conform to the Basic Profile 1.0 protocol. Uses HTTP for transport, and
text/XML for message encoding.

PowerBuilder .NET Features Guide

109

WCF Client Proxy Reference

WCFBindingType value

Description

wsHttpBinding

Suitable for communication with nonduplex Web services (services without a

callback contract). Implements WS-Reliable Messaging and WS-Security protocols.
Uses HTTP for transport, and text/XML for message encoding.

ws2007HttpBinding

Binding that derives from the wsHttpBinding, but adds support for updated versions
of the ReliableSession, Security, and TransactionFlow binding elements.

wsFederationHttpBinding

Binding that supports the WS-Federation protocol for securely sharing resources by
participants in a federation.

ws2007FederationHttpBinding Binding that derives from the ws2007HttpBinding, but that also supports federated
security.
NetTcpBinding

Suitable for communication between WCF applications. Uses Transport Layer

Security (TLS) over TCP for message transport security, and supports duplex
contracts.

NetNamedPipeBinding

Binding that is similar to the NetTcpBinding binding, but only supports on-machine
communication. Uses named pipes for message delivery and binary message
encoding.

NetMsmqBinding

Suitable for WCF clients and services that communicate with Microsoft Message
Queuing (MSMQ) endpoints. By default uses MSMQ transport security.

WebHttpBinding

Suitable for communication with services over the Web. Uses HTTP for transport, and
supports text/XML and JavaScript Object Notation (JSON) message encodings.

The following binding types are not currently supported in PowerBuilder WCF client applications: NetPeerTcpBinding,
MsmqIntegrationBinding, BasicHttpContextBinding, NetTcpContextBinding, and WSHttpContextBinding.

WCFEndpointIdentity Enumeration
The WCFEndpointIdentity enumeration defines the identity to use with an endpoint for authentication.

Enumerated values
WCFEndpointIdentity
value

Meaning

None

No identity is needed.

UPN

User Principal Name (UPN) is an identity that is used with the SSPINegotiate
authentication mode. The value for a UPN identity takes the format of an e-mail address,
with a user account name, and a name that identifies the domain of the user separated by
an arrobas (@) character. For example, [email protected].

SPN

Service Principal Name (SPN) is a name by which a client uniquely identifies a service
instance. You can use this identity type with three different authentication modes:
SSPINegotiate, Kerberos, and KerberosOverTransport.
The value for a UPN identity takes the format of an e-mail address, with a user account
name, and a name that identifies the domain of the user separated by an arrobas (@)
character. For example, [email protected].

DNS

110

Domain Name System (DNS) specifies the expected identity of the server. The identity
value is a domain name, such as Sybase.com.

WCF Client Proxy Reference

WCFEndpointIdentity
value

Meaning

RSA

RSA is a public key encryption algorithm for signing and encrypting messages. It also
requires a private key for decrypting messages. For an RSA identity, you must specify the
public key for the identity value.

CERTIFICATE

Use the Certificate identity when a certificate is required for authentication to the service
endpoint. For the identity value, you must specify a Base64 encoded string representing
the raw data of the certificate.

WebHttpSecurityMode Enumeration
The WebHttpSecurityMode enumeration defines security mode settings for a WCF client using WebHttpBinding to bind
to a Web service.

Enumerated values
WebHttpSecurityMode value

Meaning

None

No security is used with HTTP requests

Transport

Specifies that HTTP requests use transport level security

TransportCredentialOnly

Specifies that only HTTP based client authentication is provided

wsSecurityMode Enumeration
The wsSecurityMode enumeration defines security mode settings for a WCF client using wsHttpBinding to bind to a Web
service.

Enumerated values
wsSecurityMode value

Meaning

None

Security is disabled

Transport

Security is provided using secure transport, such as HTTPS

Message

SOAP message security is enabled

TransportWithMessageCredential Transport security provides integrity and confidentiality, and SOAP message
security provides client authentication

WSTransferMode Enumeration
Use the WSTransferMode enumeration to get or set a value indicating whether SOAP request and response messages are
buffered or streamed .

Enumerated values
WSTransferMode value

Meaning

Buffered

The request and response messages are both buffered

Streamed

The request and response messages are both streamed

PowerBuilder .NET Features Guide

111

WCF Client Proxy Reference

112

WSTransferMode value

Meaning

StreamedRequest

The request message is streamed and the response message is buffered

StreamedResponse

The request message is buffered and the response message is streamed

Index

Index
A
accelerator characters 46
accelerator keys
assigning to menu items 26
adding
XML comments 62
Adobe Flash 4
advantages of WPF applications 4
Alt key
and menu items 26
applications
MDI 18
architecture 1
area graphs
about 64
making three-dimensional 68
arrays
jagged 50
returning in function or event 50
runtime bounds creation 50
System.Array type 50

B
bands
in DataWindow painter 77
bar graphs
about 64
making three-dimensional 68
BasicHttpMessageCredentialType enumeration 106
BasicHttpMessageSecurity class 93
BasicHttpSecurity class 94
BasicHttpSecurityMode enumeration 106
BitLeft operators 51
BitRight operators 51
BMP files
adding to DataWindow objects 81
bubble graphs 65
BubbleSize property 67
Build Action property 15
buttons
adding to DataWindow objects 84

C
CertStoreLocation enumeration 107
CertStoreName enumeration 107
ClientCertificateCredential class 94
CLS (Common Language Specification) 49
CLS and .NET component projects 62
code snippets 44
column graphs
about 64
columns
adding to DataWindow objects 80
named in DataWindow painter 78
selecting in Select painter 75
Common Language Specification

PowerBuilder .NET Features Guide

See CLS
computed columns versus computed fields 82
computed fields
adding to DataWindow objects 81
defining custom buttons for 83
computed fields versus computed columns 82
conditional compilation 6
cone graphs 69
constructors
parameterized 60
continuous data, graphing 64
controls in DataWindow objects
adding 79
controls in windows
adding to window 18
creating
custom attributes 61
enumerations 58, 59
interfaces 52
WCF Client Proxy projects 41
custom attributes
creating 61
PowerScript syntax for 61
custom controls
about 29
adding to Toolbox 30
in DataWindow objects 31
WinForm, adding to window objects 30
WPF, adding to window objects 30

D
data entry forms 72
data source
SQL Select 74
database
tracing connections 88
Database painter 87
previewing data 87
database profiles 87
databases
accessing through SQL Select 74
retrieving, presenting, and manipulating data 87
DataWindow objects
about 71
adding controls 79
buttons, adding 84
columns, adding 80
computed fields, adding 81
custom buttons that add computed fields 83
drawing controls, adding 80
graphs, adding 86
group boxes, adding 81
Group style 73
multiple column 72
nesting reports 86
presentation styles 71
text, adding 80

113

Index

Treeview style 73
using 71
DataWindow painter
working in 77
declaring
namespaces 59
defaults
menu item names 23
delegates
consuming 54
syntax example 55
deployment requirements
.NET component targets 33
WPF Application targets 4
descendent menus
building 28
detail bands
in DataWindow painter 78
DirectX 4
DISTINCT keyword 74
donut graphs
about 64
making three-dimensional 68
drawing controls, adding to DataWindow objects 80
drop-down menus
deleting menu items 25
DSI Database Trace tool 88

E
Enumeration painter 16
enumerations
BasicHttpMessageCredentialType 106
BasicHttpSecurityMode 106
CertStoreLocation 107
CertStoreName 107
creating 58, 59
HttpClientCredentialType 107
HttpProxyCredentialType 108
ImpersonationLevel 108
MessageCredentialType 108
ProtectionLevel 109
syntax 58
TcpClientCredentialType 109
WCFBindingType 109
WCFEndpointIdentity 110
WebHttpSecurityMode 111
wsSecurityMode 111
WSTransferMode 111
errors
compile 45
event sequence 5
events 60

F
footer bands, in DataWindow painter 79
Freeform style
of DataWindow objects 72

G
GAC (Global Assembly Cache) 4

114

generic classes
syntax for consuming 56
GIF files, adding to DataWindow objects 81
global
enumerations 58
Global Assembly Cache
See GAC
Graph functions
SetBubbleSize 66
graphic user interface
See GUI
graphics, adding to DataWindow objects 81
graphs
about 63
adding to DataWindow objects 86
parts of 63
types of 64
Grid style
detail band in 78
of DataWindow objects 72
group box, adding to DataWindow objects 81
GUI (graphic user interface) 7

H
header bands, in DataWindow painter 78
headings
in DataWindow objects 78
Help
Visual Studio shell features 7
HttpClientCredentialType enumeration 107
HttpDigestCredential class 95
HttpProxyCredentialType enumeration 108
HttpTransportSecurity class 95
hyphens (-) 24

I
IDataWindowBase system interface 52
IDataWindowChild system interface 52
IDataWindowControl system interface 52
IDataWindowStore system interface 52
ImpersonationLevel enumeration 108
inheritance
building menus with 28
inheriting from .NET classes 57
instances, menu 29
IntelliSense
using 44
Interface Painter 16
interfaces
creating 16, 52
implementing 53
IPicture system interface 52
items
adding to menus 24

J
jagged arrays 50
JPEG files

Index

adding to DataWindow objects 81

K
keyboard
using with menus 26

using inheritance with 28

MessageCredentialType enumeration 108
MessageSecurityOverTcp class 95
Metal skin 15
multiple columns in DataWindow objects 72

N
L
Label style
DataWindow objects 72
detail band in 78
labels
mailing 72
line drawing controls 80
line graphs
about 64
making three-dimensional 68
lines, in menus 24
local
enumerations 59

M
mailing labels 72
MDI applications
building 18
using menus 19
using sheets 19
MDI frames
adding toolbars to 26
opening sheets 19
MDI sheets
opening 19
using menus with 19
MDI windows 5
menu bars
about 19
adding to windows 28
deleting items 25
menu items
about 19
deleting 25
inserting 23
navigating in 25
properties 25
renaming 25
writing scripts for 28
Menu painter
opening 23
saving menus 25
workspace 20
menus
about 19
creating by inheriting 28
creating new 23
creating separation lines 24
deleting menu items 25
in MDI applications 19
navigating in 25
saving 25

PowerBuilder .NET Features Guide

N-Up style
detail band in 78
of DataWindow objects 72
names
of menu items 28
names, of columns in DataWindow painter 78
namespaces
declaring 59
navigating in a menu 25
.NET classes
inheriting from 57
syntax for inheriting from 57
.NET component target types 33
.NET delegates
consuming 54
syntax example 55
NetTcpSecurity class 96
New dialog 14
New dialog box
creating a menu 23
creating a window 17
NoDualHttpMessageSecurity class 96
NOT_IN_BETA1 59

O
opening
Menu painter 23
Select painter 74
Window painter 17
OpenSheet function 19
operators
bitwise 51
oval drawing controls 80

P
painters in PowerBuilder .NET 16
parameterized constructors 60
PB Obect Outline 12
PBDefault skin 15
PBWPF preprocessor symbol 6
periodic data, in DataWindow objects 72
pictures
adding to DataWindow objects 81
pictures, adding 81
pie graphs
about 64
making three-dimensional 68
PNG files
adding to DataWindow objects 81
polymorphism 52
pop-up menus

115

Index

creating an instance of the menu 29

displaying 29
PopMenu function 29
Powerscript
unsupported properties, events, and functions 46
PowerScript language enhancements 49
preprocessor symbols 6
presentation styles
of DataWindow objects 71
Project painter 40
properties
of menu items 25
window-level 17
Properties view
in Window painter 17
ProtectionLevel enumeration 109

Q
queries
saving 76

R
radar graphs 68
rectangle drawing controls 80
reports
Cascading style 73
Composite style 73
Crosstab style 73
Group style 73
presentation styles 71
requirements
.NET component deployment 33
runtime 4
rich text 73
RLE files
adding to DataWindow objects 81
RoundRectangle drawing controls 80
RTF 73
runtime class library 2
runtime requirements 4

S
saving
menus 25
queries 76
scatter graphs 65
Script view 43
scripts
for menu items 28
Select painter
opening 74
selecting tables 74
selecting for SQL select 74
semantic differences 3
separation lines, in menus 24
ServiceCertificateCredential class 97
shortcut keys
assigning to menu items 26
Skin property 15

116

skins 15
SQL Select
selecting columns 75
selecting tables 74
using as data source 74
SQL statements
generating through SQL Select 74
stacked graphs 69
StringBuilder system class 60
style
of windows 17
summary bands, in DataWindow painter 79
symbols for preprocessing 6
system interfaces 52
System Tree 8
System.Object
inheritance from 60

T
tables
presenting in Freeform style 72
presenting in Grid style 72
presenting in Label style 72
presenting in N-Up style 72
presenting in Tabular style 72
Tabular style
detail band in 78
of reports 72
target types 1, 33
TcpClientCredentialType enumeration 109
TcpTransportSecurity class 98
text
in DataWindow objects 80
of menu items 25
third-party controls
about 29
adding to Toolbox 30
in DataWindow objects 31
WinForm, adding to window objects 30
WPF, adding to window objects 30
three-dimensional graphs
about 68
toolbars
in MDI applications 26
Toolbox 10
tooltips, adding to a DataWindow object 86
tracing database connections 88

U
underline(_) character
in menu items 26
unsupported features in WPF applications 5
user objects
about 29
custom 29
third-party 29
user-defined enumerations 58, 59
UserNameCredential class 98

Index

V
visual controls 9
Visual Studio 3

W
WCF (Windows Communication Foundation) 40
WCF Client
connection classes 93
WCF Client Proxy projects
creating 41
overview 40
WCFBasicHttpBinding class 98
WCFBindingType enumeration 109
WCFClientCredential class 99
WCFConnection class 99
WCFConnection object 91
WCFEndpointAddress class 101
WCFEndpointIdentity class 101
WCFEndpointIdentity enumeration 110
WCFnetTCPBinding class 102
WCFProxyServer class 102
WCFReaderQuotas class 103
WCFReliableSession class 103
WCFWebHttpBinding class 104
WCFwsHttpBinding class 104

PowerBuilder .NET Features Guide

WebHttpSecurity class 105

WebHttpSecurityMode enumeration 111
Window painter
opening 17
properties 17
window scripts
displaying pop-up menus 29
windows
creating new 17
using menus 28
Windows Communication Foundation
See WCF
WindowsCredential class 105
WMF files
adding to DataWindow objects 81
workspace
in Menu painter 20
WPF controls 9
wsHttpSecurity class 105
wsSecurityMode enumeration 111
WSTransferMode enumeration 111

X
XAML editor 7
XML comments 62

117

Index

118