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.
| 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 constants |
| 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) |
LostFocus 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 |
Val Str CDate |
| 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 |
_ &, + |
| 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": dw_Detail.SetTransObject(SQLCA) 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 |
| 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: Close(Parent) The Save button might be coded to save any changes on a DataWindow, as follows: dw_Detail.Update() |
| 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 CHOOSE CASE dwo.Name CASE "this_code"
IF data = "bad value" THEN
MessageBox("Error","Invalid Code")
li_Return = 1
END IF
CASE "another column"
IF data = "another bad value" THEN
MessageBox("Error","Invalid Value")
END IF
END CHOOSE // If an error occurred, suppress unhelpful standard DW error message IF li_Return = 1 THEN ib_SuppressMsg = True // declared instance variable END IF Return(li_Return) 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 END IF Return li_Return A full sample of ItemChanged and ItemError events is provided on this site. |