du_tool

Product	Command type
ClearCase®	Perl script

Platform
Windows®
Linux®
The UNIX® system

Synopsis

du_tool.pl --generate
             --directory staging-dir [[--directory staging-dir]...]
             --name release-name --version release-version
             [--tag dynamic-view-tag | --pname snapshot-view-pname]
             [--out output-file]

du_tool.pl { --decorate [--instance instance-id]
               [[--baseline baseline-text]...]
               [[--logvendor vendor] [--buildlog log-file]...]
             | --resolve
             }
             [--tag dynamic-view-tag | --pname snapshot-view-pname]
             [--out output-file]
             [input-file]

du_tool.pl --verify [input-file]

Description

The du_tool Perl script is a command-line utility that is supported in environments running either base ClearCase or Unified Change Management (UCM). The du_tool utility must be invoked using ratlperl on a ClearCase client host from which named views and VOBs are accessible.

Table 1 lists operations that can be run on deployment units using du_tool.

Table 1. du_tool operations
Operation	Command-line argument	Description
Generate	–generate	Searches through one or more directory trees within one or more VOBs and generates a deployment unit template XML file that consists of entries for each file found.
Decorate	–decorate	Creates a deployment unit XML file from the deployment unit template, and adds the following information to the file: VOB object references (OREFs) to the files listed in the deployment unit The config spec of the view in which the decorate option was run The specific config spec rule that selected the versions in your VOB that are selected by the decorate option The names of the registry server and registry region of the machine on which the decorate operation was run A history element indicating that the decorate option has been run on the deployment unit template
Resolve	–resolve	Is run at deployment time to resolve the OREFS in a deployment unit to version-extended pathnames.
Verify	–verify	Verifies that a deployment unit template is in valid XML format. If you have created your deployment unit template file by means other than running du_tool –generate, you can use this option to verify that the files consist of well-formed XML.

Additional options and arguments

Specifying which VOB directory trees to search
The following option enables you to specify one or more directory trees in one or more VOBs in which you want du_tool to search for files that will be deployed. This option is required and only valid for the du_tool –generate command.

–directory

You must specify at least one VOB directory tree in which you want du_tool to search for files that you want to deploy. You can specify multiple directories as needed.
Specifying a view context
When running the du_tool –generate, –decorate, or –resolve commands, you must either be in a view context or specify a view context using the following options. A view context is not required for the du_tool –verify command.

–tag

This option is used to specify the tag of a dynamic view in which you want to run du_tool.

–pname

This option is used to specify the pathname to a snapshot view in which you want to run du_tool.
Specifying information about your release
The following options can be used with the du_tool –generate and –decorate commands to enter information about your release, such as the release's name, version, instance ID, and baselines, into a deployment unit. You must specify these options using the appropriate quoting syntax for the shell you are running.

–name

This option is required for the du_tool –generate command; it is not valid when running du_tool with other command-line options. This option is used to specify the name of your release, which gets noted in your deployment unit template file.

–version

This option is required for the du_tool –generate command; it is not valid when running du_tool with other command-line options. This option is used to specify the version of the release that you specified using the –name option.

–instance

This argument is optional for the du_tool –decorate command; it is not valid when running du_tool with other command-line options. This option can be used to specify an additional ID for a particular decorated instance. You can use this argument multiple times to specify multiple IDs.

–baseline

This argument is optional for the du_tool –decorate command; it is not valid when running du_tool with other command-line options. This option can be used to specify the name of a baseline, which gets noted in your deployment unit XML file. This option can be specified multiple times to specify multiple baselines; for example, you could use this option multiple times to describe all constituent baselines in a composite baseline.
Specifying an output file name
The following option enables you to specify an output file name when running du_tool with supported command-line options other than –verify.

–out

This option is optional for commands other than du_tool –verify. This option can be used to specify the name of the output file resulting from running the du_tool –generate, – decorate, or –resolve commands. If a value is not specified for this option, the results of the du_tool command are directed to STDOUT.
Specifying information about your build
The following options can be used with du_tool to enter information about your build into a deployment unit, such as the location in your VOB of the build log and the name of the vendor of your build software. These options must be used with one another; they are not valid when used alone.

–buildlog

This argument is optional for the du_tool –decorate command; it is not valid when running du_tool with other command-line options. This option can be used to specify the location of a build audit log that has been checked in to your VOB. It can be specified multiple times to specify multiple build logs.

–logvendor

This argument is optional for the du_tool –decorate command; when running du_tool with other command-line options. This option can be used to specify the vendor of the software that you are using to perform builds.

Restrictions

You must invoke du_tool using ratlperl; du_tool will not work with other versions of Perl.
du_tool must be run on a machine accessible by ClearCase views and VOBs.
du_tool works with dynamic and snapshot views only. Web views are not supported.

Examples

Generating a deployment unit template

In the following example, a list of files to be built and deployed is captured by running the du_tool –generate command. This command creates a deployment unit template XML file, myApp_du_template.xml, that lists all files in \testvob\shlib to be deployed:

Z:\test_vob\shlib>ratlperl "\Program Files\Rational\ClearCase\etc\du_tool.pl" 
--generate --directory \test_vob\shlib --name "My Test App" --version 1.0 
 --out myApp_du_template.xml
Z:\test_vob\shlib>more myApp_du_template.xml

<?xml version="1.0" encoding="UTF-8"?>
<tracking:deploymentUnit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:tracking="http://www.ibm.com/deployment/schema/deploymentTracking.xsd" 
name="My Test App" version="1.0">
    <file path="\test_vob\shlib\foo.so" origPath="foo.so" />
    <file path="\test_vob\shlib\bar.so" origPath="bar.so" />
    <file path="\test_vob\shlib\baz.so" origPath="baz.so" />
    <file path="\test_vob\shlib\linked_foo.txt" origPath="linked_foo.txt" />
    <history changeOperation="Generate" changeNote="" user="deployment_engr" 
hostname="melamine.lexma.ibm.com" datetime="2005-11-11T15:05:04-05:00" />
</tracking:deploymentUnit>

Add your deployment unit template file to version control by checking it into your VOB.

Verifying a deployment unit template
Run du_tool to verify that your deployment unit template consists of valid XML only if you have created it by means other than running du_tool –generate. If you use du_tool –generate to create your deployment unit template, the template is guaranteed to be in valid XML format.

The following example shows how to run du_tool –verify to verify a deployment unit template:
```
Z:\testvob\shlib>ratlperl "\Program Files\Rational\ClearCase\etc\du_tool.pl" 
--verify myApp_du_template.xml
```

Decorating a deployment unit

In the following example, a deployment unit called myApp_du.xml is created from the template file myApp_du_template.xml by running the du_tool –decorate command:

Z:\test_vob\shlib>ratlperl "\Program Files\Rational\ClearCase\etc\du_tool.pl" 
--decorate --instance build_20051102 --baseline some_baseline --logvendor "ISV" 
--buildlog \test_vob\build_log_20051102.txt 
--buildlog \test_vob\build_log_20051102_secondary.txt 
--out myApp_du.xml myApp_du_template.xml
Z:\test_vob\shlib>more myApp_du.xml

<?xml version="1.0" encoding="UTF-8"?>
<tracking:deploymentUnit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
instanceID="build_20051102-20051111150819-0500" version="1.0" name="My Test App" 
xmlns:tracking="http://www.ibm.com/deployment/schema/deploymentTracking.xsd">
    <file path="\test_vob\shlib\foo.so" versionURI="ccase:/vobs/test_vob/shlib/foo.so?
OREF=oid%3A286b43cd.291e11da.8af5.00%3A01%3A80%3Aa6%3Ad4%3A39%40
vobuuid%3Aaf2b2c77.291a11da.8ae0.00%3A01%3A80%3Aa6%3Ad4%3A39&
registry_server=melamine.lexma.ibm.com&region=atria_r_d_unc" csrule="\main\LATEST" 
origPath="foo.so" />
    <file path="\test_vob\shlib\bar.so" versionURI="ccase:/vobs/test_vob/shlib/bar.so?
OREF=oid%3A290b43d9.291e11da.8af5.00%3A01%3A80%3Aa6%3Ad4%3A39%40
vobuuid%3Aaf2b2c77.291a11da.8ae0.00%3A01%3A80%3Aa6%3Ad4%3A39&
registry_server=melamine.lexma.ibm.com&region=atria_r_d_unc" csrule="\main\LATEST" 
origPath="bar.so" />
    <file path="\test_vob\shlib\baz.so" versionURI="ccase:/vobs/test_vob/shlib/baz.so?
OREF=oid%3A290b43e5.291e11da.8af5.00%3A01%3A80%3Aa6%3Ad4%3A39%40
vobuuid%3Aaf2b2c77.291a11da.8ae0.00%3A01%3A80%3Aa6%3Ad4%3A39&
registry_server=melamine.lexma.ibm.com&region=atria_r_d_unc" csrule="\main\LATEST" 
origPath="baz.so" />
    <file path="\test_vob\shlib\linked_foo.txt" 
versionURI="ccase:/vobs/test_vob/shlib/linked_foo.txt?
OREF=oid%3A70f083b0.29e611da.8b9b.00%3A01%3A80%3Aa6%3Ad4%3A39%40
vobuuid%3Aaf2b2c77.291a11da.8ae0.00%3A01%3A80%3Aa6%3Ad4%3A39&
registry_server=melamine.lexma.ibm.com&region=atria_r_d_unc" csrule="\main\LATEST" 
origPath="linked_foo.txt" />
    <CCOrigin>
        <baseline baselineName="some_baseline" originAuthority="UserProvided" />
        <configSpec>
            element * CHECKEDOUT
            element * /main/LATEST
        </configSpec>
    </CCOrigin>
    <buildOrigin>
        <buildLog path="\test_vob\build_log_20051102.txt" 
versionURI="ccase:/vobs/test_vob/build_log_20051102.txt?
OREF=oid%3A142327c7.4bac11da.8678.00%3A01%3A80%3Aa6%3Ad4%3A39%40
vobuuid%3Aaf2b2c77.291a11da.8ae0.00%3A01%3A80%3Aa6%3Ad4%3A39&
registry_server=melamine.lexma.ibm.com&region=atria_r_d_unc" vendor="ISV" />
        <buildLog path="\test_vob\build_log_20051102_secondary.txt" 
versionURI="ccase:/vobs/test_vob/build_log_20051102_secondary.txt?
OREF=oid%3A4bcddb45.4d4411da.87b4.00%3A01%3A80%3Aa6%3Ad4%3A39%40
vobuuid%3Aaf2b2c77.291a11da.8ae0.00%3A01%3A80%3Aa6%3Ad4%3A39&
registry_server=melamine.lexma.ibm.com&region=atria_r_d_unc" vendor="ISV" />
    </buildOrigin>
   < history changeOperation="Decorate" changeNote="" user="deployment_engr" 
hostname="melamine.lexma.ibm.com" datetime="2005-11-11T15:08:19-05:00" />
    <history changeOperation="Generate" changeNote="" user="deployment_engr" 
hostname="melamine.lexma.ibm.com" datetime="2005-11-11T15:05:04-05:00" />
</tracking:deploymentUnit>

Add your deployment unit file to version control by checking it into your VOB.

Resolving a deployment unit

In the following example, version-extended pathnames of the files that you want to deploy are added to the deployment unit file by running the du_tool –resolve command. This enables the versions of the files that are being deployed to be tracked throughout the deployment lifecycle: