Introduction to Pocket PowerBuilder

Introduction to Pocket PowerBuilderPocket PowerBuilder®1.0DOCUMENT ID: DC50059-01-0100-01LAST REVISED: July 2003Copyright © 2003 by Sybase, Inc. All rights reserved.This publication pertains to Sybase software and to any subsequent release until otherwise indicated in new editions or technical notes. Information in this document is subject to change without notice. The software described herein is furnished under a license agreement, and it may be used or copied only in accordance with the terms of that agreement.To order additional documents, U.S. and Canadian customers should call Customer Fulfillment at (800) 685-8225, fax (617) 229-9845.Customers in other countries with a U.S. license agreement may contact Customer Fulfillment via the above fax number. All other international customers should contact their Sybase subsidiary or local distributor. Upgrades are provided only at regularly scheduled software release dates. No part of this publication may be reproduced, transmitted, or translated in any form or by any means, electronic, mechanical, manual, optical, or otherwise, without the prior written permission of Sybase, Inc.Sybase, the Sybase logo, AccelaTrade, ADA Workbench, Adaptable Windowing Environment, Adaptive Component Architecture, Adaptive Server, Adaptive Server Anywhere, Adaptive Server Enterprise, Adaptive Server Enterprise Monitor, Adaptive Server Enterprise Replication, Adaptive Server Everywhere, Adaptive Server IQ, Adaptive Warehouse, Anywhere Studio, Application Manager, AppModeler, APT Workbench, APT-Build, APT-Edit, APT-Execute, APT-FORMS, APT-Translator, APT-Library, AvantGo, AvantGo Application Alerts, AvantGo Mobile Delivery, AvantGo Mobile Document Viewer, AvantGo Mobile Inspection, AvantGo Mobile Marketing Channel, AvantGo Mobile Pharma, AvantGo Mobile Sales, AvantGo Pylon, AvantGo Pylon Application Server, AvantGo Pylon Conduit, AvantGo Pylon PIM Server, AvantGo Pylon Pro, Backup Server, BizTracker, ClearConnect, Client-Library, Client Services, Convoy/DM, Copernicus, Data Pipeline, Data Workbench, DataArchitect, Database Analyzer, DataExpress, DataServer, DataWindow, DB-Library, dbQueue, Developers Workbench, Direct Connect Anywhere, DirectConnect, Distribution Director, e-ADK, E-Anywhere, e-Biz Integrator, E-Whatever, EC Gateway, ECMAP, ECRTP, eFulfillment Accelerator, Embedded SQL, EMS, Enterprise Application Studio, Enterprise Client/Server, Enterprise Connect, Enterprise Data Studio, Enterprise Manager, Enterprise SQL Server Manager, Enterprise Work Architecture, Enterprise Work Designer, Enterprise Work Modeler, eProcurement Accelerator, EWA, Financial Fusion, Financial Fusion Server, Gateway Manager, GlobalFIX, ImpactNow, Industry Warehouse Studio, InfoMaker, Information Anywhere, Information Everywhere, InformationConnect, InternetBuilder, iScript, Jaguar CTS, jConnect for JDBC, Mail Anywhere Studio, MainframeConnect, Maintenance Express, Manage Anywhere Studio, M-Business Channel, M-Business Network, M-Business Server, MDI Access Server, MDI Database Gateway, media.splash, MetaWorks, My AvantGo, My AvantGo Media Channel, My AvantGo Mobile Marketing, MySupport, Net-Gateway, Net-Library, New Era of Networks, ObjectConnect, ObjectCycle, OmniConnect, OmniSQL Access Module, OmniSQL Toolkit, Open Biz, Open Client, Open ClientConnect, Open Client/Server, Open Client/Server Interfaces, Open Gateway, Open Server, Open ServerConnect, Open Solutions, Optima++, PB-Gen, PC APT Execute, PC Net Library, Power++, power.stop, PowerAMC, PowerBuilder, PowerBuilder Foundation Class Library, PowerDesigner, PowerDimensions, PowerDynamo, PowerJ, PowerScript, PowerSite, PowerSocket, Powersoft, PowerStage, PowerStudio, PowerTips, Powersoft Portfolio, Powersoft Professional, PowerWare Desktop, PowerWare Enterprise, ProcessAnalyst, Rapport, Report Workbench, Report-Execute, Replication Agent, Replication Driver, Replication Server, Replication Server Manager, Replication Toolkit, Resource Manager, RW-DisplayLib, S-Designor, SDF, Secure SQL Server, Secure SQL Toolset, Security Guardian, SKILS, smart.partners, smart.parts, smart.script, SQL Advantage, SQL Anywhere, SQL Anywhere Studio, SQL Code Checker, SQL Debug, SQL Edit, SQL Edit/TPU, SQL Everywhere, SQL Modeler, SQL Remote, SQL Server, SQL Server Manager, SQL SMART, SQL Toolset, SQL Server/ CFT, SQL Server/DBM, SQL Server SNMP SubAgent, SQL Station, SQLJ, STEP, SupportNow, S.W.I.F.T. Message Format Libraries, Sybase Central, Sybase Client/Server Interfaces, Sybase Financial Server, Sybase Gateways, Sybase MPP, Sybase SQL Desktop, Sybase SQL Lifecycle, Sybase SQL Workgroup, Sybase User Workbench, SybaseWare, Syber Financial, SyberAssist, SyBooks, System 10, System 11, System XI (logo), SystemTools, Tabular Data Stream, TradeForce, Transact-SQL, Translation Toolkit, , UNIBOM, Unilib, Uninull, Unisep, Unistring, URK Runtime Kit for UniCode, Viewer, Visual Components, VisualSpeller, VisualWriter, VQL, WarehouseArchitect, Warehouse Control Center, Warehouse Studio, Warehouse WORKS, Watcom, Watcom SQL, Watcom SQL Server, Web Deployment Kit, Web.PB, Web.SQL, WebSights, WebViewer, WorkGroup SQL Server, XA-Library, XA-Server and XP Server are trademarks of Sybase, Inc. 03/03Unicode and the Unicode Logo are registered trademarks of Unicode, Inc.All other company and product names used herein may be trademarks or registered trademarks of their respective companies.Use, duplication, or disclosure by the government is subject to the restrictions set forth in subparagraph (c)(1)(ii) of DFARS 52.227-7013 for the DOD and as set forth in FAR 52.227-19(a)-(d) for civilian agencies.Sybase, Inc., One Sybase Drive, Dublin, CA 94568.ContentsAbout This Book (v)CHAPTER 1Working with Pocket PowerBuilder (9)About Pocket PowerBuilder (10)Concepts and terms (10)Workspaces and targets (10)Objects (11)DataWindow objects (11)Pocket PowerBuilder libraries (11)Painters and editors (12)Events and scripts (12)Functions (13)Properties (13)The Pocket PowerBuilder environment (13)The System Tree (14)The PowerBar (16)The Clip window (18)The Output window (18)Creating and opening workspaces (19)Creating a workspace (19)Opening a workspace (20)Using wizards (21)Creating a target (21)PowerScript application targets (22)Managing workspaces (24)Adding an existing target to a workspace (24)Removing a target from a workspace (25)Specifying workspace properties (25)Building workspaces (26)Working with tools (27)Using the To-Do List (28)Using the File Editor (30)Using online Help (30)Building an application (31)Introduction to Pocket PowerBuilder iiiContentsCHAPTER 2Customizing Pocket PowerBuilder (35)Starting Pocket PowerBuilder with an open workspace (35)Changing default layouts (36)Arranging the System Tree, Output, and Clip windows (37)Using views in painters (37)Using toolbars (42)Toolbar basics (42)Drop-down toolbars (43)Controlling the display of toolbars (43)Moving toolbars using the mouse (44)Customizing toolbars (45)Creating new toolbars (49)Customizing keyboard shortcuts (50)Changing fonts (51)Defining colors (52)Managing the Pocket PowerBuilder IDE (53)About the registry (53)About the initialization file (54)Index (57)iv Pocket PowerBuilderAbout This BookAudience This book is for anyone building applications with Pocket PowerBuilder®who is not already familiar with PowerBuilder®.How to use this book This book gives an overview of the Pocket PowerBuilder developmentenvironment. It provides an introduction to the Pocket PowerBuilder userinterface which allows you to create and deploy applications to asupported Windows CE device or emulator.Related documents Pocket PowerBuilder documentation The Pocket PowerBuilderUser’s Guide describes basic techniques for building the objects in aWindows CE application, including windows, menus, DataWindow®objects, and user-defined objects.The Resource Guide and Reference presents advanced programmingtechniques and database connection parameters for use with DataWindowobjects and Pocket PowerBuilder applications.PowerBuilder collection for Pocket PowerBuilder A supportingreference collection on the Sybase Technical Library CD includes severalbooks from the PowerBuilder9 documentation set. Many of the methodsand events described in the DataWindow Reference and PowerScriptReference in this collection are also valid for Pocket PowerBuilder. TheObjects and Controls book describes the system-defined objects inPowerBuilder and their default properties, functions, and events, many ofwhich are also relevant to Pocket PowerBuilder development.You can use the online Help to see whether specific PowerBuildermethods are applicable to Pocket PowerBuilder. For a description of thedifferences between these products, see Appendix B in the PocketPowerBuilder User’s Guide.Adaptive Server Anywhere® (ASA) documentation PocketPowerBuilder uses ODBC connections to ASA databases on Windows CEdevices. MobiLink is provided along with ASA to synchronize databaseson Windows CE devices with databases running on the desktop.Documentation for ASA and MobiLink is included in a separate collectionon the Pocket PowerBuilder Technical Library CD and in online Help. Introduction to Pocket PowerBuilder vWindows CE documentation If you do not have a basic familiarity with Windows CE devices, you might want to consult a book that describes these devices.Other sources of information Use the Sybase Getting Started CD, the Sybase Technical Library CD and the Technical Library Product Manuals Web site to learn more about your product: •The Getting Started CD contains release bulletins and installation guides in PDF format, and may also contain other documents or updatedinformation not included on the Technical Library CD. It is included with your software. To read or print documents on the Getting Started CD you need Adobe Acrobat Reader (downloadable at no charge from the Adobe Web site, using a link provided on the CD).•The Technical Library CD contains product manuals and is included with your software. The DynaText reader (included on the Technical Library CD) allows you to access technical information about your product in an easy-to-use format.Refer to the Technical Library Installation Guide in your documentation package for instructions on installing and starting the Technical Library.•The Technical Library Product Manuals Web site is an HTML version of the Technical Library CD that you can access using a standard Webbrowser. In addition to product manuals, you will find links toEBFs/Updates, Technical Documents, Case Management, Solved Cases, newsgroups, and the Sybase Developer Network.To access the Technical Library Product Manuals Web site, go to Product Manuals at /support/manuals/.Sybase EBFs andsoftware updates❖Finding the latest information on EBFs and software updates1Point your Web browser to the Sybase Support Page at/support.2Select EBFs/Updates. Enter user name and password information, ifprompted (for existing Web accounts) or create a new account (a freeservice).3Select a product.4Specify a time frame and click Go.5Click the Info icon to display the EBF/Update report, or click the productdescription to download the software.vi Pocket PowerBuilderAbout This BookConventions The formatting conventions used in this manual are:Formatting example To indicateRetrieve and Update When used in descriptive text, this font indicates:•Command, function, and method names•Datatypes such as integer and char•Database column names such as emp_id andf_name•User-defined objects such as dw_emp orw_mainvariable or file name When used in descriptive text and syntaxdescriptions, oblique font indicates:•Variables, such as myCounter•Parts of input text that must be supplied, such aspblname.pbd•File and path namesFile>Save Menu names and menu items are displayed in plaintext. The greater than symbol (>) shows you howto navigate menu selections. For example,File>Save indicates “select Save from the Filemenu.”dw_1.Update()Monospace font indicates:•Information that you enter in a dialog box or ona command line•Sample script fragments•Sample output fragmentsIf you need help Each Sybase installation that has purchased a support contract has one or moredesignated people who are authorized to contact Sybase Technical Support. Ifyou cannot resolve a problem using the manuals or online help, please have thedesignated person contact Sybase Technical Support or the Sybase subsidiaryin your area.Introduction to Pocket PowerBuilder viiviii Pocket PowerBuilderIntroduction to Pocket PowerBuilder 9C H A P T E R 1Working with PocketPowerBuilderAbout this chapterThis chapter describes the basics of working in the Pocket PowerBuilder integrated development environment (IDE).Contents Before you begin The Pocket PowerBuilder IDE is very similar to the PowerBuilder IDE.Wizards, tools, and application development features in PocketPowerBuilder are based on the same or similar features in PowerBuilder. For this reason, reference documentation for PowerBuilder is included on the Technical Library CD that ships with Pocket PowerBuilder.About the PowerBuilder Collection for Pocket PowerBuilder A number of objects, methods, events, and properties listed in thePowerBuilder documentation do not apply to Pocket PowerBuilder or the Windows CE environment. You can use the online Help to see if methods are applicable to Pocket PowerBuilder. For other differences between PowerBuilder and Pocket PowerBuilder, see the Appendix B in the Pocket PowerBuilder User’s Guide .TopicPage About Pocket PowerBuilder10Concepts and terms10The Pocket PowerBuilder environment13Creating and opening workspaces19Using wizards21Creating a target21Managing workspaces24Building workspaces26Working with tools27Using online Help30Building an application 31About Pocket PowerBuilder10 Pocket PowerBuilder About Pocket PowerBuilderPocket PowerBuilder is a smart-client application development tool for the Windows CE platform. It enables developers to build handheld applications in an object-centric, graphical, desktop environment, then deploy the same applications to a supported Pocket PC device or emulator. Standard visual controls—such as buttons, check boxes, drop-down lists, and edit controls—as well as special custom controls, make your applications easy to develop and easy to use.Database applications Pocket PowerBuilder brings powerful data access and sophistication toWindows CE devices with features that include the DataWindow and tight integration with Adaptive Server Anywhere. Built-in support for MobiLink enables bidirectional data synchronization to heterogeneous enterprise systems.For information describing MobiLink support in Pocket PowerBuilder, see the MobiLink.PDF file in the Pocket PowerBuilder collection on the Sybase Product Manuals Web site at /support/manuals/.Extending PowerBuilder applications Because the Pocket PowerBuilder IDE is similar to that of PowerBuilder, developers can leverage their existing PowerBuilder skills, reusing knowledgeand expertise to build and deploy new mobile applications. By using Pocket PowerBuilder, you can extend PowerBuilder applications to handheld devices, saving time, and reusing code.Concepts and termsThis section discusses some basic concepts and terms you need to be familiar with before you start using Pocket PowerBuilder to develop applications and components.Workspaces and targetsIn Pocket PowerBuilder, you work with one or more targets in a workspace. You can add as many targets to the workspace as you want, open and edit objects in multiple targets, and build and deploy multiple targets at once.CHAPTER 1 Working with Pocket PowerBuilderA Pocket PowerBuilder target is also referred to as a PowerScript target.Pocket PowerBuilder targets have PKT extensions to differentiate them fromPowerScript targets in PowerBuilder, which have PBT extensions.PowerBuilder Web and JSP targets are not supported in Pocket PowerBuilder.For more information about creating a workspace and targets, see “Creatingand opening workspaces” on page 19 and “Creating a target” on page 21.ObjectsA Pocket PowerBuilder application is a collection of objects. PocketPowerBuilder provides many types of objects, including visual objects such aswindows, menus, buttons, and graph controls, and nonvisual objects such asthe datastore, exception, and timing objects.As you work to develop a Pocket PowerBuilder application, you create newobjects and open and modify existing objects.For more information about creating, opening, and editing objects, see thesection “Working with Objects” in the Pocket PowerBuilder User’s Guide.DataWindow objectsThe applications you build are often centered around your organization’s data.With Pocket PowerBuilder you can define DataWindow objects to retrieve,display, and manipulate data. For more information about DataWindowobjects, see the part “Working with Databases and DataWindows” in thePocket PowerBuilder User’s GuidePocket PowerBuilder librariesAs you work in a target, the objects you create are stored in one or morelibraries (PKL files) associated with the application. PKL files are similar toPBL files associated with PowerBuilder applications. When you run yourapplication, Pocket PowerBuilder retrieves the objects from the library.Pocket PowerBuilder provides a Library painter for managing your libraries.For information about creating a new library and working with libraries in theLibrary painter, see the chapter “Working with Libraries” in the PocketPowerBuilder User’s Guide.Concepts and termsPainters and editorsThe editors you use to edit objects are called painters. For example, you builda window in the Window painter. There you define the properties of thewindow, add controls such as buttons and labels, and code the window and itscontrols to work as your application requires.Pocket PowerBuilder provides painters for windows, menus, DataWindowobjects, visual and nonvisual user-defined objects, functions, structures,databases, and the application itself. For each of these object types, there is alsoa Source editor in which you can modify code directly. See the sections“Working in painters” and “Using the Source editor” in the PocketPowerBuilder User’s Guide.There is also a file editor you can use to edit any file without leaving thedevelopment environment. See “Using the File Editor” on page 30.Events and scriptsPocket PowerBuilder applications are event driven: users of the PocketPowerBuilder applications you develop can control the flow of the applicationsby the actions they take. When a user clicks a button, chooses an item from amenu, or enters data into a text box, an event is triggered. You write scripts thatspecify the processing that should happen when events are triggered.For example, buttons have a Clicked event. You write a script for a button'sClicked event that specifies what happens when the user clicks the button.Similarly, edit controls have a Modified event, that is triggered each time theuser changes a value in the control.You write scripts in Pocket PowerBuilder using PowerScript, anobject-oriented scripting language. You can type, drag and drop, or paste scriptin a Script view of the painter for the object you are working on. Scripts consistof PowerScript functions, expressions, and statements that perform actions, ordata and text processing, in response to an event.The script for a button's Clicked event might retrieve and display informationfrom the database; the script for an edit control's Modified event might evaluatethe data and perform processing based on the data.Scripts can also trigger events. For example, the script for a button’s Clickedevent might open a new window that triggers, in turn, the Open event in thatwindow.CHAPTER 1 Working with Pocket PowerBuilderFunctionsPowerScript provides a rich assortment of built-in functions you use to actupon the objects and controls in your application. There are functions to opena window, close a window, enable a button, retrieve data, update a database,and so on.You can also build your own functions to define processing unique to yourapplication.PropertiesAll the objects and controls in a PowerScript target have properties, many ofwhich you set as you develop an application. For example, you specify a labelfor a button by setting its text property. You can set these properties in paintersor set and modify them dynamically in scripts.The Pocket PowerBuilder environmentWhen you start Pocket PowerBuilder for the first time, the Welcome to PocketPowerBuilder dialog box lets you create a new workspace with or withouttargets.Figure 1-1: The Welcome to Pocket PowerBuilder dialog boxThe Pocket PowerBuilder environmentWhen Pocket PowerBuilder starts, it opens in a window that contains the menubar and the toolbar (PowerBar) at the top, the System Tree and Clip window onthe left, and the Output window at the bottom. The remaining area is for thedisplay of painters and editors that you open when you start working withobjects.The System TreeThe System Tree provides an active resource of programming information thatyou use while developing targets. It lets you not only get information, but alsodrag objects into painter views (such as the Script view or Layout view) forimmediate use.Displaying or hiding the System Tree The System Tree displays by default when you start Pocket PowerBuilder for the first time. You can hide or display the System Tree by using the System Tree button on the PowerBar or by selecting Window>System Tree.In Pocket PowerBuilder, the System Tree has a single Workspace tab page that displays the current workspace and all its targets. PowerScript targets display the library list for the target and all the objects in each PKL. The Workspace page works like a tree view in the Pocket PowerBuilder Library painter, but you can keep it open all the time to serve as the control center of the development environment. It also displays properties, functions, events, structures, and controls, duplicating features in the Pocket PowerBuilder Browser.Setting the root in the System Tree You can set the root of the Workspace page to your computer’s root directory, the current selection, or any directory or library, as well as to the current workspace. The same capability is available in the Library painter.Working with targetsTo access the pop-up menu that lets you perform operations on a target such as search, build, and migrate, you must set the root of the System Tree or the view in the Library painter to the current workspace.The following illustration shows a couple of PowerScript targets, including one that lists multiple libraries in its search path.CHAPTER 1 Working with Pocket PowerBuilder Figure 1-2: Workspace tab in the System TreeYou can use the System Tree as the hub of your Pocket PowerBuilder session. Pop-up menus let you build and deploy targets, and open and edit any object. The following table lists the actions you can take from the pop-up menu that displays for each item in the System Tree. You can also set properties for each item, choose which object types display in the tree view, change the root of the Workspace page, and reset the root to the current workspace.Table 1-1: Action items for objects in the System TreeItem Menu action itemsWorkspace (PKW)New (opens New dialog box), Add Target, OpenWorkspace, Incremental Build, Full Build, Deploy,Debug, Run, Close, Show, Properties.PowerScript target (PKT)New, Search, Incremental Build, Full Build, Migrate, Deploy, Debug, Run, Remove Target, Show, Properties.Pocket PowerBuilder library (PKL)Delete, Search, Optimize, Print Directory, Build Runtime Library, Import, Show, Properties.Pocket PowerBuilder object Edit, Edit Source, Copy, Move, Delete, Export, Regenerate, Search, Print, Properties.Edit Source is not available for project objects. Inherit and Run/Preview are available only for some object types.The Pocket PowerBuilder environment The PowerBarDefault PowerBar buttons Like the System Tree, the PowerBar provides a main control point for building Pocket PowerBuilder applications. From the PowerBar you can create new objects and applications, open existing objects, and debug and run the current application.Figure 1-3: Default PowerBar buttonsWhen you start using Pocket PowerBuilder, you can display a label on each button in a toolbar to remind you of its purpose. To do so, right-click a toolbar button and select Show Text from the pop-up menu.Table 1-2: PowerBar buttons and their usesThis PowerBarbutton Lets you do thisNew Create new objects.Inherit Create new windows, user objects, and menus by inheriting froman existing object.Open Open existing objects.Run/Preview Run windows or preview DataWindows.System Tree Work in the System Tree window, which can serve as the hub ofyour development session.Output Window Examine the output of a variety of operations (migration, builds,deployment, project execution, object saves, and searches). See“The Output window” on page 18.Next Error,Previous ErrorNavigate through the Output window.To-Do List Keep track of development tasks you need to do for the currentapplication and use links to get you quickly to the place whereyou complete the tasks.Browser View information about system objects and objects in yourapplication, such as their properties, events, functions, and globalvariables, and copy, export, or print the information.Clip Window Store objects or code you use frequently. You can drag or copyitems to the Clip window to be saved and then drag or copy theseitems to the appropriate painter view when you want to use them.See “The Clip window” on page 18.Library Manage your libraries using the Library painter.DB Profile Define and use named sets of parameters to connect to aparticular database.CHAPTER 1 Working with Pocket PowerBuilderCustomizing the PowerBar You can customize the PowerBar. For example, you can choose whether tomove the PowerBar around, add buttons for operations you perform frequently, and display text in the buttons.For more information, see “Using toolbars” on page 42.About PowerTips In the PowerBar, when you leave the mouse pointer over a button for a secondor two, Pocket PowerBuilder displays a brief description of the button, called a PowerTip. PowerTips display in Pocket PowerBuilder wherever there are toolbar buttons.Database Maintain databases and database tables, control user access todatabases, and manipulate data in databases using the Databasepainter.Edit Edit text files (such as source, resource, and initialization files)in the file editor.WinCE EmulationOpens the Pocket PC 2000 emulator.WinCE 2002 EmulationOpens the Pocket PC 2002 emulator.IncrementalBuild WorkspaceUpdate all the targets and objects in the workspace that have changed since the last build.Full BuildWorkspaceUpdate all the targets and objects in the workspace.DeployWorkspaceDeploy all the targets in the workspace.Skip Interrupt a build, deploy, or search operation. When a series ofoperations is in progress, such as a full deploy of the workspace,the Skip button lets you jump to the next operation.Stop Cancel all build, deploy, or search operations.Debug Debug the last target you ran or debugged. You can setbreakpoints and watch expressions, step through your code,examine and change variables during execution, and view thecall stack and objects in memory.Select & Debug Select a target and open the Debugger.Run Run the last target you ran or debugged just as your users wouldrun it.Select & Run Select a target and run it.ExitClose Pocket PowerBuilder.This PowerBarbutton Lets you do this。