Users Guide

Appeon PowerBuilder® 2017 R3

FOR WINDOWS

DOCUMENT ID: DC00844-01-1700-01

LAST REVISED: July 25, 2018

Copyright © 2018 by Appeon Limited. All rights reserved.

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

Upgrades are provided only at regularly scheduled software release dates. No part of this publication may be reproduced, transmitted, or translated in any form or by any means, electronic, mechanical, manual, optical, or otherwise, without the prior written permission of Appeon Limited.

Appeon and other Appeon products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Appeon Limited.

SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP and SAP affiliate company.

Java and all Java-based marks are trademarks or registered trademarks of Oracle and/or its affiliates in the U.S. and other countries.

Unicode and the Unicode Logo are registered trademarks of Unicode, Inc.

All other company and product names mentioned may be trademarks of the respective companies with which they are associated.

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

Appeon Limited, 1/F, Shell Industrial Building, 12 Lee Chung Street, Chai Wan District, Hong Kong.


Table of Contents

The PowerBuilder Environment
Working with PowerBuilder
About PowerBuilder
Concepts and terms
Workspaces and targets
Objects
DataWindow objects
PowerBuilder libraries
Painters and editors
Events and scripts
Functions
Properties
Source control
PowerBuilder extensions
The PowerBuilder environment
The System Tree
The PowerBar
The Clip window
The Output window
Creating and opening workspaces
Creating a workspace
Opening a workspace
Using wizards
About wizards
Creating a target
Target types
Application targets
.NET targets
Managing workspaces
Adding an existing target to a workspace
Removing a target from a workspace
Specifying workspace properties
Building workspaces
In the development environment
From a command line
Working with tools
Using the To-Do List
Using the file editor
Using online help
Building an application
Customizing PowerBuilder
Starting PowerBuilder with an open workspace
Using options in the development environment
Using a workspace file
Using command line arguments
Changing default layouts
Arranging the System Tree, Output, and Clip windows
Using views in painters
Using toolbars
Toolbar basics
Drop-down toolbars
Controlling the display of toolbars
Moving toolbars using the mouse
Customizing toolbars
Creating new toolbars
Customizing keyboard shortcuts
Changing fonts
Defining colors
How the PowerBuilder environment is managed
About the registry
About the initialization file
Using Source Control
About source control systems
Using SVN or Git
Using source control manager via SCC API
Using PBNative
Constraints of a multi-user environment
Extension to the SCC API
Using SVN source control system
Add a workspace to SVN
Get a workspace from SVN
Commit objects to SVN
Get objects from SVN
Resolve conflicts
Revert changes
Refresh objects
Upload PBL
Lock objects
Show logs
Compare objects
View the connection settings
View the status of source-controlled objects
Using Git source control system
Add a workspace to Git
Get a workspace from Git
Commit objects to Git
Get objects from Git
Resolve conflicts
Revert changes
Refresh objects
Upload PBL
Show logs
Compare objects
View the connection settings
View the status of source-controlled objects
Using source control systems via SCC API
Using a source control system with PowerBuilder
Source control operations via SCC API in PowerBuilder
Initialization settings that affect source control
Modifying source-controlled targets and objects
Migrating existing projects under source control
Working with Targets
Working with Targets
About targets
Working in painters
Opening painters
Painter summary
Painter features
Views in painters that edit objects
About the Application painter
Specifying application properties
Specifying default text properties
Specifying an icon
Specifying default global objects
Writing application-level scripts
Setting application properties in scripts
Specifying target properties
Specifying the target's library search path
Importing .NET assemblies
Looking at an application's structure
Which objects are displayed
Working with objects
Creating new objects
Creating new objects using inheritance
Naming conventions
Opening existing objects
Running or previewing objects
Using the Source editor
Working with Libraries
About libraries
Using libraries
Organizing libraries
Opening the Library painter
About the Library painter
Working with libraries
Displaying libraries and objects
Using the pop-up menu
Controlling columns that display in the List view
Selecting objects
Filtering the display of objects
Creating and deleting libraries
Filtering the display of libraries and folders
Working in the current library
Opening and previewing objects
Copying, moving, and deleting objects
Setting the root
Moving back, forward, and up one level
Modifying comments
Searching targets, libraries, and objects
Optimizing libraries
Regenerating library entries
Rebuilding workspaces and targets
Migrating targets
Exporting and importing entries
Creating runtime libraries
Including additional resources
Creating reports on library contents
Creating library entry reports
Creating the library directory report
Coding Fundamentals
Writing Scripts
About the Script view
Opening Script views
Modifying Script view properties
Editing scripts
Limiting size of scripts
Printing scripts
Pasting information into scripts
Reverting to the unedited version of a script
Using AutoScript
Using the AutoScript pop-up window
Customizing AutoScript
Example
Getting context-sensitive Help
Compiling the script
Handling problems
Compiler Errors
Declaring variables and external functions
Working with User-Defined Functions
About user-defined functions
Deciding which kind you want
Defining user-defined functions
Opening a Prototype window to add a new function
Defining the access level
Defining a return type
Naming the function
Defining arguments
Defining a THROWS clause
Coding the function
Compiling and saving the function
Modifying user-defined functions
Using your functions
Working with User Events
About user events
User events and event IDs
Defining user events
Using a user event
Examples of user event scripts
Working with Structures
About structures
Deciding which kind you want
Defining structures
Modifying structures
Using structures
Referencing structures
Copying structures
Using structures with functions
Displaying and pasting structure information
Working with Windows
Working with Windows
About windows
Designing windows
Building windows
Types of windows
Main windows
Pop-up windows
Child windows
Response windows
MDI frames
About the Window painter
Building a new window
Creating a new window
Defining the window's properties
Adding controls
Adding nonvisual objects
Saving the window
Viewing your work
Previewing a window
Printing a window's definition
Writing scripts in windows
About events for windows and controls
About functions for windows and controls
About properties of windows and controls
Declaring instance variables
Examples of statements
Running a window
Using inheritance to build a window
Building two windows with similar definitions
Advantages of using inheritance
Instance variables in descendants
Control names in descendants
Working with Controls
About controls
Inserting controls in a window
Selecting controls
Defining a control's properties
Naming controls
About the default prefixes
Changing the name
Changing text
How text size is stored
Moving and resizing controls
Moving and resizing controls using the mouse
Moving and resizing controls using the keyboard
Aligning controls using the grid
Aligning controls with each other
Equalizing the space between controls
Equalizing the size of controls
Copying controls
Defining the tab order
Establishing the default tab order
Changing the window's tab order
Defining accelerator keys
Specifying accessibility of controls
Using the Visible property
Using the Enabled property
Choosing colors
Using the 3D look
Using the individual controls
CommandButton
PictureButton
CheckBox
RadioButton
StaticText
StaticHyperLink
Picture
PictureHyperLink
GroupBox
Drawing controls
SingleLineEdit and MultiLineEdit
EditMask
HScrollBar and VScrollBar
HTrackBar and VTrackBar
HProgressBar and VProgressBar
DropDownListBox
DropDownPictureListBox
ListBox
PictureListBox
ListView
TreeView
Tab
MonthCalendar
DatePicker
Animation
InkEdit and InkPicture
Understanding Inheritance
About inheritance
Creating new objects using inheritance
The inheritance hierarchy
Browsing the class hierarchy
Working with inherited objects
Using inherited scripts
Viewing inherited scripts
Extending a script
Overriding a script
Calling an ancestor script
Calling an ancestor function
Working with Menus and Toolbars
Menus and menu items
Using the Menu painter
Menu painter views
Menu styles
Building a new menu
Creating a new menu
Working with menu items
Saving the menu
Defining the appearance and behavior of menu items
Setting General properties for menu items
Setting menu style properties for contemporary menus
Setting menu item style properties
Providing toolbars
How toolbars work
Adding toolbars to a window
Selecting a toolbar style
Setting toolbar properties
Setting toolbar properties in the Window painter
Setting toolbar properties in the Application painter
Writing scripts for menu items
Menu item events
Using functions and variables
Referring to objects in your application
Using inheritance to build a menu
Using the inherited information
Inserting menu items in a descendant menu
Using menus in your applications
Adding a menu bar to a window
Displaying pop-up menus
Working with User Objects
About user objects
Class user objects
Visual user objects
Building user objects
About the User Object painter
Building a new user object
Creating a new user object
Building a custom class user object
Building a standard class user object
Building a custom visual user object
Building an external visual user object
Building a standard visual user object
Events in user objects
Saving a user object
Using inheritance to build user objects
Using the inherited information
Using user objects
Using visual user objects
Using class user objects
Using global standard class user objects
Communicating between a window and a user object
Examples of user object controls affecting a window
Working with Databases
Managing the Database
Working with database components
Managing databases
Using the Database painter
Modifying database preferences
Logging your work
Creating and deleting a SQL Anywhere database
Working with tables
Creating a new table from scratch
Creating a new table from an existing table
Specifying column definitions
Specifying table and column properties
Altering a table
Cutting, copying, and pasting columns
Closing a table
Dropping a table
Viewing pending SQL changes
Printing the table definition
Exporting table syntax
About system tables
Creating and editing temporary tables
Working with keys
Working with indexes
Working with database views
Manipulating data
Retrieving data
Modifying data
Sorting rows
Filtering rows
Viewing row information
Importing data
Printing data
Saving data
Creating and executing SQL statements
Building and executing SQL statements
Customizing the editor
Controlling access to the current database
Using the ASA MobiLink synchronization wizard
What the wizard generates
Wizard options
Trying out MobiLink synchronization
Managing MobiLink synchronization on the server
Starting the MobiLink synchronization server
Using SQL Central
Working with Data Pipelines
About data pipelines
Defining a data pipeline
Piping extended attributes
Creating a data pipeline
Modifying the data pipeline definition
Choosing a pipeline operation
Dependency of modifications on pipeline operation
When execution stops
Piping blob data
Changing the destination and source databases
Correcting pipeline errors
Saving a pipeline
Using an existing pipeline
Pipeline examples
Working with DataWindows
Defining DataWindow Objects
About DataWindow objects
DataWindow object examples
How to use DataWindow objects
Choosing a presentation style
Using the Tabular style
Using the Freeform style
Using the Grid style
Using the Label style
Using the N-Up style
Using the Group style
Using the Composite style
Using the Graph and Crosstab styles
Using the OLE 2.0 style
Using the RichText style
Using the TreeView style
Building a DataWindow object
Selecting a data source
Using Quick Select
Selecting a table
Selecting columns
Specifying sorting criteria
Specifying selection criteria
Using SQL Select
Selecting tables and views
Selecting columns
Displaying the underlying SQL statement
Joining tables
Using retrieval arguments
Specifying selection, sorting, and grouping criteria
Using Query
Using External
Using Stored Procedure
Using a Web service data source (Deprecated)
Using the OData Service (Deprecated)
Choosing DataWindow object-wide options
Generating and saving a DataWindow object
About the extended attribute system tables and DataWindow objects
Saving the DataWindow object
Modifying an existing DataWindow object
Defining queries
Previewing the query
Saving the query
Modifying a query
What's next
Enhancing DataWindow Objects
Working in the DataWindow painter
Understanding the DataWindow painter Design view
Using the DataWindow painter toolbars
Using the Properties view in the DataWindow painter
Selecting controls in the DataWindow painter
Resizing bands in the DataWindow painter Design view
Using zoom in the DataWindow painter
Undoing changes in the DataWindow painter
Using the Preview view of a DataWindow object
Retrieving data
Modifying data
Viewing row information
Importing data into a DataWindow object
Using print preview
Printing data
Working in a grid DataWindow object
Saving data in an external file
Saving the data as PDF
Saving the data in HTML Table format
Working with PSR files
Modifying general DataWindow object properties
Changing the DataWindow object style
Setting colors in a DataWindow object
Setting gradients and background pictures in a DataWindow object
Setting transparency properties for a DataWindow object
Specifying properties of a grid DataWindow object
Specifying pointers for a DataWindow object
Defining print specifications for a DataWindow object
Modifying text in a DataWindow object
Defining the tab order in a DataWindow object
Naming controls in a DataWindow object
Using borders in a DataWindow object
Specifying variable-height bands in a DataWindow object
Modifying the data source of a DataWindow object
Storing data in a DataWindow object using the Data view
What happens at runtime
Retrieving data
Prompting for retrieval criteria in a DataWindow object
Retrieving rows as needed
Saving retrieved rows to disk
Working with Controls in DataWindow Objects
Adding controls to a DataWindow object
Adding columns to a DataWindow object
Adding text to a DataWindow object
Adding drawing controls to a DataWindow object
Adding a group box to a DataWindow object
Adding pictures to a DataWindow object
Adding computed fields to a DataWindow object
Adding buttons to a DataWindow object
Adding graphs to a DataWindow object
Adding InkPicture controls to a DataWindow object
Adding OLE controls to a DataWindow object
Adding reports to a DataWindow object
Adding table blob controls to a DataWindow object
Adding tooltips to a DataWindow control
Reorganizing controls in a DataWindow object
Displaying boundaries for controls in a DataWindow object
Using the grid and the ruler in a DataWindow object
Deleting controls in a DataWindow object
Moving controls in a DataWindow object
Copying controls in a DataWindow object
Resizing controls in a DataWindow object
Aligning controls in a DataWindow object
Equalizing the space between controls in a DataWindow object
Equalizing the size of controls in a DataWindow object
Sliding controls to remove blank space in a DataWindow object
Positioning controls in a DataWindow object
Rotating controls in a DataWindow object
Controlling Updates in DataWindow objects
About controlling updates
What you can do
Specifying the table to update
Specifying the unique key columns
Specifying an identity column
Specifying updatable columns
Specifying the WHERE clause for update/delete
Specifying update when key is modified
Using stored procedures to update the database
Using a Web service to update the database (Deprecated)
Displaying and Validating Data
About displaying and validating data
Presenting the data
Validating data
About display formats
Working with display formats
Working with display formats in the Database painter
Working with display formats in the DataWindow painter
Defining display formats
Number display formats
String display formats
Date display formats
Time display formats
About edit styles
Working with edit styles
Working with edit styles in the Database painter
Working with edit styles in the DataWindow painter
Defining edit styles
The Edit edit style
The DropDownListBox edit style
The CheckBox edit style
The RadioButtons edit style
The EditMask edit style
The DropDownDataWindow edit style
The RichText edit style
The InkEdit edit style
Defining a code table
How code tables are implemented
How code tables are processed
Validating user input
About validation rules
Understanding validation rules
Working with validation rules
Defining validation rules
Defining a validation rule in the Database painter
Defining a validation rule in the DataWindow painter
How to maintain extended attributes
Filtering, Sorting, and Grouping Rows
Filtering rows
Sorting rows
Suppressing repeating values
Grouping rows
Using the Group presentation style
Defining groups in an existing DataWindow object
Highlighting Information in DataWindow Objects
Highlighting information
Modifying properties when designing
Modifying properties at runtime
Modifying properties conditionally at runtime
Example 1: creating a gray bar effect
Example 2: rotating controls
Example 3: highlighting rows of data
Example 4: changing the size and location of controls
Supplying property values
Background.Color
Border
Brush.Color
Brush.Hatch
Color
Font.Escapement (for rotating controls)
Font.Height
Font.Italic
Font.Strikethrough
Font.Underline
Font.Weight
Format
Height
Pen.Color
Pen.Style
Pen.Width
Pointer
Protect
Timer_Interval
Visible
Width
X
X1, X2
Y
Y1, Y2
Specifying colors
Using Nested Reports
About nested reports
Creating a report using the Composite presentation style
Placing a nested report in another report
Placing a related nested report in another report
Placing an unrelated nested report in another report
Working with nested reports
Adjusting nested report width and height
Changing a nested report from one report to another
Modifying the definition of a nested report
Adding another nested report to a composite report
Supplying retrieval arguments to relate a nested report to its base report
Specifying criteria to relate a nested report to its base report
Using options for nested reports
Working with Graphs
About graphs
Parts of a graph
Types of graphs
Using graphs in applications
Using graphs in DataWindow objects
Placing a graph in a DataWindow object
Using the graph's Properties view
Changing a graph's position and size
Associating data with a graph
Using the Graph presentation style
Defining a graph's properties
Using the General page in the graph's Properties view
Sorting data for series and categories
Specifying text properties for titles, labels, axes, and legends
Specifying overlap and spacing
Specifying axis properties
Specifying a pointer
Using graphs in windows
Working with Crosstabs
About crosstabs
Two types of crosstabs
Creating crosstabs
Associating data with a crosstab
Specifying the information
Viewing the crosstab
Specifying more than one row or column
Previewing crosstabs
Enhancing crosstabs
Specifying basic properties
Modifying the data associated with the crosstab
Changing the names used for the columns and rows
Defining summary statistics
Cross-tabulating ranges of values
Creating static crosstabs
Using property conditional expressions
Working with TreeViews
TreeView presentation style
Creating a new TreeView DataWindow
TreeView creation process
Creating a TreeView DataWindow
Adding and deleting TreeView levels
Selecting a tree node and navigating the tree
Sorting rows in a TreeView DataWindow
TreeView DataWindow Design view
Setting properties for the TreeView DataWindow
Setting general TreeView properties
Setting TreeView level properties
Setting detail band properties
TreeView DataWindow examples
Data Explorer sample
Data Linker sample
Exporting and Importing XML Data
About XML
Valid and well-formed XML documents
XML syntax
XML parsing
XML support in the DataWindow painter
The Export/Import Template view for XML
Creating templates
Saving templates
Header and Detail sections
Editing XML templates
XML declaration
Document type declaration
Root element
Controls
DataWindow expressions
Attributes
Composite and nested reports
CDATA sections
Comments
Processing instructions
Exporting to XML
Setting data export properties
Selecting templates at runtime
Importing XML
Importing with a template
Default data import
Tracing import
Working with Rich Text
About rich text
Using the RichText presentation style
Creating the DataWindow object
Formatting for RichText objects within the DataWindow object
Previewing and printing
Using the RichTextEdit control
Formatting keys and toolbars
Using OLE in a DataWindow Object
About using OLE in DataWindow objects
OLE objects and the OLE presentation style
Adding an OLE object to a DataWindow object
Using the OLE presentation style
Defining the OLE object
Specifying data for the OLE object
Previewing the DataWindow object
Activating and editing the OLE object
Changing the object in the control
Using OLE columns in a DataWindow object
Creating an OLE column
Running Your Application
Debugging and Running Applications
Overview of debugging and running applications
Debugging an application
Starting the debugger
Setting breakpoints
Running in debug mode
Examining an application at a breakpoint
Stepping through an application
Debugging windows opened as local variables
Just-in-time debugging
Using the DEBUG preprocessor symbol
Breaking into the debugger when an exception is thrown
Running an application
Running the application
Handling errors at runtime
Tracing and Profiling Applications
About tracing and profiling an application
Collecting trace information
Tracing an entire application in PowerBuilder
Using a window
Collecting trace information using PowerScript functions
Analyzing trace information using profiling tools
Profiling Class View
Profiling Routine View
Profiling Trace View
Setting call aggregation preferences
Analyzing trace information programmatically
Analyzing performance with a call graph model
Analyzing structure and flow using a trace tree model
Accessing trace data directly
Generating a trace file without timing information
Creating Executables and Components
About building PowerBuilder targets
Creating a project
Using the Project painter
Defining an executable application project
Using dynamic libraries
Attaching or embedding manifest files
Distributing resources
Distributing resources separately
Using PowerBuilder resource files
What happens at runtime
Tracing execution
Building an executable file and dynamic libraries
How PowerBuilder builds the project
How PowerBuilder searches for objects
Listing the objects in a project
Building proxies and .NET targets
Appendixes
The Extended Attribute System Tables
About the extended attribute system tables
The extended attribute system tables
Edit style types for the PBCatEdt table
CheckBox edit style (code 85)
RadioButton edit style (code 86)
DropDownListBox edit style (code 87)
DropDownDataWindow edit style (code 88)
Edit edit style (code 89)
Edit Mask edit style (code 90)
The OrcaScript Language
About OrcaScript
OrcaScript Commands
Usage notes for OrcaScript commands and parameters
Usage notes for OrcaScript commands with SVN/Git