# Ant ClearCase Tasks

by:
Curtis White (cwhite at aracnet dot com),
Sean P. Kane (spkane at genomatica dot com),
Rob Anderson (Anderson.Rob at vectorscm dot com), and
Sean Egan (sean at cm-logic dot com)

Version 1.6 - 02/25/2003

# ClearCase Support

## Table of Contents

- Introduction
- CCCheckin
- CCCheckout
- CCUnCheckout
- CCUpdate
- CCMklbtype
- CCMklabel
- CCRmtype
- CCLock
- CCUnlock
- CCMkbl
- CCMkattr
- CCMkdir
- CCMkelem

## Introduction

Ant provides several optional tasks for working with ClearCase. These tasks correspond to various ClearCase commands using the Cleartool program. The current tasks available for Ant correspond to only a few of the significant ClearCase commands.

More tasks can be easily added by deriving from the ClearCase class and then adding functionality that is specific to that ClearCase command.

Important: these tasks all require `cleartool` on the command line. If a task fails with an IOException, especially error code 2 on Windows, this is your problem.

## CCCheckin

### Description

Task to perform a "cleartool checkin" command to ClearCase.

### Parameters

Attribute | Values | Required
--- | --- | ---
viewpath | Path to the ClearCase view file or directory that the command will operate on | No
comment | Specify a comment. Only one of comment or commentfile may be used. | No
commentfile | Specify a file containing a comment. Only one of comment or commentfile may be used. | No
nowarn | Suppress warning messages | No
preservetime | Preserve the modification time | No
keepcopy | Keeps a copy of the file with a .keep extension | No
identical | Allows the file to be checked in even if it is identical to the original | No
failonerr | Throw an exception if the command fails. Default is true | No

### Examples

>     <cccheckin viewpath="c:/views/viewdir/afile"
>             commentfile="acomment.txt"
>             nowarn="true"
>             identical="true"/>

Does a ClearCase checkin on the file c:/views/viewdir/afile. Comment text from the file acomment.txt is added to ClearCase as a comment. All warning messages are suppressed. The file is checked in even if it is identical to the original.

## CCCheckout

### Description

Task to perform a "cleartool checkout" command to ClearCase.

### Parameters

Attribute | Values | Required
--- | --- | ---
viewpath | Path to the ClearCase view file or directory that the command will operate on | No
reserved | Specifies whether to check out the file as reserved or not | Yes
out | Creates a writable file under a different filename | No
nodata | Checks out the file but does not create an editable file containing its data | No
branch | Specify a branch to check out the file to | No
version | Allows checkout of a version other than main latest | No
nowarn | Suppress warning messages | No
comment | Specify a comment. Only one of comment or commentfile may be used. | No
commentfile | Specify a file containing a comment. Only one of comment or commentfile may be used. | No
notco | Fail if it's already checked out to the current view. Set to false to ignore it. Since ant 1.6.1 | No
failonerr | Throw an exception if the command fails. Default is true. Since ant 1.6.1 | No

### Examples

>     <cccheckout viewpath="c:/views/viewdir/afile"
>             reserved="true"
>             branch="abranch"
>             nowarn="true"
>             comment="Some comment text"/>

Does a ClearCase checkout on the file c:/views/viewdir/afile. It is checked out as reserved on branch called abranch. All warning messages are suppressed. A Some comment text is added to ClearCase as a comment.

## CCUnCheckout

### Description

Task to perform a UnCheckout command to ClearCase.

### Parameters

Attribute | Values | Required
--- | --- | ---
viewpath | Path to the ClearCase view file or directory that the command will operate on | No
keepcopy | Specifies whether to keep a copy of the file with a .keep extension or not | No
failonerr | Throw an exception if the command fails. Default is true Since ant 1.6.1 | No

### Examples

>     <ccuncheckout viewpath="c:/views/viewdir/afile"
>             keepcopy="true"/>

Does a ClearCase uncheckout on the file c:/views/viewdir/afile. A copy of the file called c:/views/viewdir/afile.keep is kept.

## CCUpdate

### Description

Task to perform an "cleartool update" command to ClearCase.

### Parameters

Attribute | Values | Required
--- | --- | ---
viewpath | Path to the ClearCase snapshot view file or directory that the command will operate on | No
graphical | Displays a graphical dialog during the update | No
log | Specifies a log file for ClearCase to write to | No
overwrite | Specifies whether to overwrite hijacked files or not | No
rename | Specifies that hijacked files should be renamed with a .keep extension | No
currenttime | Specifies that modification time should be written as the current time. Either currenttime or preservetime can be specified. | No
preservetime | Specifies that modification time should preserved from the VOB time. Either currenttime or preservetime can be specified. | No
failonerr | Throw an exception if the command fails. Default is true. Since ant 1.6.1 | No

### Examples

>     <ccupdate viewpath="c:/views/viewdir"
>             graphical="false"
>             log="log.log"
>             overwrite="true"
>             currenttime="true"
>             rename="false"/>

Does a ClearCase update on the snapshot view directory c:/views/viewdir. A graphical dialog will be displayed. The output will be logged to log.log and it will overwrite any hijacked files. The modified time will be set to the current time.

## CCMklbtype

### Description

Task to perform a "mklbtype" command to ClearCase.

### Parameters

Attribute | Values | Required
--- | --- | ---
typename | Name of the label type to create | Yes
vob | Name of the VOB | No
replace | Replace an existing label definition of the same type | No
global | Either global or ordinary can be specified, not both. Creates a label type that is global to the VOB or to VOBs that use this VOB | No
ordinary | Either global or ordinary can be specified, not both. Creates a label type that can be used only in the current VOB. Default | No
pbranch | Allows the label type to be used once per branch in a given element's version tree | No
shared | Sets the way mastership is checked by ClearCase. See ClearCase documentation for details | No
comment | Specify a comment. Only one of comment or cfile may be used. | No
commentfile | Specify a file containing a comment. Only one of comment or cfile may be used. | No
failonerr | Throw an exception if the command fails. Default is true Since ant 1.6.1 | No

### Examples

>     <ccmklbtype typename="VERSION_1"
>             ordinary="true"
>             comment="Development version 1"/>

Does a ClearCase mklbtype to create a label type named VERSION_1. It is created as ordinary so it is available only to the current VOB. The text Development version 1 is added as a comment.

## CCMklabel

### Description

Task to perform a "mklabel" command to ClearCase.

### Parameters

Attribute | Values | Required
--- | --- | ---
typename | Name of the label type | Yes
viewpath | Path to the ClearCase view file or directory that the command will operate on | No
replace | Replace a label of the same type on the same branch | No
recurse | Process each subdirectory under viewpath | No
version | Identify a specific version to attach the label to | No
vob | Name of the VOB | No
comment | Specify a comment. Only one of comment or cfile may be used. | No
commentfile | Specify a file containing a comment. Only one of comment or cfile may be used. | No
failonerr | Throw an exception if the command fails. Default is true Since ant 1.6.1 | No

### Examples

>     <ccmklabel viewpath="c:/views/viewdir/afile"
>             comment="Some comment text"
>             recurse="true"
>             version="\main\2"
>             typename="VERSION_1"/>

Does a ClearCase mklabel on the file c:/views/viewdir/afile under the main branch for version 2 (\main\2). Text Some comment text is added as a comment. It will recurse all subdirectories.

## CCRmtype

### Description

Task to perform a "rmtype" command to ClearCase.

### Parameters

Attribute | Values | Required
--- | --- | ---

typekind

The kind of type to create. Valid types are:

| attype brtype eltype hltype lbtype trtype | - - - - - - | attribute type branch type element type hyperlink type label type trigger type

Yes

typename | The name of the type to remove | Yes
ignore | Used with trigger types only. Forces removal of trigger type even if a pre-operation trigger would prevent its removal | No
rmall | Removes all instances of a type and the type object itself | No
comment | Specify a comment. Only one of comment or cfile may be used. | No
commentfile | Specify a file containing a comment. Only one of comment or cfile may be used. | No
failonerr | Throw an exception if the command fails. Default is true Since ant 1.6.1 | No

### Examples

>     <ccrmtype typekind="lbtype"
>             typename="VERSION_1"
>             commentfile="acomment.txt"
>             rmall="true"/>

Does a ClearCase rmtype to remove a label type (lbtype) named VERSION_1. Comment text from the file acomment.txt is added as a comment. All instances of the type are removed, including the type object itself.

## CCLock

### Description

Task to perform a "cleartool lock" command to ClearCase.

### Parameters

Attribute | Values | Required
--- | --- | ---
replace | Specifies replacing an existing lock | No
nusers | Specifies user(s) who can still modify the object | No
obsolete | Specifies that the object should be marked obsolete | No
comment | Specifies how to populate comments fields | No
pname | Specifies the object pathname to be locked. | No
objselect | This variable is obsolete. Should use objsel instead. | No
objsel | Specifies the object(s) to be locked. Since ant 1.6.1 | No
failonerr | Throw an exception if the command fails. Default is true. Since ant 1.6.1 | No

### Examples

>     <cclock
>         objsel="stream:Application_Integration@\MyProject_PVOB"
>         />

Does a ClearCase lock on the object stream:Application_Integration@\MyProject_PVOB.

## CCUnlock

### Description

Task to perform a "cleartool unlock" command to ClearCase.

### Parameters

Attribute | Values | Required
--- | --- | ---
comment | Specifies how to populate comments fields | No
pname | Specifies the object pathname to be unlocked. | No
objselect | This variable is obsolete. Should use objsel instead. | No
objsel | Specifies the object(s) to be unlocked. Since ant 1.6.1 | No
failonerr | Throw an exception if the command fails. Default is true. Since ant 1.6.1 | No

### Examples

>     <ccunlock
>         objsel="stream:Application_Integration@\MyProject_PVOB"
>         />

Does a ClearCase unlock on the object stream:Application_Integration@\MyProject_PVOB.

## CCMkbl

### Description

Task to perform a "cleartool mkbl" command to ClearCase.

### Parameters

Attribute | Values | Required
--- | --- | ---
comment | Specify a comment. Only one of comment or cfile may be used. | No
commentfile | Specify a file containing a comment. Only one of comment or cfile may be used. | No
baselinerootname | Specify the name to be associated with the baseline. | Yes
nowarn | Suppress warning messages | No
identical | Allows the baseline to be created even if it is identical to the previous baseline. | No
full | Creates a full baseline. | No
nlabel | Allows the baseline to be created without a label. | No
failonerr | Throw an exception if the command fails. Default is true. Since ant 1.6.1 | No

### Examples

>     <ccmkbl
>         baselinerootname="Application_Baseline_AUTO"
>         identical="yes"
>         full="no"
>         viewpath="v:\ApplicationCC"
>         />

Does a ClearCase mkbl on the Integration view at v:\ApplicationCC even if it is identical to a previous baseline. The new baseline with be incremental and named "Application_Baseline_AUTO".

## CCMkattr

### Description

Task to perform a "cleartool mkattr" command to ClearCase.
Since ant 1.6.1

### Parameters

Attribute | Values | Required
--- | --- | ---
viewpath | Path to the ClearCase view file or directory that the command will operate on | Yes
replace | Replace the value of the attribute if it already exists | No
recurse | Process each subdirectory under viewpath | No
version | Identify a specific version to attach the attribute to | No
typename | Name of the attribute type | Yes
typevalue | Value to attach to the attribute type | Yes
comment | Specify a comment. Only one of comment or cfile may be used. | No
commentfile | Specify a file containing a comment. Only one of comment or cfile may be used. | No
failonerr | Throw an exception if the command fails. Default is true | No

### Examples

>     <ccmkattr viewpath="c:/views/viewdir/afile"
>         typename="BugFix"
>         typevalue="34445"
>         />

Does a ClearCase mkattr on the file c:/views/viewdir/afile and attaches the attribute BugFix with a value of 34445 to it.

## CCMkdir

### Description

Task to perform a "cleartool mkdir" command to ClearCase.
Since ant 1.6.1

### Parameters

Attribute | Values | Required
--- | --- | ---
viewpath | Path to the ClearCase view directory that the command will operate on | Yes
comment | Specify a comment. Only one of comment or cfile may be used. | No
commentfile | Specify a file containing a comment. Only one of comment or cfile may be used. | No
nocheckout | Do not checkout after element creation | No
failonerr | Throw an exception if the command fails. Default is true | No

### Examples

>     <ccmkdir viewpath="c:/views/viewdir/adir"
>             nochcekout="true"
>             comment="Some comment text"/>

Does a ClearCase mkdir on the dir c:/views/viewdir/adir and does not automatically check it out.

## CCMkelem

### Description

Task to perform a "cleartool mkelem" command to ClearCase.
Since ant 1.6.1

### Parameters

Attribute | Values | Required
--- | --- | ---
viewpath | Path to the ClearCase view file or directory that the command will operate on | Yes
comment | Specify a comment. Only one of comment or cfile may be used. | No
commentfile | Specify a file containing a comment. Only one of comment or cfile may be used. | No
nowarn | Suppress warning messages | No
nocheckout | Do not checkout after element creation | No
checkin | Checkin element after creation | No
preservetime | Preserve the modification time (for checkin) | No
master | Assign mastership of the main branch to the current site | No
eltype | Element type to use during element creation | No
failonerr | Throw an exception if the command fails. Default is true | No

### Examples

>     <ccmkelem viewpath="c:/views/viewdir/afile"
>             eltype="text_file"
>             checkin="true"
>             comment="Some comment text"/>

Does a ClearCase mkelem on the file c:/views/viewdir/afile with element type text_file. It also checks in the file after creation.