Distributing resources

You can choose to distribute your resources (pictures, pointers,
and icons) separately or include them in your executable file or
dynamic library.

Distributing resources separately

If a resource has not been included in the executable file
or in a dynamic library, when a resource is referenced at execution
time PowerBuilder looks in the search path for the resource (such
as the file FROWN.BMP). So you need to distribute the resources
with your application and make sure they get installed in the user’s
search path.

For example, assume you use two bitmap files as in the following
script:

You could distribute the files FROWN.BMP and SMILE.BMP with
your application. As long as the files are on the search path at
execution time, the application can load them when they are needed.

Windows search path

The Windows search path is as follows:

1. The current directory
2. The Windows directory
3. The Windows system directory
4. All directories in the PATH environment variable

UNIX search path

The UNIX search path is as follows:

1. The current directory
2. The user’s home directory
3. The directories in the user’s PATH environment
   variable

Using PowerBuilder resourcefiles

Instead of distributing resources separately, you can create
a PowerBuilder resource file (a PBR file) that lists all dynamically
assigned resources.

You can also include dynamically assigned DataWindow objects
in PBR files. PowerBuilder compiles the listed resources into the
executable file or a dynamic library file, so the resources are
available directly at execution time.

Using DataWindow objects If the objects in one PBL reference DataWindow objects, either
statically or dynamically, that are in a different PBL, you must
either specify a PowerBuilder resource file that includes the DataWindow
objects or define the library that includes them as a PBD or DLL
that you distribute with your application. You cannot distribute
them separately (as you can, for example, bitmaps and cursors).

To create and use a PowerBuilder resource file:

1. Using a text editor, create a text file
   that lists all resource files referenced dynamically in your application
   (see below for information about creating the file).

   When creating a resource file for a dynamic library, list all
   resources
   used by the dynamic library, not just those assigned dynamically
   in a script.

2. Specify the resource files in the Project painter.
   The executable file can have a resource file attached to it as can
   each of the dynamic libraries.

   When PowerBuilder builds the project, it includes all resources
   specified in the PBR file in the executable file or dynamic library.
   You no longer have to distribute your dynamically assigned resources
   separately; they are in the application.

Creating the PowerBuilder resource file

A PBR file is an ASCII text file in which you list resource
names (such as BMP, CUR, ICO, RLE, and WMF files) and DataWindow
objects. To create a PBR file, use a text editor. List the name
of each resource, one resource on each line, then save the list
as a file with the extension PBR. Here’s a sample PBR file:

Naming resources

If the resource file is in the current directory, you can
simply list the file, such as:

If the resource file is in a different directory, include
the path to the file, such as:

Paths in PBR files and scripts must match exactly The filename specified in the PBR file must exactly match
the way the resource is referenced in scripts.

If the reference in a script uses a path, you must specify
the same path in the PBR file. If the resource file is not qualified
with a path in the script, it must not be qualified in the PBR file.

For example, if the script reads:

then the PBR file must read:

If the PBR file says something like:

and the script doesn’t specify the path, PowerBuilder will
not find the resource at execution time. That is because PowerBuilder does
a simple string comparison at execution time. In the preceding example,
when PowerBuilder executes the script it will look for the object
identified by the string “FROWN.BMP” in the executable file. It
won’t find it, because the resource is identified in the
executable file as “C:MYAPPFROWN.BMP”.

In this case, the picture will not display at execution time;
the control will be empty in the window.

Including DataWindows
objects in a PBR file

To include a DataWindow object in the list, enter the name
of the library (with extension PBL) followed by the DataWindow object
name enclosed in parentheses. For example:

If the DataWindow library is not in the directory that is
current when the executable is built, fully qualify the reference
in the PBR file. For example:

What happens at execution time

When a resource such as a bitmap is referenced at execution
time, PowerBuilder first looks in the executable file for it. Failing
that, it looks in the PBDs that are defined for the application.
Failing that, it looks in directories in the search path for the
file.

---