Paul Horan

As we all know by now, the interface between PowerBuilder and the myriad of Source Code Control (SCC) providers was completely rewritten with the release of PB 8.0. Over the past three years, PowerBuilder's SCC interface has been in a nearly constant state of evolution, and several key enhancements were released with PB9.0 and 9.0.1.

These included:

• The OrcaScript batch command language processor was released; it allows the development of unattended refresh and build scripts.
• The Refresh Status thread in the IDE was moved to an asynchronous thread, allowing it to run in the background.
• The SccQueryInfoEx() extension to the SCC API allowed the implementation of "Diff by Version Number," which significantly improved the performance of the Refresh Status process.

PowerBuilder 10.0 was released in August of 2004, in conjunction with the 20th anniversary of Sybase, and the SCC interface is once again a subject of discussion. This article focuses on several key issues that development shops will need to be aware of as they migrate to PowerBuilder 10, with regard to their use of Source Code Control tools.

Unicode!
PowerBuilder 10 is the first release to fully support the Unicode encoding scheme. Unicode is the universal character encoding scheme for written characters and text. Unicode replaces a proliferation of character sets and encoding schemes with a single, globally interoperable standard. PowerBuilder 10 not only supports Unicode, it actually uses Unicode character encoding internally. What does this mean to you, as a PowerBuilder developer? It means that even if your application will never need to store or display an Arabic or Kanji 16-bit (double-byte) character, the code in your PBLs will be stored internally in a 16-bit encoding scheme. In fact, you may notice that after migrating to PB10, your PBLs will be just about twice as large as their PB9 counterparts.

Remember that nearly all SCC providers operate by archiving the individual revisions to ASCII text files. When a revised PowerBuilder object is checked in, PB will first export the object's source into the Local Root Folder, and then send that ASCII text file to the SCC provider. The SCC tool increments the tip revision number and tracks the change accordingly. ASCII is an 8-bit, or single-byte, encoding scheme. However, the code in the PBLs is now stored in UTF-16LE, a 16-bit Unicode scheme. The PB engineering team had to devise an encoding format that could use 8-bit ASCII to represent 16-bit Unicode source. The answer was HEXASCII, which is one of several new source file export formats available in the Export Entry dialog. Figure 1 shows the PB10 Export Entry dialog, with the four new export formats available in the Encoding: dropdown list.

Unicode LE (Little Endian)
This format is the "default" format when using the Export... menu option to manually export an object to a source file. This encoding scheme is capable of handling source that contains both single-byte and double-byte characters, and it also matches the internal encoding scheme within the PBL. The first line in the file will contain a 2-byte prefix 0xFFFE that flags the encoding scheme as UTF-16LE. You won't see this prefix unless you open the source file in a Hex editor. Files exported with this encoding scheme cannot be imported back into PB9.

UTF-8
This format is the single-byte encoding scheme, so files encoded with this format will be half the size of their Unicode partners. The prefix in these files is 3-bytes long: 0xEFBBBF. Files encoded in this scheme cannot handle source code containing double-byte characters, nor can they be imported back into earlier versions of PowerBuilder.

ANSI/DBCS
Files exported with this choice will be single-byte or double-byte, depending on the source. In PB9 and earlier, source was either all single-byte or double-byte. These files contain no prefix code, therefore ANSI/DBCS is the only encoding scheme that PB9 can successfully import.

HEXASCII
Files encoded with the HEXASCII scheme contain the two-byte prefix HA, and use a single-byte ANSI encoding scheme. However, this encoding scheme is still capable of representing double-byte characters through the use of bracketed "escape sequences." For example, a typical HEXASCII export file might contain the following single-byte string sequence:

$$HEX2$$c189d063$$ENDHEX$$Single byte
text$$HEX2$$417ed49a$$ENDHEX$$

Any characters found between the $$HEX2$$ and $$ENDHEX$$ strings represent the double-byte characters in the original source code. This format was developed so that PowerBuilder could use Unicode internally, but the SCC providers could still operate on single-byte ANSI-encoded text files. This format is used for all SCC operations with PB10, and is not backward compatible with PB9.

Migrating to PowerBuilder 10
I'm sure you've found all that fascinating, but what does it have to do with migrating to PowerBuilder 10? I'm glad you asked...

A typical migration effort from one version of PowerBuilder to another is a simple matter of opening the application or target in the new version of PowerBuilder and allowing the IDE to "do its thing." A cup of coffee later, and your PBLs have all been migrated into the new version. However, this is the first release of PowerBuilder that actually changes the code during the migration process. The PB10 migration process reencodes the entire source into Unicode. From that point forward, all SCC operations are conducted with the HEXASCII encoding scheme, therefore all the export files have the HA header prefix. It doesn't sound like a significant change - just two letters in the first line of code, but these two letters are not in the tip revision inside the SCC repository. Migrating to PowerBuilder 10 therefore violates the first commandment of source code management: thou shalt not edit an object unless thou hast first checked out that object.

If you migrate your source-controlled application code to PowerBuilder 10, you've done exactly that - written a change into your local copy of the PBL without first checking out the objects. The first time you connect to the SCC provider from PB10, all the objects will show as "out of sync," and a subsequent GetLatestVersion will actually "unmigrate" them.

There are two possible solutions to this dilemma:

1. Start fresh. Migrate into a new PB10 workspace and register all the objects into a new SCC project as revision 1.0. The only downside (for everyone except PBNative users) is that the history of changes to the objects remains in the previous SCC project.
2. Perform a target-wide checkout prior to migration. Open the workspace in your current version of PowerBuilder and perform a target-wide checkout. Do this for all the targets in the workspace. When you open the workspace in PB10, the migration process will proceed to completion, rewriting the objects in place. Now, go to the workspace properties dialog and reconnect it to the SCC project. The object statuses will all show as "checked out," and you can perform a target-wide check in for all the objects. This will maintain all the existing history in the SCC repository prior to the migration.

OrcaScript Enhancements
PowerBuilder 10.0 includes several enhancements to the OrcaScript command-line utility and a sizeable number of bug fixes. The following list contains several of the bigger-ticket items.

SCC SET CONNECT PROPERTY PASSWORD "password"
This new command was added specifically for users of Borland StarTeam. StarTeam is one of the few SCC providers that requires user authentication for all connection attempts. OrcaScript could provide the user name, but not the password, so the SCC CONNECT command would cause StarTeam to present their connection dialog and wait for user input. This totally defeats the purpose of writing unattended batch scripts, so this command was added to supply the password during the StarTeam connection attempt.

SCC CONNECT OFFLINE
At first glance, the terms "Connect" and "Offline" might sound mutually exclusive, but this new command addresses a very typical situation. The SCC REFRESH TARGET command is not allowed without first issuing the SCC CONNECT command. However, mobile or occasionally connected developers may not be able to establish a direct connection to the SCC provider. SCC Connect Offline can be used with the IMPORTONLY option to rebuild a target from exported source code files on a laptop or other remote workstation. The typical scenario would be:

• Developer synchronizes the files in his or her Local Root Folder from the SCC repository while connected.
• Disconnects the laptop from the network and boards a plane.
• Refreshes and rebuilds the target from the exported source while disconnected.

For example:

start session
SCC get connect properties "myWorkspace.pbw"
SCC connect offline
SCC set target "myTarget.pbt" "refresh_all importonly"
SCC refresh target "full"
SCC close
end session

IMPORTONLY OUTOFDATE
The IMPORTONLY option to the SCC SET TARGET command tells OrcaScript that the files in the local root folder contain the desired source, and a "GET" from the SCC repository is not necessary. In previous versions of OrcaScript, this would import and refresh all the files in the target, whether or not they were actually out of sync. PB10 now allows the combination of the IMPORTONLY and OUTOFDATE options on the SCC SET TARGET command. This will compare the source in the PBL with the content of the exported source file, and only import those objects found to be out of sync.

To use this feature, you must first synchronize the files in the local root folder from the SCC repository, which is typically done with the SCC provider's command-line utility. This is a much more efficient way of performing a target-wide GetLatestVersion than requesting the operation from within the IDE.

For example:

start session
SCC get connect properties "myWorkspace.pbw"
SCC connect offline
SCC set target ".\myTarget.pbt" "importonly outofdate"
SCC refresh target "full"
SCC close
end session

IMPORTONLY EXCLUDE_CHECKOUT
The EXCLUDE_CHECKOUT option can also be added to the SCC SET TARGET command, and that will skip the import process for any objects currently checked out to the specified user.

This feature can also be used in conjunction with CONNECT OFFLINE for disconnected rebuilds. However, that forces OrcaScript to look into the .PBC file to retrieve the checkout status of the objects, so the objects must be checked out prior to disconnecting from the SCC repository. In addition, SCC GET CONNECT PROPERTIES "workspace" is required to obtain the .PBC file when using CONNECT OFFLINE.