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

Related Topics: PowerBuilder

PowerBuilder: Article

Source Code Control

Source Code Control

Every software development project of any significant size or complexity has a requirement for controlling the source code asset. PowerBuilder is capable of integrating with any third-party Source Code Control (SCC) tool that implements Microsoft's SCC API. However, the fact that PowerBuilder stores its code inside PowerBuilder Libraries (PBLs) and not as individual ASCII text files adds a layer of complexity to that integration. The release of PowerBuilder 8.0 in 2001 brought with it a new set of challenges in the form of a completely redesigned interface with SCC providers, including PBNative.

In this article, I outline the nature of the changes that were introduced in PowerBuilder 8.0, and discuss many of the enhancements that have been released with PB 9.0.

Why Version Control?
Version Control software adds significant administrative overhead to every project, and the management of this process can become a full-time job. In addition, many of the "best in class" SCC tools carry a significant price tag. It becomes necessary at that point to ask, "Why bother with Version Control at all?" Developers are paid to design and construct software systems, not to function as librarians, monitoring the checking in and out of source code modules. The answer is simple: as development projects increase in size, scope, and complexity, the need for management to establish best practices and control the development process also increases. The applications of yesterday that were developed, debugged, and deployed on a single platform are a thing of the past. Today's applications may involve several different processing platforms and programming languages. The time wasted in misguided and misdirected development efforts can more than justify the cost of development tools that enforce a clear and well-understood development process.

A basic laundry list of requirements for the selection and implementation of an SCC tool might include the following:

  • A secure repository for digital assets: The SCC repository should be able to manage any digital asset, including source code, documentation, and marketing materials. And the repository should prevent unauthorized persons from registering or altering objects under source control.
  • Object versioning: The SCC tool should track each individual revision to an object in its repository. These revisions should be identified with a specific revision numbering scheme that's understandable and meaningful, and can be used to identify the proper version of an object to include in any build of the project.
  • Developer "insulation" and branching: The repository should implement a "locking" mechanism that prevents two or more developers from editing the same code object concurrently. There are situations, however, where concurrent access is required. In these cases, the SCC tool should support the concept of "branching" within the main line of development.
  • Traceability of source code changes: The SCC tool should provide full audit trails indicating the date, time, and author of a specific revision, along with any meaningful comments.
  • "Time travel": It should be possible to re-create the state of the source code at any time, from the latest "tip" revisions back to the initial registration of the project. This process can be made much easier if the tool supports the concept of "labeling," in which all objects at a specific configuration are given a consistent and meaningful name.
  • Integrated change management/tracking: As an added bonus, many enterprise-level SCC tools will include or integrate with additional utilities that support the entire software development process, such as defect tracking, development workflow management, and e-mail integration.

    Above all else, the SCC system should be seen as a tool by developers, not as a hindrance or source of annoyance. An effective tool will fit seamlessly within the development processes and procedures and not interfere with them.

    A Brief Review of SCC Integration with PowerBuilder
    The vast majority of the SCC tools that exist in today's marketplace were developed for languages such as C/C++, Visual Basic, Java, and other languages that maintain their source code modules as separate and distinct ASCII text files. The source control tool would store each revision to these files in its repository of archives, identifying each revision with a specific revision or version number. At build time, the developer would simply do a "get" of the latest revision level of each file and compile the application into an executable. PowerBuilder, as we all know, does not store its source code modules out on the file system as individual ASCII files. PowerBuilder objects are stored inside a PowerBuilder Library (PBL), a proprietary repository known affectionately as the "pibble." This posed quite a challenge for SCC tool providers. Controlling the PBL file was useless, and the SCC tools weren't able to "peek" inside the PBL to version the individual objects. PowerBuilder was gaining momentum in the marketplace, and several of the larger SCC vendors scrambled to provide custom interfaces between their tools and the PowerBuilder IDE. However, these custom interfaces were notoriously buggy, and often resulted in lost source code or corrupted PBLs.

    Ultimately, Microsoft came to the rescue with the release of their SCC Application Programming Interface (API). The SCC API is a standard programming interface that defines the integration between any development tool and any SCC provider. Finally, it was possible to have an enterprise-class SCC repository fully integrated with PowerBuilder, and development teams could manage PowerBuilder code down to the individual object level. The next challenge for PowerBuilder shops would be to develop standard procedures and workflows to take advantage of this new level of integration.

    Code Management Architectures
    Even with the new SCC API in place, the PowerBuilder IDE still depended upon critical SCC metadata written directly in the PBL, such as checkout status and folder. The fact that this data was stored in the PBL forced developers to maintain a "registered" set of PBLs out on a shared LAN drive, so that each member of the team would instantly see any change in an object's status. Two distinct approaches to managing PowerBuilder code under source control quickly emerged.

    Some teams chose to work directly from the PBLs out on the LAN drive. This was the simplest and most straightforward approach. It allowed developers to see each other's "work" PBLs that contained their work-in-progress, and there was a single set of PBLs being managed. Unfortunately, the PB IDE locked the PBLs when at least one developer was in the debugger or running the app from within the IDE. Attempting to check an object in or out while someone else was debugging often resulted in I/O errors and incorrect checkout status data. This approach proved effective only for smaller project teams.

    The alternative approach was to copy the registered PBLs onto each machine and to have each developer work only from their local drives. A developer would check an object out from the registered PBL into a local work PBL where it would be edited and tested, then ultimately checked back into the registered PBL. This avoided the I/O errors associated with the locked PBLs, but required each developer to periodically synchronize their local copies with the registered PBLs. With everyone working locally, there were now several duplicate copies of each PBL, and keeping everyone in sync became a complex and error-prone task.

    Neither approach was totally foolproof, and it became apparent that a new architecture for SCC integration was necessary. The underlying goal of the new architecture was to use the SCC repository as the ultimate reference for both the source code and the relevant status information. SCC metadata would no longer be maintained in the PBL, and the PB IDE would use the SCC API to query the repository for accurate status information. That revised architecture was included in the release of PowerBuilder 8.0 and has been further enhanced and refined in the 9.0 release.

    Architectural Changes in the SCC Interface
    The fundamental shift in thinking that drove the redesign of the SCC interface in PowerBuilder 8.0 was that the SCC repository should be the "source of all knowledge" about the content and status of the source code asset. In other words, there should be nothing stored in the PBL that the SCC repository is capable of providing. This meant that metadata such as checkout status would no longer be stored in the PBL; PowerBuilder would now "ask" the SCC provider for the current status of each object through the SCC API. The adoption of this philosophy led to several key changes in the way developers will work with PowerBuilder.

  • The necessity for using shared PBLs on a LAN drive has been eliminated: The SCC repository not only contains every revision of every object, it's now the source for all SCC metadata such as checkout status. Therefore, there's no longer any need to have a set of "registered" PBLs out on a shared LAN drive. Each developer will now work with his or her own dedicated copy of all the PBLs within the target and workspace.
  • A separate "work" PBL is no longer required: In prior versions of PowerBuilder, each object would be checked out from the "registered" PBLs into a separate "work" PBL, where it would be edited and debugged. The revised version of the object would be checked back into the registered PBL prior to performing a compile. This architecture was important, because it helped to isolate each developers' work-in-progress.

    In PowerBuilder 8 and 9, objects are checked out and edited "in place" in each developer's local copy of the PBLs. The use of a "work" PBL is no longer required and is not automatically supported as in version 7.x and earlier. Users of previous versions of PowerBuilder may be uncomfortable with this initially, and it may take some adjustment. It's still possible to set up an architecture that uses a work PBL, however, the movement of the code between the "work" and the "home" PBL would be a manual effort.

  • The SCC configuration is now a Workspace property: Each application in pre-PB8 releases was linked to a specific .CFG file, which contained the SCC connection properties for that application. In PB8, the concept of the Workspace and Target was introduced, and the .CFG files were replaced with an entry in the Windows registry. This registry entry is maintained in the Source Code tabpage in the Workspace Properties dialog. Since each Workspace is now mapped to a single SCC project, every registered object within the Targets of that Workspace will be managed within that single SCC archive.

    IDE Changes in PowerBuilder 8 and 9
    The PowerBuilder IDE got a complete makeover with the release of version 8.0, just as developers were getting used to the new PB7 look-and-feel. We were introduced to the System Tree, the Clip Window, and dockable "panes" that could be configured to suit any programming style. The good news is, the 9.0 interface is pretty much the same as the 8.0, so the concepts discussed in this article will pertain to both versions.

    Workspace Properties Dialog
    As mentioned earlier, the SCC configuration is now a property of the Workspace and is maintained in the Workspace Properties dialog. This dialog is opened by right-clicking on the Workspace in the System Tree and selecting Properties... from the context menu. Figure 1 shows a typical setup for a PBNative project.

    Source Control System
    This is a dropdown list of the installed SCC providers that are installed on the workstation. PBNative has been rewritten as an SCC provider and appears as a valid choice when PowerBuilder is installed. For other third-party tools to appear in this list, they must be installed and implement the Microsoft SCC API.

    Each user must have a valid ID created in the SCC repository. For PBNative, there's no authentication process, but it's recommended that each developer use a separate UserID.

    For PBNative, this field must contain the fully qualified pathname of the shared network folder that contains the PBNative archive files. This must be set to the same location for all developers who are working on the project. Use the button labeled "..." to browse the file system and locate the archive folder.

    For third-party SCC providers, this will identify the Project within the SCC repository. Refer to your specific provider's documentation on the use of Projects within their SCC tool. In this case, the "..." button next to the Project field will open the SCC provider's Project dialog.

    Local Root Directory
    This must point to the fully qualified pathname of the folder that contains the Workspace file.

    This command button will become enabled whenever one of the attributes of the SCC connection is changed. When you click this button it will attempt to connect to the selected SCC repository with the supplied parameters.

    This command button calls the API that opens the Advanced SCC properties dialog for the selected provider. For PBNative, the user is allowed to specify a different Visual Diff tool to compare two versions of an object.

    Log All Activity
    Selecting this option will cause all SCC operations to be written to the specified Log file in either Append or Overwrite mode.

    Require Comments on Check in
    This option will only be enabled for SCC providers that are capable of tracking developer comments inside the repository. PBNative is not capable of storing this data, so the checkbox is disabled. When selected, the OK button on the Check In dialog remains disabled until a comment is entered.

    This Project Requires That I Sometimes Work Offline
    This option allows developers to continue to work, even in the absence of a network connection to the SCC repository (laptop and remote desktop users, for example). When this option is selected, the user will be prompted to Connect to the Repository or Work Offline. Objects must be checked out from the repository prior to going offline. While offline, the object status is maintained in an "offline status cache" or .PBC file. When a network connection is established, the revised objects can be checked back into the repository.

    Delete PowerBuilder Generated Object Files
    SCC providers, even PBNative, work by archiving the exported source files (.srd, .srw, and so on). Therefore, PB must export the source before a check-in, and import the source upon checkout. When this option is selected, PB will "clean up" the exported source files from the Local Root folder when the SCC operation is completed. Leaving this setting off will result in additional disk space consumption in the Local Root folder, but will improve the performance of SCC operations in general.

    Perform Diff on Status Update
    The IDE will periodically query the SCC provider on the status of objects in the current Target in order to place the appropriate icon next to the object in the System Tree. This process can include a full "diff" on each object. Selecting this option enhances the reliability of the Status Refresh process, but adds to the processing overhead. It's not recommended to select both this option and the "Delete PowerBuilder-generated Object Files" option. Having both options turned on would force PB to reexport each object to source code prior to performing the diff process.

    Suppress Prompts to Overwrite Read-Only Files
    Several SCC providers write the exported source files in the Working Folder as read-only, to prevent inadvertent editing of these files without a prior checkout. As PowerBuilder exports files to this folder and encounters the read-only version, it will prompt the user whether it should overwrite the file or not. This prompt can be suppressed by selecting this option.

    Status Refresh Rate
    This sets the automatic refresh interval for the System Tree and Library Painter. When this period expires, PB will query the SCC provider for the current status of each object in any PBL that's currently expanded in either the System Tree or the Library Painter.

    System Tree and Library Painter SCC Icons
    One of the most noticeable differences between the pre-8.0 and post-8.0 versions is the different SCC icons. A completely new set of icons was chosen for the 8.0 release (see Table 1). The icons appear only when a valid connection to an SCC provider has been established. They can appear in both the System Tree and the Library Painter immediately to the left of the object icon.

    There are situations in which two icons may be displayed side-by-side. For example, if one member of a development team checks out an object, edits the object and checks the changes back in, and then rechecks the object back out again before the other members of the project team have had a chance to synchronize their local copies, then all the other users will see both the "out of sync" icon and the "checked out to another user" icon. Performing a Get Latest Version on the object will clear the "out of sync" icon, but will leave the "checked out to another user" icon.

    Source Control Menus
    Source control functions now appear in both the System Tree context menus and the Entry menu in the Library Painter.

    Figure 2 shows the right-click context menu from within the System Tree. The source control options begin in the third section down.

    Get Latest Version...
    Selecting this option on a single object will present the Get Latest Version (GLV) dialog window (see Figure 3). PB will evaluate the status of the object (performing a Diff, if that option has been selected in the Workspace Properties dialog). If the object is determined to be "out of sync," the checkbox in the GLV dialog will be shown as checked on. In Figure 3, the object was currently in sync, so the checkbox was shown as off. PB will only perform the GLV operation on the objects with checkboxes on.

    In addition, the object that's selected in the System Tree or Library Painter will drive the content of the GLV dialog. For example, selecting a PBL will populate the list with every object in that PBL, and only the objects that are out of sync will be checked on. If a Target is selected, the user must first tell PB whether to operate on the Target object or on multiple files within that Target. If the "multiple files" option is selected, PB will populate the GLV dialog with a list of all the objects in that Target, and determine the sync status for each of them. For large targets, this operation can take a significant amount of time, and should therefore be used judiciously.

    The Select All button will toggle all the checkboxes on (and change to a Deselect All button); however, this option should be used with extreme caution. It's essentially overriding PowerBuilder's evaluation of the current status of an object and forcing the GLV operation. In complex Targets, especially those based on PFC, the relationships and dependencies between objects are far too complex to re-import into a PBL in a single pass.

    The Advanced... button will be enabled for SCC providers that support an Advanced dialog, and when clicked will open the SCC provider's Advanced "Get" dialog. Refer to the documentation of the specific SCC tool for additional information on this dialog.

    Check Out...
    Selecting this option on a single object will present the Check Out object dialog window. This option will be disabled if the object is currently checked out. Figure 4 shows the Check Out dialog that's presented when a single object is selected. The Check Out operation is available at the PBL and Target level as well, and the list of objects presented will exclude objects that are already checked out.

    PowerBuilder will get the current version of the object's source file from the SCC repository, import that into its corresponding PBL, and set the object's status to "checked out" in the SCC repository. If the "Delete PowerBuilder-generated Object Files" option is turned on, the exported source file that was imported will then be deleted from the local root folder.

    This dialog also changes appearance based upon the capabilities of the SCC provider, showing a Comment field when the repository is capable of accepting comments on Check Out.

    Check In...
    This option is enabled only when the object is checked out to the current user. Selecting it will present the Check In dialog (see Figure 5). The Check In operation will export the source code of the revised object to the local source folder, and then archive that file in the SCC repository. Depending upon the capabilities of the SCC tool and the properties of the SCC project, this will either increment the version number of the object's "tip" revision or create a "branch" from the main source code line.

    When this option is selected at the PBL or Target level, the list of objects will be only those that are checked out to the current user at that specific level. This is different from the Get Latest Version dialog, which presents every object at that specific level.

    If the "Require Comments on Check In" workspace option was turned on, then the OK button will be disabled until a comment is entered.

    Undo Check Out...
    This option is only enabled when the object is checked out to the current user. Selecting this option will present a dialog similar to Check In (see Figure 5). However, instead of archiving the revised version of the object, Undo Check Out will revert the object to the latest revision in the SCC repository and discard any pending changes.

    Add/Remove From Source Control...
    These two options are mutually exclusive, and only one will appear for any selected object; they both appear at the PBL and Target level. If the object is not currently registered, then the "Add..." option is visible and vice versa. Selecting the Add option will register version 1.0 of the object into the SCC repository, and the "Remove..." option will unregister the object from source control. An object must be registered before it can be checked out, and must be removed from source control before it can be deleted or moved between PBLs.

    Show Differences...
    This option is enabled if the SCC tool provides a "Visual Diff" tool or allows a third-party diff tool such as WinDiff or PBDelta to be used. Selecting this option will invoke the Visual Diff utility, which will highlight any differences between the version of the object in the repository and the version currently in the PBL (first exporting the source of the object to the source folder). Figure 6 shows an example of the Visual Diff utility provided by Microsoft's Visual Source Safe.

    SCC Properties...
    This option invokes the SCC provider's "object properties" dialog. This will only be enabled for SCC tools that support this API call.

    Refresh Status
    This option will query the SCC provider for the current status of the selected object. At the PBL or Target level, the dialog will contain a list of all objects that exist at that level, with all the checkboxes defaulted on.

    Other New SCC Artifacts
    There are several new filetypes that were created as a part of the new SCC architecture. This section will describe the purpose and content of each of these files.

    .PBG Files
    These are used to relate an object to the PBL in which it belongs. These are created during the Add to Source Control operation, and are automatically maintained by PowerBuilder. An excerpt from a typical .PBG file is shown here:

    Save Format v3.0(19990112)
    @begin Libraries
    "PEAT\\peat.pbl" "";
    @begin Objects
    "PEAT\\pfc_n_cst_explorer.sru" "PEAT\\peat.pbl";
    "PEAT\\d_ds_projectsummary.srd" "PEAT\\peat.pbl";

    Note that the path and filenames are relative references. These references are relative to the "Local Root Folder", which contains the Workspace file. In this example, the PEAT.pbl resides in the \PEAT subfolder under the root folder.

    As objects are added or removed from source control, the .PBG file will be automatically updated to reflect the current object list. This file will be versioned in the SCC repository along with all the other PB objects.

    .PBC Files
    This file is the offline status cache and is used by PB when working in "offline" mode.

    .PRP Files
    These files are used by PBNative to manage the checkout/check-in process. Every object registered in the PBNative repository will have a corresponding .PRP file. The Check Out operation updates the object's .PRP file with the developer's user ID and marks the object as checked out. This file is subsequently updated and this data is cleared upon check in.

    For PBNative users, these files and the exported source files serve as the "repository" and must be placed into a folder on a shared LAN drive. Do not edit or delete these files from the archive folder, as that would cause PBNative source control to fail.

    This article is based on PowerBuilder 9 Client/Server Development by Bill Green, Paul Horan, et al, ISBN 0672325004. This book will be published by Sams Publishing in March, 2003. Also look for PowerBuilder 9 Internet and Distributed Application Development, also coming March 2003.

  • 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 (0)

    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.