When you upgrade to a new version of PowerBuilder, your existing targets need to be upgraded to the new version. Typically, when you open a workspace that contains targets that need to be upgraded, or add a target that needs to be upgraded to your workspace, PowerBuilder prompts you to upgrade the targets. However, there are some situations when you need to upgrade a target manually. For example, if you add a library that has not been upgraded to a target's library list, you will not be able to open objects in that library until the target has been upgraded.
You cannot upgraded a target that is not in your current workspace and you must set the root of the System Tree or the view in the Library painter to the current workspace.
Before you upgrade
There are some steps you should take before you upgrade a target:
-
Use the Migration Assistant to check for obsolete syntax or the use of reserved words in your code
-
Check the release notes for migration issues
-
Make backup copies of the target and libraries
-
Make sure that the libraries you will upgrade are writable (not read-only)
Always back up your PBLs before upgrading
Make sure you make a copy of your PBLs before upgrading. After migration, you cannot open them in an earlier version of PowerBuilder.
The Migration Assistant is available on the Tool page of the New dialog box. For help using the Migration Assistant, click the Help (?) button in the upper-right corner of the window and click the field you need help with, or click the field and press F1. If the Migration Assistant finds obsolete code, you can fix it in an earlier version of PowerBuilder to avoid errors when you upgrade to the current version.
PowerBuilder libraries and migration
PowerBuilder libraries (PBLs) contain a header, source code for the objects in the PBL, and binary code. There are two differences between PowerBuilder 10 and later PBLs and PBLs developed in earlier versions of PowerBuilder:
-
The source code in PowerBuilder 10 and later PBLs is encoded in Unicode (UTF-16LE, where LE stands for little endian) instead of DBCS (versions 7, 8, and 9) or ANSI (version 6 and earlier).
-
The format of the header lets PowerBuilder determine whether it uses Unicode encoding. The header format for PowerBuilder 10 is the same as that used for PUL files in PowerBuilder 6.5 and for PKL files in PocketBuilder. These files do not need to be converted to Unicode when they are upgraded to PowerBuilder 10 or later.
When PBLs are upgraded
Before opening a PBL, PowerBuilder checks its header to determine whether or not it uses Unicode encoding. PBLs are not converted to Unicode unless you specifically request that they be upgraded.
You cannot expand the icon for a PBL from PowerBuilder 9 or earlier in the Library painter. To examine its contents, you must upgrade it to PowerBuilder 10 or later.
When you attempt to open a workspace that contains targets from a previous release in PowerBuilder, the Targets to be Migrated dialog box displays. You can upgrade targets from this dialog box, or clear the No Prompting check box to open the Migrate Application dialog box.
PowerBuilder dynamic libraries and migration
If you plan to reference a PowerBuilder dynamic library (PBD) that was created in an earlier version of PowerBuilder, you must regenerate the PBD file in the new version of PB IDE, and then migrate the application.
For example, if your application contains a base.pbd file, you should generate a new base.pbd file from the base.pbl file and replace the old base.pbd with the new base.pbd before migrating the application.
For information on creating PBDs, see Creating runtime libraries.
PFC and migration
If your application uses the PFC framework from an earlier version of PowerBuilder, you must upgrade the PFC framework and make sure the PFC version matches the PowerBuilder version.
The PFC is now available at https://github.com/OpenSourcePFCLibraries.
The Migrate Application dialog box
The Migrate Application dialog box lists each PBL that will be upgraded and lets you choose the type of messages that display during the migration process.
If you click OK, each PBL is first upgraded to the new version of PowerBuilder. If necessary, PowerBuilder converts source code from DBCS to Unicode. PowerBuilder performs a full build and saves the source code back to the same PBL files. Changes to scripts display in informational messages in the Output window and are written to a log file for each PBL so that you can examine the changes later. Recommended changes are also written to the log file.
Migration from DBCS versions
The migration process automatically converts multibyte strings in DBCS applications to unicode strings. You do not need to select the Automatically Convert DBCS String Manipulation Functions check box for this conversion. If the migration encounters an invalid multibyte string, it sets the invalid string to a question mark and reports the error status. You can modify question marks in the Unicode output string after the migration.
The following two lines from a log file indicate that the FromAnsi function is obsolete and was replaced with the String function, and that an encoding parameter should be added to an existing instance of the String function:
2006/01/27 08:20:11 test.pbl(w_main).cb_1.clicked.4: Information C0205: Function 'FromAnsi' is replaced with function 'String'. 2006/01/27 08:20:11 test.pbl(w_main).cb_2.clicked.4: Information C0206: Append extra argument 'EncodingAnsi!' to function 'String' for backward compatibility.
The log file has the same name as the PBL with the string _mig appended and the extension .log and is created in the same directory as the PBL. If no changes are made, PowerBuilder creates an empty log file. If the PBL is upgraded more than once, output is appended to the existing file.
PowerBuilder makes the following changes:
-
The FromUnicode function is replaced with the String function and the second argument EncodingUTF16LE! is added
-
The ToUnicode function is replaced with the Blob function and the second argument EncodingUTF16LE! is added
-
The FromAnsi function is replaced with the String function and the second argument EncodingAnsi! is added
-
The ToAnsi function is replaced with the Blob function and the second argument EncodingAnsi! is added
-
An Alias For clause with the following format is appended to declarations of external functions that take strings, chars, or structures as arguments or return any of these datatypes:
ALIAS FOR "functionname;ansi"
If the declaration already has an Alias For clause, only the string ;ansi is appended.
DBCS users only
If you select the Automatically Convert DBCS String Manipulation Functions check box, PowerBuilder automatically makes appropriate conversions to scripts in PowerBuilder 9 applications. For example, if you used the LenW function, it is converted to Len, and if you used the Len function, it is converted to LenA. The changes are written to the Output window and the log file. This box should be selected only in DBCS environments.
Adding PBLs to a PowerBuilder target
When you add PBLs from a previous release to a PowerBuilder target's library list, the PBLs display in the System Tree. The PBLs are not upgraded when you add them to the library list. Their contents do not display because they have not yet been converted. To display their contents, you must upgrade the target.
You can upgrade a target from the Workspace tab of the System Tree by selecting Migrate from the pop-up menu for the target. You can also upgrade targets in the Library painter if they are in your current workspace.
