VisualAge TeamConnection integration to the Microsoft Source Code
Control Application Programming Interface

Taylor Schock, Lee Perlov, Angel Rivera VisualAge TeamConnection Development
IBM Software Solutions
Research Triangle Park, North Carolina, USA
March 23, 1999

Abstract

This technical report provides information about how to exploit the Microsoft Source Code Control Application Programming Interface (SCC API) enablement within VisualAge TeamConnection Enterprise Server Version 3. This function allows users to store parts in TeamConnection from several Integrated Development Environments (IDEs), among them: Microsoft Visual Studio, Sybase PowerBuilder, MERANT NetExpress, and IBM VisualAge for Java.

• VisualAge TeamConnection
• Source Code Control API
• SCC API
• Integration

The most up to date version of this technical report can be obtained as follows:

• By selecting the item Library from the IBM VisualAge TeamConnection Enterprise Server home page.
• From the IBM VisualAge TeamConnection Enterprise Server FTP site.

See the file README.index.txt for details.

We would like to thank John Suchy for reviewing this document and for providing many useful comments and suggestions to improve its readability. 

Abstract

About the Authors

Using VisualAge TeamConnection Enterprise Server Version 3 with Integrated Development Environments (IDE)

• How TeamConnection Manages Tasks
• Process Control Features
• Integration Overview
• Workarea Refresh
• Managing Shadows
• Shadow Commands
• The VisualAge TeamConnection SCC API Interface
• Requirements and Supported IDEs
• Concepts
• Environment Variables
• TC_SCCCASE
• TC_SCCDIFFSET
• TC_SCCREPORT
• TC_SCCLOG
• TC_SCCWRAPLOG
• TC_SCCDISPERR
• Event Logging
• IBM Visualage for Java
• Typical Scenario
• Serial development with VisualAge for Java
• Concurrent development with VisualAge for Java
• Naming Convention and Description Matrix
• MERANT NetExpress
• Typical Scenario
• Serial development with NetExpress
• Concurrent development with NetExpress
• Unique Features 
• Naming Convention and Description Matrix
• Microsoft Visual Basic
• Typical Scenario
• Serial development with Visual Basic
• Concurrent development with Visual Basic
• Unique Features
• Naming Convention and Description Matrix
• Microsoft Visual C++
• Typical Scenario
• Serial development with Visual C++
• Concurrent development with Visual C++
• Unique Features
• Synchronizing Visual C++ with TeamConnection
• Relationship of the Working Directories
• Naming Convention and Description Matrix
• Sybase PowerBuilder
• Serial development with PowerBuilder
• Concurrent development with PowerBuilder
• Using a Network PBL
• Naming Convention and Description Matrix

Copyrights, Trademarks and Service Marks

Integrated Development Environments (IDEs) provide ease of use and improved productivity for small groups of developers. The IDEs simplify many of the programming tasks that can be cumbersome without the assistance of a highly customized GUI. This saves time and allows developers to focus on solving problems.

However, these tools that make small groups very efficient require the appropriate infrastructure to be effective when scaling a development effort to dozens, hundreds or even thousands of developers. Questions like, "Who has the most current version of an object/file?" and "What version of each part is required in order to make up a complete application?" can become daunting tasks to resolve.

IBM VisualAge TeamConnection Enterprise Server Version 3 is designed specifically for managing the development efforts of large groups. TeamConnection supports the Source Code Control (SCC) API interface in order to work with IDEs such as IBM VisualAge for Java, Sybase PowerBuilder, Microsoft Visual Studio, and MERANT NetExpress. TeamConnection provides the structure that allows developers to be highly productive within their IDE, while coordinating their effort with the efforts of the other developers on the team. Further, this allows developers that are not using an IDE to work with developers who are using one.

In TeamConnection, there are some basic concepts that are common to all users:

• All users developing a product together work in the same TeamConnection Release.
• Each developer deals with one problem (a TeamConnection Defect) or idea (a TeamConnection Feature) at a time.
• In order to make a change to a release, each developer opens a TeamConnection Workarea for a defect or feature in that release.
• In order to functionally decompose the release, the TeamConnection Parts are managed by TeamConnection Components.
• Developers open their own new project in their IDE and reference the release, the component, and the workarea using the menus that access the SCC API.
• Developers perform their normal activities in the IDE, allowing the SCC API to check parts into and out of TeamConnection.
• Once the development is complete, the workarea is moved to Integrate state and added to a TeamConnection Driver, so that the collected work of the team can be gathered together to incrementally enhance the baseline of the release.
• A build administrator opens a new project, pointing to the driver so that the integrated parts can be extracted using the SCC API, and the entire release built.
• Once the build administrator has a valid build, the driver is committed and completed so that testing can begin.
• The new driver is tested, defects are written and the process is repeated.

Of course, there are unique behaviors for each IDE and the details of using each one will be covered in the following sections. 

VisualAge TeamConnection has a wide range of process control features that can impact the usability of an IDE.

Once the release, component, and workarea are defined through the menus of the IDE that access the SCC API, the user can then begin to add parts through the IDE's user interface. After the parts are created, they can be checked in and out along with additional actions such as difference comparison, part history information, etc.

Serial development environment

In a serial environment, when a second user attempts to perform an action on a part that is in a state for which the action is not allowed, an error or warning message appears indicating the problem with the requested action. For example, when a user has a part checked out, a second user will not be able to check out that same part and an appropriate message will be displayed to the second user. Once the first user has checked in the part, the second user can then check out the part and make changes as needed.

Concurrent development environment

Concurrent development is an option that allows multiple developers to update the same part in the same release without linking the part from the previously updated and uncommitted version. Any conflicts caused by updating parts in more than one workarea are resolved when the workareas are added to the driver.

For example, User1 might create workarea1 for a specified part in a given component and release. User2 would then need to create a different workarea (e.g. workarea2) in order to check out the same part. In this scheme, multiple users can perform concurrent development on a given part. As individual users complete development on the part independently, they can check the part back into TeamConnection.

When the workareas are then integrated into a driver, a Collision Record is created that will have to be resolved by a user, possibly merging different versions of the affected part. Once the integration of the workareas is done, the merged part is now the latest copy and can be used again in the same manner as described previously.

As of VisualAge TeamConnection Enterprise Server, fixpak 302 (fp302), specifying the verbose option will report when a part has already been modified in an active workarea. This allows developers to refresh from another workarea, or plan for integration of changes.

Merging multiple versions of a changed part can be performed by the VisualAge TeamConnection Merge Utility, tcmerge, if the changed part is text-based, such as procedural code written in Cobol, C or C++.

Concurrent vs. Serial considerations

When using an IDE and the SCC API, you may encounter the following limitations on the reconciliation of collisions:

• None of the IDEs that support the SCC API can process more than one version of a single part, so more than one IDE must be opened, each containing a different version of the part. Then cut-and-paste must be used to manually merge the version.
• Some IDEs, such as PowerBuilder, do not export full source copies of the file, so the merge cannot be performed outside of the IDE.
• More detail on working with parts in concurrent mode is provided in the VisualAge TeamConnection Enterprise Server User's Guide

Because the Build Administrator is typically responsible for resolving collision records, the build process of the development cycle will take longer when concurrent development is used.

In order to reduce the development cycle, it is recommended to:

• Provide the MemberCreate and MemberDelete actions to the the authority groups used by developers, such as developer+
• Use the teamc driver -restrict action to prevent developers from changing the content of a driver prior to an integration build or test
• Require that developers perform their on resolution of collision records, including the use of tcmerge

Managing links between Releases

The current VisualAge TeamConnection SCC API automatically breaks links between releases when a part is checked into a workarea. This is the same behavior as setting the release to the -coupling loose option. However, parts can be relinked after check in.

Use of Shadowing to populate projects

For some IDEs that support the SCC API, it is more efficient to extract the contents of a workarea or a release into a directory prior to opening a new project in the IDE. This allows the project to register all of the parts in the current version of the workarea prior to checking out any parts. For tools such as MERANT NetExpress, this is more efficient than creating the project first.

VisualAge TeamConnection provides a command line interface for creating a shadow of a workarea or a release. A shadow is an extracted copy of all of the parts in that workarea or release. The shadowing facility can keep the contents of the shadow directories synchronized with the contents of the workarea or release, which means that all changes are reflected in the shadow.

In addition, some IDEs support using script files that are read when the tool or a project is opened. This can be used to extract files to the project directory. Again, the use of shadows will limit the number of files that need to be extracted.

Other features of the TeamConnection SCC API that benefit IDE users

TeamConnection line commands issued by the use of the SCC API can be logged. This allows developers to learn about the TeamConnection command line interface in order to write tools that issue line commands. More details on logging line commands are provided in Environment Variables

This is the typical integration scenario for VisualAge TeamConnection and an IDE that uses a project directory.  It provides for Unit Test build and Integration Test build, as well as the normal interaction between an IDE and a TeamConnection workarea.

The developer uses the IDE to perform updates to the code (e.g. C++, HTML), storing the results in a VisualAge TeamConnection Enterprise Server family. The build administrator uses TeamConnection to manage the build of a complete product, organizing the data from workareas into drivers. The drivers are committed and delivered to production, either manually or using TeamConnection to automate the process.

When a user refreshes the workarea associated with a project from another context (that is, a workarea, a driver or a release), the parts identified as changed for that workarea are updated to reflect the changes in the other context. This includes the command teamc part -link.

To update the project to have all of the same versions of each part as the workarea, all of the parts that were added to the workarea view need to be extracted to the project directory, by performing the following actions:

• Query for changes in workarea:

  teamc report -view partView -workarea XXX -release YYY -where "workAreaName is not NULL"

• Extract changes in workarea:

  teamc release -extract YYY -version XXX -delta -root ProjectDirectory 

Shadowing can be controlled manually or configured to automatically update upon each change. For example, a release shadow would automatically update each time a driver is committed. In the case where drivers are not used, the shadow would be updated each time a workarea is integrated to the release.

It is recommended that drivers be used in order to incrementally update the release. This provides a baseline for testing that will not change over time. Therefore, it is always possible to go back to that version of the release and understand what has subsequently changed.

By using the driver type field, it is possible to describe how a driver is used. For example, development, integration test, acceptance test and production. When using driver type effectively, manually synchronizing the release shadow whenever a driver of type production is committed, developers will be able to build their changes on top of the production release without extracting it.

# Define a program to use by shadowing facility
teamc shadow -define shadow2 -family testfam -description "Shadow for Release using TCshadow.c with debugging"
             -program e:\teamc\testfam\TCshadow.exe -verbose

# Create a specific shadow instance for shadowing the committed version of Release
# concurrent1 to a directory where the Web page can access the files
# NOTE: If only Drivers of type "production" are to be copied to the shadow,
#       as in the case of publishing to the web, it is recommended that the
#       shadow be created as "manual".
teamc shadow -create relshad1 -family testfam -release concurrent1 -type shadow2 -location e:\teamc\testfam\$N\$R\$P
             -contents release -synchronous -timestamp preserve -priority 100 -verbose


# Activate shadowing for the committed Release
teamc shadow -enable relshad1 -family testfam -release concurrent1 -verbose

# Force the first copy of the shadowed files into the directory structure
# - All subsequent updates will occur during "teamc driver -commit"
teamc shadow -synchronize relshad1 -family testfam -release concurrent1 -force -verbose

The SCC API acts as a connection between TeamConnection and the IDE. IDEs that support the SCC API architecture can perform typical source code control functions with TeamConnection as the source repository. TeamConnection also acts as the control for the parts in the repository. The IDE may have some control over parts within its own working environment, primarily in respect to how a part is managed within the IDE's concept of the project in which that part resides.

Some IDEs also keep their own "local" information as to the status of the parts within the project which may not be the current status of the parts within TeamConnection; however, the IDE may also provide a method in order to synchronize the local copy with the one stored in TeamConnection. The supported functions are accessed via the IDE's GUI.

The TeamConnection SCC API interface requires that the TeamConnection Client be installed along with the IDE. When an SCC call is issued through the IDE's GUI, it is translated into a TeamConnection command which is then issued as any other valid TeamConnection commands. The SCC API interface is available with the TeamConnection Client on the following platforms:

• Windows NT
• Windows 95
• Windows 98

More and more IDEs are adding SCC integration to their products. While this increases the flexibility and availability of integrating a particular IDE with TeamConnection, it also requires that TeamConnection validate that the newly integrated IDE works as specified. In theory any IDE that adheres to the SCC specifications should work, however testing has revealed that the various IDEs access the SCC APIs in different ways and for different purposes. For example, one IDE may use an API call to generate a list of available parts that can be selected to perform checkin, checkout, etc. while another IDE may use the same call ONLY as a method of determining if the parts exist in TeamConnection.

The IDEs that use the SCC APIs are broken down into three different groups:

• Supported - An IDE that is fully supported and has had extensive integration testing performed as part of the TeamConnection testing procedure.
• Tested - An IDE that has had some basic SCC functional testing (such as checkin and checkout) but has not been integrated into the TeamConnection testing procedure.
• Compliant - An IDE that has incorporated the SCC APIs but has not be tested with TeamConnection.

A list of IDEs and an indication into which group they fall is listed below.

In all cases, when using an IDE that supports the SCC API interface with TeamConnection, it is necessary to set a context to identify the Family, Release, Workarea, and Component to be used when the SCC API issues TeamConnection line commands such as:

• teamc report ... (for queries), or
• teamc part ... (for check-in, check-out, extract, etc)

Most of the basic concepts for source control management are available in all the IDEs that support the SCC interface. While functional naming conventions may vary from one IDE to another, the following is a list of TeamConnection supported functions with a brief description:

• Check-In - Check a part into TeamConnection that is currently locked by the user.
• Check-Out - Check out (and lock) a part from TeamConnection into the current project in the IDE.
• Create - Add a part that exists in the IDE to TeamConnection; the added part would then be under source control.
• Delete - Remove a part from source control (removing it from TeamConnection), but not necessarily removing it from the IDE.
• Extract - Get a copy of the latest version of a part; the part is not locked but can be browsed.
• Uncheck-out - Unlocks the selected part, allowing it to be checked-out by subsequent users.
• Show History - Display a history of the selected part.
• Compare - Display the differences between the local copy of the selected part and the one stored in TeamConnection.
• Run - Invokes a copy of the TeamConnection GUI.
• Show Properties - Display the SCC TeamConnection Properties dialog for the current project.

Some IDEs may have unique functions that use the SCC API calls while other IDEs may not supply a similar function. For example, PowerBuilder has an entry that allows the ability to display a list of the parts in TeamConnection. From this list the user can then select parts to extract or retrieve the history information for the selected parts.

Workareas are created in order to make changes to a part. Other items, such as a release, are needed in order to determine the exact version of the part that will be used. This collection of information is accessed anytime a project is opened through the TeamConnection Settings dialog. The following values are found in this dialog:

• Project Name
• Family Name
• TCP/IP Host Name
• Port Address
• Release
• Component
• Workarea
• User
• Working Directory

The TeamConnection Settings Project Name is not equivalent to an IDE project name (although it may be beneficial to keep these the same in order to reduce confusion), but is simply a unique identifier that defines the combination of the other parameters. There can be multiple project names with the exact same release, component, etc., or there can be various project names where the only difference is the workarea. The list of project names, along with all their associated parameters, are stored in a file so users only need to enter certain information (family name, for example) one time and apply those values to any new project names they create. This also makes it easier to change only the workarea information when the user is finished working in one workarea and wishes to move on to another.

Once the values are entered for the TeamConnection Settings dialog, all subsequent functions are called through the GUI of the IDE, and, for the most part, the interaction with TeamConnection is transparent to the user. Most IDEs have the ability to use both menu options and context sensitive options (using mouse button 2 from a selected object) to perform a task on the object. In most cases the task can be performed on multiple objects. While the concepts of source code control are the same across all IDEs, items such as functional naming conventions and the availability of certain functions will vary from one IDE to another. The appearance and uniqueness of each IDE will be discussed further.

There are a number of environment variables available to the TeamConnection SCC interface that allow the user to customize the operation of the TeamConnection with the IDE. These variables need to be set before the IDE is invoked since they are read when the TeamConnection SCC interface is loaded and in most cases, the IDE loads the SCC interface during the initialization of the IDE. Below is a list of the variables along with the accepted values and a brief description.

Each TeamConnection command that is generated via the SCC interface is logged into the teamc.log file located in the bin directory of the TeamConnection client. If the user is not using the TeamConnection GUI or directly the TeamConnection line commands, then it is fairly simple to follow the flow of calls that were made from the IDE. However, if the user is using the TeamConnection GUI, then it might be confusing to interpret the events in the log because there is no way to determine whether the TeamConnection command was issued from the TeamConnection GUI or from the SCC interface. In order to determine if the call was made from the SCC interface, the user would need to add the TC_SCCLOG environment variable. 

IBM VisualAge for Java has no "local" knowledge of the status of parts that are under source control. There are no icons in the VisualAge for Java GUI that indicate whether or not the part is under source control, or the status of any part that is under source control, whether or not it is checked out. A part that was placed under source control by one user may not be recognized as such by another user on another machine

VisualAge for Java, unlike most IDEs, does not have its own "local" knowledge of the status of parts that are under source control. It queries TeamConnection for the status of all the selected files whenever the user performs any source control action on the an object within the IDE. In addition, VisualAge for Java will initialize and uninitialize the SCC interface multiple times within a session in order to maintain a synchronization of status with TeamConnection. This results in the TeamConnection Settings dialog to appear multiple times during a session. It is recommended that the user just select the OK and continue working.

The user must first connect to TeamConnection by selecting Project -> Tools -> External SCM -> Change Connection. This produces and SCM Connection dialog that requires an entry for the Project Name and the Work Directory. The Project Name is the value used to identify the group of TeamConnection Settings for that project. The user must press the Change button and enter the appropriate values in the TeamConnection Settings dialog. The Work Directory is the directory that VA Java places working copies of its files.

Once the user has connected to the TeamConnection, the latest copies of the parts under source control can be obtained by selecting Project -> Tools -> External SCM -> Get Latest to access the files based on the TeamConnection settings supplied previously. All selected files with then be extracted into the Working Directory. At this point, any function selected that requires interaction with TeamConnection will query the file in TeamConnection before that action is performed, and the TeamConnection Settings dialog will be displayed.

When an error is encountered, a message is displayed to the user by VisualAge for Java. For example, if a user attempts to add a part to source control that was already added by another user in a previously committed Workarea, TeamConnection informs VisualAge for Java that this part already exists, and VisualAge for Java informs the user.

Once the Release, Component, and Workarea(s) are defined through TeamConnection, the user can then begin to add parts through the VisualAge for Java interface. Additional actions can be taken as desired, such as difference comparison, file history information, etc., through the VisualAge for Java interface.

In a serial environment, when a second user attempts to perform an action on a part that is in a state for which the action is not allowed, an error/warning message appears, indicating the problem with the requested action. For example, when a user has a part checked out, a second user will not be able to check out that same part, and an appropriate message will be displayed to the second user. Once the first user has checked in the part, the second user can then check out the part and make changes as needed.

Any conflicts that may occur are resolved by TeamConnection and reported back to the VisualAge for Java interface. Such conflicts will be reported in a message to the user.

As with serial development, in a concurrent development scheme the release, component, and workarea(s) are defined through TeamConnection, and users can then begin to work with parts in the same manner.

For example, User1 might create workarea1 for a specified part in a given component and release. User2 would then need to create a different workarea (workarea2, for example) in order to check out the same part. In this scheme, multiple users can perform concurrent development on a given part. As individual users complete development on the part independently, they can check the part back into TeamConnection using the check in command in the VisualAge for Java interface.

At this point, the user actions are dependent upon whether a single or multiple workareas were involved.

In a single workarea scenario, the first User to issue the check in command checks the changed part back in. Each subsequent check in creates a collision record that will have to be resolved by merging the two versions of the changed part into a third version. The third version becomes the latest copy.

In a multiple workarea scenario (each user has checked the part out from a separate workarea), each user issues the check in command. However, when the workareas are then integrated into a driver, a collision record is created that will have to be resolved. Once the integration has been done, the merged part is now the latest copy and can be used again in the same manner as described previously.

The following table lists the naming convention for the SCC functions available from within the VisualAge for Java Workspace Window. Most of the SCC functions listed are found under the menu option Project -> Tools -> External SCM (or by using the second mouse button on the selected part) with the expected results:

NetExpress attempts to keep its own "local" copy of the project parts in synch with the status of parts that are under source control. This "local" status of a part may not be the same status recognized by TeamConnection (which is the "true" status), but NetExpress queries TeamConnection whenever a project is opened in order to synchronize the status of parts in the opened project with the status of the parts stored in TeamConnection. This is done to accommodate the fact that NetExpress is designed based on a single-user model, rather than a model that anticipates multiple users working within the same project.

NetExpress recognizes this situation and resolves such conflicts by querying the source control provider (TeamConnection) and updating local versions of the parts based on the information returned from the provider. Whenever the user requests to perform an action on a part, NetExpress not only queries TeamConnection on the status of the selected part, but it queries for all parts in TeamConnection (based on the current TeamConnection settings) that are available for that selected action and a list of these parts are displayed to the user. From this list the user can select additional parts for the currently selected action.

NetExpress, unlike most IDEs, does not have its own "local" knowledge of the status of parts that are under source control. It queries TeamConnection for the status of all the parts in the NetExpress project. Parts may be created by one user through NetExpress using the SCC TeamConnection interface and accessed by a second user through the NetExpress interface. This allows the second user to add files to an existing NetExpress project with no prior knowledge of pre-existing or newly created files.

The user can also create a new project by selecting File -> New -> Project. By selecting Source Control -> Connect to Source Control the user will be prompted to input the TeamConnection settings to access the desired project. The user selects Source Control -> Get Latest Version to access the files based on the TeamConnection settings supplied previously. A dialog will be displayed with the list of files available to be extracted. Once the user extracts the desired files, Project -> Add Files to Project allows the user to select which files are to be added to the NetExpress project.

At this point, the list of files in the project will indicate what state they are in within TeamConnection (such as checked out, available, etc). Whenever an action is performed on a file that is under source code control, NetExpress queries the status of all the files within that project. For example, if a user attempts to add a part to source control that was already added by another user in a previously committed workarea, TeamConnection informs NetExpress that this part already exists, and NetExpress informs the user and provides the opportunity to update that file in the NetExpress project area.

In both serial and concurrent development, all part changes can be made in one workarea. But, in order to track those changes (for example, through a defect or feature), a workarea must be created for each change. Using TeamConnection subprocesses, a workarea can be created a defect or feature is accepted. This workarea will be named after the associated defect or feature.

The following subsections briefly describe the two modes of development.

Once the Release, Component, and Workarea(s) are defined through TeamConnection, the user can then begin to add parts through the NetExpress interface. Additional actions can be taken as desired, such as difference comparison, file history information, etc., through the NetExpress interface.

In a serial environment, when a second user attempts to perform an action on a part that is in a state for which the action is not allowed, an error/warning message appears, indicating the problem with the requested action. For example, when a user has a part checked out, a second user will not be able to check out that same part, and an appropriate message will be displayed to the second user. Once the first user has checked in the part, the second user can then check out the part and make changes as needed.

Any conflicts that may occur are resolved by TeamConnection and reported back to the NetExpress interface. Such conflicts will be reported in a message to the user.

As with serial development, in a concurrent development scheme the release, component, and workarea(s) are defined through TeamConnection, and users can then begin to work with parts in the same manner.

For example, User1 might create workarea1 for a specified part in a given component and release. User2 would then need to create a different workarea (workarea2, for example) in order to check out the same part. In this scheme, multiple users can perform concurrent development on a given part. As individual users complete development on the part independently, they can check the part back into TeamConnection using the check in command in the NetExpress interface. At this point, the user actions are dependent upon whether a single or multiple workareas were involved.

In a single workarea scenario, the first User to issue the check in command checks the changed part back in. Each subsequent check in creates a collision record that will have to be resolved by merging the two versions of the changed part into a third version. The third version becomes the latest copy.

In a multiple workarea scenario (each user has checked the part out from a separate workarea), each user issues the check in command. However, when the workareas are then integrated into a driver, a collision record is created that will have to be resolved. Once the integration has been done, the merged part is now the latest copy and can be used again in the same manner as described previously.

MERANT NetExpress provides the following capabilities when using the SCC API with TeamConnection :

• Users can set up a new project using a startup script file.
• Users can populate a project by referencing a directory that already contains files.
• The TeamConnection Shadowing feature can be used to automatically extract to a directory (synchronizing) prior to creating the startup script that creates a new project and references the directory.

As with any IDE, it is more efficient for the project to track only those parts that are likely to change, not all of the parts in a release. However, all of the parts need to be accessible for compiles and links. The recommended solution is to set the environment variables for NetExpress to look first in the project directory, then to look into another directory that contains the source and output parts that are in the currently committed version of the release. To do this, a second shadow, for the committed release is also needed.

If the workarea changes are not shadowed to the project directory, it is necessary to extract any parts that are linked or refreshed from other workareas. This is most easily performed by executing a query for changed parts in the current workarea within a user exit on PartLink, PartRefresh and WorkareaRefresh that reports the parts changes caused by links within the current workarea. The user would then execute the part extract commands would be performed manually. The automated alternative would be to mount a drive from all workstations so that the user exit could extract to the server, delivering the files to the mounted drives.

The following table lists the naming convention for the SCC functions available from NetExpress Window along with the expected results. These functions are available from the Source Control menu option or by using the second mouse button on the selected part. Some items may not appear in both methods or may not appear due to the current state of part.

Visual Basic attempts to keep its own "local" copy of the project parts in synch with the status of parts that are under source control. This "local" status of a part may not be the same status recognized by TeamConnection (which is the "true" status), but Visual Basic queries TeamConnection whenever a project is opened in order to synchronize the status of parts in the opened project with the status of the parts stored in TeamConnection. This is done to accommodate the fact that Visual Basic is designed based on a single-user model, rather than a model that anticipates multiple users working within the same project. Visual Basic also knows what projects are under source control. When the user opens a project that is under source control, Visual Basic may request the latest version of the files from TeamConnection.

Visual Basic recognizes that the files may be out of synch and resolves such conflicts by querying the source control provider (TeamConnection) and updating local versions of the parts based on the information returned from the provider. Whenever the user requests to perform an action on a part, Visual Basic not only queries TeamConnection on the status of the selected part, but it queries for all parts in TeamConnection (based on the current TeamConnection settings) that are available for that selected action and a list of these parts are displayed to the user. From this list the user can select additional parts for the currently selected action.

As discussed previously, Visual Basic has its own "local" knowledge of the status of parts that are under source control. Parts may be created by one user through Visual Basic using the SCC TeamConnection interface and accessed by a second user through the Visual Basic interface once the files have been synchronized.

The user can also create a new project by selecting File -> New Project and then selecting the type of project. When the project is saved, a message appears asking whether to place this project under source control at which time the user will be required to fill in the TeamConnection Settings, which will probably already have information displayed in the Project Name and Working Directory fields. Once the fields have been entered, the user can select OK and the connection to TeamConnection for this project will be established.

For an existing project name, all the fields in the TeamConnection Settings dialog should already contain an entry. Any information can be added or changed at this point but a change to the Working Directory field once the settings have been saved should only be done with extreme caution. Once the project workspace is opened, files can be added/created in the Visual Basic project and added to TeamConnection along with any SCC function that is valid for that selected file. All files from this point will be accessed in TeamConnection based on the values set in the TeamConnection Settings dialog.

At this point, the list of files in the project will indicate what state they are in within TeamConnection (such as checked out, available, etc). Whenever an action is performed on a file that is under source code control, Visual Basic queries the status of all the files within that project. For example, if a user attempts to add a part to source control that was already added by another user in a previously committed Workarea, TeamConnection informs Visual Basic that this part already exists, and Visual Basic informs the user and provides the opportunity to update that file in the Visual Basic workspace area.

Once the Release, Component, and Workarea are defined through TeamConnection, the user can then begin to add parts through the Visual Basic interface. Additional actions can be taken as desired, such as difference comparison, file history information, etc., through the Visual Basic interface.

In a serial environment, when a second user attempts to perform an action on a part that is in a state for which the action is not allowed, an error/warning message appears, indicating the problem with the requested action. For example, when a user has a part checked out, a second user will not be able to check out that same part, and an appropriate message will be displayed to the second user and the status for that part will be updated in the Visual Basic window . Once the first user has checked in the part, the second user can then check out the part and make changes as needed.

Any conflicts that may occur are resolved by TeamConnection and reported back to the Visual Basic interface. Such conflicts will be reported in a message to the user.

As with serial development, in a concurrent development scheme the release, component, and workarea(s) are defined through TeamConnection, and users can then begin to work with parts in the same manner.

For example, User1 might create workarea1 for a specified part in a given component and release. User2 would then need to create a different workarea (workarea2, for example) in order to check out the same part. In this scheme, multiple users can perform concurrent development on a given part. As individual users complete development on the part independently, they can check the part back into TeamConnection using the check in command in the Visual Basic interface.

At this point, the user actions are dependent upon whether a single or multiple workareas were involved.

In a single workarea scenario, the first User to issue the check in command checks the changed part back in. Each subsequent check in creates a collision record that will have to be resolved by merging the two versions of the changed part into a third version. The third version becomes the latest copy.

In a multiple workarea scenario (each user has checked the part out from a separate workarea), each user issues the check in command. However, when the workareas are then integrated into a driver, a collision record is created that will have to be resolved. Once the integration has been done, the merged part is now the latest copy and can be used again in the same manner as described previously.

Visual Basic is not enabled directly to use the SCC APIs. There is a subset of MicroSoft SourceSafe DLLs that are required for Visual Basic to work with any source code control provider, which requires the installation of SourceSafe. Once SourceSafe has been installed, the following value needs to be updated in the Add-Ins32 section of the VBAddin.ini file.

• vbscc=3

Visual Basic also provides the following capabilities when using the SCC API with TeamConnection from the Tools -> TeamConnection -> Options menu. These options provide a way to control the interface capabilities of the Visual Basic/TeamConnection default actions. The user can specify a Yes, No, or Ask value for the following questions.

• Get latest checked-in versions of files when opening a VB project?
• Check in files when closing the VB project?
• Add files to source control when adding them to a VB project?
• Remove files from source control when deleting them from the VB project?

As with any IDE, it is more efficient for the project to track only those parts that are likely to change, not all of the parts in a release. However, all of the parts need to be accessible for compiles and links. To do this, a second shadow, for the committed release is also needed. See the information on the use of shadowing in the Process Control Features section for more information.

The following table lists the naming convention for the SCC functions available from within the Visual Basic Window. The SCC functions listed are found under the menu option Tools -> TeamConnection (or by using the second mouse button on the selected part or items that may appear under the Tools menu option) with the expected results. Some items may not appear in both methods or may not appear due to the current state of part.

MicroSoft Visual C++ is an IDE that attempts to use its own knowledge of the "local" copy of the project and its parts as the basis for what project and parts are under source control. This "local" status of a part may not be the same status recognized by TeamConnection (which is the "true" status), and there is no automated method in which to keep the status of the two in synch. This situation is due to the fact that Visual C++ is designed based on a single-user model, rather than a model that anticipates multiple users working within the same project.

As discussed previously, Visual C++ has its own "local" knowledge of the status of parts that are under source control. Parts may be created by one user through Visual C++ using the SCC TeamConnection interface and accessed by a second user through the Visual C++ interface once the files have been synchronized.

The user can also create a new project by selecting File -> New -> Projects, selecting the type of project, and entering the project name and the location of the project. A message appears asking whether to place this project under source control at which time the user will be required to fill in the TeamConnection Settings, which will probably already have information displayed in the Project Name and Working Directory fields. Once the fields have been entered, the user can select OK and the connection to TeamConnection will be established. If a dialog asking for to "Specify Working Directory" appears, it is recommended that this field be left as is and not changed.

For an existing project name, all the fields in the TeamConnection Settings dialog should already contain an entry. Any information can be added or changed at this point; however, a change to the Working Directory field once the settings have been saved should only be done with extreme caution. For more details see Relationship of the Working Directories.

Once the project workspace is opened, files can be added/created in the Visual C++ project and added to TeamConnection along with any SCC function that is valid for that selected file. All files from this point will be accessed in TeamConnection based on the values set in the TeamConnection Settings dialog.

At this point, the list of files in the project will indicate what state they are in within TeamConnection (such as checked out, available, etc). Whenever an action is performed on a file that is under source code control, Visual C++ queries the status of all the files within that project. For example, if a user attempts to add a part to source control that was already added by another user in a previously committed workarea, TeamConnection informs Visual C++ that this part already exists, and Visual C++ informs the user and provides the opportunity to update that file in the Visual C++ workspace area.

Once the Release, Component, and Workarea(s) are defined through TeamConnection, the user can then begin to add parts through the Visual C++ interface. Additional actions can be taken as desired, such as difference comparison, file history information, etc., through the Visual C++ interface.

In a serial environment, when a second user attempts to perform an action on a part that is in a state for which the action is not allowed, an error/warning message appears, indicating the problem with the requested action. For example, when a user has a part checked out, a second user will not be able to check out that same part, and an appropriate message will be displayed to the second user and the status for that part will be updated in the Visual C++ window . Once the first user has checked in the part, the second user can then check out the part and make changes as needed.

Any conflicts that may occur are resolved by TeamConnection and reported back to the Visual C++ interface. Such conflicts will be reported in a message to the user.

As with serial development, in a concurrent development scheme the release, component, and workarea(s) are defined through TeamConnection, and users can then begin to work with parts in the same manner.

For example, User1 might create workarea1 for a specified part in a given component and release. User2 would then need to create a different workarea (workarea2, for example) in order to check out the same part. In this scheme, multiple users can perform concurrent development on a given part. As individual users complete development on the part independently, they can check the part back into TeamConnection using the check in command in the Visual C++ interface. At this point, the user actions are dependent upon whether a single or multiple workareas were involved.

In a single workarea scenario, the first User to issue the check in command checks the changed part back in. Each subsequent check in creates a collision record that will have to be resolved by merging the two versions of the changed part into a third version. The third version becomes the latest copy.

In a multiple workarea scenario (each user has checked the part out from a separate workarea), each user issues the check in command. However, when the workareas are then integrated into a driver, a collision record is created that will have to be resolved. Once the integration has been done, the merged part is now the latest copy and can be used again in the same manner as described previously.

MicroSoft Visual C++ provides the following capabilities when using the SCC API with TeamConnection from the Tools -> Options -> Source Control menu. These options provide a way to control the interface capabilities of the Visual C++/TeamConnection default actions.

• Get files when opening the workspace
• Check out source file(s) when edited
• Check in files when closing the workspace
• Prompt to add files when inserted
• Perform background status updates
• Use dialog for checkout
• Add new projects to source control
• Include only selected files in dialogs

As with any IDE, it is more efficient for the project to track only those parts that are likely to change, not all of the parts in a release. However, all of the parts need to be accessible for compiles and links. One possible solution is to set the Tools -> Options -> Directories variable for Visual C++ to look first in the project directory, then to look into another directory that contains the source and output parts that are in the currently committed version of the release. To do this, a second shadow, for the committed release is also needed. See the information on the use of shadowing in the Process Control Features section for more information.

If the workarea changes are not shadowed to the project directory, it is necessary to extract any parts that are linked or refreshed from other workareas. This is most easily performed by executing a query for changed parts in the current workarea within a user exit on PartLink, PartRefresh and WorkareaRefresh that reports the parts changes caused by links within the current workarea. The user would then execute the part extract commands would be performed manually. The automated alternative would be to mount a drive from all workstations so that the user exit could extract to the server, delivering the files to the mounted drives.

There are a couple of methods in which to synchronize the local copies with the copies in TeamConnection through the Visual C++ user interface. Once a project is opened and under source control, the user can select Project -> Source Control -> Refresh Status in order to synchronize the status of the files within that project with the status of the files as known by TeamConnection.

When a file is added to the project by another user, the local copy of the project and files within that project, need to be updated to account for this new file. Again, there is no automated way for this to happen with Visual C++. One solution (for the user who needs to access this new file) is to attempt to add a different copy of the new file to the existing local project. In doing so, the user will be asked to add this file to source control also. When the user accepts, an error message appears stating that the file is already under source control. From there, the user can then get the latest copy of the file out of TeamConnection though the Visual C++ user interface. It should be pointed out that all of the above assumes that this is all performed within the same component, release, and workarea name.

All of the above situations are resolved by querying the source control provider (TeamConnection) and updating local versions of the parts based on the information returned from the provider. Whenever the user requests to perform an action on a part, Visual C++ queries TeamConnection on the status of the selected part, along with all parts that Visual C++ "thinks" are under source control. The actual query and response from TeamConnection (based on the current TeamConnection settings) depend on the specific action desired. The results are displayed to the user as a list of the available parts. From this list the user can select additional parts for the currently selected action.

Both Visual C++ and TeamConnection have a concept of a working directory. In Visual C++, the working directory is the location of the project and (in many cases) the files within that project. This directory is the "Location:" field when creating a new project in Visual C++ and is where all the project files (along with all the new files that are created for the project) will be stored. Generally, this is also the source directory for the parts to be added to TeamConnection.

The TeamConnection Settings window also has an entry for a working directory but this value has a slightly different significance. In general, it may be the same value as the Visual C++ directory or it may be just a "part" of the Visual C++ working directory. The TeamConnection working directory specifies the top level directory for the part names that are stored in TeamConnection. When filenames are passed from Visual C++ to TeamConnection through the SCC APIs, the SCC will attempt to strip off this working directory value before accessing the TeamConnection repository. This allows the user to utilize a directory structure within the TeamConnection database for part storage and retrieval.

For example, a user creates a new project named credits in the location of E:\C++\banking\credits, where all "local" copies of the files for this project will be created. The user wants to distinguish all of these files as part of banking\credits. In order to do this, the user should enter the value of E:\C++ in the working directory field of the TeamConnection Settings window. Every filename that is passed to TeamConnection for those settings will attempt to be filtered by removing the E:\C++ from the filename. Keep in mind that this has no effect on where the files are stored locally, just at how they are stored in TeamConnection.

The above scenario is fine provided that all the files reside in the working directory of Visual C++, but what if there are some common files that reside in the D:\tools\common\include directory? The field for the working directory in the TeamConnection Settings dialog has the ability to handle multiple paths (separated by a semicolon). All you need to do to be able to access these files in TeamConnection (once they have been created) is to include that path in the TeamConnection Settings working directory path for that project.

The working directory field setting of E:\C++;D:\tools will try to interpret filenames that are passed in the SCC APIs using both path values as a filter. If the file D:\tools\common\include\common.h is received in the checkout command, TeamConnection will first try and strip off the first path in the field (E:\C++) and since that path is not part of the passed filename, it will go to the next path (D:\tools) and attempt to strip off that name. In this case, the file in TeamConnection to be checked out will be common\include\common.h. Should no paths specified in the working directory be filtered, then the base name only is the filename that will be accessed in TeamConnection. In our example here, if the filename of E:\Visual C++\banking\credits\checking.cpp is passed in the SCC API call, then the filename to be accessed in TeamConnection would be checking.cpp.

Note: TeamConnection will only attempt to resolve the top part of the part name passed on the function call and will not attempt to determine whether or not the part exists in TeamConnection or on the local disk before the command is issued. It will only attempt to filter the part name based on the paths in the working directory. This still leaves open the possibility that the part may not be found in either place. With this in mind, multiple paths in the TeamConnection Settings working directory field should be used with extreme caution! It is also highly recommended that once you create your project and set the TeamConnection Settings that these values not be changed.

The following table lists the naming convention for the SCC functions available from within the Microsoft Developer Studio Window. The SCC functions listed are found under the menu option Project -> Source Control (or by using the second mouse button on the selected part) with the expected results. Some items may not appear in both methods or may not appear due to the current state of part.

PowerBuilder, as with most IDEs, has its own "local" knowledge of the status of parts that are under source control. This "local" status of a part may not be the same status recognized by TeamConnection (which is the "true" status), because most IDE designs are based on a single-user model, rather than a model that anticipates multiple users working within the same library. A part that was placed under source control by one user may not be recognized as such by another user on another machine

PowerBuilder is very good at recognizing this situation and resolving such conflicts by querying the source control provider (TeamConnection) and updating local versions of the parts based on the information returned from the provider. For example, if a user attempts to add to source control a part that was already added by another user, then TeamConnection informs PowerBuilder that this part already exists and PowerBuilder updates the part's local status for the user.

In both serial and concurrent development, all part changes can be made in one workarea. But in order to track those changes (for example, through a defect or feature), a workarea must be created for each change. Using the subprocesses from TeamConnection, a workarea can be created at the acceptance of a defect or feature. This workarea will be named after the associated defect or feature.

The following subsections briefly describe the two modes of development with PowerBuilder and TeamConnection.

Once the release, component, and workarea are defined through TeamConnection, the user can then begin to add parts through the PowerBuilder Register command. After the parts are registered, they can be checked in and out through the PowerBuilder interface. Additional actions can be taken as desired, such as difference comparison, file history information, etc.

In a serial environment, when a second user attempts to perform an action on a part that is in a state for which the action is not allowed, an error/warning message appears indicating the problem with the requested action. For example, when a user has a part checked out, a second user will not be able to check out that same part and an appropriate message will be displayed to the second user. Once the first user has checked in the part, the second user can then check out the part and make changes as needed.

Note: The second user will receive a message warning that a workarea refresh or a part -link is required before checking in the part.

Any conflicts that may occur when a user is trying to checkout a part that is already locked by another user are resolved by TeamConnection and reported back to the PowerBuilder interface. Such conflicts will be reported in a message to the user, issued from PowerBuilder, TeamConnection, or in some cases both, depending upon the error.

As with serial development, in a concurrent development scheme the release, component, and workarea are defined through TeamConnection, and users can then begin to work with parts in the same manner.

For example, User1 might create workarea1 for a specified part in a given component and release. User2 would then need to create a different workarea (workarea2, for example) in order to check out the same part. In this scheme, multiple users can perform concurrent development on a given part. As individual users complete development on the part independently, they can check the part back into TeamConnection using the check in command in the PowerBuilder interface. At this point, the user actions are dependent upon whether a single or multiple workareas were involved.

In a single workarea scenario, the first User to issue the check in command checks the changed part back in. Each subsequent check in creates a collision record that will have to be resolved by merging the two versions of the changed part into a third version. The third version becomes the latest copy.

In a multiple workarea scenario (each user has checked the part out from a separate workarea), each user issues the check in command. However, when the workareas are then integrated into a driver, a collision record is created that will have to be resolved. Once the integration has been done, the merged part is now the latest copy and can be used again in the same manner as described previously.

Since PowerBuilder stores its source in a byte code format inside PowerBuilder Libraries (PBLs)., a text-based merge tool cannot be used directly. In order to merge different versions of the same PowerBuilder part, it will be necessary to open two separate PowerBuilder IDE sessions. In each session, open a different version of the changed part. Then manually transfer the changes from one version to the other. This, in effect, creates a third version that will become the current part in TeamConnection.

PowerBuilder maintains all of a single project's "parts" within a single library, which is stored as a single PBL file. When a part is stored in TeamConnection, PowerBuilder will first export this part as a file and then pass this on to TeamConnection through the SCC API. This is done whenever a user registers a part through the PowerBuilder interface.

Likewise, when a part is needed within a PowerBuilder library, the part is retrieved from TeamConnection through the SCC API and imported into the selected library. The exporting and importing is all done with temporary files that are never seen by the user. In order to use these parts under source control, PowerBuilder requires that they be checked out from one library and checked into another library.

The PowerBuilder parts are meaningless outside of a PowerBuilder library. This presents the users with an interesting problem: How to access the PowerBuilder library that is needed to interpret the parts that are under source control. One way to accomplished this would be with a network PBL as described below.

The initial PowerBuilder library to be placed under source control should be placed on a network drive that can be accessed by all users who need to work with that library. All the parts can then be added to TeamConnection by a single user through the Register command. The user should then see that these parts are under source control in the PowerBuilder interface. Any other user that accesses this network library will see the same status for the parts.

Note: Perhaps the easiest way to refresh the status for the network library is to select the library, double click on it (once to close it), then double click again (to re-open it).

Once this network library is under source control, users can then check out parts to a local library, make changes, test their changes, and then check their changes back into TeamConnection. The network library is needed to interpret the parts that are changed and can be actually used for the build. To some extent, TeamConnection would act merely as the controlling mechanism.

Parts that were checked back into the network library would contain the updates from the users even though the workareas were not integrated in TeamConnection. This could be of value since the latest parts would not need to be extracted from TeamConnection in order to test the build with the changes in the library; however it is recommended that all the parts be extracted from TeamConnection when the workareas are integrated.

All of the PBLs in this relationship would work best when they only process one release.

The following table lists the naming convention for the SCC functions available for the PowerBuilder Library Window along with the expected results. These functions are available from the Source menu option or by using the second mouse button on the selected part. Some items may not appear in both methods or may not appear due to the current state of part.

Copyrights, Trademarks and Service Marks
The following terms used in this technical report, are trademarks or service marks of the indicated companies: