Step by Step guide to using UD6/CMtool Driver with eChange Man

eChange Man (formerly known as Diamond CM) is popular in HP/3000 and mainframe environments and is also available for many unix variants and Windows NT. It offers process control, version control, release / build management, programming editor, software distribution, and other features.

The home of eChange Man on the web is http://www.serena.com

A complete list of configuration management tools can be found at http://www.iac.honeywell.com/Pub/Tech/CM/CMTools.html

If you have not already done so, please read A methodology to Uniface source code control before you continue with these topics and examples.

Configuration Information

The Windows-NT version of eChange Man is a combination of server, and clients. Clients can use either a Win32 based browser or a Java based browser. These examples are all using the Win32 based browser.

• Install eChange Man Server according to the installation guide provided with it.
• Create a directory on the NT server for the source code files (if this is on a different server than eChangeMan was installed on then a communication agent must be installed on the machine hosting the directory). This will become the primary 'Production Area'.
• Share the created directory as 'echangeman', allowing full read-write (it will be modified later, to restrict access).
• Connect drive M: on an NT Workstation to the NT share 'echangeman'
  For the purposes of this demonstration, the default directory of the shortcut used to start the IDF should be m:\ (the drive where the sources have been loaded).
• Install eChange Man client (either the win32 or Java client, but the win32 client is the only one that will be discussed here) on the NT Workstation.
• 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 Joins File (in the Uniface bin directory) to locate the source code on drive M:
• Alter the usys.asn file to have a 'catchall' to direct all non-joined source code to drive M:, set the $MAXFILES and set temporary files to be stored in another database.
• Start and then close the IDF to initialise an empty repository. (For the purposes of this demonstration, the default directory of the shortcut used to start the IDF should be m:\ (the drive where the sources have been loaded). The file m:\sources\other\udicver.xml now exists.
• Add the 'nokeycheck' parameter to the USYS$UD6_PARAMS setting in the usys.asn file (this setting improves the performance of the UD6 driver for bulk load operations, but must be disabled for normal use).
• Load the repository from a backup with a command like:

Configuration Files - Joins File

The Joins file was:

UFORM:ULABEL:ULABEL::\sources\components\*
UXGROUP:UFORM:ULABEL,UBASE::UFORM
UXFIELD:UFORM:ULABEL,GRP,UBASE::UFORM
UXREGS:U_FORMLIB:U_NAME::UFORM
UCTABLE:U_VLAB,U_TLAB:U_VLAB,U_TLAB::\sources\tables\*
UCKEY:U_VLAB,U_TLAB:U_TLAB,U_KSEQ::UCTABLE
UCFIELD:U_VLAB,U_TLAB:U_FLAB::UCTABLE
UCGROUP:U_GLAB,U_VLAB:U_GLAB,U_VLAB::\sources\sub-types\*
UCRELSH:U_GLAB,U_VLAB,U_RGLAB:U_GLAB,U_VLAB,U_RGLAB::\sources\relationships\*
USOURCE:USUB!UVAR,ULAN:USUB,UVAR,ULAN::\sources\globals\*
UAPPL:ULABEL:ULABEL::\sources\applications\*
UAPLFRM:ULABEL:ULABEL,UFORM::UAPPL
USIMPL:UIMPLNAM:UIMPLNAM::UFORM
USILINK:UIMPLNAMCAL:::USIMPL
USIMPKW:UIMPLNAM:::USIMPL
USIOPER:UIMPLNAM:::USIMPL
USIPARM:UIMPLNAM:::USIMPL
USSPEC:USPECNAM:USPECNAM::UFORM
USLINK:USPECNAMCAL:::USSPEC
USOPER:USPECNAM:::USSPEC
USSPCKW:USPECNAM:::USSPEC
USPARM:USPECNAM:::USSPEC
USMENU:UMENU,UVAR,ULAN:UMENU,UVAR,ULAN::\sources\menus\*
USITEM:UMENU,UVAR,ULAN:UMENU,UVAR,ULAN,UTECHSEQ::USMENU
UGREGS:U_FORMLIB:U_FORMLIB,U_NAME::\sources\registers\*
USICPLB:UTLBNAM:UTLBNAM::\sources\type-libraries\*
USILBCP:UTLBNAM:UTLBNAM::USICPLB
USILBSS:UTLBNAM:UTLBNAM::USICPLB
UGGIF:U_MLAB:U_MLAB::\sources\templates\entity-interface\*
UGFIF:U_MLAB:U_MLAB::\sources\templates\field-interface\*
UGFLAY:U_MLAB:U_MLAB::\sources\templates\field-layout\*
UGFSYN:U_MLAB:U_MLAB::\sources\templates\field-syntax\*
UTPLFLD:TEMPLATENAME:TEMPLATENAME::\sources\templates\field\*
UTPLFRM:TEMPLATENAME:TEMPLATENAME::\sources\templates\component\*
UTPLGRP:TEMPLATENAME:TEMPLATENAME::\sources\templates\entity\*
USUBS:SUBSYSTEM:SUBSYSTEM::\sources\subsystems\*
UGLYPH:UCSUB,UCLABEL,UCVAR:UCSUB,UCLABEL,UCVAR::\sources\glyphs\*

For the purposes of this demonstration, the default directory of the shortcut used to start the IDF should be m:\ (the drive where the sources have been loaded).

Configuration Files - ASN File

An assignment file was set up to redirect the other entities, as follows:

[SETTINGS]
$language=USA
$enhanced_edit=all
$search_object=file_first
$MAXFILES=2046

[FILES]
usys:idf.aps usys:..\ud\idf.aps
usys:ur*.svc usys:..\ud\ur*.svc
usys:uu*.svc usys:..\ud\uu*.svc
usys:uu*.frm usys:..\ud\uu*.frm
usys:uv*.frm usys:..\ud\uv*.frm
usys:idf*.frm usys:..\ud\idf*.frm
usys:pv*.frm usys:..\ud\PV*.frm
usys:usys*.frm usys:usys*.frm
usys:*.dis usys:*.dis
usys:*.dsc usys:*.dsc
usys:*.trx usys:..\trx\*.trx
usys:udbg.aps usys:udbg.aps
udbg:udbg*.frm usys:udbg*.frm
gpm.aps usys:..\usys\gpm.aps
*.frm usys:..\project\*.frm
*.svc usys:..\project\*.svc
*.rpt usys:..\project\*.rpt
*.aps usys:..\project\*.aps

[PATHS]
$ud6=ud6:
$DEF=$DB3
$UUU=$DB3
$IDF=$ud6
$SYS=$DB3

[ENTITIES]
;
; Dont store temporary data in XML
USTMP.DICT $uuu:usys:..\project\USTMP.*
ULANA.DICT $uuu:usys:..\project\ULANA.*

*.sysenv usys:*.*
*.dict $ud6:\sources\other\*.*

[WIDGETS]

[LOGICALS]

[SERVICES_EXEC]

[REPORTS_EXEC]

[DRIVER_SETTINGS]
USYS$UD6_PARAMS=nokeycheck

[TM]
;MANAGER = ...
;PATHS = ...
;TIMEOUT=0
;TXRETURNPHASE=2

This will work regardless of what the current working directory is. Alternatively it is possible to make the file specifications relative to the current working directory. The added lines, and altered sections are shown in BLACK and the lines that already existed in the default asn file are shown in GREY. For the purposes of this demonstration, the default directory of the shortcut used to start the IDF should be m:\ (the drive where the sources have been loaded).

The nokeycheck parameter must be removed after doing the initial repository load, otherwise the driver will not work correctly.

This assignment file assumes that only the Uniface source code is being stored using UD6/CMtool Driver, not temporary records, or 'compiled' source (e.g.: UOBJ).

WARNING: If you have a USYS$UD6_PARAMS specified in both a local ASN file and the usys.asn file, the settings in the usys.asn file override the local assignment file.

Taking Control

As a way of introducing eChange Man, we'll go through a typical work-session using it. . The first thing to understand is that eChange Man stores all files in multiple distributed repositories.

Before continuing, ensure that the nokeycheck parameter has been removed from the USYS$UD6_PARAMS setting in the assignment file, otherwise the driver will not work correctly.

Prior to loading your source into eChange Man, it is wise to compile all objects and forms, eg:

$idf /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.

Taking Control - Create areas

Once you have set up eChangeMan with users and groups, you need to set up at least two (2) 'areas' for use with Uniface:
A Production type area, containing all of the XML files produced by the load operation in the previous step
A 'sandbox', development type area for one or more developers to modify the code in.

The 'sandbox', development type area may be on the same server or even on each developers own machine. If you wish to use a machine other than the server, you must install a communication agent on that machine. The example here will have both areas on the same server.

In the previous step we created an NT share called echangeman, and mapped it on our NT workstation to M: drive. On the server that 'shared directory' is c:\echangeman.

Using either the workstation or the server, add a directory at the same level as 'sources', called 'archive', eg: c:\echangeman\archive or m:\archive. This directory will contain the deltas between different versions of each file, it may be stored anywhere on the same server as the echangeman directory (please consult the eChange Man reference manual for further information about 'archive path').

Using the server, add a directory and equivalent NT share called 'dev', eg: c:\dev. This directory will contain the source code that is currently 'checked out' to developers, and an INUSE file.

In our example all developers are sharing the one 'developers' area. Using eChangeMan, multiple developer views are as simple as creating an area for each developer or development team, or alternatively you can create INUSE files for each developer or team but still use a single development area as described in Using an INUSE per developer or team.

Copy the programs add2list.exe and del2list.exe from your Uniface bin directory to a place on the server, in the PATH (eg: c:\windows).

Add a new production area in eChange Man (Tools->System configuration, Edit->Areas)

Properties
Name: BridalLib
Description: Bridal Registry Library
Host: ntsrvr01
Path: c:\echangeman
Archive Path: c:\echangeman\archive

Delete From:
Search Tree: Yes
AutoDoc: Yes
Type: Production
Preference: Home

Script
Script User: Administrator
Script (on one line):
del2list -rC:\dev \dev\inuse n:%from_dir%\%vcsfile%

Add a new development 'sandpit' area:

Properties
Name: BridalDev
Description: Bridal Registry Development
Host: ntsrvr01
Path: c:\dev
Archive Path: *leave blank*

Delete From: Yes
Search Tree: Yes
Type: Development
Preference: Same

Script
Script User: Administrator
Script:
set p1=\dev\inuse
set p2=%from_dir%\%vcsfile%
set p3=n:%to_dir%\%vcsfile%
add2list -rC:\dev;C:\echangeman %p1% %p2% %p3%

Taking Control - Create projects

Once you have set up eChangeMan with users and groups and areas, you need to set up a project describing the work to be done.

Projects are convenient ways of grouping a series of modifications into a single entity, a project. The project also serves as a place for bug reports generated later in testing, etc.

A project can also limit the scope of changes. So for instance, if adding a customer surcharge, perhaps only components would need to be modified, not messages, procs, templates etc. So within the project you can assign the parts of the source directory tree that you wish to allow developers to be able to check out.

For the purposes of this example, a simple project was created.

Add a new project in eChange Man (Tools->System configuration, Edit->Projects):

:Properties
Name: CustomerSurcharge
Description: Add a customer surcharge to the bridal registry

Attachments

Taking Control - Create workflow

In addition to setting up eChangeMan with users, groups, areas and project(s), you need to have at lease one workflow process defined.

This identifies how source code moves between environments. Since we are only using 2 environments in our example, it does not make a lot of difference.

Add a new process in eChange Man (Tools->System configuration, File->New):

Taking Control - Finish taking control

The final step in taking control, is to alter the NT share you created 'echangeman' for the source code, to be read-only. Alter the permissions on the share tab to allow the Administrator full-control and everyone read access only:

Using the Workstation, disconnect and reconnect drive M: so you only have read access.

Releasing a form

As a way of introducing eChange Man, we are continuing to go through a typical work-session using it with Uniface and UD6/CMtool Driver. In the previous section we loaded the current source into UD6/CMtool and set up areas in eChange Man to manage it. Now in this section we will check out a form.

Firstly you need to log into the eChange Man client as whoever has access to move something from the Production area to the Development (sandpit) area.

From the main screen open up the Areas tree, then the production tree etc. When you find a component to check out (ignoring the archive directory), drag it to the development area. If you are prompted for a description, then type a reason for this transfer. This is also the point that you may specify which version you wish to check out (the default is the top version).

To check out a component using the CustomerSurcharge project, open the tree Projects-> New ->CustomerSurcharge ->Attachments ->BridalLib instead. Once you have found a file to check out, right click on it, select Promote, Check Out (and select check out to BridalDev).

If this is the first time an object has been checked out into the development area, the 'tree' may need to be created. If you are asked permission for eChange Man to create the tree, respond YES.

In the background, on the server, the script that you specified in an earlier step will run, placing the details that the file has been 'checked out' into the INUSE file. This may take a minute or so to run, depending on the system configuration.

Connect drive N: on the Workstation to the NT share 'dev' which was created earlier (use Tools->Map Network Drive from windows explorer). When you examine the N: drive, you will see a file called 'inuse'. This is like a mini joins file for the UD6/CMtool Driver, it specifies the exceptions to the rules you set up in the joins file. The inuse file typically contains 1 line for every 'checked out' file.

Alter your usys.asn file to include the 'listdir' setting in USYS$UD6_PARAMS, eg:

[DRIVER_SETTINGS]
USYS$UD6_PARAMS=listdir n:\inuse

See also: Using an INUSE per developer or team

Start the IDF, and edit one of the components that you 'checked out'. You should be able to make changes and store them successfully. Now 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 eChange Man Client and drag this component into the development area. You now should be able to reopen the component and make changes and store them successfully (allowing time for the server to complete the request)..

Using an INUSE per developer or team

One way, with eChange Man, to use different INUSE files for each developer or team (so they can only see the changes THEY are making, not other peoples changes) is by using the listdir parameter to point to different files.

The listdir parameter setting in USYS$UD6_PARAMS, can be used to name the 'inuse' file anything. So, for instance, it would be possible to have a separate inuse file for each developer, then use the %vcsuser% batch variable in the eChange Man script. It is equally possible to use the %vcsproject% variable to name the 'inuse' file the same as a project, then allow any developer using that project to specify that inuse file, eg:

For example: the script for BridalDev could be:

set p1=\dev\%vcsuser%
set p2=%from_dir%\%vcsfile%
set p3=n:%to_dir%\%vcsfile%
add2list -rC:\dev;C:\echangeman %p1% %p2% %p3%

This technique has its drawbacks, since no two developers or projects or teams could have the same file booked out (which may not be good practice anyway).

It is even possible for the SQL Workbench to be used to change the 'inuse' file being used, in the middle of an IDF session eg:

Checking a form in

Now that we have our new copy of the form, you may make changes to it (remember that the source files in the reference area are read-only). Add a comment to the form that you checked out earlier.

To put this source back into the eChange Man production area you need to log into the eChange Man client as whoever has access to move something from the Development area to the Production area. You may also have set up rules in eChangeMan to require that another person has to signoff the change before eChange Man will move it from development to production.

From the main screen open up the Areas tree, then the development tree etc. When you find a component to check in, right click on the file and select Send Home. If you are prompted for a description, then type a reason for this transfer.

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

Adding a form

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 'reference area', 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 eChange Man and then check it out and use it as normal.

e.g.:
New.xml contains:

<?xml version="1.0"?>
<?xml-stylesheet href="components.xsl" type="text/xsl"?>
<?xml-stylesheet href="components.css" type="text/css"?>
<uniface_schema xmlns:html="http://www.w3.org/TR/REC-html40">
</uniface_schema>

To put this source into the eChange Man production area you need to log into the eChange Man client as whoever has access to move something from the Development area to the Production area. You may also have set up rules in eChangeMan to require that another person has to signoff the change before eChange Man will move it from development to production.

From the main screen open up the Areas tree, then the development tree etc. When you find a component to check in, drag it into the CORRECT FOLDER in the production area. If you are prompted for a description, then type a reason for this transfer.

The form can now be checked out and worked on as described previously.

NOTE: Even though there is an XML file, since it is empty of any data, the IDF will not show that the 'FORM' exists. Once the XML file is checked out, you can create the 'FORM' in the usual manner in the IDF.

Finding the differences in versions

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

To get to the "Diff analysis" window, select a file in the production area, from the right click menu select 'Show History', then press the 'Find Now' button. If you select any 2 versions and press the compare button at the bottom of the window, the "Diff analysis" window is displayed.

Consult the eChange Man reference manual for further information

Problems with eChange Man

When testing UD6/CMtool Driver with eChange Man the following problems were observed, that we were unable to find reference to in the associated manuals.

• Must reboot server after installation
• Scripts are not run if code is checked from Development into Production using Send Home, and the code had not changed. This leads to extraneous records in the INUSE file that need to be manually removed. March Hare do not consider this a major problem since we would expect users to usually promote from Development to QA, which will correct the INUSE file records (by placing a script in the QA Area)
• XML files are not removed from an area if a script is run, but the script cannot remove the file itself. March Hare do not consider this a major problem since as long as the inuse file is updated the extra files will be ignored. When the same file is demoted to development at a later point, eChange Man gives the user the ability to overwrite the old file.
• If you double click on an XML file when Internet Explorer 5 is installed, eChange Man opens up IE5 to display the file. Unfortunately it copies the file to the TEMP directory to display it. In the XML file, the references to the stylesheet are relative to its current location. This in turn means that IE5 cannot find the stylesheet, so it fails to display it.

To resolve this issue, first double click on the XSL file (e.g.: components.xsl), then the ud6logo.gif file, then the file that you wish to view. This copies the stylesheet to the temp directory until it is cleared by another process

.