PowerBuilder Migration Steps
\The Sandbox \PB Help \PB Migration \Migration Steps
a Target
Migration Steps

The following is a list of steps to follow when migrating. It is not published by Sybase. This is my own list, as developed with the PowerBuilder community over the years through the peer-to-peer support newsgroups. It includes both migration-specific steps and steps that should be done on a regular basis during a development project. In this list, these terms will be defined as follows:

    Source version: The application source and the corresponding version of PowerBuilder before the migration.

    Target version: The application source and the corresponding version of PowerBuilder that is the final destination.

This list includes high level descriptions of procedures to follow. The actual steps to implement many of these procedures has changed over the history of PowerBuilder. It is expected that the user of this guide is able to use the manuals for their source or target versions to get specific instructions on how to perform standard procedures.


The importance of this step cannot be underemphasized. While this is listed as the first step, it should be done repeatedly throughout the process. While it is important for reasons that backups are typically important, it is also important in the migration process for these reasons:

  • Migration affects all objects. If something should go wrong, such as an invalid installation of PowerBuilder, the corruption of all your application code is conceivable.
  • Often, problems identified after migration are more easily fixed in the source version and the source re-migrated.
  • Back-migration is not natively possible. After migration, the application code becomes incompatible with the source version of PowerBuilder. If you ever find a need to move back to a previous version of PowerBuilder (e.g. after 3 months, you discover a major client is on an operating system that is no longer supported), it will likely be less effort to revert to this pre-migration backup and apply any code changes to the source version.

Install Target Software

While people seem to worry about installing more than one major version of PowerBuilder on a system at any given time, there are no publicly known issues in doing so. The inclusion of the major PowerBuilder version number in the naming convention of most PowerBuilder DLLs prevents most issues. (This does not allow multiple maintenance releases from the same major version with the standard configuration, but an end user has shared an alternate configuration that allows multiple maintenance version installation.) Personally, I’ve had 3-4 major versions of PowerBuilder installed at any given time on my primary systems over the last 10 years.

This is also the point that any maintenance releases and Emergency Bug Fixes (EBF) patches should be applied to reach your target version. Not only is it not necessary to migrate to an x.0.0 version if that is not your target, but it is counterproductive to identify and resolve bugs that are fixed in your target version.

It is worth pointing out that migration to intermediate major versions of PowerBuilder is similarly unnecessary. For example, if you are migrating from PowerBuilder 7 to PowerBuilder 9, there is no need, and in fact it is useless, to migrate to PowerBuilder 8.

Before doing anything in the target IDE, it is worth confirming the configuration of the installed version of PowerBuilder. While this won’t be an issue in a typical situation, if a badly behaved application built with PowerBuilder has installed conflicting PowerBuilder DLLs on the system path, it could cause problems for your IDE (see the Troubleshooting Guide for more details). The best way to confirm your PowerBuilder configuration is to load the IDE, then check which DLLs are loaded with Process Explorer, a free tool from SysInternals. If the DLLs are the expected versions and are being loaded from the expected location (typically Program Files\Sybase\Shared\PowerBuilder), then you are in good shape.

Read the Warnings

Your target version of PowerBuilder comes with ReadMe’s and Release Notes. They provide warnings of potential migration issues, so they are very much worth reading. In fact, given that the Release Notes are available online, it would be wise to read these before choosing a target version.

Store Library Path

If your source version of PowerBuilder does not use targets, go to the application properties dialog and copy the Library Path out to a text file. If you don’t have duplicate objects (same name and object type, different PBLs), this won’t be anything more than a convenience for developers by replicating their environment more closely in the target version. If there are duplicate objects, your application’s behaviour may change if the Library Path is changed so that a different object is picked up in PowerBuilder’s object search algorithm, which simply uses the first object of matching name and type that it finds in the Library Path. (If you do have duplicates or are not sure, PBL Peeper will help you identify them and compare them in preparation for deleting all but one. In general, having duplicate objects is bad practice.)

If your source version of PowerBuilder uses targets, this target file, which includes the Library Path, will simply be reused by the target version.


Optimization is advertised as being a tool for reducing PBL size and defragmenting the objects for better performance. However, optimization provides an additional benefit. Failed imports of object source can leave source loaded in the PBL, but without a directory entry in the PBL object directory. While you can’t see this object source, the PowerBuilder object search algorithm does. This can cause unusual and undiagnosable errors. This makes optimization of PBLs a good practice as part of development, a recommended step in troubleshooting, and an essential first step in migration. Enough things can change during a migration that a previously dormant problem with “orphaned” objects can surface. So, in the source environment, optimize the PBLs. If the optimization process prompts you that it has found source without an entry, continue with the prompts to delete it, exporting it if you see fit.

Migration Assistant

In recent versions of PowerBuilder, Sybase has provided a Migration Assistant tool to help identify potential problems that may arise in a migration, such as calls to deprecated functions. Running the Migration Assistant at this stage is recommended, as fixing problems in the source version is much easier than fixing them after migration in the target version. Objects that fail to compile cannot be opened in painters, although PowerBuilder versions that provide Edit Source can edit them in the IDE. In recent versions of PowerBuilder, the Migration Assistant has been hidden under the File / New / Tools dialog. Open the Migration Assistant in the target version, point it at your source PBLs, and let it read them and report on them. The report may contain both critical errors and messages that are just warnings. Once you receive the report from the Migration Assistant, it is between you, the Migration Assistant and the manuals to determine the severity of the messages and whether they need to be fixed immediately.

Full Build

After the migration, the first thing you want to look for is new messages. You cannot do this if you don’t know what messages your application produced originally. To provide a point of comparison, you want to do a full build of your application in the source version. To provide a complete comparison, you want to turn on Information and Obsolete messages, options that are often turned off for typical development. If this Full Build produces any messages, save them somewhere. You may want to choose to deal with these messages in the source version. While non-critical messages like duplicate objects may not cause a problem in a stable environment, it may be easier to resolve these issues before migration than to potentially troubleshoot them after.

Framework Upgrade

This step is applicable is you use a framework like PowerBuilder Foundation Classes (PFC). If there is a version specific to your target version of PowerBuilder, you need to choose if you want to apply that upgrade now. If you want to make all your foundational changes to your application at once so that one testing sweep will cover all your upgrades, this is the time to substitute in the upgraded libraries and follow any other upgrade steps the framework may suggest. My personal advice is to follow the scientific method of experiments, and allow only one variable at a time. That way, if testing identifies a change in behaviour, you won’t have to identify if the cause is the framework change or a PowerBuilder change. Frameworks are nothing more than PowerBuilder objects with PowerScript code, and should migrate just as well as any other code you have written.


You backed up again before starting this step?

In a perfect world, this is the only step you need to do to migrate your application. The above steps prepare you in case you don’t live in such a world.


Fix Errors

In that perfect world, the migration process produced a list that falls under one of the following three categories:

  • no errors were reported
  • errors reported matched exactly the list of errors produced in the source version
  • the only differences between the list of errors reported by the source version and the target version were Information and Obsolete messages which, after careful consideration, you’ve decided don’t need to be addressed immediately

If your list doesn’t fall into the above three categories (in my experience migrating applications for my customers, most times they do), you have some fixing to do before running the application. Fixing can either be done in the source version or the target version.

If you do your fixing in the source version, you obviously need to repeat the migration process. For source version fixing, you’ll have to decide which of the above safety steps you want to repeat, although backing up is highly recommended.

If you choose to fix in the target version, you need to be aware that any objects that did not compile successfully can’t be opened in standard painters. In target versions previous to PowerBuilder 8, you will have to export the object to a text file, edit the text file, and import the fixed file back into the PBL. In PowerBuilder 8 and forward, the context menu for the object (right click in most cases) will have an Edit Source option, where you can open the source in a text editor directly, and the Save button for the editor will compile the object directly back into the PBL. If fixing in the target version, a Full Build is recommend when you think you are finished, to check for any additional errors that may not have been caught because of the previous errors. (This step is not necessary if fixing in the source version, as the migration process includes a Full Build.)


In 90% of the migrations I’ve been through, the above steps produce no problems. If any problems come up in the migration, it’s the final step of testing the application where the problems arise. With the above procedure, you’ve avoided many of the truly difficult problems. Now, you need to test for changed behaviour. Since the foundation of your application has been altered, a full test of your application is highly recommended. You may identify changes relating to the documented changes in PowerBuilder behaviour, and having read the Release Notes, you’ll be prepared to identify those changes. You may identify undocumented changes in PowerBuilder behaviour, which have caused changes in your application. More likely than this last possibility, based on my experience, you’ll find bad programming that happened to work one way in your source version of PowerBuilder, and now behaves another way in your target version of PowerBuilder. My experience is that this last category is both most common and most difficult to diagnose.

This is not to say that you should expect problems at this stage. A well written application can migrate without problems. (This is not to say that a well written application won’t run into problems, nor that a successful migration implies the application is well written. Just that well written applications have better probabilities of only having problems with documented areas of change.) However, a good developer needs to be skeptical of things running smoothly, so that problems can be identified at a stage when the problem is manageable, as opposed to when the problem will cost the business significantly.

PBL Peeper PB Help PB History
& Future About Us Feedback Site Map

Web www.techno-kitten.com