|By Chris Pollach||
|July 1, 2004 12:00 AM EDT||
Maybe you have just downloaded the evaluation version of Pocket PowerBuilder (PPB) and are playing around with the sample applications. This may also be your first time trying to construct an application for your organization and perhaps you have never used the Sybase PowerBuilder product line before.
On the other hand, maybe you have a seasoned background in using PowerBuilder and this is your first time venturing into the Pocket PC world. Either way, the new Pocket PowerBuilder tool and PPC platform can present a challenging learning curve. You can jump-start your first application development project and tap into PPB's rich object-oriented features and data prowess by using the Software Tool & Die - Foundation Classes (STD-FC). This set of Base and Abstract prebuilt objects can be downloaded from Sybase's CodeXchange (www.codexchange.sybase.com). First-time visitors may have to acquire an account, but that's free and only takes a minute to set up.
Once you can log into CodeXchange, navigate to the "Pocket PowerBuilder" section and select the category "Foundation Classes." Within the Foundation Class area of the Web site are various entries. The most critical step here is to select the STD-FC version that matches your installed version of PPB. Each STD-FC version is written to exploit the features of its PPB counterpart. For the purposes of this article I'm going to refer to the latest production copy of PPB - version 1.5.1, build 385. If you're not sure of your PPB version, start the product and look at the lower right-hand side of your main IDE control dialog or check out the About dialog from the Help menu. Now that you know your PPB development version, download the appropriate STD-FC version. Note that you can also download a sample order entry application built from the STD-FCs as well. This will help developers who have previous PB knowledge and are familiar with its PFC Foundation Classes. This article though will take the novice or the PB developer who has never used the PFC through the basics.
After selecting the STD-FC for PPB 1.5.1 you should receive a compressed file named STD_FC_2004_04_14.zip. This file contains the STD-FC: a starter INI file, a text "Read Me" (features and changes) file, PPB "WorkSpace", PPB "Target", and, most important - a PKL library of reusable objects. I'll walk you through the construction of an Employee Information System (EIS) using the sample database that comes with PPB 1.5.1.
To get started let's allocate an "EIS" folder somewhere on your hard drive and then unzip the contents of the STD_FC_2004_04_14.zip file into that new folder. The STD-FC objects are located in the PPB library named STD_PPB_Base.pkl. Since you'll be adopting this as your application's base set of objects, first rename this to EIS_Base.pkl.
The first step in creating a new PPB application is to allocate a WorkSpace. Select the "New" button on the PPB main toolbar. From the next dialog choose the "WorkSpace" tab page and component and press "OK." Then navigate to your new EIS folder and enter "EIS" for the WorkSpace name and press "Save". You should now see an EIS WorkSpace listed in the PPB System Tree on your left-hand side. The second critical step is to allocate a target that will define the EIS application. Again, choose "New" on the PPB toolbar, and then select the "Target" tab page followed by the "Application" type of target (see Figure 1).
In the target information dialog enter ap_eis for the application name, then tab into the library name field. Edit the name to eis.pkl and tab into the target name field. Edit the target name to eis.pkt. Now press the "Finish" button to complete this step. You should now see a WorkSpace => Target => PPB library displayed in your system tree of the PPB IDE. We now need to add the STD-FC library to your new application's library list (remember we renamed that to EIS_Base.pkl). To do that, use the right-hand mouse button (RHMB) on the new EIS Target object and select "Properties". The target's property dialog has a tab page for the library list that includes a "Browse" button. Press "Browse" and select the base library, then press "OK". You should now see the EIS_Base.pkl added in your PPB IDE's System Tree (see Figure 2).
We now have the PPB IDE ready to start your new application development work and can begin to tap into the capabilities of the STD-FCs. The next section will address getting the basic framework started that will control all aspects of your application's flow and interaction with the business user.
To coordinate your application and control its various activities, the STD-FC includes an object known as the application controller (AC). This is a concept similar to the PB PFC's application manager. The AC needs to be the first object instantiated (loaded) and requires an INI control file. Let's get these two pieces ready to use and tested. The INI file is the easiest to build as the STD-FCs already provided you with a template called Application.ini. You should see that file in your EIS folder. Let's rename this to EIS.ini in keeping with the Employee Information System theme. Once you have done that, open the INI file and look at its contents (see Figure 3).
You'll observe some interesting points in this INI file. If you try and do a File=>SaveAs from the menu in NotePad, notice that the Encoding property is Unicode. This also corresponds to the first line of the INI file being "0xFEFF", which directs the PPC O/S to read/write to this file using Unicode standards. The last item I would direct you to is the "[System]" section that directs the application controller to check for PPC O/S, PPB, and ASA versions (or system-to-system) controls. This will guarantee that the runtime components you encounter on the deployed PPC match your current development software levels.
To incorporate the application controller into the new EIS application we need to first inherit (subclass) the object. In the PPB IDE's System Tree expand the EIS_Base.pkl library and locate the AC named "nc_app_controller_master". Using the RHMB choose the "Inherit" option from the resulting pop-up menu. Save your new AC (tailored for EIS) as nc_eis_app_controller (I use the prefix N: Nonvisual and C: Custom) in the EIS.pkl (your application library). You'll also notice that you are now in the PPB User Object Painter and on the right-hand side there's a properties pane with a list of protected variables. These variables will direct the ancestor code to use various features of the STD-FC components (see Figure 4).
We need to tailor a few property entries for the moment. The most important property is for the critical INI file to use at startup. Looking through the properties you should find the is_appl_ini_name variable. This is an instance variable of type string (hence the prefix IS that must be changed to EIS.ini, which is the name I asked you to assign to the original INI file you unzipped from the STD-FC download). For now, I don't wish any special dialogs to be used at startup, so I'll ask you to uncheck the ib_use_logon_window, ib_use_controller_window, and ib_use_splash_window variables. Save your work.
The AC object must be started from the application object. PPB created that object for you when you performed the target creation and, if you followed my naming suggestion, you should see the object ap_eis in the PPB System Tree. Double-click on that object now and this will open the Application Painter. Once you're there, look through the script pane and you should see a tab page named Declare Instance Variables. Activate this tab page and at the top of the pane you should see a dropdown list box (DDLB) called Instance Variables. Activate the DDLB and choose Global Variables. Type in the following statement as per Figure 5:
Next, we have to write a few lines of code in the application object to transfer control to the AC object at startup. Navigate to the open event in the script pane (see Figure 6) and type in the following:
go_ac = CREATE nc_eis_app_controller
go_ac.event oe_open (commandline)
For testing purposes to see if the STD-FC framework will start, you'll need to add two lines of code to your nc_eis_app_controller. This will be a message box command followed by a halt. The code will be added to the AC's oe_open event as follows:
MessageBox ("Hello", "World")
We can now test the EIS application framework by running the application. To do this, press the "Run" icon on the PPB toolbar. You should see the message shown in Figure 7.
The error in Figure 7 is caused by the AC not having information to complete the display name for the application. This will be used for various internal dialogs and system messages that are delivered to the application user. To correct this condition, open the AC and look through the properties for is_appl_display_name. Enter into this property: "Employee Information System," save the AC, and run the test again.
The next error you might receive is asking for a DataWindow (DW) title display name (see Figure 8).
- Where Are RIA Technologies Headed in 2008?
- PowerBuilder History - How Did It Evolve?
- Creation and Consumption of Web Services with PowerBuilder
- Cloud People: A Who's Who of Cloud Computing
- DDDW Tips and Tricks
- Cloud Expo 2011 East To Attract 10,000 Delegates and 200 Exhibitors
- Working with SOA & Web Services in PowerBuilder
- Dynamically Creating DataWindow Objects
- Cloud Expo, Inc. Announces Cloud Expo 2011 New York Venue
- OLE - Extending the Capabilities of PowerBuilder