When you upgrade to a new version of PowerBuilder, your existing targets need to be migrated to the new version. Typically, when you open a workspace that contains targets that need to be migrated, or add a target that needs to be migrated to your workspace, PowerBuilder prompts you to migrate the targets. However, there are some situations when you need to migrate a target manually. For example, if you add a library that has not been migrated to a target’s library list, you will not be able to open objects in that library until the target has been migrated.
You cannot migrate 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.
There are some steps you should take before you migrate 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 migrate are writable
Always back up your PBLs before migrating
Make sure you make a copy of your PBLs before migrating. 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 migrate to the current version.
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 migrated to PowerBuilder 10 or later.
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 migrated.
You cannot expand the icon for a PBL from PowerBuilder 9 or earlier in the Library painter. To examine its contents, you must migrate 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 migrate targets from this dialog box, or clear the No Prompting check box to open the Migrate Application dialog box.
PowerBuilder dynamic libraries
If you plan to reference a PowerBuilder dynamic library (PBD)
that was encoded in ANSI formatting (for example, if it was created
in PowerBuilder 9 or earlier), you must regenerate the PBD to use
Unicode formatting. Dynamic libraries that you create in PowerBuilder
10 or later use Unicode formatting exclusively.
For information on creating PBDs, see “Creating runtime libraries”.
The Migrate Application dialog box lists each PBL that will be migrated and lets you choose the type of messages that display during the migration process.
If you click OK, each PBL is first migrated 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 migrated 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.
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 migrated 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 migrate the target.
You can migrate a target from the Workspace tab of the System Tree by selecting Migrate from the pop-up menu for the target. You can also migrate targets in the Library painter if they are in your current workspace.
To migrate a target in the Library painter:
Select the target you want to migrate and select Entry>Target>Migrate from the menu bar.
The Migrate Application dialog box displays.
Select OK to migrate all objects and libraries in the target's path to the current version.
