This chapter explains how to use a source control manager (SCM), also known as a source code control system (SCCS), through Mainframe Express.
This chapter applies to all SCC-compliant SCMs, but all examples use MERANT PVCS Dimensions.
The concepts of SCC and the SCC interface in Mainframe Express are introduced in the chapter Source Control in the Mainframe Express Getting Started book. Dimensions is introduced there too.
Mainframe Express detects and provides integrated support for any source control manager that conforms to the Microsoft Common Source Code Control Interface. This includes commonly used systems such as MERANT PVCS Version Manager, MERANT PVCS Dimensions, Microsoft Visual SourceSafe and IBM VisualAge TeamConnection.
Source control managers typically provide a number of services that are useful to software developers; for example:
Gives named users permission to modify files or to have read-only access to files. Other users cannot gain access to the files.
Groups files together into work units or projects, ensuring that files that don't change often are not forgotten about.
Gives several users access to files, but prevents more than one person changing a file at the same time.
Provides a storage-efficient way of reverting to previously-saved versions of files. Also enables you to label specific versions so that they can easily be found by other users.
Mainframe Express provides an easy way of using the services offered by a source control manager. The services available and their behavior depend on which source control manager is installed, and how you or your administrator have configured it.
A source control project is a group of related files that correspond to a project in Mainframe Express.
You should create one source control project for each Mainframe Express project. If you create the SCM project from the Mainframe Express IDE, Mainframe Express makes an association between the two projects. When you subsequently open a Mainframe Express project, the corresponding SCM project is opened automatically.
If you are using Microsoft Visual SourceSafe, we advise you to keep project names to 247 characters or less.
When you want to edit a file that is under source control, you need to check the file out first. Checking the file out creates a working copy in your Mainframe Express project directory, and sets a lock on the file in the SCM. This lock prevents other users from changing the file while you have it checked out.
When you have finished editing the file, check it back in to the SCM again. The working copy becomes the latest revision in the SCM, but remains on your disk. In some SCM's this automatically or optionally removes the lock from the file, allowing others to access it. There may also be a separate function to do this.
Note there's no SCM function that deletes your working copy from your disk, though with some SCM's you can overwrite it with a later or earlier revision from the SCM.
When you start Mainframe Express, it looks for an SCM installed on your machine. If it finds one it automatically links to it. This causes the following additions to the Mainframe Express IDE:
The SCC Status column displays the file's status as returned by the SCM. Possible values are:
The functions on the Source Control menu operate on the latest revision of the selected file(s). The Check Out function, which gets a file out of the SCM onto your disk for editing, creates a new revision and gets that out.
With some SCMs there may be a way to get an earlier revision of a file. For example, in Dimensions, use Show History to display all revisions and use the function buttons on the dialog box. See below for details.
When the SCC Status field on the project view shows Checked Out, it means some user has the file checked out. You may need to use Refresh Status or Refresh Status - All to ensure this field is up to date.
With some SCMs there may be a way to see which user has a file checked out. For example, with Dimensions, use Show History. In some SCM's, it may be possible for different users to have different revisions of the same file checked out at the same time.
The SCC functions available from the Source Control menu in Mainframe Express are those provided by the SCM. This section lists those commonly found in most SCMs, and their typical behavior. See your SCM's documentation for more details.
In many functions you select files for action by putting check marks next to them in a list box that the function displays. In all these functions:
Gets the latest revision of the file, that is, gets it from the SCM and puts a copy on your disk. Sets the access permissions to read-only, so you can look at it but not edit it. This function does not lock the file - users on other machines are able to check it out.
Use this function when you want to look at a file; or if you want to cancel edits you've just done on a file you've already got Checked Out.
The function displays a list of all files in the Mainframe Express project that are not currently checked out. Put check marks by those you want to Get.
If there are no files in the Mainframe Express project, this function displays a list of all files in the corresponding SCM project. Those you choose to Get are automatically added to the Mainframe Express project.
Creates a new revision of the file, gets it from the SCM and puts a copy on your disk. Sets the access permissions to writeable (that is, read/write) and, in the SCM, locks the file so that users on other machines cannot check out any revision (they can still Get it, to look at).
If you already have the file checked out you are asked to confirm to overwrite it. If you have the file read-only, it is overwritten without asking for confirmation
Use this function when you want to edit a file; or if you want to cancel edits you've just done on a file you've already got checked out.
The function displays a list of all files in the Mainframe Express project that are not currently checked out. Put check marks by those you want to Check Out.
If there are no files in the Mainframe Express project, this function displays a list of all files in the corresponding SCM project. Those you choose to Check Out are automatically added to the Mainframe Express project.
To configure Check Out to check out the files selected in the project view straightaway instead of displaying the file list, see Source Control on the Options menu.
Updates the file in the SCM by copying your latest revision from your disk to it. This revision of the file becomes "not checked out".
You can only do this if you have the file checked out.
Use this function when you want to save your edits in the SCM.
The function displays a list of all files in the Mainframe Express project that are currently checked out. Put check marks by those you want to Check In.
If you select the Keep checked out check box, a new revision is created, and is checked out. So the SCC Status field still shows the file as checked out. Otherwise, it is as if you had followed this function by Undo Check Out.
If you type a comment in the Comment field, it is stored in the SCM, attached to each of the files you are checking in.
You cannot check a file in until you have added it to source control (see Add to Source Control) - it does not appear in the list of checked out files until you have done this.
In many SCM's, the SCM command invoked by this Mainframe Express function undoes the check out. Selecting Keep checked out makes Mainframe Express send a second command to check the file out again.
Releases a file for others to edit; that is, changes its access permissions on your disk to read-only, and unlocks it in the SCM.
Use this function when you have completed your edits, after using Check In to save them.
Depending on the SCM, this function may replace the revision on your disk by the latest saved one, thus undoing any unsaved edits.
The function displays a list of all files in the Mainframe Express project that are currently checked out. Put check marks by those you want to Undo Check Out.
Adds a file to the SCM; that is, creates an archive for it.
The function displays a list of all files in the Mainframe Express project that are not currently under source control. Put check marks by those you want to Add to Source Control.
If you select the Keep checked out check box, the file remains checked out. Otherwise, it is as if you had followed this function with an Undo Check Out.
If you type a comment in the Comment field, it is stored in the SCM, attached to each of the files you are checking in.
You do not need to specify a location for the archive, as it is fixed relative to the archive representing the project.
If the Mainframe Express project is not currently connected to the SCM, this function invokes Connect Project to Source Control instead of adding any files. Once the project has been connected to source control, use this function again to add the files. (Most functions are simply grayed out if the project is not connected.)
Removes a file from the SCM; that is, deletes its archive with all its revisions. All trace of the file is removed from the SCM.
The function displays a list of all files in the Mainframe Express project that are currently under source control. Put check marks by those you want to Remove from Source Control.
Make sure no revision of the file is checked out before you use this function. Any revision that is checked out will not be removed from source control (you get an error message), while other revisions will be successfully removed. If this happens, do Undo Check Out on the remaining revision and use this function again.
Invokes the SCM's function that shows the properties of a file. This function does not appear on the menu if the SCM does not have such a function.
An example is the Show History function in Dimensions, described briefly under the History function.
See your SCM documentation for details.
Invokes the SCM's function that shows the history of a file. This function does not appear on the menu if the SCM does not have such a function.
An example is the Show History function in Dimensions. It displays a dialog box showing history and other information for the selected file. You must select an individual file on the project view before using this function. The dialog box shows all revisions, and you can select one and then use function buttons on the dialog box. In this way you can operate on earlier revisions of a file.
See your SCM documentation for details.
Invokes the SCM's function that compares two files, or two revisions of a file, to find the differences. This function does not appear on the menu if the SCM does not have such a function.
An example is the Show Differences function in Dimensions.
See your SCM documentation for details.
Updates the SCC Status field, in the project view, for the selected file. You must select an individual file on the project view before using this function.
Use this function whenever you suspect that the SCC Status field may be out of date, for example if the status shown seems inconsistent with recent actions.
A common case is where a file is shown as checked out but when you try to edit it you get a message that it's read-only. However, this could mean that it is checked out by a user on another machine, in which case the field is correct.
Updates the SCC Status field, in the project view, for all files. You do not need to select an individual file before using this function.
You may get a message warning you that this function may take a while. Click OK to go ahead anyway.
In all other respects this behaves like Refresh Status.
Connects your Mainframe Express project to source control, that is, associates it with a file called the project marker file, which represents it in the SCM. If this is the first time the project has been connected to source control, the function creates the project marker file.
The function displays the dialog box provided by the SCM for you to specify a location for the archive. If your administrator has set default values, these are displayed. It may provide an option for creating a new project marker file - for if this is the first time you have connected this project - and an option for connecting to an existing one.
The project marker file is not visible to you through Mainframe Express, and you don't normally need to see it. If you do look for it in your SCM's native client interface (for example, PC Client in Dimensions), its path within the location you specified is project-folder\project.mfe, where project-folder is your project folder and your project file is project.mvp.
For example, say your project is called Sccdemo, your project file is sccdemo.mvp and the path to your project folder is c:\mfuser\projects\gsdemo\sccdemo, and you are using Dimensions and have specified $PRODUCT1:$WORKSET1 as the location. Then the project marker file is created in sccdemo\sccdemo.mfe in Product/Workset $PRODUCT1:$WORKSET1.
Disconnects your Mainframe Express project from source control, so that you can use it without reference to the SCM.
This makes no change to the archives stored in the SCM. If you subsequently reconnect the project to source control, using Connect Project to Source Control, you have access to them again.
Opens the native user interface of your SCM. For example, if your SCM is PVCS Dimensions, this function appears on the menu as PVCS Dimensions, and it opens PC Client.
This section describes the SCC function available from the Options menu in Mainframe Express.
Invokes the Source Control Options dialog box, where you can set the one configurable option in Mainframe Express source control.
Put a check mark by Use dialog box for check out to have Check Out display a list of eligible files. If there is no check mark here, Check Out checks out the files selected in the project view, without displaying the dialog box. By default, this option is check marked.
Copyright © 2001 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.