Creating an executable version of your application – PB Docs 70

Creating an executable version of your application

The next few sections tell you more about the packaging process
and provide information to help you make choices about the resulting
application. You’ll read about:

  • Compiler basics
  • What can go in the package
  • How to choose a packaging model
  • How to implement your packaging model
  • How to test the executable application you create

Compiler basics

When you plan an application, one of the fundamental topics
to think about is the compiler format in which you want that application
generated. PowerBuilder offers two alternatives: Pcode and machine


Pcode (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. Advantages of Pcode include its
convenience and its portability.

Machine code

PowerBuilder generates and compiles code to create a machine
code executable or dynamic library. The key advantage of machine
code is speed of execution.

On UNIX, PowerBuilder must have access to a
supported compiler to generate machine code. For information about
supported compilers, see the Installation Guide
the Release Notes.

Deciding which one to use

Here are some guidelines to help you decide whether Pcode
or machine code is right for your project:

  • Speed If your primary goal is to optimize execution speed and your application
    does intensive script processing, then choose machine code. It will
    perform better than Pcode if your code makes heavy use of looping constructs,
    floating point or integer arithmetic, and function calls.
    Pcode does have one speed advantage–it is faster
    to generate than machine code. That makes it especially handy when
    you want to quickly create an executable version of their application
    for testing.
  • Size The files generated for Pcode are smaller than those generated
    for machine code. If your application 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 Pcode instead.
  • Portability Pcode can be useful for cross-platform applications because it
    is portable. You can deploy the same PBD on any Windows or UNIX platform.
    However, you still need to generate the executable file on the target
    platform, and performance is usually better if you also generate PBDs
    on the target platform.
    Machine code is, of course, platform-specific. That means
    it requires you to generate and maintain complete versions of your
    executable application on each platform. But you may still be willing
    to do this to ensure the best performance.

Learning what can go in the package

matter which compiler format you pick, an application that you create
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.

About the executable file

If you are building a single- or two-tier application that
you will distribute to users as an executable file, rather than
as a server component or on the Internet, you will always create
an executable (EXE) file. If you are building a distributed PowerBuilder application,
you will create a client executable file and a server executable

At minimum, the executable file contains code that enables
your application to run as a native application on its target platform.
That means, for example, when users want to start your application,
they can double-click the executable file’s icon on their

What else can go in it 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
    You can choose to put all of your objects in the executable
    file (so that you have to deliver only this one file) or you can
    choose to split your application into one executable file and one
    or more dynamic libraries. More about that in just a moment.
  • An execution library list
    the PowerBuilder execution system uses to find objects and resources
    in any dynamic libraries you’ve packaged for the application
  • Resources
    that your application
    uses (such as bitmaps)


Size guidelines Try to keep an executable file smaller than 1.2 to 1.5 megabytes.
If it approaches that size, consider using dynamic libraries.

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 Your dynamic libraries will be
Machine code DLL files (dynamic link libraries) on
Windows and shared (dynamic) libraries on UNIXMachine-code dynamic libraries are given the extension .dll.
These dynamic libraries are like any other standard shared libraries
in your operating environment. The only caveat is that they aren’t
intended to be called from external programs
Pcode PBD files (PowerBuilder dynamic libraries)These dynamic libraries are similar to DLLs in that they are
linked to your application at execution time. But they are not interchangeable
with DLLs, because they have a different internal formatYou can’t mix the two different kinds of dynamic
libraries (DLLs and PBDs) in one application

As with an executable file, only compiled
of objects go into dynamic libraries (not their source):


What else can go in them Unlike your executable file, dynamic libraries don’t
include any startup code. That’s because they can’t
be executed independently. Instead, they are accessed as an application
executes when needed to provide objects the application requires
(if it can’t find those objects in the executable file).

But 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).


Why use them There are several reasons why you might want to use dynamic

Reason Details
Modularity They let you break up your application
into smaller, more modular files that are easier to manage
Maintainability They enable you to deliver your application
components separately. That means when you need to provide users
with an upgrade or bug fix, you don’t have to redistribute
the entire application–you can just give them the particular
dynamic library that was affected
Reusability They make it possible for multiple applications
to reuse the same components. That’s because dynamic libraries
can be shared among applications as well as among users
Flexibility They enable you to provide your application
with objects that it references only dynamically at execution time
(such as a window object referenced only through a string variable)You can’t put such objects in your executable file
(unless they are DataWindow objects)
Efficiency They can help a large application use
memory efficiently because:

  • 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
    faster to load and less obtrusive

Organizing them 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.

But suppose your application uses only some of those objects.
In that case, you may 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
  2. Use this new PBL file
    as the
    source of your dynamic library.

For further details on these steps, see the PowerBuilder User’s


About resources

In addition to PowerBuilder objects such as windows and menus,
applications also use various resources. Examples of resources include:

  • Bitmaps
    you might display in Picture or PictureButton controls
  • Custom pointers
    that you might
    assign to windows

When you use resources, you need to deliver them as part of
the application along with your PowerBuilder objects.

What kinds there are 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:

These objects Can use these kinds of resources
Window objects and user objects Icons (ICO files)Pictures (BMP, GIF, JPEG, RLE, and WMF files)Pointers (CUR files)
DataWindow objects Pictures (BMP, GIF, JPEG, RLE, and WMF
Menu objects (when in an MDI application) Pictures (BMP, GIF, JPEG, RLE, and WMF

Delivering them When deciding how to package the resources that need to accompany
your application, you can choose from the following approaches:

  • 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 right
    into the executable file.

    But PowerBuilder doesn’t automatically copy in 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, GIF, JPEG, RLE, 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.)

  • Include them in dynamic libraries

    You will often want to include resources right in one or more
    dynamic libraries. But PowerBuilder doesn’t automatically
    copy any resources into a dynamic library that you ask to create
    (even if they are explicitly referenced by objects in that file).
    So you 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

  • Deliver them as separate files

    This means that when you deploy the application, you’ll
    give users various image 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.

    But 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 next 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

You can use one of these approaches or any combination of
them when packaging a particular application.

note.gif Using a PBR file to include a dynamically referenced
DataWindow object
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 you’re creating.
To do that, you must list its name in a PBR file (along with the
names of the resources you want PowerBuilder to copy into that executable

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.

For more information on working with PBR files,
see the PowerBuilder User’s Guide

Choosing a packaging model

As you can see from reading the previous section, you have
a lot of options when it comes to packaging an executable version
of an application. To help you choose what’s best for your
project, here are several of the most common packaging models you
might consider.

A standalone executable file

In this model, you include everything (all objects and resources)
in the executable file. That means there’s just one file
to deliver.

Illustration Here’s a sample of what this model can look like:


Use This model is good for small, simple applications–especially
those you expect won’t need a lot of maintenance. For such
projects, it ensures the best performance and the easiest delivery.

An executable file and external resources

In this model, you include all objects and most resources
in the executable file. But you deliver separate files for particular

Illustration Here’s a sample of what this model can look like:


Use This model is also for small, simple applications. But it
differs from the preceding model in that it facilitates maintenance
of resources that are subject to change. In other words, it lets
you give users revised copies of specific resources without forcing
you to deliver a revised copy of the executable file.

You could also use this model to deal with resources that
must be shared by other applications or that are large and infrequently

An executable file and dynamic libraries

In this model, you split up your application into an executable
file and one or more dynamic library files (DLLs or PBDs). When
doing so, you can organize your objects and resources in various
ways, including these:

To organize You can
Objects Place them all in dynamic libraries so
that there are none in the executable file (which facilitates maintenance), or
Place a few of the most frequently accessed ones in the executable file
(to optimize access to them) and place all the rest in dynamic libraries
Resources Place most or all of them in dynamic
libraries along with the objects that use them (which facilitates
reuse), or
Place most or all of them in the executable file (to optimize
access to them)

Illustration Here’s a sample of what this model can look like:


Use This model is good for most substantial projects. That’s
because of the flexibility it gives you in organizing, delivering,
and maintaining your applications.

For instance, it enables you to make revisions to a particular
part of an application (in one dynamic library) and deliver that
revised dynamic library to users without disrupting the remainder
of the application. It also lets you deliver the same dynamic library
for use in multiple applications.

An executable file, dynamic libraries, and external

This model is just like the preceding one except that you
deliver separate files for particular resources (instead of including
all of them in your executable file and dynamic libraries).

Illustration Here’s a sample of what this model can look like:


Use This model is good for substantial applications, particularly
those that call for flexibility in handling certain resources. Such
flexibility may be needed if a resource:

  • Might have to be revised
  • Must be shared by other applications
  • Is large and infrequently used

Implementing your packaging model

When you have decided which is the appropriate packaging model
for your application, you can use the packaging facilities in PowerBuilder to
implement it. For the most part, this involves working in the Project
. You can use the Project painter
to build components, proxy libraries, and HTML files as well as
executable applications.

Using the Project painter for executable applications

The Project painter for executable applications orchestrates
all aspects of the packaging job by enabling you to:

  • Specify the executable

    to create
  • Specify any dynamic libraries
    or PBD files) to create
  • Specify the resources you want included
    the executable file or in each particular dynamic library (by using
    appropriate PBR files that indicate where to get those resources)
  • Choose machine code or Pcode
    the compiler format to generate
    With machine code, you can also specify a variety of code
    generation options (such as optimization, trace information, and
    error context information).
  • Choose build options
    , including
    whether you want the Project painter to do a full or incremental
    rebuild of your application’s objects when generating the
    executable application
  • Save all of these specifications as a project
    that you can use whenever necessary to rebuild
    the whole package

For more information on using the Project
painter, see the PowerBuilder User’s Guide

Building individual dynamic libraries

When revising an existing application, you
might want to deliver only those portions that have been changed–such
as a particular dynamic library (DLL or PBD file). In these cases,
your project object may do more than what you need. So instead,
you can use the Library painter to rebuild dynamic libraries from
their library (PBL) files on an individual basis.

Testing the executable application

Once you create the executable version of your application,
test how it runs before proceeding with delivery. You may have already
executed the application many times within the PowerBuilder development
environment, but it’s still very important to run the executable
version as an independent
the way end users will.

To do this, you:

  1. Leave PowerBuilder and
    go to your operating (windowing) environment.
  2. Make sure that the PowerBuilder deployment libraries
    are accessible to the application.
    You can do this by verifying that the location of the PowerBuilder
    virtual machine and other deployment files is in your PATH environment variable.
    On Windows, you could also create a shortcut and set the Start In property
    to the location of the deployment files or you could create a registry
    entry for the application that specifies the path.
  3. Run the application’s executable file as
    you run any native application.

Tracing the application’s execution

To help you track down problems, PowerBuilder provides tracing
and profiling
facilities that
you can use in the development environment and when running the
executable version of an application. Even if your application’s executable
is problem-free, you might consider using this facility to generate an
audit trail of its operation. For more information
on tracing execution, see the PowerBuilder User’s


Document get from Powerbuilder help
Thank you for watching.
Was this article helpful?
Notify of
Inline Feedbacks
View all comments
Would love your thoughts, please comment.x