Welcome!

PowerBuilder Authors: Chris Pollach, Yeshim Deniz, Jayaram Krishnaswamy, Kevin Benedict, Avi Rosenthal

Related Topics: PowerBuilder

PowerBuilder: Article

Building the Executable, Pt. 1

Building the Executable, Pt. 1

This month I'll show you how to prepare a completed PowerBuilder application for deployment to users. PowerBuilder lets you develop and deploy applications for many application architectures. This month (and next) I'll try to help you make decisions about creating an executable and packaging an application for deployment in a client/server architecture.

Creating an executable is a matter of packaging the various pieces it needs in an appropriate manner. To get the kind of executable you want, you need to know how to choose the right pieces and the correct way of packaging them. Once you know how to do this, you can use the packaging tools provided by PowerBuilder to do the job. The following topics will be covered:

  • Project compiler basics
  • What can go in the deployment runtime libraries
Project Compiler Basics
When you plan on building an executable file, one of the first things to think about is which compiler format you want the application generated in. PowerBuilder gives you two choices: Pcode and machine code.

P-code
P-code (short for pseudocode) is an interpreted language that's supported on all PowerBuilder platforms. It's the same format that PowerBuilder uses in libraries (PBL files) to store individual objects in an executable state. Convenience and portability are two of the advantages of p-code. A minor disadvantage is that it tends to run a bit slower than machine code because it has to be interpreted at runtime.

Machine Code
PowerBuilder generates and compiles code to create a machine-code executable using a compiler supported on your computer platform. Because machine code is truly binary, the key advantage of machine code is speed of execution.

Do I Use P-code or Machine Code?
Here are a few considerations to help you decide which code is right for your executable. If you're looking for blinding execution speed, choose machine code. If your application has long scripts, many function calls or does a lot of math, it'll perform much better with machine code; however, it takes a long time to build. One major advantage p-code has over machine code is that it's much faster to generate. This makes it especially attractive to developers who want to quickly create an executable version of their application for testing. The files generated for p-code are much smaller than those generated for machine code. If your executable is to be deployed on computers where file size is a major issue, then you might decide to give up the speed of machine code and choose p-code instead. P-code can be useful for cross-platform applications. In fact, it's portable across every platform supported by PowerBuilder, including Windows (16-bit and 32-bit), Macintosh and UNIX. On the other hand, machine code is platform-specific: it requires you to generate and maintain complete versions of your executable application on each platform. However, you might still be willing to do this to ensure the best performance. Both p-code and machine code can be deployed on 32-bit or 16-bit platforms.

What Do I Need to Deploy?
No matter which compiler format you pick, an executable application created in PowerBuilder can consist of one or more of the following pieces:

  • An executable file
  • Dynamic libraries
  • Resources
To decide which of these pieces are required for your particular project, you need to know something about them.

The Executable File
You'll always create exactly one executable (EXE) file for any PowerBuilder client application you want to deploy. At minimum, this file contains code that enables your application to run as a native application on its target platform. This means, for example, when Windows or Macintosh users want to start your application, they can double-click the executable file's icon on their desktop. Try to keep an executable file smaller than 1.2 to 1.5 megabytes. If it approaches that size, consider using dynamic libraries.

What Can Go Into the Executable?
Depending on the packaging model you choose for your application, the executable file will also contain one or more of the following:

  • Compiled versions of objects from your application's libraries. You can choose to put all of your objects in the executable file (so you have to deliver only this file) or you can choose to split your application into one executable file and one or more dynamic libraries.
  • An execution library list that's used by the PowerBuilder execution system to find objects and resources in any dynamic library you've packaged for the application.
  • Resources, such as bitmaps and cursors, used by your application.
About Dynamic Libraries
As an alternative to putting your entire application in one large executable file, you can deliver some (or even all) of its objects in one or more dynamic libraries. The way PowerBuilder implements dynamic libraries depends on the compiler format you choose. If you're generating machine code, your dynamic libraries will be DLL files (dynamic link libraries) on Windows and shared (dynamic) libraries on Macintosh and UNIX. Machine-code dynamic libraries are given the extension .dll on Windows and UNIX. On the Macintosh, "lib" is appended to the name of the PBL. For example, the machine-code library built from test.pbl is named test.dll on Windows and UNIX, and testlib on the Macintosh. These dynamic libraries are like any other standard shared libraries in your operating environment. The only caveat is they're not intended to be called from external programs. In other words, they're not true DLL files.

PBD files (PowerBuilder dynamic libraries) are similar to DLLs because they're linked to your application at execution time. They're not interchangeable with DLLs because they have a different internal format. You can't mix the two different kinds of dynamic libraries (DLLs and PBDs) in one application. As with an executable file, only compiled versions of objects go into dynamic libraries (not their source).

What Can I Include in Dynamic Libraries?
Unlike your executable file, dynamic libraries don't include any start-up code. That's because they can't be executed independently. Instead, an executing application accesses them when it needs to provide required objects (if it can't find those objects in the executable file). However, dynamic libraries can include resources (such as bitmaps). In fact, you'll often want to put any resources needed by a dynamic library's objects in that DLL or PBD file. This makes the dynamic library a self-contained unit that can easily be reused (although if performance is your main concern, you'll find that resources are loaded faster at execution time when they're in the executable file).

There are several reasons why you might want to use dynamic libraries. First, they allow you to break up your application into smaller, more modular files that are easier to manage. They also enable you to deliver your application components separately. This means that when you need to provide users with an upgrade or bug fix, you don't have to redistribute the entire application - just give them the particular dynamic library that was affected. Furthermore, dynamic libraries make it possible for multiple applications to reuse the same components because they can be shared among applications as well as users. Moreover, they enable you to provide your application with objects that they reference dynamically at execution time only (such as a window object referenced only through a string variable). You're not allowed to put such objects in your executable file (unless they're DataWindow objects). Last of all, dynamic libraries can help a large application use memory efficiently since PowerBuilder doesn't load an entire dynamic library into memory at once. Instead, it loads individual objects from the dynamic library only when needed. Your executable file can remain small, making it less obtrusive and faster to load.

Once you decide to use a dynamic library, you need to tell PowerBuilder which library (PBL file) to create it from. PowerBuilder then places compiled versions of all objects from that PBL file into the DLL or PBD file. Suppose your application uses only some of those objects. In that case you might not want the dynamic library to include the superfluous ones since they'll just serve to make the file larger than it has to be. The solution is to:

  1. Create a new PBL file and copy just the objects you want into it.
  2. Use this new PBL file as the source of your dynamic library.

Resources
When you use resources, you need to deliver them as part of the application along with your PowerBuilder objects. A PowerBuilder application can employ several different kinds of resources. Here's a list of them, organized by the specific objects in which they might be needed:

  • Window and user objects
  • Icons (ICO files)
  • Pictures (BMP, RLE, PICT and WMF files)
  • Pointers (CUR files)
  • DataWindow objects
  • Menu objects (when in an MDI application)
Building the Executable
When deciding how to package the resources that need to accompany your application, you can include them in the executable file. Whenever you create an executable file, PowerBuilder automatically examines the objects it places in that file to see if they explicitly reference any resources (icons, pictures, pointers). It then copies all such resources into the executable file.

PowerBuilder doesn't automatically copy resources that are dynamically referenced (through string variables). To get such resources into the executable file, you must use a resource (PBR) file. This is simply a text file in which you list existing ICO, BMP, RLE, PICT, WMF and CUR files. Once you have a PBR file, you can tell PowerBuilder to read from it when creating the executable file to determine which additional resources to copy in. (This might even include resources used by the objects in your dynamic libraries if you decide to put most or all resources in the executable file for performance reasons.)

Put the Resources in Runtime Libraries
You may want to include resources in one or more dynamic libraries. However, PowerBuilder doesn't automatically copy any resources into a dynamic library that you ask to create (even if they're explicitly referenced by objects in that file). So you'll need to produce a PBR file that tells PowerBuilder which resources you want in this particular DLL or PBD file. Use a different PBR file for each dynamic library in which you want to include resources. (When appropriate, you can even use this approach to generate a dynamic library that contains only resources and no objects - simply start with an empty PBL file as the source.)

Deliver Them as Separate Files
When you deploy the application, give users various ICO, BMP, RLE, PICT, WMF and CUR files in addition to the application's executable file and any dynamic libraries. As long as you don't mind delivering a lot of files, this can be useful if you expect to revise some of them in the future.

Keep in mind that this is not the fastest approach at execution time because it requires more searching. Here's what happens: whenever your application needs a resource, it first searches the executable file. If the resource isn't there, it searches the dynamic libraries. If the resource isn't there, it finally searches for a separate file. Make sure your application can find where these separate files are stored; otherwise it won't display the corresponding resources. You can use one of these approaches or any combination of them when packaging a particular application.

Adding a Dynamically Allocated DataWindow to a Runtime Library
You may occasionally want to include a dynamically referenced DataWindow object (one that your application knows about only through a string variable) in the executable file that you're creating. To do this, you must list its name in a PBR file (along with the names of the resources you want PowerBuilder to copy into that executable file). You don't need to do this when creating a dynamic library because PowerBuilder will automatically include every DataWindow object from the source library (PBL file) in your new DLL or PBD file.

Conclusion
As you can see, you have many things to consider when it comes to packaging an executable version of an application. This month I covered the compiler basics as well as the use (or nonuse) of resource files. Next month we'll complete this build and cover executable deployment and testing.

More Stories By Bob Hendry

Bob Hendry is a PowerBuilder instructor for Envision Software Systems and a frequent speaker at national and international PowerBuilder conferences. He specializes in PFC development and has written two books on the subject, including Programming with the PFC 6.0.

Comments (0)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.