Use the Source Control interface to store files in an SCC-compliant source control manager (SCM) for controlled access by multiple users and for version management.
You need to have read the chapter Start Here for the Tutorials and worked through the first session, Using Mainframe Express, before you do this session.
You need to have an SCM installed to do this session. The SCM used in all examples is PVCS Dimensions from MERANT.
For the later sections in this session, you need two computers, with Mainframe Express and your SCM installed on both.
A source control manager (SCM) - also called a source code control system (SCCS) - stores files centrally on a server and gives multiple users controlled access to them. It can store multiple revisions of a file, by storing a base version plus the changes (deltas) needed to create the later revisions. When one user is working on a file, the file is locked so that no other user can work on it.
Microsoft has defined a standard enabling the functions of an SCM to be called from other software. This standard is called the Microsoft Common Source Code Control (SCC) Interface.
The Mainframe Express menus include a Source Control menu, which appears only if an SCC-compliant SCM is present on the computer. The functions on this menu map directly onto the functions of the SCM, so that you can store and retrieve files from within Mainframe Express.
If more than one SCM is installed, Mainframe Express normally links to the most recently installed one.
Some well-known source code control systems are MERANT PVCS Version Manager (VM), Microsoft Visual SourceSafe and IBM VisualAge TeamConnection.
The MERANT product PVCS Dimensions (Dimensions for short) is a Configuration Management tool, which companies use for planning and managing major undertakings. As part of this it maintains the masters of files, and makes them available in a controlled way for staff to work on. Thus this SCM-type activity is one small part of what Dimensions does. Dimensions complies with SCC, so if you have Dimensions installed you can use its SCM-type functions from the Source Control menu of Mainframe Express.
This session demonstrates the use of an SCM through Mainframe Express. The SCM used is Dimensions, but this session is still relevant if you are using some other SCM - we make clear which points are specific to Dimensions.
Dimensions has several components. Dimensions Server maintains the database in which the masters of the files are stored. It needs to be running either on your computer or on a server on your network. It needs access to an Oracle database system, because it uses Oracle to store the masters of files. PC Client is the native user interface of Dimensions. Dimensions SCC is an installation option of PC Client. For Mainframe Express to recognize that Dimensions is on your machine, you must have PC Client installed, including the Dimensions SCC option. Please see your administrator to check that Dimensions Server, Oracle, and PC Client including SCC are present.
Because Dimensions emulates the planning of a major project, files stored in Dimensions are assigned to groups called Products and Worksets. Your administrator will have decided what Product and Workset your files are to be assigned to, and configured Dimensions accordingly. Within the Product and Workset, files are organized into directories. As in any SCM, files stored in Dimensions are often referred to as archives.
For complete details, see Dimensions' own extensive documentation. Its Generic Product Guide is a good starting point.
In this session, you add an existing Mainframe Express project to source control. This means you add the project and all its source files to your SCM so that the SCM henceforth maintains masters (archives) of all the files centrally, and can give copies of the latest or specific revisions to individual users to work on. It controls access to them by locking them so that, while multiple users can get copies of a file to look at, only one user at a time can check it out and edit it. With some SCMs, multiple users can have the same file checked out, provided they have different revisions.
In Dimensions, adding an IDE project to source control is called registering it. It must be done before any file belonging to the project can be stored in Dimensions.
The demo application used in this session is called Sccdemo. It is similar to Idedemo, which you used in the chapter Using Mainframe Express, but without the deliberate source errors. At most sites, adding a project to the SCM, so that users (usually developers) have access to it, would normally be done by an administrator. Doing it yourself in this tutorial is convenient for the purposes of the tutorial, and will also give you useful background knowledge. The remaining tasks that you do in this tutorial are tasks that all users do.
Before you start, obtain from your administrator the information to enable you to log in to your SCM. For example, with Dimensions, your administrator will have created your Dimensions account and your Oracle database account, and the information you need is:
If there is a risk of you clashing with other users running this session against the same database, your administrator may have created a Product and Workset specifically for you to use for running this session.
Depending on your site's setup, you may also need:
In this session you edit one of the source files. If you should want to run the session again, you can restore the original file by copying vsamdemo.cbl into folder d:\mfuser\projects\gsdemo\sccdemo\source from d: \mfuser\projects\gsdemo\sccdemo\source\original - see the appendix Windows Tips if you need help.
You have already seen how to create a project, in the chapter Using Mainframe Express. To save you creating the project used in this session, we supply the project sccdemo.mvp. It has already had its source files added to the project and its data files added to the catalog.
A splash screen identifying the SCM may appear for a few seconds, if the SCM provides one and is configured to show it.
The full path is \mfuser\projects\gsdemo\sccdemo\sccdemo.mvp. If you use Open on the File menu, you need the Files of Type field on the Open dialog box set to Project files (*.mvp) to see this file.
In this session you:
Notice that the menus in the Mainframe Express IDE include a Source Control menu, and the tabs in the Output window include a Source Control tab. These are present because Mainframe Express has detected your SCM and linked to it.
To add the files in a project to source control you first need to connect the project to the SCM. The first time you do this for the project, this creates in the SCM a file representing the project itself. This is called adding the project to the SCM. The file created is called the project marker file and is created by the Connect function. The .mvp file itself does not get stored.
If you try to add a project's files to an SCM without first connecting the project, you are automatically prompted to do so. In general this is the most convenient way to do it, but in this session for clarity we will connect first. Also, the first time you connect after starting Mainframe Express, you are prompted to log in. There is no separate login function.
To add a Mainframe Express project to source control:
Because this is the first source control function you have used since starting Mainframe Express, you are automatically prompted to log in - it brings up the login dialog box of your SCM.
Enter your User ID and Database login ID. Invent a password for yourself and enter it in the Password field - you will have to enter it whenever you login in future. You can normally leave the Database password field blank, as this password is stored by Dimensions. You can normally use Remote Login, and ignore the Local button, even if the Dimensions server is on your own machine. The remaining fields may have been set for you by your administrator, but if not, click More>>> to display them.
Otherwise, your project is now added to the SCM - that is, a project marker file representing it is created and stored in the SCM. This is not in itself visible to you, but if your SCM provides an acknowledgment message, this message appears. Where it appears depends on the SCM - for example, it may appear in a message box or in the Output window, in which case click the Source Control tab to see it. If it is in a message box, you may need to click OK or Yes on it.
If you look at the Source Control menu, you see that Connect Project to Source Control is now grayed out, because the project is now connected.
Whatever SCM you have, the function at the bottom of this menu is always the function to start its native client interface. For example, with Dimensions, this function is PVCS Dimensions and it starts PC Client.
A file representing this Mainframe Express project has been created in your SCM. For example, with Dimensions:
If you already had this open, refresh it by clicking View > Refresh > Current.
In the tree view there is now a directory called Sccdemo. It has no subtree at present. If you click it, the right-hand pane shows it contains one file, Sccdemo.mfe. If you right-click this file and Browse it, you see it is empty. (You need a default browser specified - use Tools > Preferences > Editors and enter the path to your desired browser in the Default field.)
The directory Sccdemo will be the root of all files belonging to project Sccdemo that you store in Dimensions via Mainframe Express. The project marker file Sccdemo.mfe identifies the project and the fact that it comes from Mainframe Express rather than some other IDE.
You can add a file via Mainframe Express provided it belongs to a Mainframe Express project. To add the files of the Sccdemo project to source control:
A dialog box titled "Add file(s) to Source Control" appears. It lists all the source files in the Sccdemo project.
This project has several data files in the catalog, and these appear in the Files View (because they have been added to the project). But they are not shown in this dialog box. Only source files (including dependencies such as copyfiles) are candidates for source control.
This is a quick way of putting check marks by all the files in the project. Putting a check mark by a file indicates it is to be added to source control. It does not matter whether you leave the files highlighted or not - it's the check marks, not the highlighting, that show the files to add.
In your SCM, this description will be associated with each individual file.
This ensures that when the files are added to your SCM, they will not be locked. (If you forget to uncheck this, you can follow this function with Undo Check Out.)
The files are stored in your SCM.
You can see in the Output window the commands that Mainframe Express sends to the SCM and the resulting messages from the SCM. Depending on the SCM, these may be simply routine progress messages, or you may need to watch them for error messages. Many SCMs display error messages in message boxes rather than through the messages displayed here.
Mainframe Express itself displays messages in the Output window, reporting the success or failure of its calls to the SCM. A message saying a call has succeeded does not necessarily mean the entire operation succeeded - you still need to check the SCM's messages.
All the files are shown as Not checked out. This is because you unchecked Keep checked out.
A message warns you it is read-only. Click OK and it opens in an edit window.
So the file is still physically on your disk, but is read-only.
No SCC function actually deletes a file from your disk. Having it "not checked out" means you haven't got it locked, so you can look at it but not edit it, and a user on another machine could check it out to edit.
Close the edit window.
For example, with Dimensions, refresh the Work Set Display. Directory Sccdemo now has subdirectories copylib and source, containing the four files. Each file has just one revision, which is revision 1.
Having added a project and its files to source control, the administrator would distribute copies of the project (.mvp) file to users and ensure they have access to the SCM and server where the archives are stored. Users can then get the files out to work on. From here on we're doing what an ordinary Mainframe Express user would do.
First, to demonstrate some points regarding using the IDE with a project that uses source control:
The SCC Status column still shows the statuses of the files you added to source control. This shows the project is still connected to source control.
The project window opens, but it is empty, and you get the SCM login prompt.
The project opens as usual.
The SCC Status column shows the statuses of the files you added to source control. The project has automatically reconnected. (Select Project in the left-hand pane to see all the files.)
The status settings disappear from the SCC Status column, showing that the project is no longer connected to source control.
For example, with Dimensions click Select Project. Select the project Sccdemo\Sccdemo.mfe from the dropdown list, accept the defaults for the other fields, and click OK. Then it connects to the existing project marker file.
The statuses in the SCC Status column reappear.
Let's say you need to make a source change to VSAMDEMO.CBL. You need to check it out of the SCM. You'll need to rebuild and test the project, but you don't need to check out the other files - even with them checked in you have your read-only copies, which is fine for building.
The Check Out File(s) Dialog box appears, showing all the files in the Sccdemo project.
vsamdemo.cbl already has a check mark because you selected it. If you had not selected it you could put a checkmark by it now.
The SCC Status field now shows vsamdemo.cbl as checked out.
For example, with Dimensions, refresh the Work Set Display. vsamdemo.cbl now has revisions 1 and 2. Revision 2 has an "X" by it, showing it is checked out. The new revision has been created for you to apply your edits to.
In some SCMs the revision number may not be incremented until you do a Check In.
The revision number of the project marker file and the other files remains at 1.
Select vsamdemo.cbl and click Source Control > Check out again.
The usual dialog box appears, but vsamdemo.cbl is not shown. Click Cancel.
This time you get no warning saying it's read-only. Because you have it checked out, it is now writeable.
This invokes the Properties dialog box of Dimensions, with the History tab selected. Looking at this you can see details such as:
Icons also show the status of each file. For example, means the file is checked out. See your Dimensions documentation for a full list of these icons.
This shows further details of this revision of this file.
Always remember to select a revision before clicking File Detail. It does not automatically show the details for the latest revision. If Is Extracted (that is, checked out) is shown as No, and you know the latest revision is checked out, it has probably defaulted to show an earlier revision.
The Check In File(s) Dialog box appears. It shows only vsamdemo.cbl, because no other file is checked out. This file has a check mark because you selected it.
The Keep checked out check box is checked by default. Accept this default and click OK to check in your changes.
The SCC Status field shows this file is still checked out.
Check in with Keep checked out saves your edits, and then creates a new revision and checks that out for you to make further edits. So the revision on your disk is now revision 3.
If you wish, use the native client interface of your SCM to confirm this. Or, if you are using Dimensions, you can use Show History as above.
Let's see whether there are any restrictions on what you can do with a project that is connected to source control.
The project is rebuilt.
The application runs in the Application window. It is similar to Idedemo, which you used in the chapter Using Mainframe Express.
The application runs with debugging. Single-step a few times, then click to complete it.
So you can build, run and debug the project as usual. It makes no difference if some or all files are not checked out and are therefore read-only.
This section is for Dimensions only, and is not essential - it shows how a Dimensions user can access different revisions of a file. Please omit it if you're not using Dimensions. Other SCMs may have analogous facilities.
Let's say we decide we don't want the above edit after all. We want to keep the revision containing the edit, for reference; but we want to make the original revision, without the edit, into the version we will apply future edits to.
At any stage, you can if you wish use PC Client to confirm what Mainframe Express has done. Remember to refresh the PC Client display at each step. You can also use Windows Explorer or a command prompt to look at files on your disk, for example to see whether they are read-only or writeable.
Select vsamdemo.cbl and click Source control > Undo check out. Click OK on the dialog box.
The file's SCC Status changes to Not checked out.
The History tab of the Properties dialog box confirms we now have revisions 1 and 2, neither of them checked out.
In the dialog box, select the line showing revision 1 and click the Check Out button.
A new revision 3 is created from revision 1 and checked out for you to edit.
Close the dialog box.
vsamdemo.cbl is now shown in the project view as Checked out.
The edit that is in revision 2 is not here in revision 3. If you wanted you could make further edits now.
Close the edit window.
In PC Client, notice that revision 3 disappears.
This creates a new revision 3 from revision 2.
You now have revisions 1, 2, and 3, of which revisions 2 and 3 contain the edit and revision 3 is checked out.
You can do this section if you have two client computers available, with Mainframe Express and your SCM client installed on both. You need two different user IDs for logging into the SCM on the two machines.
We'll assume you have user IDs USER1 and USER2, and we'll refer to the two machines by these names. USER1 is the machine you've been using in previous sections.
This section uses the copies of Sccdemo supplied in the Mainframe Express on the two machines. To some extent this is unrealistic, because it's unlikely you'd start off with the same files on two client machines, rather than distributing them to the clients via the SCM, but it will illustrate some important points.
Then click Select Project. Enter the same location (Product and Workset in the case of Dimensions) as on USER1. Select the project Sccdemo\Sccdemo.mfe from the dropdown list, then accept the defaults for the other fields. Click OK.
USER2 connects to the existing project, and the SCC Status fields are filled in with the statuses of the files.
If the SCC Status fields on USER2 remain blank, it has not found the existing project in the SCM. Probably the location for adding projects is not correct. Disconnect from source control, and then connect again specifying the correct location.
On both machines, vsamdemo.cbl is shown as Checked out. We know it is in fact checked out on USER1, but Mainframe Express cannot tell this from the information returned via the SCC interface.
vsamdemo.cbl is not shown in the dialog box, because it is already checked out. Close the dialog box.
vsamdemo.cbl is still not shown in the dialog box. Close the dialog box.
The SCC Status field is updated. Alternatively, you could use Refresh Status - All without selecting any file. If a project contains a lot of files this can take a while, as it updates the SCC Status fields for all the files.
vsamdemo.cbl is still now shown in the dialog box, and with a check mark because you selected it.
You already have a writeable copy of vsamdemo.cbl on USER2, supplied with the Mainframe Express on that machine. You get a message asking whether to overwrite it. Click Yes or Yes to All.
You now have revision 3 checked out onto USER2.
This section is for Dimensions only, and is not essential - it shows how Dimensions users on two computers can access different revisions of a file. Please omit it if you're not using Dimensions. Other SCMs may have analogous facilities.
This section continues from the previous section. We assume Sccdemo is still open on both machines.
The Properties dialog box shows additional information, as we saw before. This includes showing which user created each revision. Revision 3, the one that is checked out, is shown as created by USER2 - so we know it is USER2 that has it checked out. As we saw in the previous section, this is information we could not get from the project view.
On USER1, still in the Properties dialog box, select revision 1 and click the Check Out button.
You get a message in the Output window saying that multiple check outs aren't allowed - in other words, two users can't have the same file checked out at the same time, even if they want different revisions.
The message says multiple extracts aren't allowed for items of type SRC. This is because by default Dimensions treats files from Mainframe Express that have the extension .cbl as if they were the Dimensions filetype SRC (the administrator can change this default).
This is the same as selecting the file in the project view and clicking Source Control > Undo Check Out, except that you can choose a specific revision. Since in this case we chose the latest revision, the effect is exactly the same.
Because you undid USER2's check out without checking in (saving) revision 3, revision 3 has disappeared.
The History tab shows revision 3 is created and checked out onto USER1.
You see that it does not contains the edit you made earlier. So revision 3 is a copy of revision 1.
Edit the file - add a comment line near the beginning saying. "Added at revision 3". Save the file and close its edit window.
USER1 has now checked in revision 3, and created revision 4 checked out on USER1.
Get gives you a read-only copy, so there is no problem in doing this even though another user has it checked out.
Notice that it has the "Added at rev 3" line. Get has given you the latest revision. Close the edit window.
Notice that it has the "Added at rev 2" line. Get has given you the revision you requested. Close the edit window.
You should delete the archives created in this session, in case the session is to be run again:
Click in the right-hand pane, click Ctrl+A to select all the files, and then click Source Control > Remove from Source Control.
This removes all revisions of all the archives. It does not remove the project marker file. As you saw above, if this session is run again the project will connect to this project marker file instead of creating it.
Close Mainframe Express on USER2.
On USER1, close the project. If you want to take a break before going on to the next session, you can close Mainframe Express.
Return to the Tutorials Map in the chapter Start Here for the Tutorials and choose which session to go on to next, depending on your interests.
Comments on the books? Click Send Us Comments.
Copyright © 2001 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.