Upgrading targets
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
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
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
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:
|
1 2 |
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:1ALIAS 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.
To upgrade a target in the Library painter:
-
Select the target you want to upgrade and select
Entry>Target>Migrate from the menu bar.The Migrate Application dialog box displays.
-
Select OK to upgrade all objects and libraries in the target’s
path to the current version.