MKS Task User Manual

Contact MKS Customer Care for support.

Introduction
The Task
Predefined Sub-tasks
Details:

Task tag: mks

Description
Parameters

Sub-tasks

General tag: command

Description
Parameters

Custom tags: co, ci, lock, unlock, freeze, thaw, createsandbox, resync

Description
Parameters

Examples
Comments

Introduction

This Task provides the implementation needed to execute MKS commands using the MKS Java API, via Apache Ant. Place the MKS Java API (mksapi.jar) library and the MKS Ant integration (mkstask.jar) library into Ant's lib directory, or ensure your build.xml file includes the absolute paths to these two libraries, as described in the sample build.xml. The MKS API library is found in your MKS Integrity Client installation: for example, C:\Program Files\MKS\IntegrityClient\lib\mksapi.jar.

To execute the commands, you need to define one task: mks.integrations.apache.ant.MKSTask. For the purposes of this manual, we assume that you have named the MKSTask mks. This task definition must go inside a target which is executed before any mks task. An example of this task definition is below:


<taskdef name="mks" classpath="${mkstask.jar};${mksapi.jar}" classname="mks.integrations.apache.ant.MKSTask" />

The properties mkstask.jar and mksapi.jar must be set to the locations of these libraries.

From within an mks task tag you can run any SI commands, as well as the custom tasks described in more detail below.

This document assumes you are familiar with both Ant and the MKS Command Line Interface (CLI). If this is not the case, visit the Apache Ant Homepage for details on Ant, and for details on the MKS Source CLI, see the MKS Source CLI Reference Guide.

The Task

mks	multipurpose task that allows any MKS command to be executed

Predefined Sub-tasks

command	general tag that permits the execution of any SI command
co	checks out members of a sandbox
ci	checks in members of a sandbox
lock	locks project members
unlock	unlocks a member
freeze	freezes a project member
thaw	thaws a project member
createsandbox	creates a new sandbox on the local machine
resync	updates a sandbox with the member revision

The Task

Task tag: mks

The mks task is designed to allow easy access to MKS Source (and MKS Integrity) commands from within Ant scripts. The task is designed to provide a bridge between Ant and the MKS Java API.

Commands are executed using sub-tasks of the mks task. See the examples section for more details.

Parameters

Attribute	Description	Required
failonerror	Specifies whether to stop the build process (`true`) or keep going (`false`) if the MKS command returns an error.	No; defaults to "false"
suppressoutput	Specifies whether or not output is shown with the execution of the MKS command.	No; defaults to "false"
append	If true, output is appended to specified files.	No; defaults to "false"
output	The file that standard output is sent to.	No; defaults to ANT Log as MSG_INFO
error	The file that error messages are sent to.	No; defaults to ANT Log as MSG_WARN
timestamp	If true, output is prefixed with a timestamp.	No; defaults to "false"

The parameters failonerror and suppressoutput have global scope. These values are inherited by inner command tags but can be overwritten by such tags.
The parameters append, output, error, and timestamp have global scope and apply to all the commands executed within this task.

Sub-tasks

General tag: command

Description

This sub-task is a general tag that allows any command to be run as long as the application and command parameters have been specified. The output generated by this tag is general.

To add a list of options to an MKS command, use the <options> tag. To add a list of selections (files, members, sandboxes, etc.) use the <selection> tag.

Parameters

Attribute Description Required

application Specifies the application executes this command. For example, "si", "im". Yes

command Specifies the command to be executed. For example, "add", "drop", "ci", "co". Yes

failonerror Specifies whether to stop the build process (true) or keep going (false) if the MKS command returns an error. No; defaults to the value defined in the mks tag

suppressoutput Specifies whether or not output is shown with the execution of the MKS command. No; defaults to the value defined in the mks tag

Custom tags: co, ci, lock, unlock, freeze, thaw, createsandbox, resync

Description

These sub-tasks are tags that provide custom output for the command execution. The output generated by these commands mimics the output generated by the Command Line Interpreter when executing the same commands.

To add a list of options to a MKS command, use the <options> tag. To add a list of selections (files, members, sandboxes, etc.), use the <selection> tag.

Parameters

Attribute	Description	Required
failonerror	Specifies whether to stop the build process (`true`) or keep going (`false`) if the MKS command returns an error.	No; defaults to the value defined in the mks tag
suppressoutput	Specifies whether output is shown with the execution of the MKS command	No; defaults to the value defined in the mks tag

Examples

The MKS Source command "si co --lock --cpid=1:1 file1.txt file2.txt" can be run as:

Using the general <command> tag:


<mks>

    <command

        application="si"

        command="co"

    >

        <options>

            <option name="lock"/>

            <option name="cpid">1:1</option>

        </options>

        <selections>

            <selection>file1.txt</selection>

            <selection>file2.txt</selection>

        <selections>

    </command>

</mks>

Or, using the predefined <co> tag:


<mks>

    <co>

        <options>

            <option name="lock"/>

            <option name="cpid">1:1</option>

        </options>

        <selections>

            <selection>file1.txt</selection>

            <selection>file2.txt</selection>

        <selections>

    </co>

</mks>

Or, if the following properties are defined in the build file


<property name="files.file1" value="file1.txt"/>

<property name="files.file2" value="file2.txt"/>

<property name="changePackageId" value="1:1"/>



<mks>

    <co>

        <options>

            <option name="lock"/>

            <option name="cpid">${changePackageId}</option>

        </options>

        <selections>

            <selection>${files.file1}</selection>

            <selection>${files.file2}</selection>

        <selections>

    </co>

</mks>

Several MKS commands can be executed inside the <mks> tags. For example:


<mks failonerror="false" append="true" error="errorFile.txt">

    <co failonerror="true">

        ...

    </co>

    <lock suppressouput="true" failonerror="false">

        ...

    </lock>

    <command application="si" failonerror="true" command="updaterevision" >

        ...

    </command>

        ...

</mks>

Does the following:

Directs standard output to the Ant Log, since "output" was not specified.
Does not stop the build if there is a problem using the MKS Java API (failonerror="false").
Appends (append="true") any error messages to the specified error output file (errorfile.txt).
Runs the three MKS commands co, lock and updaterevision, in that order:

While executing co, stops the build if any errors are encountered.
While executing lock, it will not output any standard output and it will not stop the build if any errors are found
While executing updaterevision, stops the build if any errors are found.

See the included build.xml file for more examples. Follow the comments included in that file to customize it for your needs.

Comments

If invalid options or selections are passed to a file, error messages are sent to the specified error attribute.
For documentation on how to run commands to the MKS Integrity Client, see the MKS Source CLI Reference Guide.
Executing commands using the <command> tag outputs all information retrieved from the command. Executing commands using the specific command tags (such as ci) only outputs command-relevant information.
To make use of an existing change package, the change package ID must be added to the options for the task. See the MKS Source CLI Reference Guide for details on how to create a change package using the <command> tag.
For general notes on creating build.xml files, see the Ant User Manual.

Copyright © 2001–2006 MKS Software Inc.; in Canada copyright owned by MKS Inc. All rights reserved. MKS, MKS Source Integrity, MKS Integrity Manager, Implementer, MKS Toolkit, Sandbox, NuTCRACKER, MKS Integrity Solution, MKS Integrity Suite, AlertCentre, and MKS Federated Server are trademarks or registered trademarks of MKS Inc. All other trademarks or registered trademarks are the property of their respective holders.

MKS Task User Manual

Contents