About source control systems
This section provides an overview of source control systems
and describes the PowerBuilder interface (API) to such systems.
What source control systems do
Source control systems (version control systems) track and
store the evolutionary history of software components. They are
particularly useful if you are working with other developers on
a large application, in that they can prevent multiple developers
from modifying the same component at the same time. You can make
sure you are working with the latest version of a component or object
by synchronizing the copy of the object you are working on with
the last version of the object checked into the source control system.
Why use a source control system
Most source control systems provide disaster recovery protection
and functions to help manage complex development processes. With
a source control system, you can track the development history of
objects in your PowerBuilder workspace, maintain archives, and restore
previous revisions of objects if necessary.
Source control interfaces
You work with a source control system through a source control
interface. PowerBuilder supports
source control interfaces based on the Microsoft Common Source Code
Control Interface Specification, Version 0.99.0823. You can use
the PowerBuilder SCC API with any source control system that implements
features defined in the Microsoft specification.
PowerBuilder institutes source control at the object level.
This gives you a finer grain of control than if you copied your PBLs directly to source control
outside of the PowerBuilder SCC API.
No other interfaces PowerBuilder does not support working with source control
systems through proprietary interfaces provided by source control
vendors. To work with source control systems from your PowerBuilder
workspace, you must use the PowerBuilder SCC API. PowerBuilder also
uses this API to connect to the PowerBuilder Native check in/check
out utility that installs with the product.
Using your source control manager
The PowerBuilder SCC API works with your source control system
to perform certain source control operations and functions described
in the next section. Other source control operations must be performed
directly from the source control management tool. After you have
defined a source control connection profile for your PowerBuilder
workspace, you can open your source control manager from the Library
painter.
To start your source control manager from PowerBuilder
-
Select Entry>Source Control>Run Source
Control Manager from the Library painter menu bar.The menu item name varies depending on the source control
system you selected in the source control connection profile for
your current workspace. There is no manager tool for the PBNative
check in/check out utility.For information on configuring a source control connection
profile, see “Setting up a connection
profile”.
Which tool to use
The following table shows which source control functions you
should perform from your source control manager and which you can
perform from PowerBuilder:
| Tool or interface | Use for this source control functionality |
|---|---|
| Source control manager |
|
| PowerBuilder SCC API |
|
* You can perform these source
control operations from PowerBuilder for some source control systems.
Using PBNative
PowerBuilder provides minimal in-the-box source control through
the PBNative check in/check out utility. PBNative allows
you to lock the current version of PowerBuilder objects and prevents
others from checking out these objects while you are working on
them. It provides minimal versioning functionality, and does not
allow you to add comments or labels to objects that you add or check
in to the PBNative project directory.
Connecting to PBNative
You connect to PBNative from PowerBuilder in the same way
you connect to all other source control systems: through the PowerBuilder
SCC API. You use the same menu items to add, check out, check in,
or get the latest version of objects on the source control server.
However, any menu item that calls a source control management tool
is unavailable when you select PBNative as your source control system.
Because there is no separate management tool for PBNative,
if you need to edit project PBG files that get out of sync, you
can open them directly on the server without checking them out of
source control.
For more information about PBG files, see “Editing the PBG file for
a source-controlled target”.
PRP files
PBNative creates files with an extra PRP extension for every
object registered in the server storage location. If an object with
the same file name (minus the additional extension) has been checked
out, a PRP file provides the user name of the person who has placed
a lock on the object. PRP files are created on the server, not in
the local path.
PowerBuilder also adds a version number to the PRP file for
an object in the PBNative archive directory when you register that
object with PBNative source control. PowerBuilder increments the
version number when you check in a new revision. The version number
is visible in the Show History dialog box that you open from the
pop-up menu for the object, or in the Library painter when you display
the object version numbers.
For more information on the Show History dialog box, see “Displaying the source control
version history”. For information
on displaying the version number in the Library painter, see “Controlling columns that
display in the List view”.
Using Show Differences functionality with PBNative PBNative has an option that allows you to see differences
between an object on the server and an object on the local computer
using a 32-bit visual difference utility that you must install separately.
For information on setting up a visual difference utility for use
with PBNative, see “Comparing local objects
with source control versions”.
Constraints of a multi-user environment
Any object added or checked into source control should be
usable by all developers who have access permissions to that object
in source control. This requires that the local paths for objects
on different computers be the same in relation to the local root
directory where the PowerBuilder workspace resides.
Best practices
The source control administrator should decide on a directory
hierarchy before creating a source-controlled workspace. The following
practices are highly recommended for each target under source control:
- Create a top-level root directory for the local
project path on each developer workstation.
This directory becomes the project path in the SCC repository.
The local workspace object (PBW), the offline
status cache file (PBC), the source control
log file, and any Orcascript files used to rebuild and refresh the source-controlled
targets should be saved to this top-level directory on local workstations - Create a unique subdirectory under the project path
for each PBL in the source-controlled
targets
This practice avoids issues that can arise if you copy or
move objects from one PBL to
another in the same target. - Instruct each developer on the team to create a
workspace object in the top-level directory and, on the
Source Control tab of the Properties of Workspace dialog box, assign
this directory as the “Local Project Path”. Each developer must
also assign the corresponding top-level directory in the SCC repository
in the “Project” text box of the Source Control tab for the workspace - Add target files (PBT) to the
project path directory or create unique subdirectories under the
project path for each target file
Project manager’s tasks
Before developers can start work on PowerBuilder objects in
a workspace under source control, a project manager usually performs
the following tasks:
- Sets up source control
projects (and archive databases) - Assigns each developer permission to access the
new project - Sets up the directory structure for all targets
in a project
Ideally, the project manager should create a subdirectory
for each target. Whatever directory structure is used, it should
be copied to all computers used to check out source-controlled objects. - Distributes the initial set of PBLs and target (PBT) files to all
developers working on the project or provides a network location
from which these files and their directory structure can be copied.
PowerScript and .NET targets require that all PBLs listed in a target library
list be present on the local computer. For source control purposes,
all PBLs in a target should
be in the same local root path, although they could be saved in separate
subdirectories. PBWs and PBLs are
not stored in source control unless they are added from outside
the PowerBuilder SCC API. They cannot be checked into or out of
source control using the PowerBuilder SCC API.
If you are sharing PBLs in
multiple targets, you can include the shared PBLs in
a workspace and in targets of their own, and create a separate source
control project for the shared objects. After adding (registering)
the shared PBL objects to this
project, you can copy the shared targets to other workspaces, but the
shared targets should not be registered with the corresponding projects
for these other workspaces. In this case, the icons indicating source
control status for the shared objects should be different depending
on which workspace is the current workspace.
For small projects, instead of requiring the project manager
to distribute PBLs and target
files, developers can create targets in their local workspaces having the
same name as targets under source control. After creating a source
control connection profile for the workspace, a developer can get
the latest version of all objects in the workspace targets from
the associated project on the source control server, overwriting
any target and object files in the local root path. (Unfortunately,
this does not work well for large PowerScript or .NET projects with
multiple PBLs and complicated
inheritance schemes.)
Ongoing maintenance tasks of a project manager typically include:
- Distributing any target (PBT) files and PBLs that are added to the workspace
during the course of development, or maintaining them on a network
directory in an appropriate hierarchical file structure - Making sure the PBL mapping
files (PBGs) do not get out of sync
For information about the PBG files, see “Editing the PBG file for
a source-controlled target”.
Connections from each development computer to the source control
project can be defined on the workspace after the initial setup
tasks are performed.
Developers’ tasks
Each user can define a local root directory in a workspace
connection profile. Although the local root directory can be anywhere
on a local computer, the directory structure below the root directory
must be the same on all computers that are used to connect to the
source control repository. Only relative path names are used to
describe the location of objects in the workspace below the root
directory level.
After copying the directory structure for source-controlled
PowerScript or .NET targets to the local root path, developers can
add these targets to their local workspaces. The target objects
can be synchronized in PowerBuilder, although for certain complex
targets, it might be better to do the initial synchronization through
the source control client tool or on a nightly build computer before
adding the targets to PowerBuilder. (Otherwise, the target PBLs may need to be manually rebuilt
and regenerated.)
For more information about getting the latest version of objects
in source control, see “Synchronizing objects with
the source control server”.
Extension to the SCC API
Status determination by version number
PowerBuilder provides third-party SCC providers with an extension
to the SCC API that allows them to enhance the integration of their
products with PowerBuilder. Typically, calls to the SccDiff method
are required to determine if an object is out of sync with the SCC
repository. (This is not appropriate for Perforce or ClearCase.)
However, SCC providers can implement SccQueryInfoEx as
a primary file comparison method instead of SccDiff.
The SccQueryInfoEx method returns the most recent
version number for each object requested. This allows PowerBuilder
to compare the version number associated with the object in the PBL with the version number of the
tip revision in the SCC repository in order to determine whether
an object is in sync.
Since SccQueryInfoEx is a much simpler
request than SccDiff, the performance of the
PowerBuilder IDE improves noticeably when this feature is implemented
by the SCC provider. For these providers, the SccDiff call
is used as a backup strategy only when a version number is not returned
on an object in the repository. Also for these providers, the version
number for registered files can be displayed in the Library painter.
For more information on viewing the version number, see “Controlling columns that
display in the List view”.
Once the new API method is implemented in an SCC provider
DLL and exported, PowerBuilder automatically begins to use the SCCQueryInfoEx call with
that provider. The SccQueryInfoEx method is currently
used by PBNative.
Overriding the version number
For source control systems that support the SccQueryInfoEx method,
you can manually override the version number of local files, but
only for PowerScript objects, and only when you are connected to
source control.
This can be useful with source control systems that allow
you to check out a version of an object that is not the tip revision.
However, the source control system alone decides the version number
of the tip revision when you check a file back into source control.
It is the version returned by the source control system that gets
added to the PBC file for the workspace and to the PBLs in the local directory.
For more information about the PBC file, see “Working in offline mode”.
You change the local version number for a source-controlled
PowerScript object in its Properties dialog box, which you access
from the object’s pop-up menu in the System Tree
or the Library painter. If the source control system for the workspace
supports the SccQueryInfoEx method and you are
connected to source control, the Properties dialog box for a source-controlled
PowerScript object (other than a PBT) has an editable SCC Version
text box. The SCC Version text box is grayed if the source control
system does not support the SccQueryInfoEx method
or if you are not connected to source control.
Local change only The version number that you manually enter for an object is
discarded on check-in. Only the source control provider decides
what number the tip revision is assigned.