Before we start, let’s make one thing very clear. PowerBuilder and Sybase only support forward migrations. The following suggestions are hacks, heavily dependent on third party tools, that get you there if you absolutely have to get there. You should also consider some of the issues presented in Choosing a Target. There are several factors that will make your life more difficult after a backward migration. If you think this is a black-and-white issue for you, then you’re missing something.
Backward migrations are not recommended for avoiding bugs in PowerBuilder, unless you have specifically identified the bug afflicting you and have verified that it doesn’t exist in your target version of PowerBuilder. To deal with bugs, see the Troubleshooting Guide first.
Approach 1: Use Your Safety Net
If you made a backup before migration in the version of PowerBuilder you want to migrate back to, this is your best starting point. By far, it will be easier for you to identify your changes and apply them to your backup. While PBL Peeper can show differences in a rudimentary document-based view, PBDelta provides a significantly more robust user interface, also providing a merge functionality. At the time of this writing, neither PBL Peeper nor PBDelta are capable of comparing across the PB9-ANSI-DBCS and PB10-Unicode divide, although a PBDelta release managing this is imminent.
Approach 2: Create from Nothingness
If you have no backup, you’re going to have to create empty PBLs in your target PowerBuilder version and start populating them. To the casual observer that hasn’t done this before, the concepts seem simple and the effort seems trivial. As someone who has performed several backward migrations, let me assure you the effort is not as trivial as it appears on the surface.
Throughout this description, I’ll be describing how using PowerGen will benefit you. A Google of my site or my newsgroup postings will show my advocacy of PowerGen is not in short supply. Let me assure you that this advice is not monetarily motivated. I receive no compensation from E Crane. My motivation for recommending PowerGen stems from my desire to see you succeed in your PowerBuilder projects, in the most economical fashion possible. The more PowerBuilder project that succeed, the more chance I have to continue my career in PowerBuilder. While there may be alternative approaches, they require time (a commodity too often undervalued when making plans like these) and are prone to error (a problem too often underestimated in terms of cost).
Step 1: Export everything
The first step is to export all the objects from all the PBLs in your source version of the application. As you probably want to reproduce your PBL structure in your target environment, make sure you track which objects belong to which PBL. Having a separate folder for each PBL is the easiest way.
Exporting objects from the Library Painter or the System Tree is the manual approach. This can be done one PBL at a time. Exporting the entire application can be done with a “single button” with PowerGen. Beware of using other tools for this task, including PBL Peeper. Both LibraryExport() in PowerScript and ORCA have “issues” exporting OLE objects’ binary data. Losing this from your objects would render the OLE classes useless. PowerGen is known to have addressed this issue.
Step 2: Convert files
This is a required only if your version conversion crosses boundaries between ANSI (PB7 and previous), ANSI/DBCS (PB8-9) and Unicode (PB10+) support. Export files will need to be converted to a text format that your target version of PowerBuilder can support. (I have yet to experiment with text conversion of a file with an OLE binary portion. I’d expect the binary portion would be corrupted.) I have successfully used TextPad to convert files from Unicode to ANSI.
Step 3: Remove or replace incompatible code
Identifying code that is incompatible is no small feat. You may be able to identify this on your own. However, it is more likely that for many required changes you won’t be able to identify the incompatible code until you’ve done a test import. There are two categories of code that you will need to remove or replace:
Code you added
Unless you are back migrating immediately after forward migrating (and if this is the case, you need to be sent for decisiveness training... well, maybe that’s too harsh), you’ve probably done some development in the later version of PowerBuilder. Code you may have changed since you migrated may not be compatible with your target version. Unless this code is linked to functionality you are willing to remove, this is the area you will more likely need to replace code. Things to watch include:
- new control types, object types, classes, etc...
- new functions
- new parameters to functions
- new enumerated data types
Code PowerBuilder added
Being a 4GL, PowerBuilder generates a lot of code for you “under the hood.” When you look at exports, you can see this code. Typically, the majority of generated code that you need to adjust when backward migrating is in DataWindows. New functionality needs to be supported by new data for the DataWindow that is stored in the DataWindow object.
Historically, PowerBuilder does not change your code or generated code in migration. (PowerBuilder 10 has created a few exceptions to the rule.) Changes to generated code usually happens when the object is saved from a painter after migration. When PowerBuilder saves a DataWindow, it saves the same data related to the same element types over and over again. For example, every DataWindow saved under PowerBuilder 10 will have an export.xhtml section added to its syntax. This makes having a tool that does search and replace across multiple files valuable, especially if it handles regular expressions. Again in this regard, TextPad has served me well.
Step 4: Import objects
To those of us that have imported objects using PowerBuilder during the course of regular development, this sounds simple. Click on an export file and push a button. Nothing could be further from the truth, with one possible exception. The catch is that most of your objects refer to other objects. If those referenced objects aren’t imported yet, your import will fail.
If you insist on doing this through PowerBuilder, you will probably go through the following cycle several times for each object:
- Import the object
- Note the compilation failures
- Fix syntactical issues
- Comment out references to objects not yet imported
- Note the point of the commenting so you can go back and remove it later
- Go back to the top and repeat, likely finding new errors, as the compiler will be able to compile more of the code
- When you finally succeed, find any commented out references to this object, go to those referencing objects and uncomment the code
I’ve done this approach, and it takes longer than I expected, and induced more frustration than any other development activity I can recall.
If you do this through PowerGen, this is little more than creating a mapping file of folders to PBLs, and pressing a Bootstrap Import button. PowerGen isn’t magic, and is bound to the rules the above process thrashes with, but it solves these problems with a much more intelligent, multipass approach, where “empty” objects are imported and the syntax is built up until the full syntax is imported on the final pass. You’ll most likely have to repeat this process, going back to remove or replace incompatible code, but you’ll have a report of many more issues to deal with at once than you would importing an object at a time.
Step 5: Add the hidden data
For some reason, PowerBuilder doesn’t store the application’s icon file name in the exported source. (No, this doesn’t make sense, especially from a source control point of view. This is a serious flaw, IMHO.) You’ll have to go into the application painter and add it yourself.
Step 6: Test like your reputation depends on it
You’ve performed major surgery on your code, largely on the free advice you picked up on a site about PowerBuilder and cats. Think about it. Free advice is often worth what you pay for it. So, before you contact a single person outside of your office walls, make a commitment to test your application thoroughly.