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 machine 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 machines be the same in relation to the local root
directory where the PowerBuilder workspace resides.
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 machines 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 targets require that all PBLs listed in a target
library list be present on the local machine. 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. Getting the latest version of all targets in a 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
projects with multiple PBLs and complicated inheritance schemes,
but it can be used for Web targets. A better way for developers
to add source-controlled Web targets to their workspaces is to use
the Source Controlled Web Target wizard on the Target page of the
New dialog box.
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 machine 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 machine, the directory structure below the root directory
must be the same on all machines 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 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 machine before adding the targets
to PowerBuilder. (Otherwise, the target PBLs may need to be manually
rebuilt and regenerated.)
Developers can use the Source Controlled Web Target wizard
to add Web targets to their workspaces. The wizard creates subdirectories
in the local root path and populates the subdirectories with the
latest version of the Web target source files from the source control
server.
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 required for Perforce and 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.