Configuration Information

Here is a quick overview of the steps to installing and running Uniface with Visual SourceSafe using UD6/CMtool Driver. Each step is explained in more detail if you click on the links that are provided.

• Install Uniface and UD6/CMtool Driver on to the NT Workstation.
• Alter the usys.ini and usys.asn files as per the Guide to Installing UD6/CMtool driver.
• Alter the usys.asn file to have a 'catchall' to direct all non-joined source code to the .\sources\other directory, set the $MAXFILES and set temporary files to be stored in another database.
• Start and then close the IDF to initialise an empty repository. ( the IDF should be a temporary directory for loading your existing source code into the XML format that the UD6/CMtool Driver uses (we used c:\usys-ud6102_7206\project).
  
  The file c:\usys-ud6102_7206\project\sources\other\udicver.xml now exists, and contains 1 record.
• Add the 'nokeycheck', and optionally the 'xmlschema ???' parameter(s) to the USYS$UD6_PARAMS setting in the usys.asn file (this setting improves the performance of the UD6 driver for bulk load operations, and creates XDR information, but must be disabled for normal use).
• Load the repository from a backup with a command like:

idf /com=100 /cpy trx:7204bkp07Feb2000.trx idf:
  
  (some unix environments may require the /com=10 switch to reduce the number of file handles used).
• Alter the usys.asn file to remove the 'nokeycheck' and/or the 'xmlschema ???' parameter(s).
• If you are upgrading versions of Uniface at the same time as setting up UD6, and you previously loaded the Uniface Meta-Dictionary, you will need to delete it and install the Meta-Dictionary that was supplied with you newer version of Uniface. To do this perform the following steps:
  
  

  cd sources\tables 
  del dict-*.xml del ucvs-*.xml 
  del sysenv-*.xml 
  del printer-*.xml 
  cd ..\sub-types 
  del *-dict-*.xml 
  del *-ucvs-*.xml 
  del *-sysenv-*.xml 
  del *-printer-*.xml

  Now start the IDF with the following command line options: /ins meta.
• Prior to controlling your source in Visual SourceSafe, it is wise to compile all objects and forms, eg:
  
  idf.exe /all
  
  This ensures that all the descriptors have been generated for the forms. Without this information you will not be able to compile forms in the CM tool since they will be read-only and the descriptors cannot be generated (see the nodeny parameter in the USYS$UD6_PARAMS help topic).
• For the same reasons you may wish to start up the IDF and select the Assembly Area, then the Assembly Workbench.
  
  
  Clicking on this ICON will start the initial synchronisation of signatures and diagram.
  
  

Configuration files

Visual SourceSafe & UD6 guide

Taking Control in Visual SourceSafe

As a way of introducing Visual SourceSafe, we'll go through a typical work-session using it.

At this point your source code is now in XML the format that the UD6/CMtool Driver uses (in the directory c:\usys-ud6102_7206\projects\sources), and is ready for 'putting into' Visual SourceSafe. The following describes a SourceSafe setup which is a fairly straightforward one and should suffice for your initial evaluation, or to give more advanced SourceSafe users an insight into the specifics of using Visual SourceSafe with the UD6/CMtool Driver for Uniface.

Installing and setting up Visual SourceSafe.

• Install the Visual SourceSafe Server and and client software (all of the commands shown here are executed from the client).

Migration tasks to be performed.

• Set SourceSafe Options using the Visual SourceSafe Administrator.
• Create SourceSafe Project using the Visual SourceSafe Administrator.
• Set Shadow Folder using the Visual SourceSafe Administrator.
• Add source code to project using the Visual SourceSafe Explorer client.
• Set working folder(s) using the Visual SourceSafe Explorer client.

At the conclusion of these tasks you should have a Visual SourceSafe project database containing all of your Uniface source, and a shadow folder containing read-only copies of the same files.

Taking Control

Visual SourceSafe & UD6 guide

Set SourceSafe Options

Visual source safe uses file groups to distinguish text and binary files for each development tool.

Start the Visual SourceSafe Administrator, and log in using an administrative account.

Open the Options... dialog from the Tools pulldown menu.

Enter the name Uniface and press OK when done.

Taking Control

Create SourceSafe Project

Visual SourceSafe organises work by projectPCMS3-7. A Visual SourceSafe project roughly equates to a single Uniface repository. Use the Visual SourceSafe Administrator to create a new project.

Use the Create Database... option from the Tools pulldown menu.

Enter a directory where this project database should reside, and press OK when complete.

When the database has been created, Visual SourceSafe gives you this completion message:

Taking Control

Set Shadow Folder

Since Uniface requires that all source code be available at all times, it is necessary to use the Shadow Folders option of Visual SourceSafe to create a read-only copy of the source code in the database at all times.

Open the database you created in the previous step.

Open the Open SourceSafe Database... dialog from the users pulldown menu.

Select the database you created in the previous step and press OPEN.

Open the Options... dialog from the Tools pulldown menu, then select the Shadow Folders tab.

Select the proeject ($/) and a folder to keep a read-only copy of the source code in. This folder will need to be 'shared' so that all workstations using Uniface and UD6/CMtool Driver have access to it. Alternatively if you are using UD6/CMtool Driver with Polyserver, the shadow folder only needs to be accessible to the Polyserver node.

The Visual SourceSafe documentation suggests using a UNC path here, e.g.:

\\ntsrvr01\c-drive\reference

This directory corresponds to the directories set in the JOINS file, and the USYS$UD6_PARAMS=shadow-folders directory-spec setting.

Press OK when complete.

Taking Control

Add Source Code to Project

Source code is added to the project using the Visual Source Safe Explorer on the client.

Log in using an account that can add and checkout files from the project database, and select the project created previously.

Using Windows Exploer, select and drag the directories that UD6/CMtool Driver has created your Uniface source code in, to the Visual SourceSafe explorer window (e.g.: applications, components etc etc).

This window will appear, giving you the opportunity to add a comment regarding the checkin. Ensure that the Recursive checkbox is ticked, and a descriptive comment is given, then press OK.

Since Visual SourceSafe has been set to use a shadow folder, but that folder does not exist yet, the above error dialog is presented. Press Yes All to automaticaly create the shadow folders.

As each sub-directory is added you will be prompted for the checkin comment. Ensure that the 'recursive' checkbox is ticked each time.

On the server you should see that the shadow folder is being populated at the same time as the project.

Taking Control

Set Working Folders

Once source code has been added to the project using the Visual Source Safe Explorer on the client, a directory for source code that has been 'checked out' must be set.

Log in to Visual SourceSafe Explorer using an account that can add and checkout files from the project database, and select the project created previously.

Select File->Set Working Folder... from the pulldown menu.

Set the directory to be the same as the SANDPIT setting in the ASN file, e.g.:

Press OK when complete.

Visual SourceSafe & UD6 guide

Releasing a form using Visual SourceSafe

When you 'check out' a file from the Visual Source Safe Project Database, Visual SourceSafe copies the file to a read-write area on your local machine (or a network drive on the local machine), as specified by your working folder.

The IDF accesses all non-checked out source from the shadow folder (as specified in the Visual SourceSafe administrator and the USSYS$UD6_PARAMS=shadow-folder directory ASN file setting.

Let us say that you are using the IDF and wish to make modifications to the Form Component AGBXTRA. You start up the Visual SourceSafe Explorer client, Select the file AGBXTRA.XML from the components directory and select Check Out in the Source Safe pulldown menu.

Note that the directory has automatically been set. Enter a descriptive comment for this change and press OK.

If this is the first time you have extracted a component, you will be asked to confirm the creation of the sub-directory 'components' in the work folder. Select YES.

Start the IDF, and edit the component that you 'checked out'. You should be able to make changes and store them successfully. If you edit a component that you did NOT check out. When you attempt to STORE your changes, you should be presented with a message similar to:

If you wish to, you can press OK, and then close the component without saving, switch back to Visual SourceSafe and check out this component. You now should be able to re-open the component and make changes and store them.

Visual SourceSafe & UD6 guide

Checking a form in using Visual SourceSafe

When you 'check in' a file to the Visual Source Safe Project Database, Visual SourceSafe copies the file from the area on your local machine (or a network drive on the local machine) specified as your working folder to the repository. With the setup as we have described it, Visual SourceSafe will also make a copy of the file in the shadow directory.

Select the file to be returned from the tree in the Visual SourceSafe explorer. Choose Check in from the Source Safe pulldown menu.

Enter a descriptive comment and check that the 'delete' checkbox is turned on. Press OK when complete.

Visual SourceSafe may not be able to delete the file because UD6/CMtool driver has cached a read-only open connection to the file. However Visual SourceSafe will not give an error message. It is very important however that you ensure the file is removed from your working folder since any inadvertant changes made to it will not be tracked in your SourceSafe repository.

To clear any outstanding locks on the file, use the SQL workbench function from the Uniface IDF to send the CLEANMMF command (data path UD6) to the UD6/CMtool Driver. This will close all currently cached file connections.

Once this step is completed you should be able to delete file manually. If the problem persists, it is probably due to the IDF not having committed the changes correctly to the UD6/CMtool driver. In this case, open a different form, then perform the CMEANMMF command from the SQL workbench again.

To check that the source has been successfully checked in, start the IDF, and edit one the components that you 'checked in'. When you attempt to STORE your changes, you should be presented with a message similar to:

Visual SourceSafe & UD6 guide

Adding a form using Visual SourceSafe

Creating a brand new form / service / report that has never existed before is a special case in a Configuration Managed environment. When Uniface is using the UD6/CMtool Driver it will always assume that if a 'file' does not exist in the 'shadow folder', then it does not exist.

This also applies to a new table / sub-type / library etc, but not a new register, field etc since these exist 'within' an existing entity (file).

So the easiest way to create a new form, is to copy an existing form file, remove its contents apart from the header and footer, check it in to Visual SourceSafe and then check it out and use it as normal.

e.g.:
v:\reference\bridal\components\New.xml contains:

If you do not follow this procedure one of two results is most likely:

• If you attempt to create a component within the IDF without first extracting one of that name into the work area, then you will get a STORE error
• If your 'shadow folder' is not read-only (as opposed to each XML file being read-only which Visual SourceSafe will take care of ), then you will be able to create the new component, but it will be placed in the 'shadow folder' not the working directory, and you will have to add it to version control from there.

After you have copied an existing XML file from the shadow folder to your working directory, and removed all the text between the <uniface schema ...> and </uniface_schema> tags, and renamed the file, you can then drag the file from Windows Explorer to the Visual SourceSafe explorer to add it to the project database.

Enter a descriptive comment and ensure that the 'Check Out immediately' box is set.

The new component will be added and then checked out to your user in your working directory.

Visual SourceSafe & UD6 guide

Finding the difference in versions using Visual SourceSafe

One of the most powerful features of a CM tool is it allows you to find out WHO made WHAT change. Visual SourceSafe includes a diff function to assist with this task.

From the Visual SourceSafe explorer select the file which was previously modified (AGBXTRA.XML) components sub directory.

To get to the "Differences" window, select Show Differences from the Tools pulldown menu.

You can compare the current workfile, to a version in the archive, or two archived versions. Once you have made your selection and pressed OK and the "differences" window is displayed showing differences line by line.

Consult the Visual SourceSafe documentation for further information.

Visual SourceSafe & UD6 guide

Problems when using Visual SourceSafe

Visual SourceSafe does not support triggers

Most Version Control systems support some ability to execute programs or scripts when certain events are 'triggered' in the Version Control System.

Visual SourceSafe does not support this concept, and so the UD6/CMtool Driver cannot use the INUSE file to determine the location of 'checked out' files.

March Hare supply an alternative technique for when Visual SourceSafe to locate the 'checked out' files, using additional parameters in the assignment file, SHADOW-FOLDER and SANDPIT. E.g.:

USYS$UD6_PARAMS=shadow-folder v:\, sandpit c:\sandpit