PB .NET Features Guide

PowerBuilder® .NET Features Guide

PowerBuilder .NET 12.0

DOCUMENT ID: Not Yet AvailableLAST REVISED: June 2009Copyright © 2009 by Sybase, Inc. All rights reserved.This publication pertains to Sybase software and to any subsequent release until otherwise indicated in new editions ortechnical notes. Information in this document is subject to change without notice. The software described herein is furnishedunder 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. Allother international customers should contact their Sybase subsidiary or local distributor. Upgrades are provided only atregularly scheduled software release dates. No part of this publication may be reproduced, transmitted, or translated in anyform 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 andthe 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 othercountries.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 the respective companieswith which they are associated.Use, duplication, or disclosure by the government is subject to the restrictions set forth in subparagraph (c)(1)(ii) of DFARS52.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

http://www.sybase.com/detail?id=1011207

Contents

About PowerBuilder .NET ........................................1PowerBuilder .NET Architecture ............................1WPF Control Classes ..........................................3Semantic Differences ........................................4Runtime Requirements for PowerBuilder .NET ..........5Advantages of WPF Applications ...........................5Modified and Unsupported Features in

PowerBuilder .NET ........................................6Conditional Compilation in PowerBuilder .NET

Targets ......................................................8Graphic User Interface ............................................9

Solution Explorer in PowerBuilder .NET .................11WPF Visual Controls .........................................13PowerBuilder .NET Toolbox ................................14Document Outline ...........................................15PB Object Outline ...........................................15Toolbars in the IDE ..........................................17Options Dialog Box ..........................................18New and Inherit From Object Dialog Boxes .............21

Customizing the New Dialog Box ...................22PowerBuilder .NET Painters ................................22

About the Enumeration Painter ....................23About the Interface Painter .........................24Project Painter User Interface ......................24Window Painter in PowerBuilder .NET ............25Building a New WPF Window ........................25MDI Applications in PowerBuilder .NET ...........27Menus and Toolbars for PowerBuilder .NET

Applications ........................................29User Objects ...........................................44

Source Control in PowerBuilder .NET ....................46

PowerBuilder .NET Features Guide iii

Adding Solutions to Source Control ................46Add-ins in the PowerBuilder .NET Environment ........47

PowerBuilder .NET Targets and Projects .....................49Creating a WPF Window Target ...........................49

WPF Window Application Target and ProjectProperties ..........................................50

Runtime Requirements for WPF Window ApplicationTargets .....................................................53

Creating a .NET Assembly Target .........................55.NET Assembly Target and Project Properties ....56

Runtime Requirements for .NET Assembly Targets .....59WCF Client Project Overview ..............................59

Creating a WCF Client ...............................60Scripts and Code Fundamentals ................................63

Script View in PowerBuilder .NET ........................63Opening the Script View ....................................64Modifying Script View Properties .........................64Editing Scripts ...............................................65Keywords as Identifiers .....................................65Code Snippets ................................................66IntelliSense ...................................................66Inner Control Properties and Methods ...................66Compiling the Script ........................................67

Handling Problems with Script Compilation ......67Declaring Variables and External Functions .............68GoTo Definition ..............................................68Skin Selection for Applications and Controls ............68Right-To-Left Formatting ...................................70

FlowDirection Property ..............................71Accelerator Characters in Control Labels ...............72Supported Custom Events ..................................72Unsupported Properties, Events, and Functions ........73

CLS Compliance in PowerBuilder .............................77PowerBuilder Array Enhancements .......................78

Runtime Array Bounds Creation ....................78

Contents

iv PowerBuilder .NET

Returning an Array for a Function or Event ......79Jagged Array Support ................................80.NET System.Array Support .........................80

Support for BitRight and BitLeft Operators .............80Inheritance from .NET System.Object ...................81Declaring a Namespace .....................................82

Syntax for Returning Namespace Names ..........83Defining an Interface .......................................83

Implementing an Interface ..........................84System Interface Syntax .............................85Deleting a Declared Interface ......................86

Inheriting from a .NET Class ...............................87Syntax Supporting Inheritance from a .NET

Class .................................................87Adding a Parameterized Constructor .....................89Defining .NET Properties ...................................90Defining Indexers ............................................91Creating a Global User-Defined Enumeration ...........92

Syntax for User-Defined Enumerations ............92Creating a Local User-Defined Enumeration ............93Consuming a .NET Delegate ...............................94

Syntax for Consuming .NET Delegates ............94Syntax for Consuming Generic Classes ...................96Enhancements to .NET Component Projects ............97

Graphs in PowerBuilder .NET ..................................99Graph Differences Between PowerBuilder Classic and

PowerBuilder .NET ......................................99Parts of a Graph ............................................100Types of Graphs in PowerBuilder .NET .................101

Area, Bar, Column, and Line Graphs .............101Pie and Donut Graphs ...............................102Scatter and Bubble Graphs ........................102Three-Dimensional Graphs .........................106Radar Graphs ........................................106Stacked Graphs ......................................107

Contents

PowerBuilder .NET Features Guide v

Cone Graphs .........................................107DataWindows .....................................................109

DataWindows in PowerBuilder .NET ....................109Using DataWindow Objects in

PowerBuilder .NET ..............................109DataWindow Differences Between

PowerBuilder Classic and PowerBuilder .NET...................................................... 110

Presentation Styles for DataWindow Objects ..........111Using SQL Select ........................................... 112

Defining the Data Using SQL Select ..............112Selecting Tables and Views Using SQL Select ...113Table Layout View in SQL Select ..................113Selecting Columns Using SQL Select ..............114Including Computed Columns Using SQL Select

...................................................... 114Defining Queries ........................................... 115

Previewing the Query ...............................115Saving the Query ....................................115Modifying the Query ................................116

DataWindow Object Enhancements ..................... 116DataWindow Painter ................................116

Adding Controls to a DataWindow Object .............120Adding Columns to a DataWindow Object ...... 120Adding Text to a DataWindow Object ...........121Adding Drawing Controls to a DataWindow

Object ............................................ 121Adding a Group Box to a DataWindow Object . 122Adding Pictures to a DataWindow Object ......122Adding Computed Fields to a DataWindow

Object ............................................ 122Adding Buttons to a DataWindow Object ....... 126Add Graphs to DataWindow Objects .............129Adding Reports to a DataWindow Object .......129

Contents

vi PowerBuilder .NET

Adding WPF Controls to a DataWindow Object...................................................... 129

Tooltips in DataWindow Objects ..................129Database Management in PowerBuilder .NET .............131

Defining Database Profiles ................................131The Database Painter in PowerBuilder .NET ..........131Manipulating Data in Database Painter .................132SQL Statements in Database Painter ....................132DSI Database Trace Tool ...................................132Sharing ADO.NET Database Connections ...............134

About ADO.NET Database Connections ..........135Exporting an ADO.NET Database Connection . . .135Importing an ADO.NET Database Connection ...136

WCF Client Proxy Reference ..................................139wcfConnection Object ....................................139Classes Supporting WCF Client Connections ...........142

BasicHttpMessageSecurity Class ..................142BasicHttpSecurity Class ............................143ClientCertificateCredential Class .................143HttpTransportSecurity Class .......................144HttpDigestCredential Class ........................144MessageSecurityOverTcp Class ....................145NamedPipeTransportSecurity Class ...............146NetNamedPipeSecurity Class ......................146NetTcpSecurity Class ................................147NoDualHttpMessageSecurity Class ................148ServiceCertificateCredential Class ...............149TcpTransportSecurity Class ........................150UserNameCredential Class .........................150WCFBasicHttpBinding Class ........................151WCFClientCredential Class ........................153WCFConnection Class ...............................154WCFEndpointAddress Class ........................156WCFEndpointIdentity Class ........................156WCFSoapMessageHeader Class ....................157

Contents

PowerBuilder .NET Features Guide vii

WCFnetNamedPipeBinding Class ..................157WCFnetTCPBinding Class ...........................159WCFProxyServer Class ..............................160WCFReaderQuotas Class ............................161WCFReliableSession Class ..........................162WCFwsHttpBinding Class ...........................162WindowsCredential Class ..........................165wsHttpSecurity Class ...............................165

WCF Client Methods .......................................166AddHttpRequestHeader Method ..................166AddMessageHeaderItem Method ..................166GetHttpResponseHeader Method .................168RemoveAllMessageHeaderItems Method .........168RemoveHttpRequestHeader Method ..............169RemoveMessageHeaderItem Method .............169

WCF Client System Constants ............................169BasicHttpMessageCredentialType Enumeration

......................................................170BasicHttpSecurityMode Enumeration ............170CertStoreLocation Enumeration ..................171CertStoreName Enumeration ......................171HttpClientCredentialType Enumeration .........172HttpProxyCredentialType Enumeration ..........172HttpRequestHeaderType Enumeration ...........173HttpResponseHeaderType Enumeration .........174ImpersonationLevel Enumeration .................175MessageCredentialType Enumeration ............176ProtectionLevel Enumeration .....................176TcpClientCredentialType Enumeration ...........176WCFBindingType Enumeration ....................177WCFEndpointIdentity Enumeration ...............178WCFHMAC Enumeration ............................179WebHttpSecurityMode Enumeration .............179wsSecurityMode Enumeration .....................180WSTransferMode Enumeration ....................180

Contents

viii PowerBuilder .NET

Index ............................................................181

Contents

PowerBuilder .NET Features Guide ix

Contents

x PowerBuilder .NET

About PowerBuilder .NET

Beginning with the version 12.0, the PowerBuilder setup program allows you to install twoseparate IDEs. The familiar PowerBuilder IDE has been rebranded as PowerBuilder Classic.The new IDE is named PowerBuilder .NET.

You start each IDE from separate items on the Start menu, and you can run multiple sessions ofeach PowerBuilder IDE at the same time. The PB120.EXE file opens the PowerBuilderClassic IDE, and the PBSHELL.EXE opens the PowerBuilder .NET IDE.

In the PowerBuilder .NET IDE, you use the WPF Window Application Target wizard in theNew dialog box to create Windows Presentation Foundation (WPF) applications. The wizardcan create WPF applications or convert standard PowerBuilder client/server or .NETWindows Forms targets.

The PowerBuilder .NET IDE also allows you to create .NET assembly components fromnonvisual user objects. You can take advantage of language enhancements for fuller .NETcompliance when you build these components in PowerBuilder .NET rather than inPowerBuilder Classic.

PowerBuilder .NET ArchitecturePowerBuilder .NET applications, including system classes and system functions, are built ontop of the PowerBuilder WPF runtime library.

The WPF runtime library reuses the existing nonvisual part of the PowerBuilder Classic .NETruntime library, which has been enhanced for for compliance with the extended CommonLanguage Specification (CLS). The major difference with PowerBuilder Classic is in thepresentation layer.

A .NET assembly, Sybase.PowerBuilder.WPF.controls.dll, containsPowerBuilder versions of all WPF controls available in the presentation layer.(Implementations for the DataWindow, EditMask, and RichText controls depend onadditional assemblies.) WPF application development reuses the existing PowerBuilderto .NET compiler (pb2cs) for application compilation.

Although PowerBuilder Classic and PowerBuilder .NET share the same compiler, it has beenmodified to correctly generate WPF applications. For example, the WPF runtime library mustlink binary application markup language (BAML) to WPF controls. The modified version ofthe compiler accomplishes this linkage for PowerBuilder .NET applications, even thoughthe .NET Windows Forms or Web Forms applications you develop in PowerBuilder Classic donot use BAML or WPF controls.


PowerBuilder .NET Features Guide 1

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 theWPF painter, a corresponding XAML file is generated.

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


2 PowerBuilder .NET

WPF Control ClassesThe runtime classes in a PowerBuilder .NET application maintain the traditionalPowerBuilder control hierarchy, but inherit from the Microsoft WPF control hierarchy.

When the runtime engine loads the application, the PowerBuilder .NET control classes (thatare actually .NET wrappers around standard PowerScript controls) marshal data and connectto PowerBuilder versions of WPF controls in the presentation layer.

The following diagram shows the dual dependency structure of controls in the PowerBuilderpresentation layer. However, only a minimal set of control classes is shown in the diagram.

The PowerBuilder .NET controls internally use a "PB" prefix. This set of controls enables youto use PowerScript code to access control properties, methods, and eventsm which marshal thedata 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 thatdisplay in the runtime presentation layer, are derived from control classes in the WPFFramework (System.Windows.Controls namespace). They are referenced at design time inXAML using the default pbwpf alias for the Sybase.PowerBuilder.WPF.Controls namespace,and at runtime, in binary application markup language (BAML).

Semantic DifferencesThere are a number of semantic differences between PowerBuilder and Visual Studio.

The main semantic differences are listed below:

• A PowerBuilder "workspace" is equivalent to a Visual Studio "solution" – inPowerBuilder .NET, a workspace file is saved with a PBWX extension, rather than the PBWextension used in PowerBuilder Classic.

• A PowerBuilder "target" is equivalent to a Visual Studio "project" – inPowerBuilder .NET, target files are saved with PBTX extensions, rather than the PBTextensions used in PowerBuilder Classic.

• A PowerBuilder "library" or "PBL" is equivalent to a Visual Studio "file" – inPowerBuilder .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 metadataand compiled code for all objects in the PBL.The PBL directory in PowerBuilder .NET must have a PBL extension. It must contain aPBLX file, and subdirectories for all build configurations. Although you can add other filesto the library directories using file management tools, the PowerBuilder .NET SolutionExplorer recognizes only PowerBuilder source files in these directories.

• The PowerBuilder "System Tree" is equivalent to the Visual Studio "Solution Explorer"that is used with System Tree functionality in PowerBuilder .NET.

• A "Window control" in PowerBuilder Classic is a container control that can host multiplecontrols, but a Window control in WPF applications can only host a single control.Therefore, by default, PowerBuilder .NET places a Grid container control in everyWindow control that you create. However, PowerBuilder .NET also lets you replace theGrid control with other panel controls that can host all the additional controls you want toinclude in a Window control.

• Radio button controls that are inside a GroupBox in belong to the GroupBox and not to thecontainer of the GroupBox. For resize events in applications that you migrate fromPowerBuilder Classic, this may require you to comment out any script that changes theposition of radio button controls inside a GroupBox.


4 PowerBuilder .NET

Runtime Requirements for PowerBuilder .NETThe applications you create in PowerBuilder .NET automatically reference several .NETassemblies that must be present in the global assembly cache (GAC) on the design time andruntime computers.

The PowerBuilder setup program installs the required assemblies in the GAC of the designtime computer, but you must also deploy or install them in the GAC of each runtime computer.

The Microsoft assemblies (and their .NET Framework version numbers) that are installedwith PowerBuilder and can be redistributed to runtime computers with the PowerBuilderRuntime Packager include:

• 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 ApplicationsPowerBuilder WPF applications allow you to take advantage of the diverse systems that WPFuses internally, such as DirectX (3-D and hardware acceleration), Adobe Flash (animationsupport), and HTML (declarative markup and easy deployment).

The advantages of WPF applications include:

• Tight multimedia integration – to use 3-D graphics, video, speech, and rich documentviewing in Windows 32 or Windows Forms applications, you would need to learn severalindependent technologies and blend them together without much built-in support. WPFapplications allow you to use all these features with a consistent programming model.

• Resolution independence – WPF lets you shrink or enlarge elements on the screen,independent of the screen’s resolution. It uses vector graphics to make your applicationsresolution-independent.

• Hardware acceleration – WPF is built on top of Direct3D, which offloads work to graphicsprocessing units (GPUs) instead of central processor units (CPUs). This provides WPFapplications with the benefit of hardware acceleration, permitting smoother graphics andenhanced performance.



• Declarative programming – WPF uses Extensible Application Markup Language(XAML) declarative programming to define the layout of application objects and torepresent 3-D models, among other things. This allows graphic designers to directlycontribute to the look and feel of WPF applications.

• Rich composition and customization – WPF controls are easily customizable. You neednot write any code to customize controls in very unique ways. WPF also lets you createskins 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. Thisfeature is not unique to WPF, but is still an important component of the technology.

• Culturally aware controls – static text in controls and the return data for the String functionare modified according to the culture and language specified by the end user's operatingsystem.

WPF is also more suitable for applications with rich media content than Windows Formsapplications. 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)

Modified and Unsupported Features in PowerBuilder .NETSome features available in PowerBuilder Classic are not supported in PowerBuilder .NET.Other features are partially supported or use a different means for obtaining similar results orfor displaying similar functionality.

The following features are not currently supported or are only partially supported inPowerBuilder .NET:

• User-defined custom events (partial support) – PowerBuilder .NET uses a different eventmodel than PowerBuilder Classic. For a list of supported custom events inPowerBuilder .NET, see Supported Custom Events on page 72.

• Fonts that are not TrueType or OpenType fonts – although PowerBuilder .NET only letsyou select installed TrueType or OpenType fonts, it does let you enter the name of otherfonts for the FaceName property of controls that display text. You can also migrateapplications with non-TrueType fonts from PowerBuilder Classic. However, at runtime,the .NET Framework replaces fonts that are not TrueType or OpenType fonts, which cancause unexpected display issues.

• MDI windows – tabbed documents are used in place of MDI sheet windows. This is similarto the tabbed document implementation in Web Forms applications in PowerBuilderClassic.

• Control handles – in PowerBuilder Classic applications, each control has its own windowhandle, and many operations depend on the window handle. In PowerBuilder .NET, there


6 PowerBuilder .NET

is only a single "big" handle for a window, but the controls nested in a window do not havetheir own handles. You must refactor migrated applications that use API calls relying oncontrol handles before importing them to PowerBuilder .NET.

• Design-time list views – the Control List, Non-Visual Object List, Function List, andEvent List views are replaced in PowerBuilder .NET by the Document Outline windowand the PB Object Outline view.

• Library painter and the (PowerScript) Browser – most of the functionality of the Librarypainter and the Browser is available from Solution Explorer pop-up menu items and the PBObject Outline view.

• The Plug-in Manager – in the PowerBuilder Classic IDE is replaced inPowerBuilder .NET by the Add-in Manager from the Visual Studio isolated shell. Toenable add-ins, see Add-ins in the PowerBuilder .NET Environment on page 47.

• OLE controls – only partially supported in PowerBuilder .NET.• PBNI (including PBDOM objects)• Profile- and trace-related objects• EAServer components• EMF and WMF image formats – these formats are not supported by WPF because they are

more susceptible to security vulnerabilities than other image formats.• For a list of unsupported PowerScript properties, functions, and events in

PowerBuilder .NET, see Unsupported Properties, Events, and Functions on page 73

Other differences in functionality relate to the WYSIWYG designer in PowerBuilder .NET,the sequence in which events are handled, and the way that section 508 support isimplemented:

• 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.

• Event sequence – the difference in event sequence in WPF applications should not affectnew applications. However, you must manually refactor applications that you migratefrom PowerBuilder Classic when they rely on the order of triggered events.Although Web Forms applications also use a different event sequence than Windows 32 orWindows Forms applications, in Web Forms applications, you can save the events to aqueue and execute them during a postback operation. For WPF applications, events mustbe handled immediately after they fire.

• Section 508 support – PowerBuilder .NET uses UI Automation (UIA) to implementaccessibility instead of the Microsoft Active Accessibility (MSAA) used by PowerBuilderClassic. UIA implements a UIA-to-MSAA bridge, so MSAA tools can still be used forapplication accessibility in PowerBuilder .NET. Newer tools based on UIA can also beused for this purpose.UIA supports the AccessibleName property, but does not support the AccessibleRole andAccessibleDescription properties on windows and controls that inherit from DragObject.



Conditional Compilation in PowerBuilder .NET TargetsAlthough you do not need to use conditional code blocks in PowerBuilder .NET toreference .NET classes as in PowerBuilder Classic, you can still use the PBDOTNET,PBWEBSERVICE, and DEBUG preprocessor symbols for conditional compilation inPowerBuilder .NET targets.

PowerBuilder .NET also recognizes the PBWPF preprocessor symbol, which lets youconditionally code blocks of script for WPF Window Application targets exclusively. Thecode in these blocks is not parsed for other target types that share objects with the WPFWindow Application targets.

PowerBuilder .NET processes code inside PBDOTNET code blocks for WPF WindowApplication, and NVO .NET Assembly targets. When the Enable Debug Symbol check box isselected in the Project painter, PowerBuilder .NET also processes code that is bracketed by theDEBUG preprocessor symbol.

PowerBuilder .NET ignores all code in PBNATIVE, PBWINFORM, PBWEBSERVICE, andPBWEBFORM code blocks in the targets that you migrate from PowerBuilder Classic. Theconditional code blocks in migrated targets are kept in place, and enabled only for thosesymbols that are valid in PowerBuilder .NET.

PowerBuilder .NET can process code in blocks with the NOT operator, even if thepreprocessor symbol used is not normally valid in PowerBuilder .NET targets. You can alsoenable invalid code blocks in migrated applications by changing the preprocessor symbols tosymbols that are valid for your current target.

For more information on conditional compilation, see Referencing .NET Classes inPowerScript 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


8 PowerBuilder .NET

Graphic User Interface

Although PowerBuilder .NET and PowerBuilder Classic share many GUI elements, there arealso a number of differences. Many of the differences are the result of the isolated VisualStudio shell that is integrated into PowerBuilder .NET.

The features in the following table are supplied with the Microsoft Visual Studio shell. Youcan use the F1 key from a Visual Studio shell feature to open the H2 Help, and in Visual Studioshell dialog boxes you can click the question mark icon in the title bar for the H2 Help. TheHelp for these features is also supplied by Microsoft.

Visual Studio shell fea‐ture

Description or comment

Start page The Start page opens in the painter area of the PowerBuilder .NETIDE and can remain open while you work in object painters andeditors. It uses functionality from the Visual Studio shell Start pageto display a news channel (that you can set on the Startup and Shut-down page of the Options dialog box) and a list of recent Power-Builder .NET solutions. You can open the Start page at any time byselecting View>Other Windows>Start Page from the PowerBuild-er .NET menu.

XAML editor The eXtensible Application Markup Language (XAML) allows youto code the presentation aspects of your applications separate fromthe business logic that you code in the PowerBuilder .NET painterScript views. Changes that you make in a painter Layout view(Design pane) are reflected in the XAML editor code, and changesyou make in the XAML editor can be seen in the Design pane. Youcan view the XAML editor for a painter only when the Design pane isalso open, although you can collapse either of these panes and al-ternately display the XAML editor or the Design pane by selectingthe corresponding tab.

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 classicPowerBuilder Object Browser that is also available from the Viewmenu.

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





Code Snippets Manager The Code Snippets Manager replaces the PowerBuilder Classic Clipwindow, and allows you to add XML snippets as well as PowerScriptsnippets. You can insert snippets from the pop-up menu in painterScript views. The Code Snippet Manager is available from the Toolsmenu.

Command window You open the Command window from the View>Other Windowsmenu. It allows you to execute commands from the design timeenvironment. Intellisense is active in the Command window to assistyou in scripting valid commands for your targets.

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

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

Intellisense Replaces PowerBuilder Classic autoscript, but also provides selec-tions for classes, methods, and members of all assemblies includedin target references. Intellisense is available in painter Script views,in the XAML editor, from the Edit menu, and in the Commandwindow.

Properties window The Properties window replaces the Properties view in PowerBuild-er Classic painters. It allows you to sort properties by category oralphabetically, and when opened from the View>Properties Windowmenu, has a status line to describe a selected property.

Configuration You open the Configruration Manager from the Properties pagesdialog box for each PowerBuilder .NET workspace/solution. Re-lease and Debug configurations are provided by default, althoughyou can add and edit configurations from the Configuration Man-ager. You can change the deployment platform for a particular con-figuration, and you can open the Edit Project Configurations dialogbox from the Configuration Manager to rename or remove a con-figuration that you added.

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


10 PowerBuilder .NET



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

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

Options dialog box The Options dialog box replaces the System Options dialog box inPowerBuilder Classic. Instead of tabs, it uses a single navigationpane to navigate pages, which are organized in groups. It is availablefrom the Tools menu.

File editor The Open With dialog box replaces the File Editor in PowerBuilderClassic. It allows you to select an editor for text in the Script views orXAML editor, or for current items in the Solution Explorer. It alsoallows you to add editors that you want to use to view these files, andset a different editor as the default file viewing selection. You canopen this dialog box from the View>Open With menu item.

Text formatting In PowerBuilder .NET, you can format text in painter Script views, inthe XAML editor, and in the Command window with the Edit>Ad-vanced cascading menu items.

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

Solution Explorer in PowerBuilder .NETThe Solution Explorer in PowerBuilder .NET functions in many ways like the System Tree inPowerBuilder Classic, although for some functionality it appears more like the SolutionExplorer in Microsoft Visual Studio.

The System Tree is typically the central point of action in PowerBuilder programming. Itprovides 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 SolutionExplorer displays the contents of the PBL directories only as separate files. The



implementation of the System Tree as a Solution Explorer extension in PowerBuilder .NEThas or enables the following enhancements:

• Integration with the Visual Studio shell "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• Use of extensions for things like code refactoring• Ability to drag and drop files from the Windows Explorer to targets and libraries• Listings 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 fileorientation of the PowerBuilder .NET Solution Explorer. This includes:

• Navigation directly from the System Tree to nested controls or to specific functions andevents in the Script Editor

• Display of the source control status of objects in the System Tree

Some functionality operates similarly in the PowerBuilder Classic System Tree and in thePowerBuilder .NET Solution Explorer. Double-clicking an item in the Solution Explorerexecutes the default action for that item. Right-clicking an item opens the pop-up menu forthat item.

The Open and Open With pop-up menu items in the PowerBuilder .NET Solution Explorerdeliver the same functionality as the Edit and Edit Source pop-up menu item labels in thePowerBuilder Classic System Tree. However, the Open With menu allows you to select theeditor you want to use to view the object. The PowerBuilder .NET Solution Explorer also hasseparate Open Layout and Open Script pop-up menu items for windows and visual userobjects.

The following pop-up menu items on a PowerBuilder Classic System Tree object are notavailable in the Solution Explorer in PowerBuilder .NET:

• PBNI ExtensionsPowerBuilder .NET library nodes do not have the Import PowerBuilder Extension pop-upmenu item for importing PBNI extensions.

• OptimizeIn PowerBuilder Classic, the Optimize menu item provides a way to clean up deletedobjects and items that have been accumulated in target PBLs. This is not necessary inPowerBuilder .NET.

• Migrate



The PowerBuilder Classic migrate capability assumes you can view a target in the SystemTree that does not list objects in an expanded PBL format. In PowerBuilder .NET, objectsare 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 anobject, and this is also not needed in PowerBuilder .NET.

• Separate Library List and .NET AssembliesSeparate pop-up menu items for the library list and .NET assemblies are not neededinPowerBuilder .NETbecause of their functional equivalence. Instead, a single pop-upmenu item, "Library List", lists all PBLs and .NET assemblies in PowerBuilder .NETtargets.

• RegenerateLike the Optimize and Migrate pop-up menu items, the Regenerate menu item is notneeded in the PowerBuilder .NET Solution Explorer because objects are always listed inan expanded format.

WPF Visual ControlsThe system defined visual controls that you include in PowerBuilder .NET applicationsmaintain the class hierarchy of traditional PowerBuilder runtime controls, but the WPFcontrols 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

DatePicker DatePicker (from WPFToolkit)

DropDownListBox and DropDownPictureList-Box

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



Windows 32 Control WPF Control Equivalent

ListBox and PictureListBox ListBox

ListView ListView

Menu Menu/Toolbar

MenuCascade Menu

MonthCalendar Calendar (from WPFToolkit)

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,DragObject, and InkEdit.

PowerBuilder .NET ToolboxThe Toolbox displays icons for controls that you can add to applications.

The PowerBuilder .NET Toolbox is similar to the standard Visual Studio toolbox. It isavailable from the View menu. You can dock the Toolbox and either leave it pinned open or setit to Auto Hide.

The Toolbox contains a list of icons that you can drag onto a design surface (such as a windowpainter), or copy and paste into a code editor. Either action adds the fundamental code to createan instance of the item in the active project file. You can tailor the list by adding and deletingitems.

Depending on the type of design window that is open, the Toolbox might be divided into one ormore of these tabs:

• General – This tab is always available. Use the General tab to copy items from yourprojects and store them for easy reuse, including:



• Controls• .NET Framework components• Your own custom 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 tabto store it there. 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 a code editor oronto an active design surface.

• WPF Controls – This tab is available with WPF window painters. It is pre-loaded withicons for standard WPF controls, like ListBox and Tab.

• Layouts – The Layouts tab is available with WPF window painters. It contains icons forPresentationFramework layouts, like Canvas and Grid layouts, which control the sizes andpositions of elements in your WPF window.

• DataWindow Controls – This tab is available with PowerBuilder DataWindows. Itcontains icons for controls that you can add to data forms.

See Visual Studio help for details about basic Toolbox usage and customization.

Document OutlineThe Document Outline provides a single view for navigating the controls in the selectedobject.

The Document Outline window displays information when certain PowerBuilder objects areopen in Layout view. It is similar to the Control List in PowerBuilder Classic, except that itshows the controls in a hierarchy. For DataWindow objects, the controls are also grouped byband (header, detail, summary, and footer).

To open the Document Outline, click View > Other Windows > Document Outline .

You can navigate the Document Outline by expanding and collapsing the levels in thehierarchy. When you select the control in the Document Outline, it is selected in the Designer.

The Document Outline is a Visual Studio feature; refer to the Visual Studio isolated shellhelp.

PB Object OutlineThe PB Object Outline provides a convenient, single view for navigating and manipulating thecomponents of an object.

The PB Object Outline shows the components of a PowerBuilder object that is open for editingin a Layout view. The components are grouped into folders of object types, such as Controls,Events, and Functions. If you open or switch to a different object in the Layout view, the PB



Object Outline changes to show the active object's components. If no PowerBuild object isopen, the window contains no outline.

You can expand and collapse individual folders, or use the buttons at the top to expand orcollapse all folders.

You can expand a single nonvisual object in the outline to show its events and functions.

You can expand interfaces to show any indexers, events, functions, and .NET properties thatthey contain. Interfaces can inherit from other interfaces. When an object in the outlineimplements other interfaces, those interfaces expand to the same information as the interfaceobject. You can expand each level recursively until there are no more implemented interfaces.

Object icons

Each object in the PB Outline Tool has an icon representing its object type, such as a control,structure, or event icon.

Events, functions, indexers, and .NET properties have an additional state icon that indicateswhether the element has a script, is a descendant of a function with a script, or is a descendantof a function with an ancestor script and script of its own. The indexer and .NET property stateicons reflect the combined get and set states, because an element can represent both methods.

An element that is under source control displays the same source control state icon in theoutline and in the system tree.

Sorting and filtering options

The context menu for scriptable elements includes shortcuts to sort and filter the outline.

For indexers, functions, events, and .NET properties, only local, scripted objects are shown inthe outline by default. Context menu Show shortcuts enable you to also include unscripted andscripted ancestor objects.

The default sorting scheme groups all locally scripted objects first, followed by objects thatare scripted in an ancestor, followed by unscripted objects. Context menu Sort shortcutsenable you to change the sorting scheme.

Items in menu and global structure outlines appear in the order defined in the menu, unless youchange the outline sort order.

When you use context menu shortcuts to to change sorting or filtering, you override the globalsettings that are defined in the Script Lists page of the Options dialog box. Those settingsapply to all instances of the PB Object Outline. Changes to the current instance of the PBObject Outline do not affect any other instances.

Context menu actions

Context menus for objects in the outline can include one or more of these actions:



• New object – Opens a new Script view tab for an indexer, event, function, .NET property,enumeration, structure, or nonvisual object that you select in the outline.

For example, in the PB Object Outline for a window object, if you right-click the Eventsfolder and select New Event, the window's Script view opens with a New Event tab, whereyou can complete the event definition.

• Nonvisual Object actions – The context menu for nonvisual objects provides twomethods for adding a nonvisual object:

• NewDisplays a submenu of built-in class user objects to choose from. It creates a newnonvisual object that inherits from the class user object you select. This method isconvenient, but does not enable you to insert a custom user object.

• Add Nonvisual ObjectOpens the Select UserObject dialog box, which you can use to insert a previouslydesigned user object into the current object. This method enables you to add a customuser object.

• Go To Declare object – Opens a new Script view tab for a Declare script. Available forusings, interfaces, instance variables, shared variables, global variables, and externalfunctions.

• Go To Script – Opens the Script view tab of the selected outline item.• Edit Namespace – Opens the Script view Namespace \ Usings tab for the selected

namespace.• Remove – Deletes the selected element.• Properties – Opens the Properties view for the selected element.

Toolbars in the IDEThe toolbars in the PowerBuilder .NET IDE are somewhat different from the toolbars in thePowerBuilder Classic IDE.

The PowerBuilder .NET toolbars include the following display and functioonality changes:

• The PowerBar is now called the Standard toolbar, and it includes additional functionality(navigation and search tools) from the Visual Studio isolated shell.

• The Standard toolbar includes buttons for building and deploying the current target inplace of the buttons for building and deploying the workspace.

• PainterBars are now called by the name of the painters they support.• StyleBar functionality is replaced by properties in the PowerBuilder .NET Window and

DataWindow painters.• There is a new Help toolbar that is supported by the Visual Studio isolated shell.• There are two toolbars for the PowerBuilder .NET Debugger; one provides debug

commands, and the other displays and allows you to select the process, thread, and stack



frame of the application you are debugging. These toolbars use button images andfunctionality from the Visual Studio isolated shell.

• All toolbars can be displayed at any time, whether or not they are supported by the currentpainter.

• Toolbars uses drop-down lists for selecting targets to run and debug.• The Toolbar Options drop-down arrow at the rightmost end of each toolbar allows you to

add or remove buttons from a toolbar, reset a toolbar, and open the Customize dialog box.You can also right-click anywhere in the menu bar or in any of the toolbars to select atoolbar to display and open the Customize dialog box.For information on the Customize dialog box, see http://msdn.microsoft.com/en-us/library/52y65fyz(VS.71).aspx.l

• You can display text labels for individual toolbar items and change, edit, or reset theirassociated button images from the button pop-up menus while the Customize dialog box isopen.The same functionality is available by clicking the Modify Selection button on theCommands page of the Customize dialog box while a toolbar button is selected.The ability to display text labels on individual toolbar items provides for finer control ofthe user interface than in PowerBuilder Classic, where the Show Text command in toolbarpop-up menus applies to all toolbar buttons and all toolbars at the same time.

Options Dialog BoxThe Options dialog box provides settings that enable you to tailor your developmentenvironment.

PowerBuilder .NET options are included in the the Visual Studio Options dialog box, insteadof the System Options dialog box that PowerBuilder Classic uses. The two dialog boxes aredifferent in several ways:

• Unlike the System Options dialog box, the Options dialog box is not tabbed. Instead,options are contained in pages. Pages are grouped into categories in a single navigationpane.

• The Options dialog box includes some pages contributed by Visual Studio. The VisualStudio shell provides help for those pages.

• Some options are not implemented in the Options dialog box, because they are notapplicable in PowerBuilder .NET. For example, there is no Automatically Clear OutputWindow option, because that function is implemented elsewhere by the Visual Studioshell.

• Options available in both IDEs might be organized differently. For example, options in theSystem Font tab of the System Options dialog box appear in the Font and Colors page ofthe Options dialog box.

The following sections describe the options that PowerBuilder adds to each page of theOptions dialog box.



Environment > Startup and Shutdown

The Startup and Shutdown page in the Environment category, and contains these options:

• Initialization path – Specifies the initialization path for PowerBuilder. By default, theinitialization path is either c:\documents and settings\userName\localsettings\application data\sybase\powerbuilder 12.0 (WindowsXP and Windows 2003) or c:\users\userName\AppData\Local\Sybase\PowerBuilder 12.0 (Vista and later), where userName is the user name for thecurrently logged in user.

Important: If you change the initialization path, be sure to copy all INI, property, andlicense files from the original initialization path to the path that you enter.

• Load last loaded solution – At startup, opens the last saved solution in its previous state.Any files that were open in the solution when it was last closed are opened and displayedwhen you start PowerBuilder .NET. If no solution is loaded when you exit the product, nosolution is loaded when you return.

• Show Start Page – At startup, displays the Start Page associated with the setting in theStart Page news channel option.

• Open Home Page – At startup, displays the default Web page specified by the Home pageoption in the Environment > Web Browser page.

• Start Page news channel – Specifies the RSS feed used to display content in thePowerBuilder News section of the Start Page.

• Download content every n minutes: – Specifies how often the IDE checks for new RSSfeed content and product headlines for the Start Page. If you do not select this setting, theStart Page does not display RSS feed content and product headlines.

• Free database driver libraries on disconnect – Releases libraries that are held inmemory after PowerBuilder disconnects from a database in the development environment.

Tips: Checking this option reduces memory use, but at the cost of performance loss andpossible problems with some database management systems associated with the freeingand subsequent reloading of libraries.

To free libraries held in memory at run time, set the FreeDBLibraries property to true onthe General category of the application's Properties view in the Application painter.

Solutions > Show Folders

The options in this page show or hide specific folders within objects in the Solution Explorer.By default, all folders are shown. For example, selecting the Indexers option makes theIndexers folder visible after you restart the solution.



Solutions > Show Objects

The options in this page show or hide object types within objects in the Solution Explorer. Bydefault, all object types are shown. For example, set the DataWindows option to show or hideDataWindows when you restart the solution.

Text Editor>PowerScript

The pages in this category enable you to set options for the PowerScript editor. These settingsdo not apply to editors for other languages.

• General – For information about these options, see the Visual Studio help for the TextEditor>All Languages page.

• Tabs – For information about these options, see the Visual Studio help for the TextEditor>All Languages>Tabs page.

• Formatting – Specify the text case that is used for PowerScript keywords:

lower caseUPPER CASETitle Case

• Miscellaneous – Specify how PowerBuilder .NET opens scripts:

Open scripts in the current script viewOpen scripts in a new script view

DataWindow Painter>General

These options control the layout of DataWindows:

• Snap to Grid – Makes controls snap to a grid position when you place them or movethem.

• Show Grid – Displays a grid in the painter.• Show Ruler – Displays a ruler. The ruler uses the units of measurement specified in the

Style dialog box.• X – Specifies the width of the grid cells.• Y – Specifies the height of the grid cells.• Show Edges – Displays the boundaries of each control in the DataWindow object.• Retrieve on Preview – Retrieves all the rows from the connected data source when a

DataWindow object opens in the Preview view.

DataWindow Painter>Prefixes

The options on this page set a default prefix for each type of DataWindow object that youcreate.



Menu Painter

This page contains a single option that sets the default prefix for menu objects.

Object Prefixes

The options on this page set the default prefixes for window and user objects.

Script Lists

The filter and sort options on this page enable you to configure the script lists in the PB ObjectOutline, Script Editor, or Solution Explorer.

The filter options specify types of scripts to include or exclude in lists:

• Show inherited scripts and controls – Includes events, functions, controls and non-visuals in the list that are referenced only in ancestors.

• Show unscripted system events – Includes events that are defined as system-supplied,like Activate. Scripted versions are listed regardless of this setting.

• Show unscripted system functions – Includes functions that are defined as system-supplied, like ArrangeSheets. Scripted versions are listed regardless of this setting.

• Show unscripted .NET events and functions – Includes .NET events and functions thatare built-in, like the Equals method. Scripted versions are listed regardless of this setting.

The sort options specify how to group and sort list items:

• Alphabetically – Sorts scripts by event or function name.• Scripted local first – Groups all locally scripted events or functions first, sorted

alphabetically within each group.• Scripted local, scripted ancestor, unscripted – Groups all locally scripted events or

functions first, followed by events or functions scripted in an ancestor, followed by eventsor functions not scripted.

• Scripted anywhere, unscripted – Sorts all scripted events or functions togetherregardless where they are scripted.

New and Inherit From Object Dialog BoxesThis topic describes changes to the New dialog box and the Inherit From Object dialog box.

The New dialog box enables you to access wizards to create most of the objects you need foryour application. It is similar to the same dialog box in PowerBuilder Classic, with thesedifferences:

• Integrated object wizards – Instead of tabbed pages, the PowerBuilder .NET New dialogbox has a single page where you can select an object type and launch its wizard.

• Filter – Before selecting an object type, you can simplify the list of available objects byentering a filter expression.



A simple filter expression is a string of characters that matches only a subset of objects. Foradvanced 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 the online help on the Match function for details about special characters.• Object tree – The main part of the window contains a tree view of all the object types that

you can create, organized into a hierarchy of folders. When you select an object, a briefdescription of it appears below the view.

• Wizard navigations – The Next button opens the first and subsequent pages in the selectobject's wizard. Each wizard has one or more pages where you provide configurationinformation for the object. The Finish button is enabled when you have entered enoughinformation to create the selected object.

The Inherit From Object dialog box has these changes:

• Objects – You can display objects in either a list or a table, using the buttons to the left ofthe Objects list.

• Object types – The Objects of Type drop-down list has an additional Classes category.

Customizing the New Dialog BoxYou can change the items that appear in the New dialog box.

To customize the New dialog box:

• 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:

• Select Reset PB Object Category to restore the objects that have been removed fromthe category.

• Select Reset All to restore all previously removed objects to the view.

PowerBuilder .NET PaintersIn PowerBuilder .NET as in PowerBuilder Classic, you edit objects, such as applications,windows, and menus, in painters.

PowerBuilder .NET includes painters that are not available in PowerBuilder Classic, such asthe Interface and Enumeration painters. You can also use painters in PowerBuilder .NET to



create indexers and .NET properties, and to declare namespaces and using namespacedirectives for PowerBuilder objects.

About the Enumeration PainterThe Enumeration painter is similar to the Structure painter. You can use the painter to defineglobal enumerations for your applications or components, and to define local enumerationsfor 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. Youmust specify a name for each item you want to include in the enumeration. If you do not enter avalue 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 theenumeration are treated as bit fields.

The Enumeration painter for local enumerations has one additional field that is not present inthe painter for global enumerations. This is the Enumeration Name field where you enter thename you want for the local enumeration. The global enumeration is saved as a file when youselect the File>Save menu. The extension for a global user-defined enumeration that you savein the Enumeration painter is .sre.

System.Enum is the base class for all PowerBuilder .NET enumerations. You can assignenumerations using System.Enum, System.Object, ANY, or integral (int, unit, byte, sbyte,long, ulong, longlong, and ulonglong) datatypes.

For example, the following code assigns an integer to the enumeration, myenum:

int a = 1 myenum e e=a

Row manipulation in the Enumeration painter

When the Enumeration painter is active, the PowerBuilder .NET Edit menu includes twoadditional items: Insert Row and Delete Row. The Insert Row item adds an empty row beforethe current row and the sequential values in the rows after the empty row are automaticallyadjusted upwards. The Delete Row item removes the current row and the values in the rowsfollowing the deleted row are adjusted downwards sequentially.

You can change the order of rows in the Enumeration painter by cutting and pasting rows, or bydragging and dropping the current row to another position. When you reorder the rows, allrows affected by these actions are modified to maintain sequential values.



About the Interface PainterYou can create interfaces in the Interface painter. It is similar to the Custom Class (nonvisualobject) painter, with a few notable differences.

You can define functions, events, indexers, and .NET properties for interfaces using theprototype pane of the Interface painter. However, the scripting area of the painter isnoneditable, since scripting is not allowed for the members of an interface. The scripting mustbe done in the objects that implement the interface.

The fields of the prototype pane are the same as those for other painters. However, forfunctions 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 forinterfaces.

When you select Declare in the upper left drop-down list of the Interface painter, you canselect only Namespace and Interfaces in the second drop-down list. You cannot declare global,instance, or shared variables for an interface.

Project Painter User InterfaceUse the Project painter to generate compiled resources, such as EXE, PBD, and .NETassembly files, for runtime applications and components.

You can also locally execute the generated files from the design time environment by selectingthe Run item from the main menu of the Project painter, or by selecting one of the Build menuitems from pop-up menus in the Solution Explorer.

The PowerBuilder .NET Project painter uses the Visual Studio style to display horizantallystacked tabs separating functional areas of a Project object rather than the classicPowerBuilder painter style that uses top row tabs.

The options for full and incremental builds are not included on the General tab of the Projectpainter as they are in PowerBuilder Classic. Instead, you specify the build scope by selectionsfrom the target and project pop-up menus in the Solution Explorer, or by selections from theDesign and Build menus of the Project painter.

The Resources tab in the Project painter for PowerBuilder Classic is not available inPowerBuilder .NET. Instead, you add resources to a target from a pop-up menu in the SolutionExplorer, or from the Project menu. The build process copies resource files to the projectoutput directory.

PowerBuilder .NET does not use PBD files, so the Library Files tab in the Project painter onlyhas a list box for Win32 dynamic library files. It does not have a separate list for PowerBuilderlibrary files. Although Windows Forms projects in PowerBuilder Classic require PBD files forapplications with DataWindow, Query, or Pipeline objects, when you migrate a WindowsForms project to PowerBuilder .NET, the list of PowerBuilder library files on the project'sLibrary Files tab is not processed during the migration.



Window Painter in PowerBuilder .NETYou design windows in the Window painter. The Window painter has several views where youspecify how a window looks and how it behaves.

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

• The Layout view, where you design the appearance of the window and edit the XAML.This view has buttons that let you split the Design and XAML panes either vertically orhorizontally, and allow you to hide one of the panes. You can also swap the pane positionsby clicking the double arrow icon between the Design and XAML panes.

• The Script view, where you modify behavior by coding window and control scripts.

You can also use the context menu in the Solution Explorer to open only one of these tabs.

Building a New WPF WindowYou can build a window from scratch. You would use this technique to create windows that arenot 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, anddeclare functions, structures, and variables for the window.

Creating a New WPF WindowYou 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 childelements by coordinates relative to the canvas area.

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

Grid A grid defines a flexible grid area consisting of columns and rows. Childelements 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 orientedhorizontally or vertically.

VirtualizingStack Panel

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

Wrap Panel A wrappanel positions child elements in sequential position from left toright, 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 viewand the XAML defining the Window are shown in the XAML view.

Defining the WPF Window PropertiesEvery window and control has a style that determines how it appears to the user. You define awindow's style by choosing settings in the Window painter's Properties view.

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 thiscategory

Name, type, state, color, and whether a menu is associatedwith it

PBGeneral

Icon to represent the window when you minimize it PBGeneral



To specify the window's Choose thiscategory

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 WindowsYou 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 receiveinformation 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 writescripts 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, andcreate scripts for its events.

MDI Applications in PowerBuilder .NETMultiple Document Interface (MDI) is an application style you can use to open multiplewindows (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 otherwindows as sheets within the frame. In a WPF application, these sheets open as tabbeddocuments.

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 thecurrent menu item or current activity).

Client area

In a standard frame window, PowerBuilder sizes the client area automatically and the opensheets 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 willopen, but may not be visible.

When you build an MDI frame window, PowerBuilder creates a control named MDI_1, whichit uses to identify the client area of the frame window. In standard frames, PowerBuildermanages MDI_1 automatically. In custom frames, you write a script for the frame's Resizeevent 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 windowexcept an MDI frame as a sheet in an MDI application. To open a sheet, use either theOpenSheet or OpenSheetWithParm function.

Creating an MDI Frame WindowWhen you create a new window in PowerBuilder, its default window type is Main. Select Mdi!or MdiHelp! in the WindowType property 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. Menususually provide a way to open sheets in the frame and to close the frame if the user has closedall the sheets.

Note: A sheet can have its own menu but is not required to. When a sheet without a menu isopened, it uses the frame's menu.

1. Click the New button in the PowerBar.

2. Select WPF Window and click Next.

3. Enter a window title and name, then click Next (or Finish).

4. (Optional) Select the layout and click Next (or Finish).

5. (Optional) Select a namespace and click Next (or Finish).

6. Click Finish.

7. When the window object is selected, open the Properties view.

8. In the PBGeneral category, set the WindowType property to Mdi! or MdiHelp!

Using Sheets in a PowerBuilder .NET ApplicationIn an MDI frame window, users can open sheets to perform activities. All sheets can be open atthe same time and the user can move among the sheets, performing different activities in eachsheet.

Note: A sheet can have its own menu but is not required to. When a sheet without a menu isopened, 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 foran 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 for PowerBuilder .NET ApplicationsBy adding customized menus and toolbars to your applications, you can make it easy andintuitive for your users to select commands and options.

Menus and Menu ItemsMenus are lists of related commands or options (menu items) that a user can select in thecurrently active window. Each choice in a menu is called a menu item.

Usually, all windows in an application have menus except child and response windows.

Menu items display in a menu bar or in drop-down or cascading menus. Each item in a menu isdefined as a Menu object in PowerBuilder.

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 Windowpainter and display whenever the window is opened.

• As pop-up menus: Pop-up menus display only when a script executes the PopMenufunction.

Designing menus

PowerBuilder gives you complete freedom in designing menus, but you should followconventions to make your applications easy to use. For example, you should keep menussimple and consistent; group related items in a drop-down menu; make sparing use ofcascading menus and restrict them to one or two levels.

A full discussion of menu design is beyond the scope of this documentation. You shouldacquire information that specifically addresses design guidelines for graphical applicationsand 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 aMenu.

Menu Painter in PowerBuilder .NETThe Menu painter has several views where you can specify menu items and how they look andbehave.

In addition to customizing the style of a menu in the Menu painter, you can also customize thestyle of a toolbar associated with a menu.

Menu Painter ViewsThere 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 baritems:

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 usingthe Properties view.

WYSIWYG Menu view The menu as you will see it and use it in your application, with theexception of invisible menu items that do display.

The Tree Menu view and the WYSIWYG Menu view are equivalent. You can use either viewto insert new menu items on the menu bar or on drop-down or cascading menus, or to modifyexisting menu items. The menus in both views change when you make a change in eitherview.

The two views are separated by a grid splitter. You can resize the views as needed, or hide oneview entirely.

You specify menu properties in two views:

This view Displays

Properties view (for thetop-level menu object)

General, Appearance and Toolbar categories for setting menu-wideproperties

Properties view (for menuitems)

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

Views for the Top Level Menu ObjectWhen 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 Menuview is on the left and the WYSIWYG Menu view is in the middle. The Properties viewdisplays the General, Appearance and Toolbar categories on the right.



Views for Submenu ItemsWhen 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 menuitem. The Tree Menu view is on the left and the WYSIWYG Menu view is in the middle. TheName, Menu Item, and Toolbar Item categories display in the Properties view on the right.



Menu Styles in PowerBuilder .NETA menu can have a contemporary or traditional style.

Menus that you import or migrate from earlier versions of PowerBuilder have the traditionalstyle, 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 2005menus

Traditional Window default menu style which has a flat appearance



The contemporary menu style has a three-dimensional menu appearance that can includeimages 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-levelmenu object in the Menu painter. You must select the top-level menu object in the Tree Menuview of the Menu painter to display its Properties view.

If you select contemporarymenu! in the Menu Style drop-down list, you can customizethe 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 UsersGuide.

Building a New Menu in PowerBuilder .NETYou can build menus that are not based on existing menus.

Creating a New MenuYou build a new menu by creating a new Menu object and then working on it in the Menupainter.

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 fordefining the menu, and the General, Appearance and Toolbar categories in the Properties viewfor setting menu and toolbar properties.

Because you are creating a new menu and have not added menu items yet, the only content isan untitled top-level tree view item in the TreeMenu view.

Working with Menu Items in PowerBuilder .NETA menu consists of at least one menu item on the menu bar and menu items in a drop-downmenu.

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 Namebox 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 theprefix to create a unique name.

Menu items in the Tree Menu view and WYSIWYG Menu view can have the same names, butthey cannot have the same name in the Properties view.

Inserting Menu ItemsThere are three Insert choices in the context menu: Insert Menu Item, Insert Menu Item AtEnd, and Insert Submenu Item. Use the first two to insert menu items in the same menu as theselected item, and use Insert Submenu Item to create a new drop-down or cascading menu forthe 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 menuA new item is added to the menu bar after the File menu.

• Select Open and select Insert Menu Item from the pop-up menuA new item is added to the File menu above Open.

• Select Open and select Insert Menu Item At End from the pop-up menuA new item is added to the File menu after Exit.

• Select Open and select Insert Submenu Item from the pop-up menuA 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 doingso, 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 MenuYou 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 ifyou 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 asa 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 Textbox and then press Enter.

After you have created the first menu bar item, you can add more items to the menu bar or startbuilding drop-down and cascading menus.

Inserting Multiple Menu Bar Items in a New Menu



You can easily add multiple items to a menu.

Use this procedure to add multiple items to the menu bar quickly.

1. Select Insert Submenu Item from the context menu.PowerBuilder displays an empty box on the menu bar in the WYSIWYG Menu view andas a submenu item in the Tree Menu view.

2. Type the text you want for the menu item and press Tab.PowerBuilder displays a new empty box on the menu bar in the WYSIWYG menu view asa submenu item in the Tree Menu view.

3. Repeat step 2 until you have added all the menu bar items you need.

4. Press Enter to save the last menu bar item.

Inserting Additional Menu Items on the Menu BarYou 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 contextmenu 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 amenu bar item before the selected menu bar item.


Adding a Drop-down Menu to an Item on the Menu BarAfter you have created the first menu bar item, you can build drop-down menus.

1. Select the item in the menu bar for which you want to create a drop-down menu.

2. Select Insert Submenu Item from the context menu.PowerBuilder displays an empty box.

3. Type the text you want for the menu item, and then press Tab.

4. Repeat step 3 until you have added all the items you want on the drop-down menu.

5. Press Enter to save the last drop-down menu item.

Adding a Cascading Menu to an Item in a Drop-down MenuAfter you have created the first menu bar item, you can start building cascading menus.

1. Select the item in a drop-down menu for which youw ant to create a cascading menu.

2. Select Insert Submenu Item from the context menu.PowerBuilder displays an empty box.

3. Type the text you want for the menu item, and then press Tab.



4. Repeat step 3 until you have added all the items you want on the cascading menu.

5. Press Enter to save the last cascading menu item.

Adding an Item to the End of a MenuYou 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.


Inserting an Item in an Existing MenuYou 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.


Creating Separation Lines in MenusUse separation lines to separate groups of related menu items with lines.

You should use lines to separate groups of related items.

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.



Duplicating Menu ItemsYou might save time creating new menu items if you duplicate existing menu items.

A duplicate menu item has the same properties and script as the original menu item. You mightbe able to modify a long script slightly to make it work for your duplicate menu item.

1. Select the menu item or the submenu item to duplicate.

2. Select Duplicate from the context menu.The duplicate item displays at the same level of the menu, following the item you selected.The name of the duplicate menu item is unique.

3. Change the text of the duplicate menu item.

4. Modify the properties and script associated with the duplicate item as needed.

Changing Menu Item TextIt 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 MenuYou 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 usethe Right Arrow, Left Arrow, Up Arrow, and Down Arrow keys on the keyboard to navigate.Deleting Menu ItemsYou 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 .NETYou can save the menu you are working on at any time. When you save a menu, PowerBuildersaves the compiled menu items and scripts in the library you specify.

The menu name can be any valid PowerBuilder identifier. For information aboutPowerBuilder identifiers, see the PowerScript Reference.

A common convention is to use m_ as a standard prefix, and a suffix that helps you identify theparticular 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 libraryand 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 agood idea to use comments so you and others can easily remember the purpose of the menulater.

4. Specify the library in which to save the menu and click OK.

Menu Item Appearance and Behavior in PowerBuilder .NETBy setting menu properties, you can customize the display of menus in applications that youcreate with PowerBuilder.

You use the Menu painter to change the appearance and behavior of your menu and menuitems by choosing different settings in the Properties view categories. For a list of all menuitem properties, see Objects and Controls.

General Properties for Menu Items in PowerBuilder .NETThere are properties you can set when you select a menu item and then select the Menu Itemcategory in the Properties view.

For information on using the menu properties, refer to the PowerBuilder Users Guide.

Shortcut Keys in Menus in PowerBuilder .NETYou 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 amenu item whether or not the menu is displayed.

You should adopt conventions for using shortcut keys in your applications. All commonlyused menu items should have shortcut keys.

Assigning a Shortcut Key to Menu ItemsYou can assign shortcut keys to menu items.

If you specify the same shortcut for more than one MenuItem, the command that occurs laterin the menu hierarchy is executed.

Some shortcut key combinations, such as Ctrl+C, Ctrl+V, and Ctrl+X, are commonly used bymany applications. Avoid using these combinations when you assign shortcut keys for yourapplication.



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 keycombination.PowerBuilder displays the shortcut key next to the menu item name.

Providing Toolbars for ApplicationsTo make your application easier to use, you can add toolbars with buttons that users can clickas a shortcut for choosing an item from a menu.

Adding Toolbars to a WindowTo define toolbars for windows, select pictures for menu commands and then PowerBuildergenerates toolbars.

PowerBuilder provides an easy way to add toolbars to a window: when you are defining anitem in the Menu painter for a menu that will be associated with a frame window, sheet, or amain window, you simply specify that you want the menu item to display in the toolbar with aspecific picture. At runtime, PowerBuilder automatically generates a toolbar for the windowcontaining the menu.

1. In the Menu painter, specify the display characteristics of the menu items you want todisplay 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 thetoolbar.

4. (Optional) In the Window painter, specify other properties, such as the size and location ofa floating toolbar, on the Toolbar property page.

For information on setting the toolbar properties, see the PowerBuilder Users Guide.

Selecting a Toolbar StyleYou select a toolbar style in the Toolbar category of the Properties view for the top-level menuobject in the Menu painter.

Toolbars can have a contemporary or traditional style.



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 traditionalstyle, 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!





If you select traditionaltoolbar! in the ToolbarStyle drop-down list, the rest of thetoolbar style properties are grayed. If you select contemporarytoolbar! style, you cancustomize the display properties for that style and have them apply to all menu items withassociated toolbar buttons in the current menu.

Unless you are using the traditional toolbar style for the current menu object, you can set theToolbarAnimation property in the Properties view for each menu item. If you do not select animage for the ToolbarItemName property of a menu item, the selection you make for theToolbarAnimation property is ignored.

Writing Scripts for Menu Items in PowerBuilder .NETYou write scripts for menu items in the Script view. The scripts specify what happens whenusers select a menu item.

To write a script for a menu item, select Script from the menu item's pop-up menu. The Scriptview 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, andreferring to objects in your application, see the PowerBuilder Users Guide.

Using Inheritance to Build a MenuWhen you build a menu that inherits its style, events, functions, structures, variables, andscripts from an existing menu, you save coding time. All you have to do is modify thedescendent object to meet the requirements of the current situation.

To use inheritance to build a descendent menu:

1. In the Solution Explorer, 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.

Menus in Your PowerBuilder .NET ApplicationsYou can use menus as the window menu bar or as pop-up menus.

Adding a Menu Bar to a WindowTo have a menu bar display when a window is opened by a user, you associate a menu with thewindow 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 toassociate 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 MenuNametext box in the PBGeneral category.

• Click the Browse button and select the menu from the Select Menu dialog box, whichlists 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 ScriptsYou can use PowerScript to assign and change menu bars in Windows.

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 eachmenu item on the path to the menu item you are referencing, separating the names withperiods.

For example, to refer to the Enabled property of menu item m_open, which is under the menubar 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 awindow at runtime.

Displaying Pop‐up Menus in WindowsTo display a pop-up menu in a window, use the PopMenu function to identify the menu and thelocation at which you want to display the menu.

If the menu is currently associated with the window, you can simply call the PopMenufunction.

The following statement in a CommandButton script displays m_appl.m_help as a pop-upmenu 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 menubefore you can display it as a pop-up menu.



The following statements create an instance of the menu m_new, then pop up the menumy_menu.m_file at the pointer location, assuming m_new is not associated with the windowcontaining the script:m_new mymenumymenu = create m_newmymenu.m_file.PopMenu(PointerX(), PointerY())

User ObjectsApplications often have features in common. If you find youself using the same applicationfeature repeatedly, you should define a user object; you define the user object once in the UserObject 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 ControlsYou can use custom and third-party WPF 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 awider range of applications and meet your requirements.

Note: WPF controls must be descendants of the FrameworkElement class.

WPF Controls in Windows

If the custom control defines public events, they are dynamically added to the event list of thecustom control. You can define your own event handler for any event of a WPF control.

WPF Controls in DataWindow objects

In DataWindow objects, you insert custom and third-party WPF controls using theCustomControl component.

The third-party control encapsulated in the CustomControl may have different capabilities ofpresenting and processing data. If the third-party control is able to present data (a TextBlock,for example), CustomControl feeds data to this third-party control; if the third-party control isable to modify data (such as a TextBox), CustomControl will retrieve modified data from thethird-party control.



Adding WPF Controls to the ToolboxYou 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 Toolboxcontrols for the DataWindow painter are different from those for the Window painter. Be surethat the appropriate object is selected before adding a WPF control to the Toolbox.

1. In the Toolbox, select the group to which you want to add the WPF control.

2. Right-click in the Toolbox group and select Choose Items.

3. Select the WPF Components tab.

4. You can select a standard WPF control in the tab, or use the Browse button to select yourown WPF control.

5. Click OK.The WPF control is added to the Toolbox.

Adding Third‐Party and Custom WPF Controls to WindowsYou 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 thecontrol.The control is added to the window, and the XAML code for the control is added to thecode for the window.

Adding Custom and Third‐Party Controls to DataWindow ObjectsYou can add custom and third-party controls to DataWindow objects using theCustomControl. You can also add controls that are in the Toolbox directly.

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 ofthe XAML file defining the custom control.

• Click the ellipsis button next to the From Assembly field and then select the control.



Source Control in PowerBuilder .NETPowerBuilder .NET leverages Visual Studio isolated shell features to provide directconnections to external SCC-compliant source control systems.

The connections to source code control (SCC) systems are very different inPowerBuilder .NET and PowerBuilder Classic. In PowerBuilder .NET, you set up sourcecontrol connections from the Options dialog box that you open from the Tools>Options menu.The source control system that you want to use must already be installed on your computerbefore you can select it on the Plug-in Selection page of the Options dialog box. The Optionsdialog box also has separate pages for configuring environment and plug-in settings for yoursource control system.

Note: Use the F1 key in the Options dialog box to access Microsoft help for the settings on anyof the dialog box pages, including those for source control.

The PBNative source code utility that is installed with PowerBuilder Classic does not workwith PowerBuilder .NET.

Adding Solutions to Source ControlYou can add solutions and the objects in a solution to source control only after you configurethe source control settings in the Options dialog box.

Note: You open the Options dialog box from the Tools>Options menu in PowerBuilder .NET.For Microsoft Visual Studio help on configuring source control settings, press F1 afterselecting source control options in the left pane of the dialog box.

You can add only one solution at a time to source control. When you add a solution, all theobjects in the solution are automatically added with the solution. Windows that you add tosource control are saved as two separate files, an SRW file and an XAML file. They areautomatically checked in and checked out together.

1. Right-click the solution in the PowerBuilder .NET Solution Explorer.

2. Select Add Solution to Source Control from the pop-up menu.This brings up a dialog box for the source control system you selected in the Options dialogbox.

3. Log in to the source control system and add the solution to source control in the same wayyou would add it from the manager for your source control system.

After you add a solution to source control, you can perform all the operations permitted byyour source control system on the solution itself or on any of the items that the solutioncontains. Adding a solution also enables the Pending Checkins window that you can openfrom the View menu or from the pop-up menus on targets in the Solution Explorer.



Add‐ins in the PowerBuilder .NET EnvironmentAdd-ins allow you to extend the functionality of the PowerBuilder .NET environment.

Add-ins can be written in any .NET language, including PowerBuilder .NET. They mustfollow Microsoft Visual Studio 2008 guidelines, but the configuration file for each add-inmust include PowerBuilder .NET as an allowed host.

The following lines in the configuration file enable you to use an add-in in thePowerBuilder .NET IDE:

<HostApplication> <Name>PowerBuilder .NET</Name> <Version>12.0</Version> </HostApplication>

For information about creating add-ins, see http://msdn.microsoft.com/en-us/library/5abkeks7.aspx and http://www.c-sharpcorner.com/UploadFile/mgold/AddIns11292005015631AM/AddIns.aspx. Microsoft help for enabling add-ins in an isolatedshell environment is available from the Environment>Add-in/Macros Security page of thePowerBuilder .NET Options dialog box.





PowerBuilder .NET Targets and Projects

In PowerBuilder .NET, as in PowerBuilder Classic, you can work with one or more targets in aworkspace. Each target can contain multiple projects that can be separately configured fordifferent runtime platforms or build types (debug or release builds)

A PowerBuilder .NET workspace can have the following target types:

• WPF Window Application• .NET Assembly

A WPF Window Application target can support WPF Window Application projects and WCFClient Proxy projects.

A .NET Assembly target can support .NET Assembly projects and WCF Client Proxyprojects.

Creating a WPF Window TargetUse the WPF Window Application target wizard to create a WPF Window Application target.

You can create a WPF Window Application target from scratch, or by converting aPowerBuilder Classic Win32 or Windows Forms 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 targetand click Next.

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 Windows Forms target to WPF

Note: If the existing target was created in an earlier version of PowerBuilder, upgrade itin PowerBuilder Classic by following the guidelines in the Migration informationsection of the current Release Bulletin. You can then convert the upgraded version inPowerBuilder .NET using this procedure.

Migration to PowerBuilder .NET makes some changes automatically that might alsorequire manual refractoring of application scripts. For example, hyphens are notallowed in identifiers in WPF applications, so these are changed to the word "dash" bythe migration process. If these identifiers are referenced in a script, you must modifythe references, since migration does not make changes to any of the scripts that youentered. You must also refactor migrated applications that use API calls relying oncontrol handles before importing them to .



4. Follow the remaining instructions of the WPF Window Application Target wizard andclick Finish.

The New WPF Target wizard creates a project object and a target and a that allows you todeploy the application.

Tip: When the Finish button is enabled at any point in this procedure, you can click it to skipthe remaining steps and create a target with just the values you have provided. You can add orchange values at a later time in the Properties Pages dialog box (that you open from the targetpop-up menu in the Solution Explorer), and in the Project painter for target projects.

WPF Window Application Target and Project PropertiesYou can enter properties for WPF Window Application targets and projects in the WPFWindow Application target wizard.

Wizard‐set properties for a target created from scratch

For WPF Window Application targets that you create from scratch, provide the informationdescribed in the following table:

Table 1. Wizard fields for a WPF Window Application target created fromscratch

Wizard field Description

Application name Name of the application object to be created. Bydefault, the application name is also used for thelibrary and target.

Example: wpfapp

Library Name and location of the PowerBuilder library tobe created. By default, this includes the currentWorkspace path, the application name you chose,and a PBL extension.

Example: C:\Documents and Set-tings\janedoe\My Documents\pbnet\wpfapp.pbl




Target Name and location of the target to be created. Bydefault, this includes the current Workspace path,the application name you chose, and a PBTX ex-tension.

Example: C:\Documents and Set-tings\janedoe\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 num-bers to be associated with this target.

Resource files and directories Optionally, identify resource files and folders thatare not compiled with the target but need to bedelivered with the application.

Use the browser buttons to select individual files,directories, or contents in PBR resource files.

Resource dictionaries Optionally, identify WPF resource dictionariesthat the application will use.

Publish as smart client application? Select this option to configure smart client pub-lishing properties in subsequent Wizard pages.For example, select this option if you want topublish 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 lo-cally (on the user's computer) or from a re-mote site.

• No – The application will installed on a website or shared path; not locally.




Install options (for smart client only) Choose one of these options:

• From web site – Specify the Web site URL.Example: http://localhost/wpfapp

• From shared path – Specify the path wherea user can find and install the application.

• From CD-ROM or DVD-ROM – Specifythis option the application will be provided onone of these media.

Update options (for smart client only) How does the application check for the latestversion and update? Choose one of these options:

• Never check for updates

• Check for updates before application starts

• Check for updates after application starts

If you choose this option, also specify theupdate frequency.

Update frequency (for smart client only) Choose one of these options:

• Every time application starts

• At least n interval from last update. Enter apositive number for the frequency n. Choosedays, hours, or weeks as the interval.

Wizard‐set properties for a target created from an existing target

When you create a WPF Window Application target from an existing target, most of thewizard fields are the same as those for creating a target from scratch, but a few fields are addedor changed. The following table describes only the new or changed fields.



Table 2. Added wizard fields for a WPF Window Application target created froman existing target


Target Location of the existing Win32 or WindowsForms target (PBT) file.

Example: C:\pb12apps\myapp.pbt

When you enter the target, the Library list dis-plays the names and locations of its library (PBL)files.

New location and target file By default, the wizard specifies a target with thesame name as the existing target but with a PBTXextension. The default location is a wpf subfolderwithin the existing target's folder.

Example: C:\pb12apps\wpf\myapp.pbtx

If you prefer a different target, change the defaultvalue.

You can modify target properties in the Properties Pages dialog box for the target, and you canenter and modify properties for projects in the Project painter.

Runtime Requirements for WPF Window Application TargetsAt runtime, the WPF applications that you generate from PowerBuilder .NET execute usingthe .NET Common Language Runtime (CLR).

For deployment of WPF Window Application targets, production servers or target computersmust have the following:

• Windows XP SP2, Windows 2003, Windows Vista, or Windows 2008 operating system• .NET Framework 3.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

Additional PowerBuilder files and assemblies are needed to execute WPF applications. Whenyou select the PowerBuilder .NET Components option in the PowerBuilder RuntimePackager and click Create, the Runtime Packager generates an MSI or MSM package thatcontains required PowerBuilder files and supporting libraries for all targets. By default, thegenerated package is named PBNETRT120.MSI.

You can extract the generated MSI or MSM file to install the included files and assemblies totheir required locations on a production server or target computer. The package that you



generate from the Runtime Packager when the PowerBuiler .NET Components option isselected includes the following files and assemblies:

• PowerBuilder runtime dynamic link libraries in the system path:pbshr120.dll, pbrth120.dll, and pbdwm120.dll.

• PowerBuilder .NET assemblies in the global assembly cache (GAC):Sybase.PowerBuilder.ADO.dll, Sybase.PowerBuilder.Common.dll,Sybase.PowerBuilder.Core.dll,Sybase.PowerBuilder.DataSource.Db.dll,Sybase.PowerBuilder.DataSource.Db2.dll,Sybase.PowerBuilder.DataSource.dll,Sybase.PowerBuilder.DataSource.Sharing.dll,Sybase.PowerBuilder.DataSource.Trace.dll,Sybase.PowerBuilder.DataSource.WS.dll,Sybase.PowerBuilder.DataWindow.Interop.dll,Sybase.PowerBuilder.DataWindow.Web.dll,Sybase.PowerBuilder.DataWindow.Win.dll,Sybase.PowerBuilder.Db.dll, Sybase.PowerBuilder.DBExt.dll,Sybase.PowerBuilder.EditMask.Win.dll,Sybase.PowerBuilder.EditMask.Interop.dll,Sybase.PowerBuilder.Graph.Core.dll,Sybase.PowerBuilder.Graph.Interop.dll,Sybase.PowerBuilder.Graph.Web.dll,Sybase.PowerBuilder.Graph.Win.dll,Sybase.PowerBuilder.Interop.dll,Sybase.PowerBuilder.LibraryManager.dll,Sybase.PowerBuilder.RTC.Interop.dll,Sybase.PowerBuilder.RTC.Win.dll,Sybase.PowerBuilder.Utility.dll,Sybase.PowerBuilder.WCF.WSDL.dll,Sybase.PowerBuilder.WCF.WSDLRemoteLoader.dll,Sybase.PowerBuilder.WCF.Runtime.dll,Sybase.PowerBuilder.Web.dll,Sybase.PowerBuilder.Web.WebService.dll,Sybase.Powerbuilder.WebService.Runtime.dll,Sybase.PowerBuilder.WebService.RuntimeRemoteLoader.dll,Sybase.PowerBuilder.Win.dll,Sybase.PowerBuilder.WinWebDataWindowCommon.dll,Sybase.PowerBuilder.WPF.Controls.dll,Sybase.PowerBuilder.WPF.Controls.Skins.dll, andSybase.PowerBuilder.WPF.dll.

• DataWindow .NET assemblies in the GAC:



Sybase.DataWindow.ADO.dll, Sybase.DataWindow.Common.dll,Sybase.DataWindow.Core.dll, Sybase.DataWindow.Db.dll,Sybase.DataWindow.DbExt.dll, Sybase.DataWindow.Interop.dll,Sybase.DataWindow.Shared.dll,Sybase.DataWindow.WebService.Runtime.dll,Sybase.DataWindow.WebService.RuntimeRemoteLoader.dll,Sybase.DataWindow.WebService.WSDL.dll, andSybase.DataWindow.Wpf.dll.

For a complete list of files deployed by the Runtime Packager, see ApplicationTechniques>Deploying Applications and Components>PowerBuilder Runtime Packager inthe PowerBuilder collection in SyBooks.

Creating a .NET Assembly TargetYou can create .NET Assembly targets from scratch or from an existing target that contains atleast one nonvisual custom class object. You can also migrate .NET Assembly targets fromPowerBuilder Classic to PowerBuilder .NET.

You use the .NET Assembly wizard in the PowerBuilder .NET New dialog box to createa .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 .NETassembly:

• 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 canclick Finish as soon as it is enabled.

When you use the .NET Assembly target wizard to create a target from scratch, the wizard alsocreates an Application object, a project object that allows you to deploy the assembly, and anonvisual object (NVO). However, you must add and implement at least one public method inthe 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 Assemblytarget and a .NET Assembly project. The target you select must include at least one NVOhaving at least one public method. The public method must be implemented by the NVO orinherited from a parent. The AutoInstantiate property of the NVO must be set to false.



.NET Assembly Target and Project PropertiesYou can enter properties for .NET Assembly targets and projects in the .NET Assemblywizard.

Properties for a target created tfrom scratch

For .NET Assembly targets that you create from scratch, you must provide the informationdescribed in the following table:

Table 3. Wizard fields for a .NET Assembly target created from scratch


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 Workspacepath and takes the name you enter for the projectobject with a PBL extension.

Target Name of the target the wizard creates. By default,this includes the current Workspace path andtakes the name you enter for the project objectwith a PBT extension.

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

PowerBuilder object name Name of the nonvisual object the wizard creates.By default this takes the name that you entered fora project object with an “n_” prefix.

Description Lets you add a description for the project objectthe wizard creates.

Namespace Provides a globally unique name to assembly el-ements and attributes, distinguishing them fromelements and attributes of the same name but indifferent assemblies.

Assembly file name Name of the assembly created by the wizard. Bydefault, the assembly file name takes the name-space name with a DLL suffix.




Resource file and directory list List of resource files, or directories containingresource files, that you want to deploy with theproject.

You can use the Add Files, Add Directories, orSearch PBR Files buttons to add files and direc-tories to the list box. You can select a file or di-rectory in the list and click the Delete button toremove that file or directory from the list. Whenyou select a directory, the resource files in all ofits subdirectories are also selected by default.However, you can use the Resource Files tab inthe Project painter to prevent deployment of sub-directory files.

Win32 dynamic library file list Specifies any Win32 DLLs you want to includewith your project. Click the Add button to open afile selection dialog box and add a DLL to the list.Select a DLL in the list and click Delete to removethe DLL from the list.

Setup file name Name of the setup file the wizard creates. You cancopy this MSI file to client computers, then dou-ble-click the files to install the .NET assembly onthose computers.

Properties for a target created from an existing target

You can create a new .NET Assembly target from an existing target in the current workspace orby converting an existing .NET Assembly target from PowerBuilder Classic.

The "Use the library list from an existing target" option only lets you select a source target inthe current workspace. When you select this option, the wizard prompts you for the sameinformation as when you create a target from scratch, except that it omits the PowerBuilderobject name, description, and library search path fields. These fields are unnecessary becausethe existing target must have a usable nonvisual object and the library search path for the targetis already set. The wizard does, however, present the following fields that are not availablewhen you create a target from scratch:



Table 4. Additional wizard fields when creating a target using an existing targetlibrary list


Choose a target Select a target from the list of targets in the currentworkspace. This is the source target that you arecopying in order to create a new target. After youhave made your selection of the source target, thewizard displays pages that let you select a newtarget name, a project name, and a project library,as described in the table listing wizard fields fora .NET Assembly target created from scratch.

Choose NVO objects to be deployed Expand the library node or nodes in the list boxand select check boxes next to the nonvisual ob-jects that you want to deploy.

Use .NET nullable types Select this check box to map PowerScript stand-ard datatypes to .NET nullable datatypes. Nulla-ble datatypes are not Common Type System(CTS) compliant, but they can be used with .NETGeneric classes if a component accepts or returnsnull arguments or if reference arguments are set tonull.

If you choose the option to "Convert an existing .NET assembly target", the .NET Assemblytarget wizard has only two editable fields—one for selecting the source target for conversion,and the other for assigning the location and name of the new .NET Assembly target. Thewizard also displays a list of the libraries from the source target that you select.

Modifying properties after wizard completion

You can modify target properties in the Properties Pages dialog box for the target, and you canenter and modify properties for projects in the Project painter.

The Project painter includes fields that are not available in the wizard. These fields aredescribed in Deploying Applications and Components to .NET, with the exception of theVerify CLS Compliance check box on the General page of the .NET Assembly Project painterin PowerBuilder .NET. When this check box is selected, PowerBuilder .NET issues warningson deployment of any object that is not compliant with the Common Language Specification(CLS).

For information on CLS compliance, see CLS Compliance in PowerBuilder on page 77.



Runtime Requirements for .NET Assembly TargetsAt runtime, the .NET assemblies that you generate from .NET Assembly targets execute usingthe .NET Common Language Runtime (CLR).

For deployment of .NET Assembly targets, production servers or target computers must havethe 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 runtimefiles” in the Deploying Applications to .NET book for PowerBuilder Classic.

WCF Client Project OverviewWindows Communication Foundation (WCF) is a runtime engine and set of APIs that allowyou to send messages between services and clients over the Internet. Use the Project painter tobuild WCF client proxy objects that consume Web services from a PowerBuilder .NETapplication.

Note: You must install the .NET Framework SDK 3.5 to use the WCF feature. The WCFClient 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 privateassembly, which is automatically referenced by the project.

The nonvisual user object (NVO) proxy generated by the WCF Client Proxy project allowsPowerBuilder .NET application users to consume a Web service. The proxy NVO representsthe service class defined by the Web service contract, which is also incorporated in a privateassembly generated by the WCF client project.

The generated proxy layer uses PowerScript and .NET interoperability to pass the call to theassembly and get a return value from the Web service. This is different from the approach usedby the Web service engine in PowerBuilder Classic, where the generated proxy uses thePowerBuilder Native Interface (PBNI) for data exchange. For this reason, you cannot migrateexisting Web service clients from PowerBuilder Classic to the WCF engine.

The WCF client engine allows PowerBuilder .NET application users to consume WSE (WebService Enhancement) extensions in addition to other Web services. The WSE extensions



cannot be accessed by the EasySoap and .NET SOAP engines available in PowerBuilderClassic.

Creating a WCF ClientCreate 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 to startthe wizard.

2. Click:

• Next and complete the wizard, entering or selecting values for the project name andlibrary, the Web Service Definition Language (WSDL) file, the proxy namespace andassembly, and the library for the proxy. One of the wizard pages also allows you toreview the services and data classes defined in the WSDL file that you select.

• Finish and complete project property selections in the Project painter.

For the WSDL File Name, you can enter or choose files with the WSDL, ASMX, or SVCextension. You must add a "?WSDL" suffix to the URL when you try to access Webservices from an ASMX or SVC file.

Note: If your development computer is behind a proxy server, the PowerBuilder WCFClient Proxy wizard uses the proxy server settings from Internet Explorer.

You can click Finish at any time in the wizard and edit any default values in the Projectpainter.

3. Build the project.PowerBuilder creates a proxy NVO that represents the service class defined by the Webservice.

4. Create an instance of the generated assembly in a PowerBuilder .NET target.

The generated proxy has one public property, WCFConnectionObject, which is assignedto a default instance of WCFConnection.

5. (Optional) Change default values of WCFConnection, or create a nondefault instance ofWCFConnection, and set all of its binding and binding-related properties.

• Change specific properties of the WCFConnection object, such as the endpoint andtimeout, as shown in the following example:

ProxyNVO.WCFConnectionObject.Endpoint="xxx.xxx.xxx" ProxyNVO.WCFConnectionObject.Timeout=00:05:00

• Create a WCFConnection object and set all its properties manually, then assign theobject to the WCFConnectionObject property of the generated proxy:

pbwcf.WCFConnection obj obj= create pbwcf.WCFConnection obj.endpoint="xxx.xxx.xxx"



obj.timeout="00:10:00" obj.BindingType=WCFBindingType.BasicHTTPBinding obj.BasicHTTPBinding=create WCFBasicHTTPBinding obj.BasicHttpBinding.TransferMode=Streamed ... ProxyNVO.WCFConnectionObject = obj

6. Call a method of the instance of the proxy NVO.

You cannot use PowerScript exception objects to catch errors from a WCF service call.You must catch any exceptions using the .NET System.Exception class, as in the followingexample, or by using a class that inherits from System.Exception:

ns_test_wsdwSoapClient svc svc = create ns_test_wsdwSoapClient

try svc.wcfConnectionObject.ClientCredential.UserName.UserName = “xx” svc.wcfConnectionObject.ClientCredential.UserName.Password= “xxx” string ret ret = svc.getProverb() messagebox("ok", ret) catch (System.Exception ee) // Error handling End try





Scripts and Code Fundamentals

PowerBuilder applications are event driven. You specify the processing that takes place whenan event occurs by writing a script.

PowerScript in PowerBuilder .NET is a productive .NET language.

Script View in PowerBuilder .NETYou use the Script view to code functions and events, define your own funtions and events, anddeclare variables and external functions.

Script views are part of the default layout in the Application, Window, User Object, Menu, andFunction painters. You can open as many Script views as you need, or perform all coding tasksin 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 ascript. You can also select Functions to edit function scripts or Declare to declare variables andexternal functions.

The second list lets you select the event or function you want to edit or the kind of declarationyou 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 controlyou are working with

Half in color

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 sothat you can view scripts in the ancestor objects.



Opening the Script ViewYou can open the Script view from the Solution Explorer context menu or by double-clicking acontrol, function, or event.

If there is no open Script view, selecting a menu or PainterBar item that requires a Script viewopens one automatically. If you want to edit more than one script at a time, you can openadditional Script views.

To open the Script view:

Options Description

From the SolutionExplorer

Right-click on a scriptable control and then select Open Script fromthe context menu.

For a control In the Layout view, double-click a scriptable control.

For a function or event Double-click an event or function in the Solution Explorer or PBObject Outline.

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

Modifying Script View PropertiesThe Script view automatically color-codes scripts to identify datatypes, system-levelfunctions, flow-of-control statements, comments, and literals. It also indents the script basedon 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

Tab size and automatic indenting Text Editor > PowerScript > Tabs



Editing ScriptsYou can perform standard editing tasks in the Script view using the Edit menu, the pop-upmenu 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.

Keywords as IdentifiersWhen you use a PowerScript keyword as an identifier, PowerBuilder .NET automaticallyprepends the commercial at symbol (@) to the identifier in the source code prior tocompilation.

The @ symbol allows the compiler to distinguish between the keyword and the identifier.Although the identifier still displays without the @ symbol in PowerBuilder .NET paintersand in Intellisense, when you add the identifier to a script by selecting it in the Intellisensedrop-down list, the Script Editor displays the identifier with the @ symbol prefix.

If you add the same identifier by typing it in a script, you must also make sure to enter the @symbol prefix. The compiler removes the symbol when it builds the application or componentcontaining the identifier. However, if you type two @ symbols as a prefix to an identifier, thesymbols are not removed by the compiler and become part of the identifier name aftercompilation.

Note: In the Beta 2 Update release, you must not use the @ symbol with the following sevenkeywords: open, close, create, destroy, post, describe, and update. After this release, use of the@ symbol will be optional for these seven keywords.

Also note that "system" is not a keyword in the PowerBuilder .NET IDE, although it remains akeyword (reserved word) in PowerBuilder Classic. The following external functiondeclaration is a correct usage of the "system" keyword in PowerBuilder Classic, but reports anerror when used in PowerBuilder .NET: function int foo() system library "aaa"

A list of PowerScript reserved words is included in the PowerScript Reference.

If you name an event in an object painter with the keyword "event", a System.Type return type,and a System.Type argument to which you assign the "for" identifier, the source code for theevent is saved as:

event type System.@Type @event (System.@Type @for) end type



Code SnippetsYou 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. Snippetsare 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 areediting code in the PowerScript editor.

For information about adding, using, and managing Intellisense Code Snippets, refer to theVisual Studio Help.

IntelliSenseIntelliSense is a tool that helps you write PowerScript code more quickly by providing alookup and paste service inside the Script view.

IntelliSense is a feature of Visual Studio similar to Autoscript in PowerBuilder Classic.

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 foryou or show you a list of alternatives.

• When you cannot remember the name or you just want a list. IntelliSense options can helpyou narrow the list if you do not know the name but you do know the type you are lookingfor.

• When you want a list of the properties and/or functions and events that apply to anidentifier followed by a dot.

Inner Control Properties and MethodsThe properties and methods of controls in the System.Windows.Controls namespace areaccesible in the PowerBuilder .NET Script Editor through the PowerScript InnerControlproperty. These controls are the ancestors to all PowerBuilder .NET controls.

The Intellisense feature in the PowerBuilder .NET Script Editor displays the list of properties,events, and functions of the ancestor Microsoft control when you enter script for thedescendant PowerScript control's InnerControl property, followed by a dot.

The InnerControl property returns the actual datatype of the ancestor control. It is read only,although you can use it to change properties or call methods on the ancestor control.



This example changes the value of the Content property of the ancestor to a PowerScriptCommandButton control:

cb_1.InnerControl.Content = “My Content”

In PowerScript code, you cannot access the Content property on the CommandButton controlitself, although you can enter a value for it in the Properties view. When you enter a value forContent in the Properties view, the value is promulgated to the Text property for theCommandButton control, but only when the Text property is not already assigned.

Compiling the ScriptBefore you can execute a script, you must compile it.

Note: This feature is not supported in Beta.

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 thecurrent script. When you save the object, such as the window containing a control you wrote ascript 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 thescript will exist.

Handling Problems with Script CompilationIf problems occur when a script is compiled, PowerBuilder displays messages in the Error Listtab 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 FunctionsThe default layout in the Application, Window, and User Object painters includes a Scriptview set up to declare variables. Keeping a separate Script view open makes it easy to declareany variables or external functions you need to use in your code without closing and compilingthe script.

To declare variables and external functions

1. Select [Declare] from the first list in the Script view.

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.

NextFor more information about declaring variables, see the PowerScript Reference. For moreinformation about declaring and using external functions, see the PowerScript Reference andApplication Techniques.

GoTo DefinitionNot enabled in Beta

Skin Selection for Applications and ControlsAt design time, you can select system-defined and custom skins for PowerBuilder .NETapplications and individual visual controls. You can also allow customers to change skins onapplications and controls at runtime.

The ability to apply different skins to PowerBuilder .NET controls allows you to createvisually compelling applications that can also be customized by application users.PowerBuilder provides system-defined skins, but also allows you to select custom skin filesthat use the XAML extension.

System‐defined skins

The default skin defines the behavior and simulates the appearance of visual controls inPowerBuilder classic. It also supports display themes that depend on system selections for thedesign time or runtime computers. These include the standard Microsoft Windows themes,such as Aero on Windows Vista, Luna on Windows XP, and Windows Classic on all Windowsoperating systems. Customized themes are also supported.



PowerBuilder also provides the following system-defined skins: ExpressionDark,Metal, RainierOrange, RoughGreen, and ShinyDarkTeal. These skins inheritfrom the default skin, enabling them to retain the behavior of all PowerBuilder controls.However, their styles are not affected by the theme setting of the host computer, and theydisplay control surfaces with different colors.

The Application object in all WPF Windows applications always has a skin, whether theapplication is migrated from a PowerBuilder Classic target or created from scratch. Visualcontrols are not assigned a skin by default. However, if you do not assign a skin to them, theyinherit a skin setting from their immediate parent. For example, if there is no skin defined for aCommandButton, 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, theCommandButton 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, theskin 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) ofthe visual controls in PowerBuilder .NET applications. However, if you use a custom skin thatis not based on the system-defined default skin, you are likely to lose some of the controls'more complex behaviors that are embedded in the default skin's XAML definitions.

Custom skin files must be added to the directory containing the application executable, or to asubdirectory of that directory. You can select the custom skin for a control by assigning it to theSkin property for the control.

To use the custom skin at runtime, you must add the XAML file to a folder that you createunder the target containing the control. If the compile time Build Action property for theXAML file is set to "Content" (default), the XAML file is deployed as a standalone file. If youset the Build Action property to "Embedded Resource", the XAML file is compiled into thetarget assembly. Custom skins do not get applied at runtime if the Build Action property forthe 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 WPFWindow target. You can set the value of the Skin property in PowerScript code, or by enteringit in the Properties view for a visual control or the Application object. The Skin property isunder 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 system-defined skin,or to a custom skin file with a XAML extension. The default skin is designated by an emptystring (" ").

This example sets an application-level skin to the system-defined Metal skin:applicationName.Skin = “Metal”



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

Right‐To‐Left FormattingIn PowerBuilder .NET, the RightToLeft PowerScript property is deprecated. It is replaced bythe FlowDirection property.

The RightToLeft properties that you set in the PowerBuilder Classic IDE are automaticallyconverted to FlowDirection values when you migrate your applications toPowerBuilder .NET.

Five levels of right‐to‐left support

Right-to-left features in WPF applications can affect text order, text and control alignment,control title bar layout, control position mirroring, and can be inherited from containercontrols.

In PowerBuilder Classic client server applications, setting the RightToLeft property onlysupports right-to-left text order, and text and control alignment. In .NET Windows Formsapplications, the RightToLeft property also determines the layout of the title bar (for controlsthat have title bars), causing the Close, Maximize, and Minimize buttons to display on the left,and the control icon on the right.

With earlier versions of PowerBuilder, two separate UIs could be designed to mimic controlposition mirroring. You can still use this type of design for PowerBuilder Classic, and you canmigrate these applications to PowerBuilder .NET, but for newer PowerBuilder .NETapplications, it is much easier to use a single UI design and take advantage of theFlowDirection property for automatic mirroring support.

Property inheritance for right-to-left features in PowerBuilder .NET applications means that ifyou set the flow direction on a container control, such as a GroupBox or Grid, all the controlsthat are placed in the container automatically use the same flow direction value—unless youoverride that value in the individual controls. In earlier versions of PowerBuilder, and inPowerBuilder Classic, this type of inheritance is not supported.

Migrating right‐to‐left applications

Migration converts RightToLeft property values that you set in the PowerBuilder IDE, but itdoes not convert the values that you set in script. Although the RightToLeft property is stillsupported by PowerBuilder .NET at runtime, it is often more useful to modify these scripts touse the FlowDirection property.

The PowerBuilder .NET Migration wizard has a "Specify RTL Conversion Option" page thatenables you to designate whether you want the conversion process to include automaticmirroring. If you are migrating right-to-left applications with separate UIs that mimic controlposition mirroring, and you want to preserve the dual UI design, you must not select this



option. When the option is not selected, the Migration wizard strategically placesFlowDirection values to prevent the automatic mirroring, yet still maintain the right-to-leftorientation where required.

If you later want to switch to automatic mirroring, you can edit the XAML to remove any of theLeftToRight! FlowDirection values strategically inserted by the Migration wizard. Without anexplicit FlowDirection value, the controls will take on the FlowDirection value of theircontainers, which, in these types of migrated applications, would be RightToLeft!.

FlowDirection PropertyThe FlowDirection property affects text order, text and control alignment, control title barlayout, and control position mirroring in WPF applications. It replaces the deprecatedPowerScript RightToLeft property.

Applies to

Application object and all visual controls

Usage

The FlowDirection property takes one of the following enumerated values:

• LeftToRight! (default) – Characters display in left-to-right order• RightToLeft! – Characters display in right-to-left order, control position is automatically

mirrored, control title bar button positions are mirrored, and text and controls are right-aligned.

The flow direction on a container control is automatically inherited by other controls placed inthe container. However, you can override the flow direction of the container by including adifferent flow direction value for the controls that you place inside the container.

When you want to display Arabic or Hebrew text for messages, set the FlowDirection propertyof the Application object to RightToLeft!. This causes the characters in messages to displayfrom right to left. However, the text continues to display in English unless you are running alocalized version of PowerBuilder.

You can set the FlowDirection property:

• In a painter – In the Properties view, select one of the enumerated values in the drop-downlist for the FlowDirection property.

• In scripts – Set the FlowDirection value to LeftToRight! (default) or RightToLeft!.



Accelerator Characters in Control LabelsUnlike PowerScript, which uses an ampersand to signal an accelerator character for thedefault action defined by a control, XAML uses the first single underscore character in acontrol label to define the character that follows the underscore as an accelerator character.

When you migrate PowerBuilder Classic targets to PowerBuilder .NET, the ampersandsignaling an accelerator character is converted to an underscore. If the control label has anunderscore in it, the migration adds an extra underscore as an escape character, and XAMLdisplays the control label with a single underscore that is a regular part of the label text. XAMLdoes not allow you to use the underscore character itself as an accelerator.

However, as in PowerBuilder Classic, accelerator characters in PowerBuilder .NET controllabels display with an underscore in the label.

Although migration handles conversion of the accelerator characters for PowerBuilderClassic targets, any new accelerator characters you want to use in Script views or in the XAMLeditor must follow the XAML accelerator character rules. The rules for accelerator charactersapply to CommandButton, PictureButton, CheckBox, RadioButton, StaticText,StaticHyperlink, and GroupBox controls.

In XAML, the control label myCommandButton__1_x will cause the control to display withthe character x as the accelerator: myCommandButton_1 x. In this example, x is the firstcharacter after a single underscore, which marks it as an accelerator character.

Supported Custom EventsBecause there is no matching concept for user-defined custom events in WPF applications,PowerBuilder .NET does not have a generic way of supporting these types of events. However,PowerBuilder .NET does provide support for some of the more commonly used events of thistype.

The following table lists PowerBuilder event IDs for custom events supported inPowerBuilder .NET. Custom events supported in an ancestor object are also supported in itsdescendants.

PowerScript object type Supported custom event

DragObject pbm_char, pbm_keydown, pbm_keyup,pbm_lbuttondown, pbm_lbuttonup,pbm_mousemove, pbm_size



PowerScript object type Supported custom event

DataWindow pbm_dwnkey, pbm_dwndropdown,pbm_dwngraphcreate, pbm_dwnmessagetext,pbm_dwnprocessenter, pbm_dwntabout,pbm_dwnbacktabout, pbm_dwntabupout,pbm_dwntabdownout

SingleLineEdit pbm_enchange

MultiLineEdit pbm_enchange

Window pbm_move

Unsupported Properties, Events, and FunctionsSeveral PowerScript properties, events, and functions are not supported inPowerBuilder .NET.

Unsupported PowerScript properties

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

Object or control Unsupported properties

All controls inheriting from DragObject AccessibleName, AccesibleDescription, and Ac-cessibleRole

Application object ToolbarUserControl

CheckBox Automatic

DataWindow control (for a list of unsupportedDataWindow object properties, see DataWindowDifferences Between PowerBuilder Classic andPowerBuilder .NET on page 110)

ControlMenu, HSplitScroll, Icon, MaxBox, Min-Box, Resizable, Title, and TitleBar

DatePicker AllowEdit

DropDownListBox IMEMode

DropDownPictureListBox IMEMode

EditMask AutoHScroll, AutoVScroll. IgnoreDefaultBut-ton, IMEMode, TabStop, and VScrollBar

ListBox TabStop



Object or control Unsupported properties

ListView IMEMode

Menu MenuItemType, MergeOption, and ToolbarItem-Space

MenuCascade Columns, CurrentItem, DropDown, MenuItem-Type, MergeOption, and ToolbarItemSpace

MultiLineEdit AutoVScroll, HideSelection. IgnoreDefaultBut-ton. 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,HScrollBar, ImeMode, PicturesAsFrame, Resiz-able, ReturnsVisible, RulerBar, SpacesVisible,TabBar, TabsVisible, Underline, UndoDepth, andWordWrap

SingleLineEdit HideSelection, IMEMode

Tab Alignment, FixedWidth, FocusOnButtonDown,ImeMode, and RaggedRight

UserObject Style

Window AccesibleDescription, AccessibleRole, and Mdi-ClientColor

Note: Several properties are renamed with a "PB" prefix. For example, Height and Widthproperties are set as PBHeight and PBWidth; the Tag and FontFamily properties are set asPBTag and PBFontFamily. TabOrder is included as a property in the Property view for anobject or control.

Unsupported PowerScript events

The following table lists PowerBuilder .NET controls with unsupported PowerScript events:



Control Unsupported events

All controls Other

DataWindow HtmlContextApplied, PrintMarginChange, andRButtonUp

DatePicker DoubleClicked and UserString

MonthCalendar DoubleClicked

RichTextEdit DragDrop, DragEnter, DragLeave, and DragWi-thin

Note: The Help event is supported, and can be triggered by pressing the F1 key in windows,menus and for all controls that inherit from DragObject. However, it is not triggered byclicking the question mark icon in the title bar of a response window, and then clicking on acontrol in the same response window.

Unsupported PowerScript functions

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

Object or control Unsupported functions

Application object SetTransPool

Obsolete method: SetLibraryList

DataStore CopyRTF, CreateFrom, GenerateResultSet, Get-StateStatus, InsertDocument, PasteRTF, Rese-tInk, SaveInk, SaveInkPicture, and SetHTMLAc-tion

Obsolete method: GenerateHTMLForm

DataWindow GenerateResultSet, GetDataLabelling, GetSerie-sLabelling, OleActivate, SetCultureFormat, Set-DataLabelling, SetHTMLAction, and SetSerie-sLabelling

Obsolete methods: DBErrorCode, DBErrorMes-sage, GenerateHTMLForm, GetMessageText,GetSQLPreview, and GetUpdateStatus

DataWindowChild OleActivate

Obsolete methods: DBErrorCode, DBErrorMes-sage, GetSQLPreview, and GetUpdateStatus



Object or control Unsupported functions

EditMask Scroll, SelectedLine, and Undo

Graph GetDataLabelling, GetSeriesLabelling, SetData-Labelling, and SetSeriesLabelling

RichTextEdit GetSpacing, PageCount, PrintEx, Scroll, and Se-lectedPage

UserObject AddItem, DeleteItem, EventParmDouble, Even-tParmString, and InsertItem

Window CloseChannel, ExecRemote, GetCom-mandDDE, GetDataDDE, GetDataDDEOrigin,GetRemote, OpenChannel, RespondRemote,SetDataDDE, SetRemote, StartHotLink, Start-ServerDDE, StopHotLink, and StopServerDDE



CLS Compliance in PowerBuilder

PowerScript supports full compliance with Common Language Specification (CLS) rules andrestrictions.

The CLS ensures that components developed in one language can be fully accessible to anyother .NET language. It describes a set of commonly used features that serve as the minimumlanguage requirement for any .NET language.

The CLS defines three separate roles for CLS compliant applications: framework, consumer,and extender.

CLS role Requirements

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

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

• 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

Extender A CLS extender must allow users to consume and extend the CLS Framework. Ev-erything that applies to CLS consumers also applies to CLS extenders, but extendersmust 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 anddeploy components that can be consumed by any CLS compliant application.

Several enhancements to the PowerScript language enable PowerBuilder .NET to support itsCLS-extender role:

• Ability to call .NET classes and methods without using preprocessor symbols (such asPBDOTNET) 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 consume generic types• Support for defining namespaces• Support for indexers• Support for user-defined enumerations• Support for additional bitwise operators• Support for methods of .NET System.Object in PowerObject class• Support for language enhancements in .NET Assembly targets

The .NET Assembly targets in the PowerBuilder .NET IDE support a framework role for CLScompliance, since the components generated from these targets can be consumed by anyother .NET language. The WPF Window Application targets in PowerBuilder .NET are CLSextenders because they allow you to consume and extend the CLS framework.

PowerBuilder Array EnhancementsPowerBuilder 12.0 introduces several array enhancements to the PowerScript language insupport of its evolution as a CLS-compliant language.

These enhancements are available in all PowerBuilder .NET targets and in the .NET targets ofPowerBuilder Classic.

Runtime Array Bounds CreationFor PowerBuilder 12.0 .NET targets, the PowerScript language allows you to declare anunbounded 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 previousreleases of PowerBuilder, you could not previously set a bounds for these arrays at runtime.

PowerScript lets you specify array bounds for one-dimensional or multidimensionalunbounded 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, and5:

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]



Although you can set runtime bounds for unbounded arrays, design-time array bounds cannotbe reset at runtime.

The following example produces an error:

int a[3] a = create int[5] //ERROR

Other useful array rules

• Any kind of array can be passed to a .NET function as long as the array dimensions matchthe dimensions in the function's array parameter

• Blob and Byte arrays, and String and Char arrays can be assigned to each other

Returning an Array for a Function or EventPowerBuilder .NET allows you to return an array datatype from a function or event.

PowerScript previously required you to map an ANY datatype whenever a function or eventreturned an array datatype. You must still do this in PowerBuilder Classic. Although you canalso map an ANY datatype for an array datatype in PowerBuilder .NET, this is not type-safe orefficient.

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 listand 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 theNew 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 scriptfor the new method in the scripting area.

For a function script, you must include a return value that matches the array datatype youentered 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



Jagged Array SupportFor PowerBuilder 12.0 .NET targets, the PowerScript array syntax allows you to declare ajagged 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[ ] . Thesubsequent lines initialize the three elements of the first array dimension with references toindividual 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 SupportPowerScript 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.Arraytype 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 usePowerScript methods to determine the lower bounds and upper bounds of a particulardimension or to get and set values of array items, but you can also use .NET array objectmethods. The System.Array methods and properties are visible in the Solution Explorer, andin the Script Editor with Intellisense.

Support for BitRight and BitLeft OperatorsPowerBuilder 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 itssecond 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 firstoperand:

• Arithmetic - If the first operand is an integer or a long, high-order empty bits are set tothe 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 itssecond operand. This works the same as the C# “<<” operator. The datatype of the secondoperand must be an integer.

The high-order bits of the first operand are discarded and the low-order empty bits are filledwith zeros. Shift operations never cause overflows. The shift amount to the left depends on thebit quantity of the first operand datatype:

• 32-bit quantity - If the first operand is a long or ulong, the shift amount is given bythe 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 isgiven by the low-order six bits of the second operand. The maximum left shift is 0x3f or 63bits.

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 concatenationoperations.

Inheritance from .NET System.ObjectIn PowerBuilder 12, the .NET System.Object type is the ancestor type of the PowerObjectdatatype.

Because the PowerObject datatype is the base class of all PowerScript object types, you caninvoke the public members of the .NET System.Object type from any PowerBuilder object.

The following example calls the ToString method that a PowerObject inherits fromSystem.Object:

PowerObject po String str Po = create PowerObject Str = Po.Tostring()

Any PowerBuilder type can be assigned to the System.Object type:

This example assigns an integer type to a System.Object instance:

System.Object o Int i = 1 o = i



Declaring a NamespaceYou can specify a namespace for the following kinds of PowerBuilder objects: Custom andStandard 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 supportsnamespace declarations.

You can also add Using (namespace) directives in the Declare Namespace window. Usingdirectives allow you to refer to a named type by its simple name rather than its compound namethat 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\Usings in thesecond drop-down list.

Note: You could click the Namespace\Usings tab at the bottom of the object painter if it isavailable rather than selecting the drop-down list items mentioned in this step.

3. Type your namespace declaration in the Namespace text box.

The namespace declaration applies only to the selected object and any objects that inheritfrom the selected object.

Skip the next step if you do not want to include a Using directive in the source code for thecurrent object.

4. Click the Add button to open the Select Namespace dialog box and include a Usingdirective.

a) Select an assembly or other item from the Assemblies list at the bottom of the dialogbox.The list at the top of the dialog box displays the list of namespaces declared for theselected item.

b) Select a namespace from the top list box and click OK.The dialog box closes and the Using list box of the object painter displays thenamespace you selected.

c) Click the Add button again to include as many Using directives as you need.

5. Save the object with its declared namespaces.

The following is an example of a namespace declaration as it would appear in source codeafter entering sybase.pb.ns for the namespace name and dir1 and dir2 for using directives: namespace namespace sybase.pb.ns using dir1



using dir2 end namespace

Syntax for Returning Namespace NamesPowerBuilder .NET provides an overload of the PowerScript ClassName system function thatallows you to return the namespace of an object along with its class name.

The syntax for the ClassName function that can return a namespace name is:

string ClassName{any variable, boolean b_namespace )

The following table describes the arguments used in the overloaded system ClassNamefunction.

Argument Description

variable The name of the object whose class you want toreturn.

b_namespace A boolean that indicates whether or not to includethe namespace name in the return value. Valuesare:

• TRUE - returns the namespace name with theobject name

• FALSE - does not return the namespace namewith the object name

The format of the returned value when b_namespace is true is:

nameSpace.className

.

Defining an InterfaceAn interface specifies the members of a class that must be supplied by any class thatimplements the interface. In PowerBuilder .NET, you can create interfaces from the Newdialog box.

Because PowerScript has no concept of abstract classes, all methods, properties, events, andindexers defined in PowerBuilder .NET interfaces (including ancestor interfaces) must beimplemented 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 youwant to save the interface, and select an interface that you want the new interface toinherit 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 painterdisplays Untitled as the temporary name for the interface.

2. Select New Event in the second drop-down list of the Interface painter to add events tothe 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 thenext step (step 3), you must select the interface name (or Untitled if you did not providea name for the interface) from the first drop-down list before you can select New Eventin the second drop-down list.

3. Select Functions, Indexers, Properties, or Declare in the first drop-down listof the Interface painter to add functions, indexers, or properties to the interface, or todeclare a namespace or another interface.

A new painter window opens for the item you select. For new functions, indexers, andproperties, or to switch between declarations for namespaces and other interfaces, youmight need to select an appropriate item from the second drop-down list in the painterwindow.

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 Interfacedialog box prompts you for an interface name and the library where you want to save theinterface.

Implementing an InterfaceTo 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.

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. Namingor identity conflicts are resolved by including the name of the interface with the name of theclass member, separated by a dot.

Note: .NET rules do not allow you to directly call an identical member of two interfaces on aclass that implements those interfaces. You must use a variable of one of the implementedinterface types to call the member. If you try to call the member on the implementing class,PowerBuilder .NET displays a compilation error.



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 andInterfaces 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 clickOK.

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 Outlineview.

System Interface SyntaxPowerBuilder .NET provides system interfaces that you can use in your WPF applications orcomponents. These system interfaces include implementations for all the methods ofDataWindow 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 theinterface 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 DataWindowsand DataStores. It also is the base interface of three other system interfaces:IDataWindowControl, IDataWindowChild, and IDataWindowStore.

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

System interface Variable datatype to which it can be assigned

IDataWindowBase and IDataWin-dowControl

DataWindow

IDataWindowBase and IDataWin-dowChild

DataWindowChild

IDataWindowBase and IDataWin-dowStore

DataStore

The following syntax defines a function that determines the number of rows in a DataWindowor 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 thevalue you want to use as a filter. The following script filters a DataStore on a department ID of100:

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 methodsof the PowerBuilder picture control. The following example calls the SetPicture and Drawmethods 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 systeminterface to set the picturename parameter in the SetRowFocusIndicator method of aDataWindow or DataWindowChild control.

Deleting a Declared InterfaceDelete 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 keepor delete the interface functions, indexers, and properties.

1. Open the painter for the object with a declared interface that you want to delete.

2. Select Declare in the first drop-down list and Interfaces in the second drop-down list.

3. Right-click the interface you want to delete and select Delete from the pop-up menu.

4. In the Delete Interface dialog box, clear any checked functions, indexers, or properties thatyou want to keep.



5. Click OK.The Delete Interface dialog box closes. If you open the PB Object Outline view, you stillsee any functions, indexers, or properties that you chose to keep.

Inheriting from a .NET ClassYou can create an object that inherits from a .NET class in the same way that you create anobject that inherits from a PowerBuilder object.

However, you must add an assembly as a target reference before you can create an object thatinherits from a .NET class in that assembly.

Use the following procedure to inherit from a .NET class defined in an assembly listed in thetarget References folder:

1. Select File>Inherit from the PowerBuilder .NET menu, or click the Inherit button in theIDE toolbar.The Inherit from Object dialog box opens.

Note: Instead of using the Inherit from Object dialog box, you can expand the node for anassembly in the References folder of your target to show the class you want to inherit from,then right-click on the class, and select Inherit From in its pop-up menu. Skip to step 6below if you use this alternate procedure.

2. In the Inherit from Object dialog box, select the target where you want to add the newobject.

3. In the Objects of Type drop-down list, select Classes or All Objects.

4. In the Libraries list, select an assembly containing the class you want to inherit from.

5. In the Objects list, select the class you want to inherit from and click OK.

6. In the Object painter, implement all abstract and virtual functions, interfaces, events,indexers, and .NET properties defined in the base class.

7. Add any new interfaces, functions, events, indexers, and .NET properties you want toimplement in the new object.

Syntax Supporting Inheritance from a .NET ClassPowerScript allows you to create nonvisual objects that override all virtual and abstractmethods, properties, indexers and events defined in .NET base classes and interfaces.

The following example defines a PowerScript nonvisual object that inherits from a .NETclass:

global type NVO from DotNetClass1, ISub1 end type

The syntax for calling PowerScript functions and events can also be used to call the functionsand 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 argumentsexcept the function or event name are optional.


objectname The name of the object where the function orevent is defined followed by a period or the de-scendant of that object, or the name of the ances-tor class of the object followed by two colons.

type A keyword specifying whether you are calling afunction or event. Values are:

• FUNCTION (Default)

• EVENT

calltype A keyword specifying when PowerBuilder looksfor the function/event. Values are:

• STATIC (Default)

• DYNAMIC

when A keyword specifying whether the function orevent should execute immediately or only afterthe current script is finished. Values are:

• TRIGGER (Default) — Execute immediate-ly

• POST — Put in the object's queue and exe-cute after other pending messages have beenhandled

name The name of the function or event you want tocall.

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



Adding a Parameterized ConstructorIn PowerBuilder .NET, you can define parameterized constructor events that overload thedefault constructor event and instantiate the object with the arguments that you assign in theoverriding event prototypes.

Parameterized constructor events are supported on all custom and standard class nonvisualuser objects. If no arguments are passed in the call to instantiate a user object, the object'sdefault 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 constructorevents.

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. If the object for which you are adding a parameterized constructor event is an inheritedobject, you must invoke a constructor event of the parent object in the first line of code ofthe parameterized consturctor.

For example:

Super::EVENT constructor(“s1”, “s2)

Note: If the ancestor class is a .NET class rather than a PowerBuilder NVO, you must notuse EVENT in the override call, since the .NET constructors are implemented as functionsrather than events. So if the above example was overriding a parameterized constructor ina .NET ancestor class, the syntax for the override call would be:

Super::constructor(“s1”, “s2)

5. Create an object by passing in values for the arguments in the overloaded constructorevent.

The following example creates an object with two arguments: Obj obj = CREATE obj(1, 2)



Defining .NET Properties.NET properties get or set a specific data value of an object, and allow you to process that valuewhile enabling the actual member instance to remain private.

You can define .NET properties in Application objects, windows, menus, and standard andcustom user objects. PowerBuilder .NET object painters provide an easy way to script"getters" and "setters" for .NET properties.

1. Open the Script Editor for the object in which you want to define .NET properties.

2. Select Properties from the first drop-down list.A property signature or prototype area appears between the main item selection area andthe scripting pane.

3. Make sure New Property appears in the second drop-down list in the main item selectionarea.

Before a .NET property is defined for the current object, New Property is the defaultselection. If .NET properties are already defined, the default selection is the last .NETproperty viewed for the current object.

4. In the last (fourth) drop-down list of the prototype area, select:

• "get" if you want to add a getter.• "set" if you want to add a setter.

5. Select the access scope for the .NET property in the first drop-down list of the prototypearea.

Available selections are public (default), protected, and private.

6. Select the return type for the .NET property in the second drop-down list of the prototypearea.

7. Enter a name for the .NET property in the third drop-down list of the prototype area.

8. Enter the processing code for the .NET property getter or setter in the scripting pane.

If you do no other processing with the values that you get or set, you typically enter:• "return" followed by a variable of the selected return type when defining getters.• set the property or a variable to the context keyword "value" when defining setters.

9. If you want to script:

• the other accessor type (getter or setter) for the current .NET property, repeat thisprocedure from step 4, making the other accessor type selection from the one youpreviously made.

• a new .NET property for the current object, repeat this procedure from step 3.

10. Save the object.



Defining IndexersIndexers get or set values stored in an object. They are similar to .NET properties, except thatthey take parameters, and can be overloaded.

You can define indexers in Application objects, windows, menus, and standard and customuser objects. PowerBuilder .NET object painters provide an easy way to script "getters" and"setters" for indexers.

1. Open the Script Editor for the object in which you want to define indexers.

2. Select Indexers from the first drop-down list.An indexer signature or prototype area appears between the main item selection area andthe scripting pane.

3. Make sure New Indexer appears in the second drop-down list in the main item selectionarea.

Before an indexer is defined for the current object, New Indexer is the default selection. Ifindexers are already defined, the default selection is the last indexer viewed for the currentobject.

4. In the last (fourth) drop-down list of the prototype area, select:

• "get" if you want to add a getter.• "set" if you want to add a setter.

5. Select the access scope for the indexer in the first drop-down list of the prototype area.

Available selections are public (default), protected, and private.

6. Select the return type for the indexer in the second drop-down list of the prototype area.

7. Enter required information for indexer argument(s):

a) Select a datatype in the Argument Type drop-down list.b) Enter a name in the Argument Name text box.c) If you want to add another argument, right-click in the prototype area, select Add

Argument from the pop-up menu and repeat this step as many times as required.

Note: The Script Editor displays grayed fields for the indexer name and the argument"pass by" fields. This is because the indexer name is always "this" (meaning the currentobject), and you can only pass indexer arguments by value.

8. Enter the processing code for the indexer getter or setter in the scripting pane.The following code sample is from a getter script for an indexer that has a single integerargument nIndex, and returns a string array or a simple string:

if nIndex >0 or nIndex <= names.Length then return names[nIndex] else



return "null" end if

The code sample for a setter script for the same indexer looks like this:

if nIndex >0 or nIndex <= names.Length then names[nIndex] = value else names[nIndex] = "no name" end if

9. If you want to script:

• the other accessor type (getter or setter) for the current indexer, repeat this procedurefrom step 4, making the other accessor type selection from the one you previouslymade.

• a new indexer for the current object, repeat this procedure from step 3.

10. Save the object.

Creating a Global User‐Defined EnumerationIn PowerBuilder .NET, you can create global enumerations in the Enumeration painter or inscript.

Global enumerations can be used by all objects in your application or component target. Thefollowing procedure uses the Enumeration painter to define global enumerations for yourapplications.

1. In the New dialog box, select the PB Object>Enumeration item and click Finish.The Enumeration painter opens.

2. If you want the values for each item in the enumeration to be bit fields, select the Flagscheck 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 foreach item in the painter.

5. Select File>Save, provide a name for your global enumeration, and click OK.

Syntax for User‐Defined EnumerationsPowerScript 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. Forexample:

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-definedtype and PowerBuilder .NET tries to find it in PowerBuilder system-defined enumerations. Ifthe enumeration type exists, PowerBuilder .NET tries to find the enumeration type first andthen find the enumeration entry for that enumeration type.

Creating a Local User‐Defined EnumerationIn PowerBuilder .NET you can create local enumerations for an object in an Enumerationpainter that you open from the object painter.

To define a local enumeration using the PowerBuilder .NET user interface, you must first openan object painter that has a local Enumeration painter attached. You can define localenumerations 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 itemthat you enter for an enumeration type.

1. In the Solution Explorer, right-click the object for which you want to add a localenumeration 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 inthe upper left corner of the view.

3. If it is not already selected, select New Enumeration in the second drop-down list of theScript 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 foreach item in the painter.

7. Save the object with its new enumeration.



Consuming a .NET DelegateIn PowerBuilder .NET you can invoke .NET delegates from PowerScript code. Delegatesmake it possible to treat functions as entities that can be assigned to variables and passed asparameters.

A delegate type represents references to methods with a particular parameter list and returndatatype.

The PowerBuilder .NET IDE exposes all the visible delegates in the .NET assembliesreferenced by the current target in the Solution Explorer 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 .NETdelegate type.

Next

If you invoke the delegate asynchronously, you must also determine whether to join the resultsimmediately after the invoked thread completes its execution, after a callback function istriggered, or as the result of polling that allows other processing to complete even after thechild thread has finished running.

You can also decide whether to use multicasting. Multicasting makes use of a function chainthat passes arguments by value or reference from one function to another in a single invocationof the .NET delegate.

Syntax for Consuming .NET DelegatesIn PowerBuilder .NET, you can use PowerScript to invoke delegates in imported assemblieseither synchronously or asynchronously.

Delegate declaration

The following C# syntax declares delegate types named Func and FuncAsync in a .NETassembly 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 theexample 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 youimport to your target. The delegate signature requires a function that takes a double and returnsa 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 tothe function of_apply which calls the function of_multiply for each value in the vector usingthe 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 besidesof_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 avalue of the double datatype.

Asynchronous use case

The following PowerScript syntax uses the delegate type FuncAsyc from the external DLLthat 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

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 useasynchronous processing in a "polling pattern", where the invoked thread is polled todetermine it is finished, or in a "callback pattern", where a callback function is called when thethread has finished executing.

The code between the BeginInvoke and EndInvoke runs in the main thread, but thecomputation of the sum has its own thread from the .NET thread pool. When EndInvoke iscalled, 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 settingproperty values in a form or its child controls. You can read from and write to the user interfaceonly from the main UI thread.

Syntax for Consuming Generic ClassesGenerics are classes, structures, interfaces, and methods with placeholders for the datatypesthat they store or use.

A generic collection class can use a datatype parameter as a placeholder for the types ofobjects that it stores or returns. A generic method can also use its datatype parameter as a typefor any of its formal parameters (arguments).

In PowerBuilder .NET, you can consume .NET generic classes and methods that conform toCLS 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 alsosupported. 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 .NETgeneric 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)

Enhancements to .NET Component ProjectsWhen you generate .NET Assembly components from PowerBuilder .NET projects, you cantake advantage of CLS compliant features of PowerBuilder .NET that are not available inPowerBuilder Classic.

PowerBuilder .NET enables you to include jagged arrays as parameter types of publicmethods in .NET assembly projects.

If you set the CLSCompliant value of a .NET component project to true, the PowerBuilderto .NET compiler (pb2cs) generates the CLSCompliantAttribute(true) attribute for thecomponent, and the C# compiler applies the CLS rules to the public methods of thecomponent. If you do this and the component is not CLS compliant, the compiler issues theappropriate warnings.





Graphs in PowerBuilder .NET

Often the best way to display information is graphically. Instead of showing users a series ofrows and columns of data, you can present information as a graph in a DataWindow object orwindow.

PowerBuilder .NET provides many types of graphs and allows you to customize your graphsin many ways. Probably most of your use of graphs will be in a DataWindow object. Thesource of the data for your graphs will be the database.

You can also use graphs and standalone controls in windows (and user objects) and populatethe graphs with data through scripts.

The way you define graphs is the same whether you are using them in a DataWindow object ordirectly in a window. However, the way you manipulate graphs in a DataWindow object isdifferent from the way you manipulate them in a window.

Graph Differences Between PowerBuilder Classic andPowerBuilder .NET

The graphs and Graph DataWindow objects have, for the most part, the same functionality asin PowerBuilder Classic. There are some differences.

New Graph Styles and Appearance

There are new graph styles available and the appearance of existing graph styles has beenimproved.

New graph styles:

• bubble• cone• donut• radar

Additionally, you can now customize the configuration of graph colors or the brushesarrangement. In 3D graphs with axis frames, you can choose the brush for each frame.

Tooltips

The Tooltip.property works a little differently in PowerBuilder .NET graphs.

Unsupported Properties

The following is a list of graph properties that are not supported in PowerBuilder .NET.



• category.backedgepicture.clip.bottom• category.backedgepicture.clip.left• category.backedgepicture.clip.right• category.backedgepicture.clip.top• category.backedgepicture.mode• category.backedgepicture.scale.x• category.backedgepicture.scale.y

Parts of a GraphBefore 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. Itshows 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 5. Components of a graph

Component Meaning

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



Component Meaning

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

Values The values for the data points (dependent variables).

Organization of a graph

Table 6. 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) areplotted. In a column graph, for example, the Value axis corresponds to the y axis inan XY presentation. In other types of graphs, such as a bar graph, the Value axiscan be along the x dimension.

Category axis The axis along which are plotted the major divisions of the data, representing theindependent variable(s). In column graphs, the Category axis corresponds to the xaxis 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 orcolumns 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 showshow each series is represented in the graph.

Types of Graphs in PowerBuilder .NETPowerBuilder 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 theGeneral category in the Properties view for the graph.

Area, Bar, Column, and Line GraphsArea, bar, column, and line graphs are conceptually very similar. They differ only in how theyphysically represent the data values—whether they use areas, bars, columns, or lines torepresent the values. All other properties are the same.

For more information on graphs, see the PowerBuilder Users Guide.



Pie and Donut GraphsPie and donut graphs typically show one series of data points with each data point shown as apercentage of a whole.

You can see the relative values in a series of data.

Figure 1: Donut graph

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

Scatter and Bubble GraphsScatter graphs show xy data points. Typically you use scatter graphs to show the relationshipbetween 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 axes—asopposed to other graphs, which have values along one axis and categories along the otheraxis.

Bubble graphs enable you to chart three data values in two dimensions, using one x data pointand two y data points for each bubble.



For example, the following data shows the effect of speed on the mileage of a sedan, and thenumber 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:

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 FunctionThe SetBubbleSize function is used to define the size of the bubbles in a bubble graph.

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


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

graphControl (Data-Window control only)

(Optional) A string whose value is the name of the graph in the Data-Window 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 negativeinteger. 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 thebubble is proportional to the value it represents. Use SetBubbleSize to define the size of thebubbles.

Example

This statement changes the size of the first bubble in the first series of graph gr_1 in theDataWindow control dw_1 to 25.dw_1.SetBubbleSize("gr_1", 1, 1, 25)

BubbleSize PropertyThe size of a bubble in a bubble graph.

Syntax

PowerBuilder dot notation:controlName.Object.graphname.BubbleSize




controlName The name of the graph in which you want to set the bubble size, or the name of theDataWindow 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 GraphsYou can create three-dimensional (3D) graphs of area, bar, column, line, pie, and donutgraphs.

For more on generating 3D graphs, see the PowerBuilder Users Guide.

The Render3D property is supported in PowerBuilder .NET for backward compatibility, but itwill work only for Column3D and Bar3D graphs.

Radar GraphsRadar 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 seepatterns such as dominant variables, outliers, and other patterns in the data.



Stacked GraphsIn 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 barsor columns for each series.

Cone GraphsThe 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 inthe series, and the heights represent the percentage it takes from the sum of the series.





DataWindows

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

DataWindows in PowerBuilder .NETA DataWindow object is an object you use to retrieve, present, and manipulate data from arelational database or other data source. In PowerBuilder .NET, the WPF DataWindows usefully managed code.

DataWindow objects have knowledge about the data they are retrieving. You can specifydisplay formats, presentation styles, and other data properties so that users can make the mostmeaningful use of the data.

Using DataWindow Objects in PowerBuilder .NETYou 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 theDataWindow painter, which lets you create and edit DataWindow objects.

This procedure describes the overall process for creating using DataWindow objects. To readabout the concepts of using DataWindow objects in different kinds of applications and writingcode that interacts with DataWindow objects, see the DataWindow Programmers Guide.

1. Create the DataWindow object by using one of the DataWindow wizards in theDataWindow group of the New dialog box.

The wizard helps you define the data source, presentation style, and other basic propertiesof the object, and the DataWindow object displays in the DataWindow painter. In thispainter, you define additional properties for the DataWindow object, such as displayformats, 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 objectyou 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 itscontents.For example, you use the PowerScript Retrieve method to retrieve data into theDataWindow control.

You can write scripts for the DataWindow control to deal with error handling, sharing databetween DataWindow controls, and so on.

DataWindows


DataWindow Differences Between PowerBuilder Classic andPowerBuilder .NET

The DataWindow in PowerBuilder .NET behaves in most ways like the DataWindow inPowerBuilder Classic. There are some differences.

Changes to the DataWindow object

The DataWindow was rewritten for PowerBuilder .NET using managed code.

To open the Preview, Column Specifications, and Data views, click View > DataWindowPainter Windows .

The Control List has been replaced with the Document Outline. The Document Outline is ahiearchical list of controls, organized within the bands of the DataWindow object (header,detail, summary, and footer).

In PowerBuilder .NET, you can add custom controls to DataWindow objects.

Closing the Layout view is the same as closing the DataWindow painter for the DataWindowobject.

RetrieveOnPreview only occurs when Preview is opened from the menu. You can also use theRetrieve button in the Preview view toolbar or the Retrieve item in the context menu.

Cascading menu item inView menu

Menu item

Other Windows Bookmark Window, Command Window, Document Outline,Task List, Error List

DataWindow Painter Windows Preview, Column Specifications, Data, Import/Export Template

Unsupported features

The following features are not supported for DataWindow objects in PowerBuilder .NET.

• EMF and WMF image formats are not supported by WPF• OLE DataWindow presentation style and OLE controls are not supported by WPF

Feature Unsupported

Expressions AscA, CharA, FillA, LeftA, LenA, MidA, PosA, ProfileInt, ProfileString, Repal-ceA, RightA

Import types Dbase 2 & 3

Export types Dbase 2 & 3, DIF, EMF, Excel, Excel 5, HTML Table, Powersoft Report, Sylk,WKS, WK1, WMF, XSL-FO

DataWindows


Feature Unsupported

DataWindowobject properties

Export.PDF.Distill.CustomPostScript, Export.PDF.Method, Ex-port.PDF.XSLFOP.Print, Font.Bias, HideGrayLine, HorizontalScrollMaximum2,HorizontalScrollPosition2, HorizontalScrollSplit, Label.Sheet, Picture.Blur,Print.ClipText, Print.Color, Print.Copies, Print.Duplex, Print.OverridePrintJob,Print.Page.Range, Print.Page.RangeInclude, Print.Paper.Source, Print.Pre-view.Rulers, Print.Quality, Print.Scale, ReplaceTabWithSpace, RichText.Con-trolsCharVisible, RichText.DisplayOnly, RichText.PictureFrame, RichText.Re-adOnly, RichText.ReturnsVisible, RichText.RulerBar, RichText.SpacesVisible,RichText.TabBar, RichText.TabsVisible, RichText.WordWrap, ShowBackColor-OnXP, Zoom

Obsolete properties: Storage, StoragePageSize, Table.CrosstabData, Table.Da-ta.Storage

OLE is not supported: OLE.Client.Class, OLE.Client.Name

Properties, functions, and methods not supported in PowerBuilder .NET are listed inUnsupported Properties, Events, and Functions.

Presentation Styles for DataWindow ObjectsThe presentation style you select for a DataWindow object determines the formatPowerBuilder uses to display the DataWindow object in the Design view. You can use theformat as displayed or modify it to meet your needs.

When you create a DataWindow object, you can choose from the presentation styles listed inthe following table.

Table 7. DataWindow presentation styles

Using this DataWindowwizard

You create a new DataWindow object

Composite That includes other DataWindow objects

Crosstab With summary data in a spreadsheet-like grid

Freeform With the data columns going down the page and labels next to eachcolumn

Graph With data displayed in a graph

Grid With data in row and column format with grid lines separatingrows and columns

Group With data in rows that are divided into groups

DataWindows


Using this DataWindowwizard

You create a new DataWindow object

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 withformatted text

Tabular With data columns going across the page and headers above eachcolumn

TreeView With data grouped in rows in a TreeView; the TreeView displaysthe data hierarchically in a way that allows you to expand andcollapse it

Using SQL SelectIn specifying data for a DataWindow object, you have more options for specifying complexSQL 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 aSELECT 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 queryby selecting File > Save As from the menu bar. Doing so allows you to easily use this dataspecification again in other DataWindows.

Defining the Data Using SQL SelectIn the SQL Select painter, you paint a SQL statement to retrieve data for the DataWindowobject.

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.

DataWindows


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, ifappropriate.

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 SelectSelect the tables and views that you want to include in the query. The tables and views that areavailable for you to select depend on the DBMS.

After you have chosen SQL Select, the Select Tables dialog box displays in front of the TableLayout view of the SQL Select painter. What tables and views display in the dialog boxdepends on the DBMS. For some DBMSs, all tables and views display, whether or not youhave authorization. Then, if you select a table or view you are not authorized to access, theDBMS issues a message.

For ODBC databases, the tables and views that display depend on the driver for the datasource. SQL Anywhere does not restrict the display, so all tables and views display, whether ornot you have authorization.

To select the tables and views, do one of the following:

Options Description

Click the name of each table orview you want to open

Each table you select is highlighted. (To deselect a table, clickit again.) Click the Open button to close the Select Tablesdialog box.

Double‐click the name of eachtable or view you want to open

Each object opens immediately behind the Select Tables dialogbox. Click the Cancel button to close the Select Tables dialogbox.

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

Table Layout View in SQL SelectIn Table Layout View, representations of any selected tables and views appear in the SQLSelect dialog. Below this view are other tabbed views, which you can use to specify the SQLSELECT statement in more detail.

Below the Table Layout view, several tabbed views also display by default.

DataWindows


Selecting Columns Using SQL SelectIn the Table Layout view, you can click each column you want to include from the tablerepresentations in the Table Layout view.

PowerBuilder highlights selected columns and places them in the Selection List at the top ofthe SQL Select painter.

1. To select a column, click on it once in the Table Layout view.

Options Description

To select all columnsfrom a table:

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

To reorder the selectedcolumns:

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

2. To see a preview of the query results, click the Execute button in the Painter bar. A tabledisplaying the query results appear in the Results tab.

3. Click the OK button to open the DataWindow painter.

Including Computed Columns Using SQL SelectComputed columns you define in the SQL Select painter are added to the SQL statement andused by the DBMS to retrieve the data. The expression you define here follows your DBMS'srules.

Note: You can also choose to define computed fields, which are created and processeddynamically by PowerBuilder after the data has been retrieved from the DBMS. There areadvantages to doing this. For example, work is offloaded from the database server, and thecomputed fields update dynamically as data changes in the DataWindow object. (If you havemany 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 ifthe Compute view is not currently displayed).

Each row in the Compute view is a place for entering an expression that defines a computedcolumn.

2. Enter one of the following:

Options Description

An expression for thecomputed column

For example: salary/12

DataWindows


Options Description

A function supportedby 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-upmenu, you can select and paste the following into the expression:

• 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 PowerBuilderfunctions. This is so because you are now defining a SELECT statement that will be sent toyour DBMS for processing.

4. Press the Tab key to get to the next row to define another computed column, or clickanother tab to make additional specifications.

PowerBuilder adds the computed columns to the list of columns you have selected.

Defining QueriesThis feature is not supported in Beta.

Previewing the QueryWhile creating a query, you can preview it to make sure it is retrieving the correct rows andcolumns.

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 thedatabase. For more about manipulating data, see Managing the Database in thePowerBuilder Users Guide.

Saving the QueryWhile 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.

DataWindows


If you have previously saved the query, PowerBuilder allows you to save the query as-is orsave a new version in the same library. If you have not saved the query, PowerBuilderdisplays 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 youname queries, use a unique name to identify each one. A common convention is to use atwo-part name to identify each one. A common convention is to use a two-partt name: astandard prefix that identifies the object as a query (such as q_) and a unique suffix. Forexample, you might name a query that displays employee data q_emp_data. Forinformation 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 remindyourself and others of the purpose of the query.

4. Specify the library in which to save the query, and click OK.

Modifying the QueryNot supported in Beta.

DataWindow Object EnhancementsBefore you put a DataWindow object into production, you can enhance it to make it easier touse and interpret data.

You make DataWindow object enhancements in the DataWindow painter.

DataWindow PainterThe DataWindow painter provides views related to the DataWindow object you are workingon.

The following picture shows a DataWindow object in the DataWindow painter.

DataWindows


DataWindow Painter Design ViewFor most presentation styles, the DataWindow painter Design view is divided into areas calledbands. 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 abovethe bar.

These bands can contain any information you want, including text, drawing controls, graphs,and computed fields containing aggregate totals.

DataWindows


Figure 4: Design view for a tabular DataWindow object

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 andpage count

Header Band in DataWindowsThe header band contains heading information that is displayed at the top of every screen orpage.

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 inthe Database painter display in the header band and the columns display on a single lineacross the detail band

• If the presentation style is Freeform, the header band is empty and labels display in thedetail band next to each column

You can specify additional heading information (such as a date) in the header band and you caninclude 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 TodayDataWindow expression function in the header band.

DataWindows


Detail Band in DataWindowsThe detail band displays the retrieved data. It is also where the user enters new data andupdates existing data.

The number of rows of data that display in the PowerBuilder at one time is determined by thefollowing expression:

(Height of the DataWindow object - Height of headers and footers) / Height of the detail band

The presentation style determines the contents of the detail band:

• If the presentation style is Tabular, Grid, N-Up, or Label, the detail band displays columnnames, representing the columns.

• If the presentation style is Freeform, the labels defined for the columns in the Databasepainter 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 andvalidation information for each column of the DataWindow object and add other controls,such as text, pictures, graphs, and drawing controls.

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 thesame as the names in the table.

If the DataWindow object uses more than one table, the names of the columns in the Designview are tablename_columnname. PowerBuilder prefaces the name of the column with thetable name to prevent ambiguity, since different tables can have columns with the same name.

Summary and Footer BandsThe 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 usesummary pages and page footers in a printed report:

• The contents of the summary band display at the end, after all the detail rows; this bandoften summarizes information in the DataWindow object

• The contents of the footer band display at the bottom of each screen or page of theDataWindow object; this band often displays the page number and name of the report

DataWindow Painter ToolbarsThe DataWindow painter contains two customizable PainterBars.

The PainterBars include buttons for standard operations (such as Save, Print, and Undo onPainterBar1) and for common formatting operations (such as Currency, Percent, and layout inPainterBar2).

DataWindows


Properties View in the DataWindow PainterEach 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. Theproperties 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 byselecting the appropriate category. If you want to choose an edit style for the column, youselect the Edit Style category.

Using the Preview View of a DataWindow ObjectYou use the Preview view of a DataWindow object to view it as it will appear with data and testthe 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 PainterViews>Preview from the menu bar. (If the menu option is not available, make sure theDataWindow painter is active.)

In the Preview view, the bars that indicate the bands do not display. You are prompted tosupply 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.

Adding Controls to a DataWindow ObjectOne 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, andcomputed fields. You can also change the layout of the DataWindow object by reorganizing,positioning, and rotating controls.

Adding Columns to a DataWindow ObjectYou 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 isautomatically placed in the DataWindow object. Typically, you would add a column to restoreone that you had deleted from the DataWindow object, or to display the column more thanonce in the DataWindow object.

Note: If you want to add a column from the DataWindow definition to a DataWindow, alwaysinsert it from the Toolbox. You might see unexpected results if you copy a column from oneDataWindow object to another if they both reference the same column but the column order is

DataWindows


different. This is because copying a column copies a reference to the column's ID in theDataWindow definition.

Suppose d_first and d_second both have first_name and last_name columns, butfirst_name is in column 1 in d_first and column 2 in d_second. If you delete the first_namecolumn in d_second and paste column 1 from d_first in its place, both columns in d_seconddisplay the last_name column in the Preview view, because both columns now have a columnID 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 ofthe DataWindow object.

3. Select the column.

Adding Text to a DataWindow ObjectYou can add text anywhere in a DataWindow object.

When PowerBuilder generates a basic DataWindow object from a presentation style and datasource, it places columns and their headings in the DataWindow painter. You can add textanywhere 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 PropertiesView.

Adding Drawing Controls to a DataWindow ObjectYou can add drawing controls to a DataWindow object.

You can add the following drawing controls to a DataWindow object to enhance itsappearance:

• Rectangle• RoundRectangle• Line• Oval

1. Select the drawing control in the Toolbox.

2. Click where you want the control to display.

3. Reize or move the drawing control as needed.

DataWindows


4. 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 ObjectUse group boxes to organize controls in a DataWindow object.

To visually enhance the layout of a DataWindow object you can add a group box. A group boxis 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 theProperties view. This changes the text to display in the frame.

4. Move and resize the group box as appropriate.

Adding Pictures to a DataWindow ObjectYou can place pictures, such as your company logo, in a DataWindow object to enhance itsappearance.

If you place a picture in the header, summary, or footer band of the DataWindow object, thepicture displays each time the content of that band displays. If you place the picture in thedetail band of the DataWindow object, it displays on each row.

Note: WMF and EMF image formats are not supported in PowerBuilder .NET.

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), Graphics InterchangeFormat (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 itsHeight and Width properties in the Properties View.

Adding Computed Fields to a DataWindow ObjectYou can use computed fields in any band of the DataWindow object.

You can enter any valid DataWindow expression when defining a computed field. You canpaste operators, columns, and DataWindow expression functions into the expression frominformation 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 useobject-level functions.

DataWindows


Note: You are entering a DataWindow expression, not a SQL expression processed by theDBMS, 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 youplace 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.

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 Lnamecolumns for each row

Fname + " " + Lname Detail

Monthly salary if Salary column con-tains annual salary

Salary / 12 Detail

Four asterisks if the value of the Salarycolumn is greater than $50,000

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

Detail

Average salary of all retrieved rows Avg(Salary) Summary

Count of retrieved rows, assuming eachrow contains a value for EmpID

Count(EmpID) Summary

You can refer to other rows in a computed field. This is particularly useful in N-UpDataWindow objects when you want to refer to another row in the detail band. Use this syntax:ColumnName[x]

DataWindows


where x is an integer. 0 refers to the current row (or first row in the detail band), 1 refers to thenext row, -1 refers to the previous row, and so on.

For complete information about the functions you can use in computed fields in theDataWindow painter, see the DataWindow Reference.

Computed Columns Versus Computed FieldsYou define computed columns in the SQL Select painter, and the value is calculated by theDBMS when the data is retrieved. You define computed fields in the DataWindow painter, andthe value is calculated after the data has been retrieved.

When creating a DataWindow object, you can define computed columns and computed fieldsas follows:

• In the SQL Select painter, you can define computed columns when you are defining theSELECT 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 theSELECT statement (or other data source).

When you define the computed column in the SQL Select painter, the value is calculated by theDBMS when the data is retrieved. The computed column's value does not change until data hasbeen updated and retrieved again.

When you define the computed field in the DataWindow painter, the value of the column iscalculated in the DataWindow object after the data has been retrieved. The value changesdynamically as the DataWindow object changes.

Tip: If you want your DBMS to do the calculations on the server before bringing data downand you do not need the computed values to be updated dynamically, define the computedcolumn as part of the SELECT statement.

If you need computed values to change dynamically, define computed fields in theDataWindow painter Design view.

Consider a DataWindow object with four columns: Part number, Quantity, Price, and Cost.Cost is computed as Quantity * Price.

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 isas follows:SELECT part.part_num,part.part_qtypart.part_pricepart.part_qty * part.part_priceFROM part;

DataWindows


If the user changes the price of a part in the DataWindow object in this scenario, the cost doesnot change in the DataWindow object until the database is updated and the data is retrievedagain. The user sees a display with the changed price but the unchanged, incorrect cost.


101 100 2.50 125.00

If Cost is defined as a computed field in the DataWindow object, the SELECT statement is asfollows, with no computed column:SELECT part.part_numpart.part_qtypart.part_priceFROM 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 costchanges immediately.


101 100 2.50 250.00

Menu Options and Buttons for Common FunctionsYou can define computed fields in the DataWindow painter.

PowerBuilder provides a quick way to create computed fields that summarize values in thedetail band, display the current date, or show the current page number.

Insert a Computed Field for the Current Date or Page NumberThe functions for the current date and page number are available in the Modify Expressiondialog 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 FieldsNot supported in Beta

1. Place the mouse pointer over the PainterBar and select Customize from the pop-up menu.

DataWindows


The Customize dialog box displays.

2.

Adding Buttons to a DataWindow ObjectButtons make it easy to provide command button actions in a DataWindow object. No codingis required.

The use of Button controls in the DataWindow object, instead of CommandButton controls ina window, ensures that actions appropriate to the DataWindow object are included in theobject 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 Filterdialog 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 inthe Clicked event, the action assigned to the button is executed, but the ButtonClicking andButtonClicked 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. Clickinga Delete button in the detail band will delete the row next to the button clicked. Clicking anInsert 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 detailband would be unavailable when needed.

3. With the button still selected, type the text to display on the button or in the Propertiesview.

4. Select the action you want to assign to the button from the Action drop-down list in theGeneral section of the Properties view.

Actions Assignable to Buttons in DataWindow ObjectsThere are actions available for you to assign to a Button control, or you can define an eventscript.

The table shows the actions you can assign to a button in a DataWindow object. Each action isassociated 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)

DataWindows


Action Effect Val‐ue

Action return code

NoAction (default) Allows the developer to programthe ButtonClicked event with nointervening action occurring.

0 The return code from the user'scoded event script.

RetrieveYield Retrieves rows from the database.Before retrieval occurs, the op-tion to yield is turned on; this willallow the Cancel action to takeeffect during a long retrieve.

1 Number of rows retrieved.

-1 if retrieve fails

Retrieve Retrieves rows from the database.The option to yield is not auto-matically turned on.

2 Number of rows retrieved.

-1 if retrieve fails

Cancel Cancels a retrieval that has beenstarted with the option to yield.

3 0

PageNext Scrolls to the next page. 4 The row displayed at the top ofthe DataWindow control whenthe scrolling is complete or at-tempts to go past the first row.

-1 if an error occurs.

PagePrior Scrolls to the prior page. 5 The row displayed at the top ofthe DataWindow control whenthe scrolling is complete or at-tempts to go past the first row.


PageFirst Scrolls to the first page. 6 1 if successful.


PageLast Scrolls to the last page. 7 The row displayed at the top ofthe DataWindow control whenthe scrolling is complete or at-tempts to go past the first row.


Sort Displays Sort dialog box andsorts as specified.

8 1 if successful.


DataWindows


Action Effect Val‐ue

Action return code

Filter Displays Filter dialog box andfilters as specified.

9 Number of rows filtered.

Number < 0 if an error occurs.

DeleteRow If button is in detail band, deletesrow associated with button; oth-erwise, deletes the current row

10 1 if successful.

-1 if an error occurs

AppendRow Inserts row at the end. 11 Row number of newly insertedrow.

InsertRow If button is in detail band, insertsrow using row number associatedwith the button; otherwise, insertsrow using the current row.

12 Row number of newly insertedrow.

Update Saves changes to the database. Ifthe update is successful, a Com-mit will be issued; if the updatefails, a Rollback will be issued.

13 1 if successful.

-1 if an error occurs

SaveRowAs Displays Save As dialog box andsaves rows in the format speci-fied.

14 Number of rows filtered.

Number < 0 if an error occurs.

Print Prints one copy of the DataWind-ow object.

15 0

Preview Toggles between preview andprint preview

16 0

PreviewWithRulers Toggles between rulers on andoff.

17 0

QueryMode Toggles between query mode onand off.

18 0

QuerySort Allows user to specify sortingcriteria (forces query mode on).

19 0

QueryClear Removes the WHERE clausefrom a query (if one was defined).

20 0

DataWindows


Add Graphs to DataWindow ObjectsPowerBuilder offers many types of graphs and provides you with the ability to control theappearance of a graph to best meet your application's needs.

Graphs are one of the best ways to present information. For example, if your applicationdisplays sales information over the course of a year, you can easily build a graph in aDataWindow object to display the information visually.

See the Graphs in PowerBuilder .NET topics.

Adding Reports to a DataWindow ObjectYou can nest reports (nonupdatable DataWindow objects) in a DataWindow object.

Nesting reports works the same in PowerBuilder .NET as in PowerBuilder Classic, except thatyou select the Report control from the Toolbox. For more information, see the PowerBuilderUsers Guide.

Adding WPF Controls to a DataWindow ObjectYou 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 thetoolbox.

Tip: If the control you want to use is not in the toolbox, add it using Choose Items in thecontext 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 ObjectsTooltips 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 Tooltipsproperties in the Properties view.

• 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

DataWindows


DataWindows


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 inPowerBuilder Classic.

PowerBuilder 12 provides enhanced support for connecting to any .NET provider through amanaged 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. Thesedrivers 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 ProfilesYou can edit an existing database profile or create a new one.

Database profiles defined in either PowerBuilder Classic or PowerBuilder .NET are availableto 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 YourDatabase.

The Database Painter in PowerBuilder .NETTo 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 inPowerBuilder 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 tabbeddocument.

To open views in the Database painter, select the view from View>Database Painter Views inthe main menu bar.



Manipulating Data in Database PainterAs you work on the database, you often want to look at existing data or create some data fortesting purposes. You might also want to test display formats, validation rules, and edit styleson real data.

PowerBuilder provides data manipulation for such purposes. With data manipulation, youcan:• 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 seethePowerBuilder Users Guide.

SQL Statements in Database PainterThe Database painter's Interactive SQL view is a SQL editor in which you can enter andexecute SQL statements. The view provides all editing capabilities needed for writing andmodifying SQL statements.

You can cut, copy, and paste text; search for and replace text; and create SQL statements. Youcan also set editing properties to make reading your SQL files easier.

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

DSI Database Trace ToolThe DSI Database Trace tool is a managed database interface that records the internalcommands PowerBuilder executes while accessing a database.

Use the DSI Database Trace tool in PowerBuilder .NET WPF applications to trace DSIdatabase connections at runtime. Unless you use the PBADO driver, the DSI data sourceinterface calls the DBI database interface to connect to a database. This, in turn, activates theDBI Database Trace tool to trace the DBI database connections, although you can disable DBItracing 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 beforethe 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 aDSI 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 disconnectfrom the database.

At design time, you can only use DBI tracing. For information about DBI tracing, see thePowerBuilder Classic Users Guide.

Parameters of the DSI database trace

You set parameters for the DSI Database Trace tool in a "DSITrace" section of theconfiguration file for your application. The DSITrace section must also include a typeparameter 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 inthe application configuration file on deployment, but it is commented out. You canuncomment 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 elementafter 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 logfile is saved in the current directory. If you do not use this parameter, the DSI tracewill not be generated.

disableDBI-Trace (option-al)

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

0 - (default) DBI tracing is enabled

1 - DBI tracing is disabled

showParame-ters (optional)

Use to include or exclude SQL command parameters in the DSI trace log file.Values are:

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

1 - SQL command parameters are included in the log file

showFetchData(optional)

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

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 DSItrace to include SQL command parameters and fetch data in its log file, and save the log file tothe root directory on the c: drive 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 fromcommands of three object types: DSConnection, DSCommand, and DSReader. The log filealso lists SQL commands and data from fetch buffers if you enabled those options in theconfiguration file.

The format for the DSI command information is as follows, where tID is the thread ID, objIDis a random 8-digit number for the DSObject, DSObject is either DSConnection,DSCommand, or DSReader, and commandIssued is the name of the command. The startingtime for the command is given to the second, and the duration of the command is given inmilliseconds (MS):

(tID.objID) DSObject.commandIssued() MM/DD/YYYY HR:MIN:SEC / #### MS

Sharing ADO.NET Database ConnectionsPowerBuilder WPF applications can share database ADO.NET connections with third-party .NET assemblies.

Sharing database ADO.NET connections between an application and third-party .NETassemblies can minimize the number of connections to a database, or reduce the connectiontime.



About ADO.NET Database ConnectionsDatabase ADO.NET connections between Windows Presentation Foundation (WPF)applications and third-party .NET assemblies are shared through a PowerBuilder connectionproxy.

The connection proxy is defined in theSybase.PowerBuilder.DataSource.Sharing.dll assembly, whichimplements the .NET Framework System.Data.IDbConnection interface. Both thePowerBuilder application and the third-party assembly manage connections and transactionsby referencing the proxy.

In the WPF application, the PowerBuilder Transaction object is the standard PowerBuildernonvisual object used in database connections. To manage the shared connection, theTransaction object references the AdoConnectionProxy object using these methods:

• bool SetAdoConnection (object connectionProxy) – Accepts an imported ADO.NETconnection.

• object GetAdoConnection() – Accepts an ADO.NET connection exported from theTransaction object.

Exporting an ADO.NET Database ConnectionYou can export an ADO.NET connection from a PowerBuilder WPF application, enabling thesame database connection to be shared by an external .NET assembly.

Follow these guidelines to export a shared connection:

• In your PowerBuilder Transaction object, include a DBMS property that starts with ADO,and a DBParm property that specifies the driver's namespace.

• Start the connection before invoking GetAdoConnection.• Use the GetAdoConnection method to export the connection proxy, using this syntax:

object GetAdoConnection().

The object is the IAdoConnectionProxy instance to be returned.

The method returns null if it fails to make the connection. It returnsfalse if theoperation fails internally.

• To use the shared connection, your third-party assembly must reference the exportedconnection proxy and manage the transaction. You can subscribe theIAdoConnection.TransactionChanged event to be notified when the active transactionis changed.

• Remember to close the connection.

The proxy's Connection property passes the shareable connection as aSystem.Data.IDbConnection object, which is available to the third-party .NET assembly atruntime. The active transaction object is assigned to the proxy'sIAdoConnectionProxy.Transaction property.



Sample PowerScript codeSQLCA.DBMS = "ADO.NET"SQLCA.AutoCommit = falseSQLCA.DBParm = "Namespace='System.Data.Odbc', DataSource='SQL Anywhere 11 Demo'"Connect Using SQLCA;emp.ConnectionProxy = SQLCA.GetAdoConnection()

// db operationsdisconnect using SQLCA;

Sample C# assembly code// Manage the transactionpublic class Emp { ...

IAdoConnectionProxy proxy; IDbTransaction trans;

...

public object ConnectionProxy { get { return proxy; } set { proxy = value as IAdoConnectionProxy; ... proxy.TransactionChanged += new EventHandler(proxy_TransactionChanged); } }

void proxy_TransactionChanged(object sender, EventArgs e) { ... trans = sender as IDbTransaction; ... } ...}

Importing an ADO.NET Database ConnectionYou can import an ADO.NET connection from an external .NET assembly into aPowerBuilder WPF application, enabling the application and the assembly to share theconnection.

Follow these guidelines to import a shared connection from a third-party .NET assembly:

• In your PowerBuilder Transaction object, include a DBMS property that starts with ADO,and a DBParm property that specifies the System.Data.Odb namespace.

• Use the GetAdoConnection method to export the connection proxy.

Use this syntax:

bool GetAdoConnection(ConnectionProxy)



ConnectionProxy is a proxy, of type IAdoConnectionProxy, that is instantiated by thethird-party .NET assembly. The proxy's Connection property passes the shareableconnection as a System.Data.IDbConnection object.

The method returns trueif the parameter is an available instance or null.

The method returns false if it fails to make the connection or if the operation failsinternally.

• Start the connection after invoking GetAdoConnection.

Sample PowerScript codeSQLCA.DBMS = "ADO.NET"SQLCA.AutoCommit = trueSQLCA.DBParm = "Namespace='System.Data.Odbc', DataSource='SQL Anywhere 11 Demo'"bool retVal = SQLCA.SetAdoConnection(emp.AdoConnectionProxy) // emp is an instance of a type in the 3rd-party .NET assemblyif (retVal = true) then connect using SQLCA; // db operationsend if

Sample C# assembly codepublic class Emp {... public object AdoConnectionProxy...}





WCF Client Proxy Reference

The WCF Client Proxy project relies on a series of classes and enumerations to connect to avariety of Web services.

When you build a WCF client proxy project, the Project painter creates a WCFConnectionobject that it automatically instantiates with information obtained from the WSDL file for theservices you want to access.

The WCFConnection object has the WCFConnection class type, and it invokes a number ofother classes that can store information about binding types, transport and message securityprotocols, 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 aboutthese connection details.

If you are accessing Web services through a firewall, building a WCF Client Proxy project caninstantiate an object of the WCFProxyServer class to include values from the Firewall page ofthe 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 projectreference classes in script.

Although you do not need to call the WCF reference classes or select enumerated values forservice binding parameters and proxy server settings, you can do this to override defaultvalues. You can also query class properties to view the parameters that the proxy object willuse to connect to Web services. The reference topics that follow provide information about theWCFConnection object, and the classes and enumerations it uses to access Web services.

wcfConnection ObjectThe wcfConnection object includes all options for calling WCF services. You create awcfConnection object automatically when you build a WCF Client Proxy project.

The wcfConnection object is an instance of the WCFConnection class.



Properties

WCFConnectionproperty

Type Description

BindingType WCFBindingType(enumeration)

Specifies the binding type andcommunciation format to use whenaccessing a WCF service. The defaultvalue is generated from the servicecontract. If you delete this value, theconnection is attempted usingBasicHttpBindiing as the default bindingtype. Values are:BasicHttpBinding,WSHttpBinding,NetTcpBinding, andNetNamedPipeBinding .

WCF connection bindings are describedon the MSDN Web site.

ClientCredential WCFClientCredential (class) Specifies the WCF credential to use forcommunication with the Web service.

EndpointAddress WCFEndpointAddress(class)

Specifies a URL for the remote Webservice, and tells the Web service enginewhere the Web service resides. If theendpoint is not explicitly set, the Webservice engine uses the default endpointembedded in the service contract file andin the generated Web service assembly.

ProxyServer WCFProxyServer (class) Allows you to specify credentials for aproxy server if the client machine is behinda firewall. If the client machine is directlyconnected to the Internet, you need not setthis property.

Timeout String Specifies how long the WCF engine waitsbefore timing out while invoking the Webservice. The default value is 10 minutes("00:10:00"). The format for the time is"hh:mm:ss".

The Web service might have a differenttimeout value on the server side.

BasicHttpBinding WCFBasicHttpBinding(class)

Defines binding settings forBasicHttpBinding. This property is usedonly when the BindingType property isBasicHttpBinding.



http://msdn.microsoft.com/en-us/library/ms731092.aspx


Type Description

wsHttpBinding WCFwsHttpBinding (class) Defines binding settings forWCFwsHttpBinding. This property isused only when the BindingType propertyis WCFwsHttpBinding.

netTcpBinding WCFNetTcpBinding (class) Defines binding settings forNetTcpBinding. This property is usedonly when the BindingType property isNetTcpBinding.

netNamedPipeBinding WCFNetNamedPipeBinding(class)

Defines binding settings forNetNamedPipeBinding. This property isused only when the BindingType propertyis NetNamedPipeBinding.

SoapMessageHeader WCFSoapMessageHeader(class)

Defines SoapHeader items for the SOAPrequest message.

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

WCFConnectionfunction

Datatypereturned

Description

ClassName String Returns the name assigned to the control

GetContextService Integer Creates a reference to a context-specific instance ofthe 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 forthe control

TriggerEvent Integer Triggers a specified event in the control and exe-cutes the script for the event

TypeOf Object Returns the type of the control



Classes Supporting WCF Client ConnectionsSeveral PowerScript system classes provide all the support required for WCF clientconnections 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 ClassThe BasicHttpMessageSecurity class enables you to get and configure the message securitysettings of a BasicHttpBinding binding for a WCF client.

Properties

BasicHttpMessageSecurityproperty

Type Description

SecurityAlgorithm SecurityAlgorithmType(enumeration)

Specifies the algorithm suite to use forHttp message security. Values are:DEFAULT, BASIC128,BASIC128RSA15,BASIC128HA256,BASIC128SHA256RSA15A15,BASIC192, BASIC192RSA15,BASIC192HA256,BASIC192SHA256RSA15,BASIC256 (default),BASIC256RSA15,BASIC256HA256,BASIC256SHA256RSA15,TRIPLEDES,TRIPLEDESRSA15,TRIPLEDESSHA256, andTRIPLEDESSHA256RSA15.

ClientCredentialType BasicHttpMessageCredentialType(enumeration)

Specifies the credential type the clientuses for authentication. Values are:UserName (default) andCertificate.



BasicHttpSecurity ClassThe BasicHttpSecurity class configures the security settings of a BasicHttpBinding bindingfor a WCF client.

Properties

BasicHttpSecurityproperty

Type Description

SecurityMode BasicHttpSecurityMode(enumeration)

Gets or sets the security mode for aBasicHttpBinding binding. Values are: None(default), Transport, Message,TransportCredentialOnly, andTransportWithMessageCredential.

Transport HttpTransportSecurity(class)

Gets the transport level security settings for aBasicHttpBinding binding.

Message BasicHttpMessageSecurity(class)

Gets the message level security settings for aBasicHttpBinding binding.

ClientCertificateCredential ClassThe ClientCertificateCredential class enables you to select a client certificate for a secureconnection to a Web service.

Properties

ClientCertificateCredentialproperty

Type Description

SubjectName string Specifies the full path file name or thedistinguished subject name of thecertificate you want to use. If you use afull path file name, the StoreLocationand StoreName properties are ignored.

StoreLocation CertStoreLocation(enumeration)

Specifies the location of the X.509certificate store where the certificateyou want to use resides.

StoreName CertStoreName(enumeration)

Specifies the name of the X.509certificate store where the certificateyou want to use resides.

Note: The distinguished subject name of a certificate that you can specify for theSubjectName property is a comma-separated textual representation of the certificate details inthe 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 Contenttab of the Internet Explorer Internet Options dialog box), switching to the Details tab, andselecting Subject in the Field column of the list view on the Details tab.

HttpTransportSecurity ClassThe HttpTransportSecurity class enables you to get and configure transport security settingsfor a WCF Web service that uses BasicHttpBinding, WebHttpBinding, or wsHttpBindingbindings.

Properties

HttpTransportSecurityproperty

Type Description

Realm string Gets or sets the authentication realmfor digest or basic authentication. Theauthentication realm string mustinclude the name of the hostperforming the authentication, and canalso list the collection of users withaccess permissions.

ClientCredentialType HttpClientCredentialType(enumeration)

Specifies the credential type for HTTPclient authentication. Values are:None (default), Basic, Digest,NTLM, Windows, andCertificate.

HttpDigestCredential ClassThe HttpDigestCredential class provides credential information that allows a WCF client touse a proxy server, or connect to a Web service that requires digest authentication.

Invoke objects of the HttpDigestCredential class from the HttpDigest property ofWCFClientCredential class objects.

Properties

HttpDigestCredentialproperty

Type Description

UserName UserNameCredential(class)

Specifies the user name, password, anddomain of the client.



HttpDigestCredentialproperty

Type Description

AllowImpersonationLevel ImpersonationLevel(enumeration)

Determines the impersonation level of theWCF client. Values are: None (default),Anonymous, Identification,Impersonation, andDelegation.

MessageSecurityOverTcp ClassThe MessageSecurity class configures message-level security settings for a message sentusing TCP transport.

Properties

MessageSecurityOverTcpproperty

Type Description

AlgorithmSuite SecurityAlgorithmType(enumeration)

Specifies the algorithm suite used for message-levelsecurity. Valid values are: DEFAULT,BASIC128, BASIC128RSA15,BASIC128HA256,BASIC128SHA256RSA15A15,BASIC192, BASIC192RSA15,BASIC192HA256,BASIC192SHA256RSA15, BASIC256(default), BASIC256RSA15,BASIC256HA256,BASIC256SHA256RSA15, TRIPLEDES,TRIPLEDESRSA15, TRIPLEDESSHA256,TRIPLEDESSHA256RSA15, andTRANSPORTWITHMESSAGECREDENTIAL.

ClientCredentialType MessageCredentialType(enumeration)

Specifies the credential type used for clientauthentication. Values are: NONE, WINDOWS(default), USERNAME, CERTIFICATE, andISSUEDTOKENS.



NamedPipeTransportSecurity ClassThe NamedPipeTransportSecurity class provides a property to control the protection level fora named pipe.

Properties

NamedPipeTransportSecurityproperty

Type Description

ProtectionLevel ProtectionLevel(enumeration)

Gets or sets the protection level for anamed pipe. Values are: NONE,SIGN, and ENCRYPTANDSIGN(default).

NetNamedPipeSecurity ClassThe NetNamedPipeSecurity class configures the security settings for endpoints with theNetNamedPipeBinding binding.

Properties

NetNamedPipeSecurityproperty

Type Description

SecurityMode NetNamedPipeSecurityMode(enumeration)

Gets or sets the security modefor the binding. Values are:None and Transport(default).

Transport NamedPipeTransportSecurity(class)

Provides properties to controlauthentication parameters andthe protection level for namedpipe transport.



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

Properties

NetTcpSecurityproperty

Type Description

SecurityMode wsSecurityMode(enumeration)

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

Transport TcpTransportSecurity(class)

Provides properties to control authenticationparameters and the protection level for TCPtransport.

Message MessageSecurityOverTcp(class)

Provides properties that control authenticationparameters and the protection level for TCPmessages.



NoDualHttpMessageSecurity ClassThe NoDualHttpMessageSecurity class represents message-level security settings over anHTTP protocol where security is not set for two-way communication.

Properties

NoDualHttpMessageSecurityproperty

Type Description

SecurityAlgorithm SecurityAlgorithmType(enumeration)

Specifies the algorithm suite to use withNoDualHttpMessageSecurity. Values are:DEFAULT, BASIC128, BASIC128RSA15,BASIC128HA256,BASIC128SHA256RSA15A15,BASIC192, BASIC192RSA15,BASIC192HA256,BASIC192SHA256RSA15, BASIC256(default), BASIC256RSA15,BASIC256HA256,BASIC256SHA256RSA15, TRIPLEDES,TRIPLEDESRSA15, TRIPLEDESSHA256,TRIPLEDESSHA256RSA15, andTRANSPORTWITHMESSAGECREDENTIAL.

ClientCredentialType MessageCredentialType(enumeration)

Specifies the credential type to use for clientauthentication. Values are: NONE, WINDOWS(default), USERNAME, CERTIFICATE, andISSUEDTOKENS.

EstablishSecurityContext boolean Controls whether a security context token isestablished through a WS-SecureConversationexchange between a client and Web service. Valuesare:

• true (default) – requires the remote party tosupport the WS-SecureConversation protocol.

• false – the WS-SecureConversationprotocol is not used for the communication.



NoDualHttpMessageSecurityproperty

Type Description

NegotiateServiceCredential boolean Specifies whether the service credential is suppliedby the Web service through a negotiated process.Values are:

• true (default) – service credential is obtainedthrough a negotiated process.

• false – service credential is supplied by theclient out of band.

ServiceCertificateCredential ClassThe ServiceCertificateCredential class provides a client certificate for a secure connection to aWeb service. Use this class instead of the ClientCredentialService class when message-levelsecurity is enabled for the service.

Properties

ServiceCertificateCredentialproperty

Type Description

SubjectName string Specifies the full path file name or thedistinguished subject name of thecertificate you want to use. If you use afull path file name, the StoreLocationand StoreName properties are ignored.

StoreLocation CertStoreLocation(enumeration)

Specifies the location of the X.509certificate store where the certificateyou want to use resides.

StoreName CertStoreName(enumeration)

Specifies the name of the X.509certificate store where the certificateyou want to use resides.

Note: The distinguished subject name of a certificate that you can specify for theSubjectName property is a comma-separated textual representation of the certificate details inthe 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 Contenttab of the Internet Explorer Internet Options dialog box), switching to the Details tab, andselecting Subject in the Field column of the list view on the Details tab.



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

Properties

TcpTransportSecurityproperty

Type Description

ClientCredentialType TcpClientCredentialType(enumeration)

Specifies the credential type for TCPclient authentication. Values are:NONE, WINDOWS (default), andCERTIFICATE.

ProtectionLevel ProtectionLevel(enumeration)

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

UserNameCredential ClassThe UserNameCredential class provides a user name, password, and domain name that enableyou to authenticate a client to a Web service or proxy server.

Invoke objects of the UserNameCredential class from the UserName property ofWCFClientCredential, 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 ClassUse 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

WCFBasicHttpBindingproperty

Type Description

TransferMode WSTransferMode(enumeration) Gets or sets a value to indicatewhether messages are bufferedor streamed. Values are:BUFFERED (default),STREAMED,STREAMEDREQUEST, andSTREAMEDRESPONSE.

MessageEncoding WSMessageEncoding(enumeration)

Specifies encoding for SOAPmessages. Values are: Text(default), and MTOM (MessageTransmission OptimizationMechanism).

TextEncoding WSTextEncoding (enumeration) Specifies character encodingfor the SOAP message text.Values are: ASCII,BIGENDIANUNICODE,UNICODE, UTF32, UTF7,and UTF8 (default).

Security BasicHttpSecurity (class) Gets or configures the securitysettings of a BasicHttpBindingconnection.

ReaderQuotas WCFReaderQuotas (class) Gets or sets processingconstraints based on the SOAPmessage complexity forendpoints with this bindingtype.

AllowCookies Boolean Indicates whether the clientaccepts cookies. Values are:

• true – accepts cookies.

• false (default) – doesnot accept cookies.



WCFBasicHttpBindingproperty

Type Description

BypassProxyOnLocal Boolean Indicates whether to bypass theproxy server for localaddresses. Values are:

• true – bypasses theproxy server.

• false (default) – doesnot bypass the proxyserver.

HostNameComparisonMode WCFHostNameComparisonMode(enum)

When matching the URI,indicates whether to use thehost name to reach the WCFservice. Values are:StrongWildCard(default), Exact, andWeakWildCard.

MaxBufferPoolSize Int64 (PowerScript longlong) Specifies the maximumamount of memory allocatedfor the manager of the buffersrequired by the endpoints usingthis binding. The default valueis 524288.

MaxBufferSize Int32 (PowerScript long) Specifies the maximum size fora buffer that receives messagesfrom the channel. The defaultvalue is 65536.

MaxReceivedMessageSize Int64 (PowerScript longlong) Specifies the maximum size fora message that can beprocessed by the binding. Thedefault value is 65536.

Methods

WCFBasicHttpBindingmethod

Description

AddHttpRequestHeader Adds an HTTP header to the HTTP request. With this method,you can add or change any header in the HTTP message.

RemoveHttpRequestHeader Removes a specified HTTP header when the HTTP requestmessage is sent.



WCFBasicHttpBindingmethod

Description

GetHttpResponseHeader Gets an HTTP header value (based on the header type) from theHTTP response message.

WCFClientCredential ClassThe WCFClientCredential class provides client credentials for a Web service or a proxy serverthat is behind a firewall.

Properties

WCFClientCredentialproperty

Type Description

UserName UserNameCredential (class) Gets a credential object you can useto set the user name and passwordfor a Web service or proxy server

HTTPDigest HttpDigestCredential (class) Gets the current HTTP digestcredential

Windows WindowsCredential (class) Gets an object with the Windowscredential you want to use toauthenticate a client to a Webservice

ClientCertificate ClientCertificateCredential(class)

Specifies an object that provides anX.509 certificate that the client canuse for authentication to a Webservice

ServiceCertificate ServiceCertificateCredential(class)

Specifies an object that provides anX.509 certificate when the messagesecurity mode is set for message-level encryption



WCFConnection ClassThe WCFConnection class specifies the properties required for a WCF client to connect to aWeb service. WCFConnection is the base class for the wcfConnection object generated by theWCF Client project wizard.

Properties


Type Description

BindingType WCFBindingType(enumeration)

Specifies the binding type andcommunciation format to use whenaccessing a WCF service. The defaultvalue is generated from the servicecontract. If you delete this value, theconnection is attempted usingBasicHttpBindiing as the default bindingtype. Values are:BasicHttpBinding,WSHttpBinding,NetTcpBinding, andNetNamedPipeBinding .

WCF connection bindings are describedon the MSDN Web site.

ClientCredential WCFClientCredential (class) Specifies the WCF credential to use forcommunication with the Web service.

EndpointAddress WCFEndpointAddress(class)

Specifies a URL for the remote Webservice, and tells the Web service enginewhere the Web service resides. If theendpoint is not explicitly set, the Webservice engine uses the default endpointembedded in the service contract file andin the generated Web service assembly.

ProxyServer WCFProxyServer (class) Allows you to specify credentials for aproxy server if the client machine is behinda firewall. If the client machine is directlyconnected to the Internet, you need not setthis property.



http://msdn.microsoft.com/en-us/library/ms731092.aspx


Type Description

Timeout String Specifies how long the WCF engine waitsbefore timing out while invoking the Webservice. The default value is 10 minutes("00:10:00"). The format for the time is"hh:mm:ss".

The Web service might have a differenttimeout value on the server side.

BasicHttpBinding WCFBasicHttpBinding(class)

Defines binding settings forBasicHttpBinding. This property is usedonly when the BindingType property isBasicHttpBinding.

wsHttpBinding WCFwsHttpBinding (class) Defines binding settings forWCFwsHttpBinding. This property isused only when the BindingType propertyis WCFwsHttpBinding.

netTcpBinding WCFNetTcpBinding (class) Defines binding settings forNetTcpBinding. This property is usedonly when the BindingType property isNetTcpBinding.

netNamedPipeBinding WCFNetNamedPipeBinding(class)

Defines binding settings forNetNamedPipeBinding. This property isused only when the BindingType propertyis NetNamedPipeBinding.

SoapMessageHeader WCFSoapMessageHeader(class)

Defines SoapHeader items for the SOAPrequest message.

The following binding types are not currently supported: WS2007HttpBinding,WSFederationHttpBinding, WS2007FederationHttpBinding,NetMsmqBinding, WebHttpBinding, WSDualHttpBinding,NetPeerBinding, and MsmqIntegrationBinding.



WCFEndpointAddress ClassThe WCFEndpointAddress class provides a unique network address that a client uses tocommunicate with a service endpoint.

Properties

WCFEndpointAddressproperty

Type Description

URL string Specifies the URI that identifiesthe endpoint location.

Identity WCFEndpointIdentity(class)

Specifies the identity for theendpoint.

WCFEndpointIdentity ClassThe WCFEndpointIdentity class defines the identity type and value of an endpoint, enablingauthentication by clients exchanging messages with it.

Properties

WCFEndpointIdentityproperty

Type Description

Type WCFEndpointIdentityType(enumeration)

Specifies the type of identity.Values are: NONE (default), UPN,SPN, DNS, RSA, andCERTIFICATE.

IdentityValue string Specifies the identity value.



WCFSoapMessageHeader ClassWCFSoapMessageHeader adds a SOAP header for the service request. This class enables youto change the encryption algorithm and key used in the header.

Methods

WCFSoapMessageHeadermethod

Description

AddMessageHeaderItem Adds a SoapHeader item. After SoapHeader items are added, theWCF client sets the SOAP header before sending out the request.The format for a SoapHeader item is:

<ItemName xmlns=”ItemNamespace”>EncryptedItemValue</ItemName>

RemoveMessageHeaderItem Removes the SoapHeader item with the name that you pass in theItemName parameter of this method.

RemoveAllMessageHeaderItems Removes all SoapHeader items

WCFnetNamedPipeBinding ClassThe WCFnetNamedPipeBinding class provides a secure binding that is optimized for on-machine use.

Note: NetNamedPipeBinding supports transactions and uses binary message encoding,transport security, and named pipes for message delivery. The default configuration for theNetNamedPipeBinding is for on-machine communication only.

WCFnetNamedPipeBindingproperty

Type Description

MaxConnections System.Int32 Specifies a value for the maximum number ofconnections to be pooled for subsequent reuse on theclient. The default is 10.

TransactionFlow boolean Specifies whether transaction flowing is supported.Values are:

• true – supported.

• false (default) – not supported.



WCFnetNamedPipeBindingproperty

Type Description

TransactionProtocol TransactionProtocolType(enumeration)

Specifies the transaction protocol to use in flowingtransactions. Values are: DEFAULT,OLETRANSACTIONS (default),WSATOMICTRANSACTION11, andWSATOMICTRANSACTION_OCTOBER2004.

TransferMode WSTransferMode (enumeration) Gets or sets a value to indicate whether messages arebuffered or streamed. Values are: BUFFERED(default), STREAMED, STREAMEDREQUEST,and STREAMEDRESPONSE.

Security NetNamedPipeSecurity (class) Specifies the type of security to use with servicesconfigured for NetNamedPipeBinding. Values are:NONE and TRANSPORT (default).

ReaderQuotas WCFReaderQuotas (class) Gets or sets processing constraints based on theSOAP message complexity for endpoints with thisbinding type.


When matching the URI, indicates whether to use thehost name to reach the WCF service. Values are:StrongWildCard (default), Exact, andWeakWildCard.

MaxBufferSize Int32 (PowerScript long) Specifies the maximum size for a buffer that receivesmessages from the channel. The default value is65536.

MaxBufferPoolSize Int64 (PowerScript longlong) Specifies the maximum amount of memory allocatedfor the manager of the buffers required by theendpoints using this binding. The default value is524288.

MaxReceivedMessageSize Int64 (PowerScript longlong) Specifies the maximum size for a message that can beprocessed by the binding. The default value is 65536.



WCFnetTCPBinding ClassThe WCFnetTCPBinding class enables you to communicate with WCF Web services from aWCF client using NetTcpBinding. This binding is intended for WCF-to-WCFcommunication only.

Properties

WCFnetTCPBindingproperty

Type Description

MaxConnections System.Int32 Specifies a value for the maximum number ofconnections to be pooled for subsequent reuse on theclient. The default for netTcpBinding is 10.

ReliableSession WCFReliableSession (class) Specifies whether to enable reliable sessions (usingthe WS-ReliableMessaging protocol) and definessettings for these sessions when enabled.

TransactionFlow boolean Specifies whether transaction flowing is supported.Values are:


• false (default) – not supported.

TransactionProtocol TransactionProtocolType(enumeration)

Specifies the transaction protocol to use in flowingtransactions. Values are: DEFAULT (default),OLETRANSACTIONS,WSATOMICTRANSACTION11, andWSATOMICTRANSACTION_OCTOBER2004.

TransferMode WSTransferMode (enumeration) Gets or sets a value to indicate whether messages arebuffered or streamed. Values are: BUFFERED(default), STREAMED, STREAMEDREQUEST,and STREAMEDRESPONSE.

Security NetTcpSecurity (class) Specifies the type of security to use with servicesconfigured for NetTcpBinding. The default securitymode is TRANSPORT.

ReaderQuotas WCFReaderQuotas (class) Gets or sets processing constraints based on theSOAP message complexity for endpoints with thisbinding type.


When matching the URI, indicates whether to use thehost name to reach the WCF service. Values are:StrongWildCard (default), Exact, andWeakWildCard.



WCFnetTCPBindingproperty

Type Description

MaxBufferSize Int32 (PowerScript long) Specifies the maximum size for a buffer that receivesmessages from the channel. The default value is65536.

MaxBufferPoolSize Int64 (PowerScript longlong) Specifies the maximum amount of memory allocatedfor the manager of the buffers required by theendpoints using this binding. The default value is524288.

MaxReceivedMessageSize Int64 (PowerScript longlong) Specifies the maximum size for a message that can beprocessed by the binding. The default value is 65536.

ListenBackLog Int32 (PowerScript long) Specifies the maximum number of queuedconnection requests permitted. The default value is10.

WCFProxyServer ClassIf you connect to a Web service from behind a proxy server, you must first instantiate an objectof the WCFProxyServer class. This class provides credential information to the proxy server.

Properties

WCFProxyServerproperty

Type Description

ProxyAddress string Specifies a URL for the proxy server orfirewall.

CredentialType HttpProxyCredentialType(enumeration)

Specifies the credential type to use for thefirewall. Values are: None (default),Basic, Digest, NTLM,Certificate, and Windows.

ClientCredential WCFClientCredential (class) Specifies the WCF credentials to be usedfor the firewall.

UseDefaultWebProxy Boolean Determines whether to use the defaultWeb proxy settings, as defined forInternet Explorer. The default value is"true".



WCFReaderQuotas ClassThe WCFReaderQuotas class defines restrictions (quotas) for the complexity of messageexchanges with service endpoints that you can set differently according to the binding typeused.

Properties

WCFReaderQuotasproperty

Type Description

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

MaxStringContentLength Int (System.Int32) Gets or sets a maximum length for messagestrings returned from the service. The defaultvalue is 8192.

MaxArrayLength Int (System.Int32) Gets or sets the maximum length for arraysreturned from the service. The default value is16384.

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

MaxNameTableCharCount Int (System.Int32) Gets or sets the maximum number ofcharacters permitted in a table name. Settingthis value can help prevent buildup of largeamounts of character data. The default value is16384.



WCFReliableSession ClassThe WCFReliableSession class allows you to use reliable messaging for your Web serviceconnections, as long as the binding type you are using supports the WS-ReliableMessagingprotocol. WCFReliableSession also lets you get and set message ordering and duration.

Properties

WCFReliableSessionproperty

Type Description

Enabled boolean Specifies whether the connection uses the WS-ReliableMessaging protocol. The default for this propertydepends on the binding type used for the Web serviceconnection. Values are:

• true – reliable messaging is enabled.

• false – reliable messaging is not enabled.

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

• true (default) – messages are delivered in the ordersent.

• false – message order is not specified.

Duration long Specifies the duration, in seconds, of a reliable messagingsequence. The default value is 600 seconds (10 minutes).

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

Properties

WCFwsHttpBindingproperty

Type Description

MessageEncoding WSMessageEncoding(enumeration) Specifies encoding for SOAPmessages. Values are: TEXT(default) and MTOM(Message TransmissionOptimization Mechanism).




Type Description

TextEncoding WSTextEncoding (class) Specifies character encodingfor SOAP message text.Values are: ASCII,BIGENDIANUNICODE,UNICODE, UTF32,UTF7, and UTF8 (default).

ReliableSession WCFReliableSession (class) Specifies whether to enablereliable sessions (using theWS-ReliableMessagingprotocol), and definessettings for these sessionswhen enabled.

TransactionFlow boolean Specifies whether transactionflowing is supported. Valuesare:


• false (default) – notsupported.

Security wsHttpSecurity (class) Gets or configures thesecurity settings of awsHttpBinding connection.

ReaderQuotas WCFReaderQuotas (class) Gets or sets processingconstraints based on theSOAP message complexityfor endpoints with thisbinding type.

AllowCookies Boolean Indicates whether the clientaccepts cookies. Values are:

• true – accepts cookies.

• false (default) – doesnot accept cookies.




Type Description

BypassProxyOnLocal Boolean Indicates whether to bypassthe proxy server for localaddresses. Values are:

• true – bypasses theproxy server.

• false (default) – doesnot bypass the proxyserver.


When matching the URI,indicates whether to use thehost name to reach the WCFservice. Values are:StrongWildCard(default), Exact, andWeakWildCard.

MaxBufferPoolSize Int64 (PowerScript longlong) Specifies the maximumamount of memory allocatedfor the manager of the buffersrequired by the endpointsusing this binding. Thedefault value is 524288.

MaxReceivedMessageSize Int64 (PowerScript longlong) Specifies the maximum sizefor a message that can beprocessed by the binding. Thedefault value is 65536.

Methods

WCFwsHttpBinding method Description

AddHttpRequestHeader Adds an HTTP header to the HTTP request. With this method,you can add or change any header in the HTTP message.

RemoveHttpRequestHeader Removes a specified HTTP header when the HTTP requestmessage is sent.

GetHttpResponseHeader Gets an HTTP header value (based on the header type) from theHTTP response message.



WindowsCredential ClassThe WindowsCredential class provides credential information that allows a WCF client to usea proxy server or connect to a Web service that requires integrated Windows authentication.

The WindowsCredential class can be invoked by the Windows property of theWCFClientCredential class.

Properties

WindowsCredentialproperty

Type Description

UserName UserNameCredential(class)

Specifies the user name, password, anddomain of the client.

AllowsImpersonationLevel ImpersonationLevel(enumeration)

Determines the impersonation level of theWCF client. Values are: None (default),Anonymous, Identification,Impersonation, andDelegation.

AllowNtlm boolean Indicates whether NT LAN Manager(NTLM) authentication is allowed asWindows Security Support ProviderInterface (SSPI) Negotiate authentication.Values are:

• true (default) – authentication isallowed.

• false – authentication is notallowed.

wsHttpSecurity ClassThe wsHttpSecurity class provides the security settings for the wsHttpBinding of a WCFclient to a Web service.

Properties

wsHttpSecurityproperty

Type Description

SecurityMode wsSecurityMode(enumeration)

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



wsHttpSecurityproperty

Type Description

Transport HttpTransportSecurity (class) Specifies the transport-level security for thebinding.

Message NoDualHttpMessageSecurity(class)

Specifies the message-level security for thebinding.

WCF Client MethodsWCF client methods enable you to add and remove headers to HTTP and Soap messages.

AddHttpRequestHeader MethodThe AddHttpRequestHeader method adds a header to the HTTP request. With this method,you can add or change any header in the HTTP message.

Syntaxclient.wcfConnectionObject.Binding.AddHttpRequestHeader (PBWCF.HTTPRequestHeaderType HeaderType!, string HeaderValue)

Parameters

• Binding – an instance of the WCFBasicHttpBinding or WCFwsHttpBinding class.• HeaderType – an enumerated value of type PBWCF.HttpRequestHeaderType.• HeaderValue – a string for the header value.

Returns

None.

Examples

• – The following code adds a cookie and a user agent name to the HTTP request header fora BasicHttpBinding connection:

client.wcfConnectionObject.BasicHttpBinding.AddHttpRequestHeader(PBWCF.HttpRequestHeaderType.Cookie!, "testing")client.wcfConnectionObject.BasicHttpBinding.AddHttpRequestHeader(PBWCF.HttpRequestHeaderType.UserAgent!, "john")

AddMessageHeaderItem MethodAdds a SoapHeader item to the SOAP header before the WCF client sends a request.



Syntaxclient.wcfConnectionObject.SoapMessageHeader.AddMessageHeaderItem (string ItemName, string ItemNamespace, string ItemValue, PBWCF.WCFHMAC ItemEncryptAlgorithm!, string EncryptKey)

Parameters

• SoapMessageHeader – an instance of the WCFSoapMessageHeader class.• ItemName – a string for the name of the SoapHeader item that you want to add.• ItemNamespace – a string for the namespace of the SoapHeader item.• ItemValue – a string for the value of the SoapHeader item.• ItemEncryptAlgorithm – an enumerated value of the type PBWCF.WCFHMAC for the

algorithm you want to use to encrypt the ItemValue.• EncryptKey – a string for the key you want to use to encrypt the ItemValue

Returns

bool. Returns true if successful, otherwise returns false.

Examples

• Setting values in the wcfConnectionObject – You can add a header to a request messagesent to Amazon Web Services as follows:

client.wcfConnectionObject.SoapMessageHeader.AddMessageHeaderItem("AWSAccessKeyId","http://security.amazonaws.com/doc/2007-01-01/","My access key",PBWCF.WCFHMAC.NONE!,"")client.wcfConnectionObject.SoapMessageHeader.AddMessageHeaderItem("Signature","http://security.amazonaws.com/doc/2007-01-01/","My secret key", PBWCF.WCFHMAC.HMACSHA256!, "")

• Setting values in an instance of WCFSoapMessageHeader – You can add a header sentto the same service as follows:

WCFSoapMessageHeader HeaderHeader = create WCFSoapMessageHeaderHeader.AddMessageHeaderItem("AWSAccessKeyId","http://security.amazonaws.com/doc/2007-01-01/","My access key",PBWCF.WCFHMAC.NONE!,"")Header. .AddMessageHeaderItem("Signature","http://security.amazonaws.com/doc/2007-01-01/","My secret key", PBWCF.WCFHMAC.HMACSHA256!, "")client.wcfConnectionObject.SoapMessageHeader = Header

UsageIf you use encryption, the format for a SoapHeader item in the request sent by the WCF clientis:



<ItemName xmlns=”ItemNamespace”>EncryptedItemValue</ItemName>

GetHttpResponseHeader MethodThe RemoveHttpRequestHeader method removes a header from an HTTP request.

Syntaxsvc.wcfConnectionObject.Binding.GetHttpResponseHeader (PBWCF.HttpResponseHeaderType.HeaderType!)

Parameters

• Binding – an instance of the WCFBasicHttpBinding or WCFwsHttpBinding class.• HeaderType – an enumerated value of type PBWCF.HttpResponseHeaderType.

Returns

String. If the header does not exist in the response message, GetHttpResponseHeader returnsan empty string.

Examples

• – The following example returns a date from the HTTP response header:String dtdt = svc.wcfConnectionObject.BasicHttpBinding.GetHttpResponseHeader(PBWCF.HttpResponseHeaderType.Date!)

RemoveAllMessageHeaderItems MethodRemoves all SoapHeader items from the SOAP header before the WCF client sends a request.

Syntaxclient.wcfConnectionObject.SoapMessageHeader.RemoveAllMessageHeaderItems ()

Parameters

• SoapMessageHeader – an instance of the WCFMessageHeader class.

Returns




RemoveHttpRequestHeader MethodThe RemoveHttpRequestHeader method removes a header from an HTTP request.

Syntaxclient.wcfConnectionObject.Binding.RemoveHttpRequestHeader (PBWCF.HTTPRequestHeaderType HeaderType!)

Parameters

• Binding – an instance of the WCFBasicHttpBinding or WCFwsHttpBinding class.• HeaderType – an enumerated value of type PBWCF.HttpRequestHeaderType.

Returns

None.

RemoveMessageHeaderItem MethodRemoves a SoapHeader item from the SOAP header before the WCF client sends a request.

Syntaxclient.wcfConnectionObject.SoapMessageHeader.RemoveMessageHeaderItem (string ItemName)

Parameters

• SoapMessageHeader – an instance of the WCFSoapMessageHeader class.• ItemName – a string for the name of the SoapHeader item that you want to remove.

Returns


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



BasicHttpMessageCredentialType EnumerationThe BasicHttpMessageCredentialType enumeration specifies the credential type required bya 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 EnumerationThe BasicHttpSecurityMode enumeration stores or supplies security mode settings for a WCFclient using BasicHttpBinding to bind to a Web service.

Enumerated values

BasicHttpSecurityMode value Meaning

None The SOAP message is not secured during transfer. This is thedefault behavior for WCF client binding.

Transport HTTPS provides security for the SOAP message and the clientauthenticates the service using the service's SSL certificate.The ClientCredentialType property of the BasicHttpBindingclass controls client authentication to the service.

Message SOAP message security provides client authentication. Theserver SSL certificate must be provided to the client separately.

TransportWithMessageCredential HTTPS provides for message integrity, confidentiality, andserver authentication. SOAP message security assures clientauthentication. The service must be configured with an SSLcertificate.

TransportCredentialOnly Client authentication is provided by HTTP, but messageintegrity and confidentiality are not provided. Use this modeonly when other means of transfer security (such as IPSec) areavailable.



CertStoreLocation EnumerationThe CertStoreLocation enumeration specifies the location of the X.509 certificate storecontaining 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 EnumerationThe CertStoreName enumeration specifies the name of the X.509 certificate store containing acertificate 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 certificateauthorities

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 andresources

TrustedPublisher Specifies the X.509 certificate store for directly trusted publishers



HttpClientCredentialType EnumerationThe HttpClientCredentialType enumeration provides the type of credential to use fortransport-level security when connecting to a Web service that uses the BasicHttpBindingbinding.

Enumerated values

HttpClientCredentialType value Meaning

None Specifies anonymous authentication

Basic Specifies Basic authentication

Digest Specifies Digest authentication

NTLM Specifies client authentication using NTLM (NT LANManager)

Windows Specifies client authentication using Windows


HttpProxyCredentialType EnumerationThe HttpProxyCredentialType enumeration provides the type of credential required by aproxy 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 proxyserver

Digest Client uses digest authentication to connect to the proxyserver

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

Windows Client uses integrated Windows authentication to connect tothe proxy server



HttpRequestHeaderType EnumerationThe HttpRequestHeaderType enumeration is used by the AddHttpRequestHeader method toadd a header to an HTTP message, and by the RemoveHttpRequestHeader method to remove aheader from an HTTP message.

Enumerated values

The HttpRequestHeaderType enumeration supports the following header types:

AcceptAcceptCharsetAcceptEncodingAcceptLanguageAllowAuthorizationCacheControlConnectionContentEncodingContentLanguageContentLengthContentLocationContentMd5ContentRangeContentTypeCookieDateExpectExpiresFromHostIfMatchIfModifiedSinceIfNoneMatchIfRangeIfUnmodifiedSinceKeepAliveLastModifiedMaxForwardsPragma



ProxyAuthorizationRangeRefererTeTrailerTransferEncodingTranslateUpgradeUserAgentViaWarning

Note: Enumerated values must be followed by an exclamation mark (!) when passed asmethod parameters.

HttpResponseHeaderType EnumerationThe HttpResponseHeaderType enumeration is used by the getHttpResponseHeader methodto specgify a header type and get its header value from an HTTP response message.

Enumerated values

The HttpResponseHeaderType enumeration supports the following header types:

AcceptRangesAgeAllowCacheControlConnectionContentEncodingContentLanguageContentLengthContentLocationContentMd5ContentRangeContentTypeDateETagExpiresKeepAliveLastModified



LocationPragmaProxyAuthenticateRetryAfterServerSetCookieTrailerTransferEncodingUpgradeVaryViaWarningWwwAuthenticate

Note: Enumerated values must be followed by an exclamation mark (!) when passed in amethod parameter.

ImpersonationLevel EnumerationThe ImpersonationLevel enumeration supplies identification values to a proxy server or a Webservice for a WCF client using integrated Windows or digest authentication.

Enumerated values

ImpersonationLevelvalue

Meaning

None An impersonation level is not assigned.

Anonymous The server process cannot impersonate the client and cannot obtainidentification information about the client.

Identification The server process cannot impersonate the client, but can obtainidentification and privileges information about the client. This allowsother services available on the server to use the client security contextfor access and validation decisions.

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

Delegation The server process can impersonate the client security context on localand remote systems.



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

Enumerated values

MessageCredentialType value Meaning



UserName Specifies client authentication using UserName


IssuedToken Specifies client authentication using an issued token

ProtectionLevel EnumerationThe ProtectionLevel enumeration provides the security service requested for an authenticatedstream. This enumeration is used by the TcpTransportSecurity class for NetTcpBindingbindings.

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 oftransmitted data

TcpClientCredentialType EnumerationThe TcpClientCredentialType enumeration provides the type of credential to use fortransport-level security when connecting to a Web service that uses the NetTcpBindingbinding.

Enumerated values

TcpClientCredentialType value Meaning





TcpClientCredentialType value Meaning


WCFBindingType EnumerationThe WCFBindingType enumeration defines the binding and communication formats to usewhen 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.0protocol. Uses HTTP for transport, and text/XML for messageencoding.

wsHttpBinding Suitable for communication with nonduplex Web services (serviceswithout a callback contract). Implements WS-Reliable Messagingand WS-Security protocols. Uses HTTP for transport, and text/XML for message encoding.

ws2007HttpBinding Binding that derives from the wsHttpBinding, but adds support forupdated versions of the ReliableSession, Security, andTransactionFlow binding elements.

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

ws2007FederationHttpBinding Binding that derives from the ws2007HttpBinding, but that alsosupports federated security.

NetTcpBinding Suitable for communication between WCF applications. UsesTransport Layer Security (TLS) over TCP for message transportsecurity, and supports duplex contracts.

NetNamedPipeBinding Binding that is similar to the NetTcpBinding binding, but onlysupports on-machine communication. Uses named pipes formessage delivery and binary message encoding.

NetMsmqBinding Suitable for WCF clients and services that communicate withMicrosoft Message Queuing (MSMQ) endpoints. By default usesMSMQ transport security.

WebHttpBinding Suitable for communication with services over the Web. UsesHTTP for transport, and supports text/XML and JavaScript ObjectNotation (JSON) message encodings.



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

WCFEndpointIdentity EnumerationThe WCFEndpointIdentity enumeration defines the identity to use with an endpoint forauthentication.

Enumerated values

WCFEndpointIdentityvalue

Meaning

None No identity is needed.

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

SPN Service Principal Name (SPN) is a name by which a client uniquelyidentifies a service instance. You can use this identity type with threedifferent 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 theuser separated by an arrobas (@) character. For example,[email protected].

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

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

CERTIFICATE Use the Certificate identity when a certificate is required forauthentication to the service endpoint. For the identity value, you mustspecify a Base64 encoded string representing the raw data of thecertificate.



WCFHMAC EnumerationThe WCFHMAC enumeration defines all supported encryption algorithms for theSoapHeader used in SOAP request messages from the WCF client.

Enumerated values

MessageCredentialType value Meaning

None No encryption is used

HMACMD5 Specifies the MD5 hash function

HMACRIPEMD160 Specifies the RIPEMD160 hash function

HMACSHA1 Specifies the SHA1 hash function




MACTRIPLEDES Specifies TripleDES for the input data

Note: The encrypt key must be specified in the SOAP header. If an encrypt key is not provided,PowerBuilder uses the default key. The default key combines the Web service method namewith the time stamp in the format “yyyy-MM-ddTHH:mm:ssZ”. For example, for theItemSearch method from Amazon.com that you call at 11:58:10AM (GMT) on April 27,2010, the default key is “ItemSearch2010-04-27T11:58:00Z”.

WebHttpSecurityMode EnumerationThe WebHttpSecurityMode enumeration defines security mode settings for a WCF clientusing 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 EnumerationThe wsSecurityMode enumeration defines security mode settings for a WCF client usingwsHttpBinding 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, andSOAP message security provides client authentication

WSTransferMode EnumerationUse the WSTransferMode enumeration to get or set a value indicating whether SOAP requestand 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

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.NET properties 90

Aaccelerator characters 72accelerator keys

assigning to menu items 38add-ins 47AddHttpRequestHeader method 166AddMessageHeaderItem method 166ADO.NET

sharing database connections 134Adobe Flash 5advantages of WPF applications 5Alt key

and menu items 38applications

MDI 27architecture 1area graphs

about 101making three-dimensional 106

arraysjagged 80returning in function or event 79runtime bounds creation 78System.Array type 80

Bbands

in DataWindow painter 117bar graphs


BasicHttpMessageCredentialType enumeration170

BasicHttpMessageSecurity class 142BasicHttpSecurity class 143BasicHttpSecurityMode enumeration 170BitLeft operators 80BitRight operators 80BMP files

adding to DataWindow objects 122bubble graphs 102

BubbleSize property 105Build Action property 68buttons

adding to DataWindow objects 126

CCertStoreLocation enumeration 171CertStoreName enumeration 171ClassName function 83ClientCertificateCredential class 143CLS (Common Language Specification) 77code snippets 66column graphs

about 101columns

adding to DataWindow objects 120named in DataWindow painter 119selecting in Select painter 114

Common Language SpecificationSee CLS

computed columns versus computed fields 124computed fields

adding to DataWindow objects 122defining custom buttons for 125

computed fields versus computed columns 124conditional compilation 8cone graphs 107constructors

parameterized 89continuous data, graphing 101controls in DataWindow objects

adding 120controls in windows

adding to window 27creating

enumerations 92, 93interfaces 83WCF Client Proxy projects 60WPF Window Application target 49

custom controlsabout 44adding to Toolbox 45in DataWindow objects 45WPF, adding to window objects 45

custom events 72

Index


Ddata source

SQL Select 112database

tracing connections 132Database painter 131

previewing data 132database profiles 131databases

accessing through SQL Select 112retrieving, presenting, and manipulating data

132DataWindow objects

about 109adding controls 120buttons, adding 126columns, adding 120computed fields, adding 122custom buttons that add computed fields 125drawing controls, adding 121graphs, adding 129group boxes, adding 122nesting reports 129presentation styles 111text, adding 121using 109

DataWindow painterworking in 116

declaringnamespaces 82

defaultsmenu item names 33

delegatesconsuming 94syntax example 94

deployment requirements.NET component targets 59WPF Application targets 5WPF Window Application targets 53

descendent menusbuilding 42

detail bandsin DataWindow painter 119

DirectX 5DISTINCT keyword 112document outline 15donut graphs


drawing controls, adding to DataWindow objects121

drop-down menusdeleting menu items 37

DSI Database Trace tool 132duplicating menu items 37

EEnumeration painter 23enumerations

BasicHttpMessageCredentialType 170BasicHttpSecurityMode 170CertStoreLocation 171CertStoreName 171creating 92, 93HttpClientCredentialType 172HttpProxyCredentialType 172HttpRequestHeaderType 173HttpResponseHeaderType 174ImpersonationLevel 175MessageCredentialType 176ProtectionLevel 176syntax 92TcpClientCredentialType 176WCFBindingType 177WCFEndpointIdentity 178WCFHMAC 179WebHttpSecurityMode 179wsSecurityMode 180WSTransferMode 180

errorscompile 67

event sequence 6events 89exporting ADO.NET connections 135

FFlowDirection property 70, 71footer bands, in DataWindow painter 119

GGAC (global assembly cache) 5generic classes

Index


syntax for consuming 96GetHttpResponseHeader method 168getters

.NET properties 90indexers 91

GIF files, adding to DataWindow objects 122global

enumerations 92global assembly cache

See GACGraph functions

SetBubbleSize 104graphic user interface

See GUIgraphics, adding to DataWindow objects 122graphs

about 99adding to DataWindow objects 129parts of 100types of 101unsupported properties 99

Grid styledetail band in 119

group box, adding to DataWindow objects 122GUI (graphic user interface) 9

Hheader bands, in DataWindow painter 118headings

in DataWindow objects 118Help

Visual Studio shell features 9HttpClientCredentialType enumeration 172HttpDigestCredential class 144HttpProxyCredentialType enumeration 172HttpRequestHeaderType enumeration 173HttpResponseHeaderType enumeration 174HttpTransportSecurity class 144hyphens (-) 36

IIDataWindowBase system interface 85IDataWindowChild system interface 85IDataWindowControl system interface 85IDataWindowStore system interface 85identifiers 65ImpersonationLevel enumeration 175

importing ADO.NET connections 136indexers 91inheritance

building menus with 42inheriting from .NET classes 87InnerControl property 66instances, menu 43IntelliSense

using 66Interface Painter 24interfaces

creating 24, 83implementing 84

IPicture system interface 85items

adding to menus 34–36

Jjagged arrays 80JPEG files

adding to DataWindow objects 122

Kkeyboard

using with menus 38keywords 65

LLabel style

detail band in 119line drawing controls 121line graphs


lines, in menus 36local

enumerations 93

MMDI applications

building 27using menus 28using sheets 28

MDI frames

Index


adding toolbars to 39opening sheets 28

MDI sheetsopening 28using menus with 28

MDI windows 6menu bars

about 29adding to windows 42deleting items 37

menu itemsabout 29deleting 37duplicating 37inserting 34navigating in 37properties 38renaming 37writing scripts for 42

Menu painteropening 33saving menus 37workspace 30

menusabout 29creating by inheriting 42creating new 33creating separation lines 36deleting menu items 37in MDI applications 28navigating in 37saving 37using inheritance with 42

MessageCredentialType enumeration 176MessageSecurityOverTcp class 145migrating

applications with RTL formatting 70

NN-Up style

detail band in 119NamedPipeTransportSecurity class 146names

of menu items 43names, of columns in DataWindow painter 119namespaces

declaring 82returning with class names 83

navigating in a menu 37

.NET assembly projects 97

.NET classesinheriting from 87returning namespace names 83syntax for inheriting from 87

.NET component target types 59

.NET delegatesconsuming 94syntax example 94

NetNamedPipeSecurity class 146NetTcpSecurity class 147New dialog box 21

creating a menu 33creating a window 25

New dialog box, customizing 22NoDualHttpMessageSecurity class 148NOT_IN_BETA2 65

Oopening

Menu painter 33Select painter 112Window painter 25

OpenSheet function 28operators

bitwise 80Options dialog box 18oval drawing controls 121

Ppainters in PowerBuilder .NET 22parameterized constructors 89PB Obect Outline 15PBWPF preprocessor symbol 8pictures

adding to DataWindow objects 122pictures, adding 122pie graphs


PNG filesadding to DataWindow objects 122

polymorphism 85pop-up menus

creating an instance of the menu 43displaying 43

PopMenu function 43

Index


Powerscriptunsupported properties and methods 73

PowerScript language enhancements 77preprocessor symbols 8presentation styles

of DataWindow objects 111Project painter 24properties

.NET 90of menu items 38window-level 26

Properties viewin Window painter 26

ProtectionLevel enumeration 176

Qqueries

saving 115

Rradar graphs 106rectangle drawing controls 121RemoveAllMessageHeaderItems method 168RemoveHttpRequestHeader method 169RemoveMessageHeaderItem method 169reports

presentation styles 111requirements

.NET component deployment 59runtime 5WPF application deployment 53

RightToLeft property 70RLE files

adding to DataWindow objects 122RoundRectangle drawing controls 121runtime

class library 3requirements 5

Ssaving

menus 37queries 115

scatter graphs 102Script view 63scripts

for menu items 42

Select painteropening 112selecting tables 113

selecting for SQL select 112semantic differences 4separation lines, in menus 36ServiceCertificateCredential class 149setters

.NET properties 90indexers 91

shortcut keysassigning to menu items 38

Skin property 68skins 68Solution Explorer 11source control 46SQL Select

selecting columns 114selecting tables 113using as data source 112

SQL statementsgenerating through SQL Select 112

stacked graphs 107Start page 9style

of windows 26summary bands, in DataWindow painter 119symbols for preprocessing 8system interfaces 85System Tree 11System.Object

inheritance from 81

TTabular style

detail band in 119target types 1, 49targets

.NET Assembly 55WPF Window Application 49

TcpClientCredentialType enumeration 176TcpTransportSecurity class 150text

in DataWindow objects 121of menu items 37

third-party controlsabout 44adding to Toolbox 45

Index


in DataWindow objects 45WPF, adding to window objects 45

three-dimensional graphsabout 106

toolbarsdesign time 17in MDI applications 39

Toolbox 14tooltips, adding to a DataWindow object 129tracing database connections 132

Uunderline(_) character

in menu items 38unsupported features in WPF applications 6user objects

about 44custom 44third-party 44

user-defined enumerations 92, 93UserNameCredential class 150

Vvisual controls 13Visual Studio 4

WWCF (Windows Communication Foundation) 59WCF Client

connection classes 142WCF Client Proxy projects

creating 60overview 59

WCFBasicHttpBinding class 151WCFBindingType enumeration 177WCFClientCredential class 153

WCFConnection class 154wcfConnection object 139WCFConnectionObject property 60WCFEndpointAddress class 156WCFEndpointIdentity class 156WCFEndpointIdentity enumeration 178WCFHMAC enumeration 179WCFnetNamedPipeBinding class 157WCFnetTCPBinding class 159WCFProxyServer class 160WCFReaderQuotas class 161WCFReliableSession class 162WCFSoapMessageHeader class 157WCFwsHttpBinding class 162WebHttpSecurityMode enumeration 179Window painter

opening 25properties 26

window scriptsdisplaying pop-up menus 43

windowscreating new 25using menus 42

Windows Communication FoundationSee WCF

WindowsCredential class 165workspace

in Menu painter 30WPF controls 13WPF Window Application target

creating 49wsHttpSecurity class 165wsSecurityMode enumeration 180WSTransferMode enumeration 180

XXAML editor 9

Index
