PowerBuilder Authors: Chris Pollach, Yeshim Deniz, Jayaram Krishnaswamy, Kevin Benedict, Avi Rosenthal

Related Topics: PowerBuilder

PowerBuilder: Article

Implement Effective Source Control with PowerBuilder 8.0

Implement Effective Source Control with PowerBuilder 8.0

Every development shop that is currently managing its PowerBuilder source code with a third-party SCC tool and has not yet migrated to PB8 will need to understand the upcoming changes in methodology before attempting a migration. Even PBNative users will be affected, as that interface has been redesigned to use the SCC interface as well.

In my previous article, "Understanding the SCC Interface in PowerBuilder 8" (PBDJ, Vol. 8, issue 11), I outlined the sweeping rewrite of the source code control (SCC) interface introduced in PowerBuilder 8.0. This article walks through some simple source code management use cases, and shows how to set up and configure PB8 for effective source code control using both PBNative and a third-party SCC tool.

Getting Started with SCC
The first step in preparing for source code management with an SCC tool is to step back and reevaluate the PBL and folder structure of your current projects. With previous versions of PowerBuilder (7.x and earlier), the library painter was the principal "navigation" mechanism for working with PBLs and the underlying file system.

Since that painter was modeled on Windows Explorer with its TreeView/ListView paradigm, it was much easier on programmers to have all the PBLs in a project located in relative proximity to each other. Scrolling through excessive layers of nested folders to find a specific PBL was cumbersome and confusing. I've even seen projects in which all the non-PFC PBLs had been lumped together in a single folder.

The good news is PB8 has introduced a new and improved mechanism for working with PBLs called the System Tree, which presents all the PBLs for a specific target in a single TreeView, regardless of their physical file location. With that restriction lifted, each PBL (even PFC) can reside in its own folder without the associated increase in frustration of past releases.

There's a good reason to adopt PBL/folder hierarchies of this nature. As you work with SCC tools, especially PBNative, you'll start to see exported source files (*.SR* files) appear in great numbers. SCC tools work by archiving these files, not the PBL itself, and PB8 must export them to the file system so they can be archived into the SCC repository. The "diff" process also must compare the "tip" revision in the repository to an exported object file. In a PBNative environment these files are the "repository" (more on that later). As such, it makes sense to have PB export these files into folders that directly correspond to the PBLs. It will make life more difficult if, for example, the source for all 512 PFC/PFE objects were exported into a single folder.

Figure 1 shows a redesigned folder structure and the corresponding PB8 System Tree view of the PEAT target in Windows Explorer. The 10 PFC/PFE PBLs have been placed into their own folders as an example - many shops may choose not to place these particular files under source control because (in theory) they shouldn't be changed. Place the Workspace (.pbw file) in a parent folder (\PEAT project), and place all the PBLs for the target into their subfolders.

Notice that even though each PBL is physically located in a separate folder, the System Tree presents them in a contiguous, easy-to-navigate TreeView.

Create the Project Structure in the SCC Repository
The next step is to sign on to the SCC package and create the Project and Folder hierarchies in its repository. The SCC examples in this article feature StarTeam 4.2 from StarBase Corporation (www.starbase.com), but the concepts should be fairly transportable from tool to tool.

We'll follow a typical day in the life of two developers, Stan and Ollie, as they work with the PEAT project objects. Figure 2 shows the StarTeam administration window with the PEAT project and its subfolders loaded. Note that no objects have yet been registered to source control. That comes later.

I recommend trying to follow the folder structure from the file system as closely as possible; however, that's not an absolute requirement. If you build the hierarchy before registering the PB objects, it's possible to direct specific objects into specific subfolders in the repository. At this point we should introduce some terminology:


  • Local root directory: This is a property of the PB8 workspace. It must point to the physical file location that contains the workspace.
  • SCC working folder: This is a property of the SCC project folders in the repository, and it represents the folder on the file system that will hold the exported PB source files while they're being checked in/out and "diff"ed. It's possible to direct this to any physical file location, and you might be tempted to use a different folder than the PB local root directory, but don't. After experimenting with several configurations, the only stable option was to use the same location as the local root directory. For example, the SCC folder pfcapsrv has a working folder of C:\PB8\PEAT Project\PFC\pfcapsrv.

    Set Up the Workspace Source Code Control Property
    The next step is to tell PowerBuilder which SCC tool is being used. In previous versions of PB, this was done in a .CFG file. In PB8, it's a property of the workspace. In the Workspace Properties dialog, navigate to the third tab (Source Control), and select the SCC tool from the dropdown list. This will enable all the pertinent fields in the dialog. Once the connection to the SCC tool is established, PB will place a green "plus" sign next to each object in the target. This indicates that the object is not currently registered with source control. Open the Workspace Properties dialog and look at the available settings.

    Let's discuss what the various options and settings mean:

    • UserID: This is the user ID that was created in the SCC tool.
    • Project: This is the SCC project name. If left blank, you'll be prompted to select an existing project or create a new one.
    • Local root directory: All the workspace files that get registered to source control must reside in this path. If you're sharing targets between workspaces, place the shared targets in a workspace of their own and create a separate SCC project for them.
    • Advanced: Several SCC tools will have advanced options that are available by clicking this button.
    • Log all activity: If this is checked, all SCC activity will be logged. The default log filename is PBSMS.LOG, but this can be changed here.
    • Log options: Append to or overwrite the specified log file.
    • Require comments on check in: Select this checkbox to disable the OK button on the Check-In dialog box until you type a comment. This checkbox is grayed if you select PBNative as your source control system.
    • This project requires that I sometimes work offline: Select this checkbox to disable the automatic connection to source control when you open the workspace. Instead, each time you open the workspace you'll get a dialog box asking whether you want to work online or offline.
    • Delete PB object files: If this is checked, PB will automatically delete the exported source files from the SCC working folder following any activity that requires temporary files. Do not select this option for Perforce, ClearCase, or Continuous source control systems.

      Selecting this option may increase the time required to refresh object status from the SCC repository since the files will need to be regenerated on the local machine, then recompiled for PowerScript targets and deleted again. Recommendation: Unless disk space is limited, do not select this option.

    • Status refresh rate: Specify the minimum time elapsed before PowerBuilder automatically requests information from the source control server to determine if objects are out of sync. Valid values are 1-59 minutes. The status refresh rate is ignored if you select the checkbox for working offline.
    Register the Objects in the Repository
    Now we'll select the objects from the PEAT target and register them in the StarTeam repository. This will create "1.0" revisions for each object, and will change the icon next to the object from a plus sign to a solid green dot, indicating that the object has been registered and is not currently checked out.

    One of the enhancements introduced into PB8 is the capability of performing SCC activities on multiple objects at once by right-clicking on the target object. However, I've found that this is not a particularly efficient interface for the initial registration process. This task needs to be tackled one PBL at a time, so that the objects can be directed to their corresponding folder in StarTeam.

    If I right-click on the target, I'm presented with the dialog shown in Figure 3 in which I can select or deselect the objects I wish to register. This dialog window is particularly "user unfriendly," as it's not resizable and the contents are not sortable.

    It's very cumbersome when you need to go PBL by PBL. What we need is an interface that shows all the objects in a single PBL. Fortunately, the library painter is still around and it's the perfect tool for this job. Open the painter to the PEAT.PBL, choose "Select All" from the toolbar, then select Add to Source Control from the context menu. The next dialog that comes up is the same dialog as Figure 3, but it contains only the objects that were selected - there's no need to deselect anything. Finally, you're asked which SCC folder will contain the object archives. When the process for the PEAT.pbl is completed, move on to the PFC PBLs and repeat the task. Fortunately, this tedious registration task needs to be completed only once for each PBL, even if the PBLs are shared across targets.

    Adding Another Developer to the Project
    Now it's time to add Stan to the project. Remember that each developer will have his or her own complete set of PBLs and will work completely off the local drives. The first step in getting Stan's workstation set up is to copy the project folder structure and contents onto his machine.

    Grab everything from Ollie's machine from the local root directory on down and copy them across the network onto Stan's machine. The entire folder structure containing all the PBLs, the workspace and target files, and the exported source files should now exist on Stan's machine.

    Once that step is complete, start PB8 on Stan's machine, open the workspace that was copied over, and use the right-mouse button to bring up the Workspace Properties dialog. Navigate to the Source Control tab. Notice that it's strangely empty? We'd gone to all the trouble of setting up the source control properties for the workspace on Ollie's machine and even copied the entire workspace over to Stan's machine. Where did this information go?

    After some digging I found it in the registry, under the key: HKCU\Software\Sybase\PowerBuilder\8.0\Workspace\<workspace location>\SourceControl. That means that we'll have to re-create this information in the Source Control tab of the Workspace Properties dialog on each machine that will use this workspace (or export and import that registry key, which this author did not attempt because the registry frightens him).

    Select the SCC provider from the source control system dropdown and fill in the user ID and local root directory fields. Clicking Connect will bring up the Connection dialog from your specific SCC tool. With StarTeam, the Connection dialog asks whether this is a New or Existing project. Since this is an existing project, selecting that option refreshes the status for all objects in the target. Once this is complete, Stan should now see all the objects in the workspace with the telltale green dot, indicating that the objects are now registered to source control and are available to be checked out.

    Typical SCC Use Cases
    Now that we have the SCC environment set up, it's time to do some actual work. Let's examine some of the typical source control use cases with an SCC tool: checking in/checking out objects, registering new objects, and performing a build.

    Checking Out Objects from SCC
    Ollie has been assigned an issue in the window w_r_analyzer, while Stan (the newest member of the team) is adding some standard comment headers to several of the NVOs.

    First Ollie needs to check out the w_r_analyzer window. This can be performed from either the System Tree or the library painter. Simply right-click on the window object and select Check Out... The Checkout dialog is presented next, confirming the object name that's being requested, and clicking OK gets the latest version from the SCC repository and places that code back into the same PBL. The SCC icon changes from a green dot to a green checkmark, indicating that Ollie has the object checked out to his own workstation. On Stan's workstation the icon will change to a red checkmark, indicating that some other user (Ollie) has that window currently checked out.

    This is an important change in procedure from PB7.x and earlier, where the checked-out object was automatically copied into a separate "work" PBL. In fact, inadvertently selecting the original source PBL during checkout would result in an error message. The concept of a work PBL is no longer automatically supported in PB8, which will take some getting used to.

    One of the side benefits of having a work PBL was that all the work-in-progress objects were physically located in a single place, so it was possible to see what was checked out in a single glance. In PB8, this is still possible, but it's not quite as intuitive. If you right-click on the target and choose Check In..., you'll be presented with a dialog that shows all the objects you've checked out. This option is also available from the library painter in the source control menu.

    Stan, in the meantime, has checked out all the NVOs in the PEAT library. In PB8, Stan has the option of checking out several objects at once. Method 1 is to right-click on the PEAT target, select Check Out, and then make sure only the objects he wants are checked in the Checkout dialog.

    Method 2, in this case the most effective, is to use the library painter. In the right-hand pane of the painter, multiselect all the desired objects and select Check Out... from the source control menu. With this method, only the selected objects are presented in the Checkout dialog, which saves you from having to deselect/reselect the desired objects. Figure 4 presents the System Tree from Stan's perspective, showing the NVO classes checked out to him and the window class checked out to Ollie.

    Examining the Code Changes
    Our developer Ollie has completed his changes in w_r_analyzer and is ready to check them back in, but first he'd like to review all the changes that were made to the window, to ensure that he didn't leave some MessageBox() calls in there. PB8 now offers a direct interface to the "visual diff" utility provided with the SCC tool by selecting Show Differences... from the context popup menu, or from the library painter's source control menu. If your SCC tool doesn't offer a visual diff tool, or you're using PBNative, you can configure your own selected tool in the Advanced dialog in the source control tab of the workspace properties. Figure 5 provides an example of the StarTeam visual diff utility for the changes that Ollie made to the window.

    Using a Work PBL
    The biggest complaint I'm hearing about the SCC interface is that a work PBL is no longer supported by PB8. Actually, this isn't totally accurate. The fact is a work PBL is no longer required, and is not automatically maintained by the checkout/check-in process. If the transition away from a work PBL is too much to bear, it's still possible to work with one. You just have to manually copy the objects from the base to the work PBLs yourself.

    The following steps outline how to set up and use a work PBL in a PB8 environment.

    1. Create a second target within the current workspace. Give it a different name to distinguish it from the original target, like "peat_Ollie" or something to that effect. This will create a new PBL and a new application object in the PBL, both called "peat_Ollie". This is your "work" target and PBL.
    2. Copy the library paths from the original target and paste these into the target properties for the new target. Note: The Library Paths dialog will be grayed out in the original target unless you first check it out from the SCC repository. The work PBL needs to remain first in the library path. Do not register this new target with source control.
    3. Copy the application object from the original PBL into the new PBL. This brings across all the global variable declarations and event code within the application object.
    4. When it's time to check out an object, do it from the primary target. This will get the latest version of that object into the main PBL and mark it as checked-out.
    5. Right-click on the object, and copy it into the work PBL. It will show as "unregistered," since the work target is not under source control.
    6. Edit and debug the object within the context of the work target. When the changes are ready to be checked back in, copy the object back into the original PBL from the work PBL, then check it in from there.
    7. Delete the copy of the object from the work PBL.
    Creating New Objects
    When all the PBLs were located on a network drive, adding new objects was a snap. As soon as one developer added an object to the PBL, all the other developers saw the object immediately. Unfortunately it's not that simple when all the developers are working off their local drives. Let's examine a scenario in which Ollie creates an NVO that Stan must get into his local PBLs.
    1. Ollie creates a new NVO by inheriting from n_ds. He names it n_ds_ollie and places it into the PEAT.pbl on his local drive. If Ollie had been using the work PBL architecture outlined earlier, he might first create/edit/test the object in the secondary work target, then copy the object into the primary target when it was ready.
    2. Ollie must register the initial version of the object with the SCC tool. Ollie selects the object (either in the System Tree or in the library painter) and chooses Add to Source Control.... This takes an export of the object and registers it as revision 1.0 in the SCC repository. Ollie also sees the SCC icon change from a green plus sign to a green dot.
    3. Stan must now get the copy of the object into his local PBL. This is accomplished through the Get Latest Version dialog. However, there are two different methods of invoking this function. Right-clicking on the target and selecting Get Latest Version... will scan the entire target, and the dialog presented will contain all the target objects with checkmarks next to the few that are found to be "out of sync."
    That's a lot of unnecessary and time-consuming scanning to detect a single object. Why waste time scanning the PFC/PFE layers, right? Once again, the library painter comes to the rescue. Selecting the PEAT.pbl and choosing Get Latest Version... from the source control menu will scan only that PBL. The list presented will be much shorter and much easier to work with. Figure 6 shows the resulting dialog from Stan's request, and there's n_ds_ollie waiting to be imported.

    How did Stan "know" to do a Get Latest Version? The IDE will refresh periodically and inform all developers of existing objects that are out of sync, but not new or deleted objects. This would be a welcome enhancement in a subsequent release. In the meantime, Ollie could send an e-mail alerting the other developers of the addition/removal of objects from the application layer PBLs, or each developer could perform this task on a regular, recurring basis.

    PBNative Support
    Now that we've examined the ins and outs of SCC support in PB8, it's time to turn our attention to good old PBNative. For shops that simply needed to protect two developers from working on the same object simultaneously and have no desire for a more robust version control methodology, PBNative was the answer. The good news is that PBNative remains an option in PB8. The bad news is that it's very different from prior versions.

    The architectural changes that were made to PB8 for the SCC interface required that the PBNative interface be overhauled as well. It was completely gutted and rewritten as an SCC provider. PBNative now uses the same API calls as any other SCC tool, and checkout status information is no longer stored in the PBL as in prior versions. The Sybase developers were faced with a dilemma - there was no "repository" in which to persist the checkout status and it couldn't be stored in the PBL either. So they created a minirepository, called the .PRP file, and you'll see one for each and every registered object in a PBNative workspace. The .PRP file implements a simple semaphore - when one user checks an object out, the .PRP file for that object is updated with the user name and current status. When the IDE does a refresh, it checks all the .PRP files to see if any object has changed status.

    In addition to the .PRP file, PBNative also maintains the latest version of each object as exported source files. This allows for the "diff" process to function properly. The exported source code and the .PRP files combine to form the "repository" in a PBNative environment. This will take some getting used to, primarily because of the presence of all those exported .SR* files. In prior versions of PB, exporting the source to a file was a last resort, reserved for those occasions when the developer needed to manipulate the raw source code. Once reimported into a PBL, the file could be safely deleted. PBNative support in PB8 requires that these files stay intact. If you have network administrators who like to purge files to conserve server disk space, and they've been told that "all those .sr* files are okay to delete," you'd better send them a memo.

    The only major points of difference between a PBNative and an SCC environment are the following:

    1. With a third-party SCC tool, everything is local. The local root directory, the SCC work directory, the workspaces, targets, and PBLs...it's all there on each machine. The only network-based resource is the SCC repository.

      With PBNative, the project directory where the .PRP and exported source files reside must be on a shared network drive. These files are functioning as the SCC repository and, as such, must be placed in a common, shared location.

    2. PBNative doesn't ship with a default visual diff utility (there are some SCC tools that don't either), so you're allowed to plug in your tool of choice in the advanced options of the workspace source control properties tab.
    Final Recommendations
    The migration process from prior versions of PB up to PB8 will be taxing enough in most shops. Don't compound the frustration by attempting to migrate while there's work in progress. Complete all outstanding branches of development in the previous version, then close out the old SCC projects as well.

    Migration will touch every object in every application, and recording these changes as revisions to an existing project is senseless. Start new SCC projects for the 8.0 codebase, finish the migration into the new PBL directory architecture, and register the migrated code as revision 1.0 of your PB8 release.

    The changes to the SCC interface in PB8 are complex, and the methodology changes that accompany this revision are just as complex. With careful planning and preparation, the impact to existing PB shops can be greatly reduced.

  • More Stories By Paul Horan

    Paul Horan is a Senior Solution Advisor and Mobility Architect at SAP, and works with the SAP Mobile Platform and SAP Mobile Secure product lines. Paul joined SAP as part of their acquisition of Sybase in June, 2010. Prior to that, Paul worked for Sybase as a technical pre-sales architect supporting PowerBuilder, PowerDesigner, and SQL Anywhere. Paul works out of SAP's Reston VA office. A 1984 graduate of Indiana University, Paul currently resides in Arlington VA.

    Comments (3)

    Share your thoughts on this story.

    Add your comment
    You must be signed in to add a comment. Sign-in | Register

    In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.