What's New
Dev Tools
Site Map

PowerBuilder Starter

PowerBuilder is not the sort of language that is easily learned by playing around. It helps to take a formal course (or work through formal course notes) to climb the tool's comparatively steep learning curve. Afterwards, you should try to work with the tool under a more experienced "mentor" until you have a good grasp of the tool's workings. Realistically, expect at least a month of hard work before you are ready to tackle non-trivial PowerBuilder applications on your own.

The primer provided below should help you understand the basic PowerBuilder concepts. If you decide to try to "go it alone", you will find that a well written book on PowerBuilder is worth the $40-$60 investment as a reference source.

If you are not in the habit of using help extensively, you will need to get used to referring to help with PowerBuilder. There are a large number of functions, events and properties in PowerBuilder and you will need to look up their syntax and workings as you learn the language. Even experienced PB developers regularly refer to help to refresh their memories on less-frequently aspects of the tool.

1. Starting PowerBuilder Concepts and Terminology

PB Term Description VB Term
1.1 Structure    
Application An application is basically a list of libraries (or PBLs). This list is defined in the application object. The application object includes (or invokes) code that needs to be executed during application start up (e.g. connection to DB). Project
PowerBuilder Library (PBL) A PBL contains a group of PowerBuilder objects (windows, menus, datawindows, user objects). PBLs typically contain grouped functionally (e.g. one PBL for customer objects, one PBL for invoice objects, one or more "common" PBLs). Each PBL is stored as one Windows/DOS file – the objects within a PBL cannot be accessed or "seen" in File Manager/Explorer. PowerBuilder must be used to see the contents of a PBL. The application object is stored in what is called the "application" PBL. no real equiv.
Window A window includes its own variables, events and functions as well as its controls (along with events for those controls). Like other PowerBuilder objects, a window is stored in a PBL. Form
Menu A menu is a separate object which holds a group of menu items that appear at the top of a window – typically a separate menu is defined for each non-response window. Since a menu is separate from a window, a "base menu" can be defined to contain the common menu items used throughout the application and individual menus for windows can inherit from this base menu. a menu is part of a Form
Menu toolbar While defining each menu item in a menu, a corresponding toolbar icon can be identified. Toolbar - built up manually.
User Object (Visual and non-Visual) User objects can be created to encapsulate re-usuable functionality. A user object can be non-visual (and contain a group of functions) or it can be visual. A visual user object might contain a single control (e.g. command button) and include program logic in certain events. A visual user object might also a group of commonly re-used visual object (e.g. a DataWindow, OK button, Cancel button) which are frequently used together in the application. Modules (for non-visual functionality)
Variables - Variables can be local (declared in and available only to the script).
- instance variables are declared at the object level and they are available to the whole "object" (i.e. any script in window object, menu object or user object)
- variables can be declared as "global" in the application objects)
- variables can be public (available outside proc) or private (available only in module) or protected (available to module and its descendants)

- constants are also supported.

local variable

general form variable

global module variable
variables can be public, private only


1.2 Main Controls    
Text Place to enter static text. Label
Single Line Edit An input or edit field – must be manually populated from and saved to database. Text Box
Radio Buttons Offer a choice of exclusive options – only one button can be selected at a time. Radio Buttons
Checkbox Offers an on/off (or yes/no) option. Checkbox
DataWindow A DataWindow (unique to PB) can be thought of as a grouping of controls. These controls are typically retrieved in a single SQL Select and each column can be formatted in an appropriate manner (e.g. simple text, edit mask, drop down, date). Several styles of DataWindows can be used (e.g. freeform, grid, rich text, graph). The DataWindow provides several events to assist with the manipulation and validation of data. It will also automatically create any update SQL required when the user adds, updates, deletes DataWindow contents. no equiv.
Edit Mask, Display Format A datawindow column's edit mask predefines appearance of data during input (e.g. dash in phone number) while a format mask defines how the data appears after the user leaves the column (e.g. inserting dollar sign and numbers in a currency column). Edit Mask Control
GroupBoxes A groupbox can be used at the window-level to logically group controls (e.g. several radio buttons or single line edits). PowerBuilder 6 now also supports groupboxes within a DataWindow too. Frame
Command Button Standard command button with a clicked event. Escape and Enter can be made the default hot keys for the Cancel and OK buttons. PowerBuilder 6 now supports DataWindow-level command buttons too. Command Button
Drop down Listbox A drop down listbox contains a hard-coded list of predefined values which the user can select (the user may also type in their own value, if set appropriately). List Box
Drop down DataWindow A drop down DataWindow is like a drop down listbox except that its predefined values are populated from a SQL Select. It can be defined so the user can select a value or type one in or it can be defined so only predefined values can be selected. Combo Box
List Box Selectable (but not enterable) list of items. List Box
Progress Meter Shows user visual progress of an action (e.g. something like data movement that takes time to complete). Progress Bar Control
Timer function Starts events behind the scenes (based on desired interval in 1000ths of a second). Timer Event
Shapes lines, squares, etc. These are just visual – these don’t hold controls but they can be drawn around one or more controls, as needed. Shapes
Picture a container that can contain a picture. Picture Box
Microhelp Status bar at the bottom of window can show Microhelp. Menu items can define microhelp text to automatically appear. Microhelp can also be set programmatically. The PowerBuilder Foundation Classes (PFC) should be used if column-level microhelp is desired. Status Bar – more comprehensive than basic PB
Tab Control Control that holds multiple tab pages (commonly known example is the MS Excel options tab). Tab Control
Tree Control Control that shows a hierarchical representation of data (Windows 95/NT Explorer is an example of a tree).  
Rich Text Control Control that lets user enter text, including bold, italics, font size, font style, margins. Rich Text Control
Standard Windows Dialogs A number of standard Windows dialogs (Open File, Save File, Print Setup, Show Help) are invoked in PowerBuilder with PowerScript functions called GetFileOpenName, GetFileSaveName, PrintSetup, ShowHelp. Common Dialog Control
OLE Any OLE compliant object can be placed on a form (e.g. Word 6 to enter data, Excel spreadsheet, etc.). OLE
1.3 Major Events    
Open command
Open event
Open command creates an instance of a window. While the window is created, its open event fires. Window control's constructor events fire just before window open event. Load / Show
Close command
Close event
Close destroys an instance of a window, causing Close event. Unload / Terminate
CloseQuery This event fires just before the window close event and lets you stop the closing (Return 1), if needed -- e.g. if there are unsaved changes. Query Unload
Resize events Controls can be set as resizable. The resize events can be used to make related adjustments (e.g. resizing adjacent objects). Control Resizing
ItemChanged DataWindow ItemChanged is used to capture/check changes to a DataWindow column. LostFocus
Get Focus
Other important DW Events - EditChanged: fired on every keystroke
- Get Focus (when control receives focus)
Get Focus
1.4 Misc.    
Editor Colour-coded editor which syntax checks as code is entered. Errors are given when the script is saved/exited. Indentation (e.g. within IF statements) is automatic. Colour Editor, automatic indentation.
Getting at DataWindow Values GetItem and SetItem functions are used to programmatically get or set a value in a DataWindow. DataWindow object syntax is also available (e.g. dw_list..object.emp_name).  
DataWindow Row Selection The SelectRow function is used to select a row while GetSelectedRow gets the row number of the currently selected row. GetRow gets the row where the cursor currently is.  
Conversion functions Long/Int converts a string to a number
String converts a number to a string
Date converts a string to a date
Special Characters / Special Values ampersand " & " tells PB that a line is continued on next line
plus " + "tells PB to concat. strings
"//" indicates that the rest of the line is a comment
/ * … */ delineates a block (multi-line) comment

&, +
' - line comnt

2. PB How To (for non-trivial items)

PB Item How To
2.1 Structure  
Create an Application Choose File-New to create the application – type in the filename of the new application PBL (best if it corresponds to the application name). Next, specify the application name and press OK. PowerBuilder can create an automatic simple template for an application (including ancestor menus and windows) – this is a good idea when creating your own simple application but should be avoided for larger projects. Larger projects will generally want to build their own set of ancestors objects with appropriate names and customized content.

Next, choose properties to define the application icon and its default fonts. When you create new PBLs, return to the application object to add them to the application's library list.

Create a Window, Menu, User Object Choose the window icon on the toolbar. Windows and menus should be inherited from a base window or menu (use m_genapp_sheet for menus and w_genapp_sheet for window if you used PowerBuilder's automatically generated application).

When creating a window (or visual user object), items can be pasted onto the window by selecting the drop down visual object toolbar – this toolbar includes the various types of controls that can be added onto a visual object (e.g. DataWindow, tab control, etc.)
2.2 Controls  
Creating a DataWindow Press the DataWindow icon on the toolbar and choose new.

Step 1, Choose DW Style: Select the appropriate source and style (SQL Select and tabular or free form are good choices for beginners).

Step 2, Write SQL: PowerBuilder will try to help you build the SQL statement graphically, as follows:

- first choose the tables in the select

- next select the columns you want displayed in the DataWindow by clicking the column names

- finally, use the tabs at the bottom to define sort criteria, where criteria etc.

At any time after you have selected the tables, you can choose "Design-Convert to Syntax" to write raw SQL (and you can also change back to graphic mode later).

Press the SQL button to "finish" your SQL design. You can return later to the SQL and modify it by pressing the SQL button again.

Step 3, DataWindow Design: Now you can move around the columns on your screen (with drag and drop) and add colours/borders (using toolbars). You can also define detailed specifics for a column like edit mask, format, etc. To add these details, press "right mouse, properties" when mouse is over desired column.

DataWindows that take Parameters 1. To make a DataWindow take one or more parameters, go back to the DataWindow SQL (either graphic or text) and choose Design-Retrieval Arguments. PB will let you define as many arguments as you need – each with the appropriate data type.

2. When referring to the Retrieval arguments (typically in the Where clause), place a colon before the name (e.g. Where Customer.Cust_No = :cust)

2.3 Major Events  
Window Open Event In the window open event, you have to establish a connection between any DataWindow (except external ones) and the database. To do this, code the following in the window open event, if the DataWindow is named "dw_Detail":


In the open event, you will often retrieve the DataWindow and/or set initial values, as follows:

dw_Detail.Retrieve() // put any parameters inside parentheses

// set cust_count to zero on row 1
dw_Detail.SetItem(1,"cust_count", 0)

Command Button Logic Most command button logic is written in the clicked event – this code will execute when the user presses the button. For example, the Cancel button would be coded as follows, to close the window:


The Save button might be coded to save any changes on a DataWindow, as follows:


Events to trap when value in control has been changed (e.g. validation at control level). The DataWindow ItemChanged event is one good place to do field-specific validation. Any column whose value has actually changed will fire this event. "dwo.name" indicates the name of the column that changed. Sample validation code is shown below:
integer li_Return
CASE "this_code"
  IF data = "bad value" THEN
    MessageBox("Error","Invalid Code")
    li_Return = 1
CASE "another column"
  IF data = "another bad value" THEN
    MessageBox("Error","Invalid Value")
// If an error occurred, suppress unhelpful standard DW error message
IF li_Return = 1 THEN
  ib_SuppressMsg = True // declared instance variable

Returning 0 means it's OK and the user can proceed to the next column. Returning 1 will cause the user to stay in the same column to correct the error.

Returning 1 in ItemChanged will cause PB to display a default error message of its own (in addition to the one you just displayed above). To avoid this, ib_SupressMsg (an instance variable) is used and the ItemError event is coded as follows:

integer li_Return = 0
IF ib_SuppressMsg THEN
  li_Return = 1 // indicate error, but suppress default message
  ib_SuppressMsg = False
Return li_Return

A full sample of ItemChanged and ItemError events is provided on this site.

Copyright Woodger Computing Inc.