source: other-projects/trunk/gs3-release-maker/apache-ant-1.6.5/docs/manual/OptionalTasks/starteam.html@ 14627

Last change on this file since 14627 was 14627, checked in by oranfry, 17 years ago

initial import of the gs3-release-maker
File size: 37.8 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Language" content="en-us">
4<title>StarTeam Tasks</title>
5<link rel="stylesheet" type="text/css" href="../stylesheets/antmanual.css">
6</head>
7<body>
8<h1>StarTeam Support</h1>
9<ul>
10 <li><a href="#stcheckout">STCheckout</a></li>
11 <li><a href="#stcheckin">STCheckin</a></li>
12 <li><a href="#stlabel">STLabel</a></li>
13 <li><a href="#stlist">STList</a></li>
14 <li><a href="#starteam"><i>StarTeam (deprecated) </i></a></li>
15</ul>
16
17<p>
18The StarTeam revision control system was recently acquired by Borland.
19These tasks make use of functions from the StarTeam API to work with that system.
20As a result they are only available to licensed users of StarTeam. You must have
21<CODE>starteam-sdk.jar</CODE> in your classpath to run these tasks.
22For more information about the StarTeam API and how to license it, see
23the <a href="http://www.borland.com/starteam/">Borland</a> web site.</p>
24 <p>
25 <em>All the StarTeam task names are in lower case.</em>
26 </p>
27<h3>Important Note on Installation and Licensing:</h3>
28<p>
29<b>On Windows machines, the mere presence of <CODE>starteam-sdk.jar</CODE> on the classpath
30is not sufficient for getting these tasks to work properly.</b> These tasks also require a
31fully-installed and fully-licensed version of the StarGate Runtime. This is part
32of a StarTeam client installation or may be installed separately. The full client
33install is not required. In particular, the Windows path must include the directory where
34the StarGate Runtime <CODE>.dll</CODE> files are installed.
35</p><p>
36Earlier versions of Ant (prior to 1.5.2) did not have this restriction because they
37were not as dependent on the StarTeam runtime - which the newer versions use to access
38StarTeam file status information. The older versions lacked this important capability.
39</p>
40<hr></hr>
41
42<a name="common-params">
43<h2>Common Parameters for All Starteam Tasks</h2></a>
44<p>
45The following parameters, having to do with making the connection to a StarTeam project, are common to all the following tasks except the deprecated <i>StarTeam</i> task.
46</p>
47
48<table border="1" cellpadding="2" cellspacing="0">
49 <tr>
50 <td valign="top"><b>Attribute</b></td>
51 <td valign="top"><b>Description</b></td>
52 <td align="center" valign="top"><b>Required</b></td>
53 </tr>
54 <tr>
55 <td valign="top">username</td>
56 <td valign="top">The username of the account used to log in to the StarTeam server.</td>
57 <td align="center" valign="top">yes</td>
58 </tr>
59 <tr>
60 <td valign="top">password</td>
61 <td valign="top">The password of the account used to log in to the StarTeam server.</td>
62 <td align="center" valign="top">yes</td>
63 </tr>
64
65 <tr>
66 <td valign="top">URL</td>
67 <td valign="top">A string of the form <code>servername:portnum/project/view</code>
68which enables user to set all of these elements in one string. </td>
69 <td align="center" valign="center"> Either this ...</td>
70 </tr>
71 <tr>
72 <td valign="top">servername</td>
73 <td valign="top">The name of the StarTeam server.</td>
74 <td align="center" valign="center" rowspan = "4">... or <b>all four</b> of these must be defined.</td>
75 </tr>
76 <tr>
77 <td valign="top">serverport</td>
78 <td valign="top">The port number of the StarTeam server.</td>
79 </tr>
80 <tr>
81 <td valign="top">projectname</td>
82 <td valign="top">The name of the StarTeam project on which to operate.</td>
83 </tr>
84 <tr>
85 <td valign="top">viewname</td>
86 <td valign="top">The name of the view in the StarTeam project on which to operate.</td>
87 </tr>
88
89
90</table>
91
92<hr></hr>
93
94<a name="stcheckout">
95<h2>STCheckout</h2></a>
96
97<h3>Description</h3>
98
99Checks out files from a StarTeam project.
100
101<p>
102The <i>includes</i> and <i>excludes</i> attributes function differently from
103other tasks in Ant. Inclusion/exclusion by folder is NOT supported.
104</p>
105
106<h3>Parameters</h3>
107See also <A href="#common-params">the required common StarTeam parameters</A>.<br></br>
108<table border="1" cellpadding="2" cellspacing="0">
109 <tr>
110 <td valign="top"><b>Attribute</b></td>
111 <td valign="top"><b>Description</b></td>
112 <td align="center" valign="top"><b>Required</b></td>
113 </tr>
114
115 <tr>
116 <td valign="top">rootstarteamfolder</td>
117 <td valign="top">The root of the subtree in the StarTeam repository from which to
118 check out files. Defaults to the root folder of the view ('/').
119 <b><i>If supplied, this should always be an "absolute" path, that is, it should begin with a '/'.
120 Relative paths have little meaning in this context and confuse StarTeam.</i></b>
121 </td>
122 <td align="center" valign="top">no</td>
123 </tr>
124 <tr>
125 <td valign="top">rootlocalfolder</td>
126 <td valign="top">The local folder which will be the root of the tree to which files are checked out. If this is not supplied, then the StarTeam "default folder" associated with <i>rootstarteamfolder</i> is used.
127 </td>
128 <td align="center" valign="top">no</td>
129 </tr>
130
131 <tr>
132 <td valign="top">createworkingdirs</td>
133 <td valign="top">creates local folders even when the corresponding StarTeam folder is empty. Defaults to "true".</td>
134 <td align="center" valign="top">no</td>
135 </tr>
136 <tr>
137 <td valign="top">deleteuncontrolled</td>
138 <td valign="top">if true, any files NOT in StarTeam will be deleted. Defaults to "true".</td>
139 <td align="center" valign="top">no</td>
140 </tr>
141 <tr>
142 <td valign="top">includes</td>
143 <td valign="top">Only check out files that match at least one of the patterns in this list. Patterns must be separated by <i>commas</i>. Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
144 <td align="center" valign="top">no</td>
145 </tr>
146 <tr>
147 <td valign="top">excludes</td>
148 <td valign="top">Do not check out files that match at least one of the patterns in this list. Patterns must be separated by <i>commas</i>. Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
149 <td align="center" valign="top">no</td>
150 </tr>
151 <tr>
152 <td valign="top">label</td>
153 <td valign="top">Check out files as of this label. The label must exist in starteam or an exception will be thrown.</td>
154 <td align="center" valign="center" rowspan="2">Either or neither, but not both, may be specified. Neither <code>locked</code> or <code>unlocked</code> may be true if either <code>label</code> or <code>asofdate</code> is specified.</td>
155 </tr>
156 <tr>
157 <td valign="top">asofdate</td>
158 <td valign="top">Check out files as of this date. The date must
159 be formatted in ISO8601 datetime
160 (<code>yyyy-MM-dd'T'HH:mm:ss</code>), ISO8601
161 date(<code>yyyy-MM-dd</code>) or a user-defined SimpleDateFormat
162 defined in the <code>asofDateFormat</code> attribute. If the date
163 is not parsable by the default or selected format, an exception
164 will be thrown. <em>Since Ant 1.6.</em></td>
165 </tr>
166 <tr>
167 <td valign="top">asofdateformat</td>
168 <td valign="top">java.util.SimpleDateFormat compatible string used
169 to parse the <code>asofdate</code> attribute. <em>Since Ant
170 1.6.</em></td>
171 <td align="center" valign="top">no</td>
172 </tr>
173 <tr>
174 <td valign="top">recursive</td>
175 <td valign="top">Indicates if subfolders should be searched for files to check out. Defaults to "true".</td>
176 <td align="center" valign="top">no</td>
177 </tr>
178 <tr>
179 <td valign="top">forced</td>
180 <td valign="top">If true, checkouts will occur regardless of the status
181that StarTeam is maintaining for the file. If false, status will be used to determine which files to check out. Defaults to "false".</td>
182 <td align="center" valign="top">no</td>
183 </tr>
184 <tr>
185 <td valign="top">locked</td>
186 <td valign="top">If true, file will be locked against changes by other
187users. If false (default) has no effect.
188 <td align="center" valign="center" rowspan="2">Either or neither, but not both, may be true. Neither may be true if a <code>label</code> or an <code>asofdate</code> is specified.</td>
189 </tr>
190 <tr>
191 <td valign="top">unlocked</td>
192 <td valign="top">If true, file will be unlocked so that other users may
193change it. This is a way to reverse changes that have not yet been checked in.
194If false (default) has no effect.</td>
195 </tr>
196 <tr>
197 <td valign="top">userepositorytimestamp</td>
198 <td valign="top">true means checked out files will get the repository timestamp.
199false(default) means the checked out files will be timestamped at the time
200of checkout.</td> <td align="center" valign="top">no</td>
201
202 </tr>
203 <tr>
204 <td valign="top">preloadfileinformation</td>
205 <td valign="top">The StarTeam server has the ability to preload file metadata for an
206 entire tree prior to beginning action on that tree. Doing so can in some instances
207 lead to substantially faster actions, particularly over large trees. Setting this
208 to "yes" (default) engages this functionality, setting it to "no" turns it off.</td>
209 <td align="center" valign="top">no</td>
210 </tr>
211
212 <tr>
213 <td valign="top">convertEOL</td>
214 <td valign="top">If true, (default) all ascii files will have their end-of-line
215 characters adjusted to that of the local machine on checkout. This is normally
216 what you'd want but if for some reason you don't want that to happen, set it to false
217 and the files will be checked out with whatever end-of-line characters are used on
218 the server. </td>
219 <td align="center" valign="top">no</td>
220 </tr>
221
222</table>
223
224<h3>Examples</h3>
225
226<pre>
227 &lt;stcheckout servername="STARTEAM"
228 serverport="49201"
229 projectname="AProject"
230 viewname="AView"
231 username="auser"
232 password="secret"
233 rootlocalfolder="C:\dev\buildtest\co"
234 forced="true"
235 /&gt;
236</pre>
237
238The minimum necessary to check out files out from a StarTeam server. This will
239check out all files in the <i>AView</i> view of the <i>AProject</i> project to
240<code>C:\dev\buildtest\co</code>. Empty folders in StarTeam will have local folders
241created for them and any non-StarTeam files found in the tree will be deleted.
242
243<pre>
244 &lt;stcheckout URL="STARTEAM:49201/Aproject/AView"
245 username="auser"
246 password="secret"
247 rootlocalfolder="C:\dev\buildtest\co"
248 forced="true"
249 /&gt;
250</pre>
251And this is a simpler way of accomplishing the same thing as the previous example, using the URL attribute.
252<br></br>
253<pre>
254 &lt;stcheckout URL="STARTEAM:49201/Aproject/AView"
255 username="auser"
256 password="secret"
257 rootlocalfolder="C:\dev\buildtest\co"
258 rootstarteamfolder="\Dev"
259 excludes="*.bak *.old"
260 label="v2.6.001"
261 forced="true"
262 /&gt;
263</pre>
264
265This will check out all files from the <i>Dev</i> folder and below that do not
266end in <i>.bak</i> or <i>.old</i> with the label <i>v2.6.001</i>.
267
268<pre>
269 &lt;stcheckout URL="STARTEAM:49201/Aproject/AView"
270 username="auser"
271 password="secret"
272 rootlocalfolder="C:\dev\buildtest\co"
273 includes="*.htm,*.html"
274 excludes="index.*"
275 forced="true"
276 /&gt;
277</pre>
278
279
280This is an example of overlapping <i>includes</i> and <i>excludes</i> attributes. Because
281<i>excludes</i> takes precedence over <i>includes</i>, files named <code>index.html</code> will
282not be checked out by this command.
283
284<pre>
285 &lt;stcheckout URL="STARTEAM:49201/Aproject/AView"
286 username="auser"
287 password="secret"
288 rootlocalfolder="C:\dev\buildtest\co"
289 includes="*.htm,*.html"
290 excludes="index.*"
291 forced="true"
292 recursive="false"
293 /&gt;
294</pre>
295This example is like the previous one, but will only check out files in
296C:\dev\buildtest\co, because of the turning off of the recursive attribute.
297
298<pre>
299 &lt;stcheckout URL="STARTEAM:49201/Aproject/AView"
300 username="auser"
301 password="secret"
302 rootstarteamfolder="src/java"
303 rootlocalfolder="C:\dev\buildtest\co"
304 forced="true"
305 /&gt;
306</pre>
307<br></br>
308<pre>
309 &lt;stcheckout URL="STARTEAM:49201/Aproject/AView"
310 username="auser"
311 password="secret"
312 rootstarteamfolder="src/java"
313 /&gt;
314</pre>
315<br></br>
316<pre>
317 &lt;stcheckout URL="STARTEAM:49201/Aproject/AView"
318 username="auser"
319 password="secret"
320 rootstarteamfolder="src/java"
321 rootlocalfolder="C:\dev\buildtest\co\src\java"
322 forced="true"
323 /&gt;
324</pre>
325
326In the preceding three examples, assuming that the AProject project has a default folder of
327"C:\work\AProject", the first example will check out the tree of files rooted in the src/java folder of the AView view of the AProject in the StarTeam repository to a local tree rooted at C:\dev\buildtest\co,
328the second to a tree rooted at C:\work\AProject\src\java (since no <i>rootlocalfolder</i> is specified) and the third to a tree rooted at C:\dev\buildtest\co\src\java. Note also, that since the second example does not set "forced" true, only those files which the repository considers out-of-date will be checked out.
329<hr></hr>
330
331<a name="stcheckin">
332<h2>STCheckin</h2></a>
333
334<h3>Description</h3>
335
336Checks files into a StarTeam project. Optionally adds files and in the local tree that are not managed by the repository to its control.
337
338<p>
339The <i>includes</i> and <i>excludes</i> attributes function differently from
340other tasks in Ant. Inclusion/exclusion by folder is NOT supported.
341</p>
342
343<h3>Parameters</h3>
344See also <A href="#common-params">the required common StarTeam parameters</A>.<br></br>
345<table border="1" cellpadding="2" cellspacing="0">
346 <tr>
347 <td valign="top"><b>Attribute</b></td>
348 <td valign="top"><b>Description</b></td>
349 <td align="center" valign="top"><b>Required</b></td>
350 </tr>
351 <tr>
352 <td valign="top">rootstarteamfolder</td>
353 <td valign="top">The root of the subtree in the StarTeam repository into which to
354 files will be checked. Defaults to the root folder of the view ('/').
355 <b><i>If supplied, this should always be an "absolute" path, that is, it should begin with a '/'.
356 Relative paths have little meaning in this context and confuse StarTeam.</i></b></td>
357 <td align="center" valign="top">no</td>
358 </tr>
359 <tr>
360 <td valign="top">rootlocalfolder</td>
361 <td valign="top">The local folder which will be the root of the tree to which files are checked out. If this is not supplied, then the StarTeam "default folder" associated with <i>rootstarteamfolder</i> is used. </td>
362 <td align="center" valign="top">no</td>
363 </tr>
364
365
366 <tr>
367 <td valign="top">comment</td>
368 <td valign="top">Checkin comment to be saved with the file.</td>
369 <td align="center" valign="top">no</td>
370 </tr>
371
372 <tr>
373 <td valign="top">adduncontrolled</td>
374 <td valign="top">if true, any files or folders NOT in StarTeam will be
375added to the repository. Defaults to "false".</td>
376 <td align="center" valign="top">no</td>
377 </tr>
378 <tr>
379 <td valign="top">includes</td>
380 <td valign="top">Only check in files that match at least one of the patterns in this list. Patterns must be separated by <i>commas</i>. Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
381 <td align="center" valign="top">no</td>
382 </tr>
383 <tr>
384 <td valign="top">excludes</td>
385 <td valign="top">Do not check in files that match at least one of the patterns in this list. Patterns must be separated by <i>commas</i>. Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
386 <td align="center" valign="top">no</td>
387 </tr>
388 <tr>
389 <td valign="top">recursive</td>
390 <td valign="top">Indicates if subfolders should be searched for files to check in. Defaults to "false".</td>
391 <td align="center" valign="top">no</td>
392 </tr>
393 <tr>
394 <td valign="top">forced</td>
395 <td valign="top">If true, checkins will occur regardless of the status
396that StarTeam is maintaining for the file. If false, checkins will use this status to decide which files to update. Defaults to "false".</td>
397 <td align="center" valign="top">no</td>
398 </tr>
399 <td valign="top">unlocked</td>
400 <td valign="top">If true, file will be unlocked so that other users may
401change it. If false (default) lock status will not change.
402 <td align="center" valign="top">no</td>
403 </tr>
404 <tr>
405 <td valign="top">preloadfileinformation</td>
406 <td valign="top">The StarTeam server has the ability to preload file metadata for an
407 entire tree prior to beginning action on that tree. Doing so can in some instances
408 lead to substantially faster actions, particularly over large trees. Setting this
409 to "yes" (default) engages this functionality, setting it to "no" turns it off.</td>
410 <td align="center" valign="top">no</td>
411 </tr>
412 </table>
413
414<h3>Examples</h3>
415
416<pre>
417 &lt;stcheckin servername="STARTEAM"
418 serverport="49201"
419 projectname="AProject"
420 viewname="AView"
421 username="auser"
422 password="secret"
423 rootlocalfolder="C:\dev\buildtest\co"
424 forced="true"
425 /&gt;
426</pre>
427
428The minimum necessary to check files into a StarTeam server. This will
429check all files on the local tree rooted at <code>C:\dev\buildtest\co</code>
430into the <i>AView</i> view of the <i>AProject</i> project in the repository.
431For files and folders in the local tree but not in starteam, nothing will be done. Since the <i>forced</i> attribute is set, the files which are checked in will be checked in without regard to what the StarTeam repository considers their status to be. This is a reasonable choice of attributes since StarTeam's status for a file is calculated based on the local file in the StarTeam default directory, not on the directory we are actually working with.
432
433<pre>
434 &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
435 username="auser"
436 password="secret"
437 rootlocalfolder="C:\dev\buildtest\co"
438 forced="true"
439 /&gt;
440</pre>
441And this is a simpler way of giving the same commands as the command above using the URL shortcut.
442<br></br>
443<pre>
444 &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
445 username="auser"
446 password="secret"
447 rootlocalfolder="C:\dev\buildtest\co"
448 rootstarteamfolder="\Dev"
449 excludes="*.bak *.old"
450 forced="true"
451 /&gt;
452</pre>
453
454This will check all files in to the <i>Dev</i> folder and below that do not
455end in <i>.bak</i> or <i>.old</i> from the tree rooted at"C:\dev\buildtest\co" .
456
457<pre>
458 &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
459 username="auser"
460 password="secret"
461 rootlocalfolder="C:\dev\buildtest\co"
462 includes="*.htm,*.html"
463 excludes="index.*"
464 forced="true"
465 /&gt;
466</pre>
467
468
469This is an example of overlapping <i>includes</i> and <i>excludes</i> attributes. Because
470<i>excludes</i> takes precedence over <i>includes</i>, files named <code>index.html</code> will
471not be checked in by this command.
472
473<pre>
474 &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
475 username="auser"
476 password="secret"
477 rootlocalfolder="C:\dev\buildtest\co"
478 rootstarteamfolder="src/java"
479 includes="*.htm,*.html"
480 excludes="index.*"
481 forced="true"
482 recursive="false"
483 /&gt;
484</pre>
485This example is like the previous one, but will only check in files from
486C:\dev\buildtest\co, because of the turning off of the recursive attribute.
487
488<pre>
489 &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
490 username="auser"
491 password="secret"
492 rootlocalfolder="C:\dev\buildtest\co"
493 rootstarteamfolder="src/java"
494 includes="version.txt"
495 forced="true"
496 recursive="false"
497 /&gt;
498</pre>
499This example is like the previous one, but will only check only in one file, C:\dev\buildtest\co\version.txt to the StarTeam folder src/java.
500
501<pre>
502 &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
503 username="auser"
504 password="secret"
505 rootlocalfolder="C:\dev\buildtest\co"
506 rootstarteamfolder="src/java"
507 includes="version.java"
508 forced="true"
509 recursive="false"
510 addUncontrolled="true"
511 comment="Fix Bug #667"
512 /&gt;
513</pre>
514This example is like the previous one, but will only check only in one file, C:\dev\buildtest\co\version.java to the StarTeam folder src/java. Because the <i>addUncontrolled</i> attribute has been set, if StarTeam does not already control this file in this location, it will be added to the repository. Also, it will write a comment to the repository for this version of the file.
515
516<pre>
517 &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
518 username="auser"
519 password="secret"
520 rootstarteamfolder="src/java"
521 rootlocalfolder="C:\dev\buildtest\co"
522 forced="true"
523 /&gt;
524</pre>
525<br></br>
526<pre>
527 &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
528 username="auser"
529 password="secret"
530 rootstarteamfolder="src/java"
531 /&gt;
532</pre>
533<br></br>
534<pre>
535 &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
536 username="auser"
537 password="secret"
538 rootstarteamfolder="src/java"
539 rootlocalfolder="C:\dev\buildtest\co\src\java"
540 forced="true"
541 /&gt;
542</pre>
543
544In the preceding three examples, assuming that the AProject project has a default folder of C:\work\buildtest\co\AProject,
545the first example will check in files from a tree rooted at C:\dev\buildtest\co,
546the second from a tree rooted at C:\work\buildtest\co\AProject\src\java,
547and the third from a tree rooted at C:\dev\buildtest\co\src\java all to a tree rooted at src/java
548
549<hr></hr>
550
551<a name="stlabel">
552<h2>STLabel</h2></a>
553
554<h3>Description</h3>
555
556Creates a view label in StarTeam at the specified view. The label will be classified by StarTeam as a "build label". This task will fail if there already exists in <i>viewname</i> a label with the same name as the <i>label</i> parameter.
557
558<h3>Parameters</h3>
559See also <A href="#common-params">the required common StarTeam parameters</A>.<br></br>
560<table border="1" cellpadding="2" cellspacing="0">
561 <tr>
562 <td valign="top"><b>Attribute</b></td>
563 <td valign="top"><b>Description</b></td>
564 <td align="center" valign="top"><b>Required</b></td>
565 </tr>
566
567 <tr>
568 <td valign="top">label</td>
569 <td valign="top">The name to be given to the label</td>
570 <td align="center" valign="top">yes</td>
571 </tr>
572 <tr>
573 <td valign="top">description</td>
574 <td valign="top">A description of the label to be stored in the StarTeam project.</td>
575 <td align="center" valign="top">yes</td>
576 </tr>
577 <tr>
578 <td valign="top">revisionlabel</td>
579 <td valign="top">Yes means that the label attribute is to be saved as a &quot;revision label&quot;. No (default) means that it will be saved as a &quot;view label&quot;</td>
580 <td align="center" valign="top">no</td>
581 </tr>
582 <tr>
583 <td valign="top">buildlabel</td>
584 <td valign="top">Yes means that the label attribute is to be saved as a &quot;build label&quot;.
585 This means that Change Requests which have an &quot;AddressedIn&quot; field value of &quot;next build&quot;
586 will have this label assigned to that field when the label is created.
587 No (default) means that no CRs will have this label assigned to them. This will have no effect if <b>revisionlabel</b> is also true. </td>
588 <td align="center" valign="top">no</td>
589 </tr>
590
591 <tr>
592 <td valign="top">lastbuild</td>
593 <td valign="top">The timestamp of the build that will be stored with the label. Must be formatted <code>yyyyMMddHHmmss</code></td>
594 <td align="center" valign="top">no</td>
595 </tr>
596</table>
597
598<h3>Examples</h3>
599
600This example shows the use of this tag. It will create a View label that is a build label named <i>Version 6.2</i> with
601<i>&quot;Thorough description&quot;</i> as its description.
602<pre>
603 &lt;tstamp&gt;
604 &lt;format property="nowstamp" pattern="yyyyMMddHHmmss" locale="en"/&gt;
605 &lt;/tstamp&gt;
606 &lt;stlabel URL="STARTEAM:49201/Aproject/AView"
607 username="auser"
608 password="secret"
609 label="Version 6.2"
610 lastbuild="${nowstamp}"
611 description="Thorough description"
612 /&gt;
613</pre>
614This example creates a non-build View label named <i>Version 6.3</i> with
615<i>&quot;Thorough description&quot;</i> as its description.
616<pre>
617 &lt;tstamp&gt;
618 &lt;format property="nowstamp" pattern="yyyyMMddHHmmss" locale="en"/&gt;
619 &lt;/tstamp&gt;
620 &lt;stlabel URL="STARTEAM:49201/Aproject/AView"
621 username="auser"
622 password="secret"
623 label="Version 6.3"
624 lastbuild="${nowstamp}"
625 description="Thorough description"
626 buildlabel="false"
627 /&gt;
628</pre>
629This example will create a Revision label that is a build label named <i>Version 6.2.00.001</i> with
630<i>&quot;revision label&quot;</i> as its description.
631<pre>
632 &lt;tstamp&gt;
633 &lt;format property="nowstamp" pattern="yyyyMMddHHmmss" locale="en"/&gt;
634 &lt;/tstamp&gt;
635 &lt;stlabel URL="STARTEAM:49201/Aproject/AView"
636 username="auser"
637 password="secret"
638 label="Version 6.2.00.001"
639 description="revision label"
640 revisionlabel="true"
641 /&gt;
642</pre>
643
644<hr></hr>
645<a name="stlist">
646<h2>STList</h2></a>
647
648<h3>Description</h3>
649
650Produces a listing of the contents of the StarTeam repository at the specified view and StarTeamFolder. The listing will contain the name of the user, if any, who has the file locked, the size of the file, its lastModifiedDate in the repository, the name of the file, and the status of the local file in the default local directory relative to the repository.
651
652<h3>Parameters</h3>
653See also <A href="#common-params">the required common StarTeam parameters</A>.<br></br>
654<table border="1" cellpadding="2" cellspacing="0">
655 <tr>
656 <td valign="top"><b>Attribute</b></td>
657 <td valign="top"><b>Description</b></td>
658 <td align="center" valign="top"><b>Required</b></td>
659 </tr>
660
661 <tr>
662 <td valign="top">rootstarteamfolder</td>
663 <td valign="top">The root of the subtree in the StarTeam repository to be listed. Defaults to the root folder of the view ('/'). <b><i>If supplied, this should always be an "absolute" path, that is, it should begin with a '/'.
664 Relative paths have little meaning in this context and confuse StarTeam.</i></b></td>
665 <td align="center" valign="top">no</td>
666 </tr>
667 <tr>
668 <td valign="top">rootlocalfolder</td>
669 <td valign="top">The local folder which will be the root of the tree to which files are compared. If this is not supplied, then the StarTeam "default folder" associated with <i>rootstarteamfolder</i> is used and a status field will appear in the listing. Otherwise, the status field will not appear.
670 </td>
671 <td align="center" valign="top">no</td>
672 </tr>
673 <tr>
674 <td valign="top">includes</td>
675 <td valign="top">Only list files that match at least one of the patterns in this list. Patterns must be separated by <i>commas</i>. Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
676 <td align="center" valign="top">no</td>
677 </tr>
678 <tr>
679 <td valign="top">excludes</td>
680 <td valign="top">Do not list files that match at least one of the patterns in this list. Patterns must be separated by <i>commas</i>. Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
681 <td align="center" valign="top">no</td>
682 </tr>
683 <tr>
684 <td valign="top">label</td>
685 <td valign="top">List files, dates, and statuses as of this label. The label must exist in starteam or an exception will be thrown. If not specified, the most recent version of each file will be listed.</td>
686 <td align="center" valign="top">no</td>
687 </tr>
688 <tr>
689 <td valign="top">asofdate</td>
690 <td valign="top">List files, dates, and statuses as of this date.
691 The date must be formatted in ISO8601 datetime
692 (<code>yyyy-MM-dd'T'HH:mm:ss</code>), ISO8601
693 date(<code>yyyy-MM-dd</code>) or a user-defined SimpleDateFormat
694 defined in the <code>asofDateFormat</code> attribute. If the date
695 is not parsable by the default or selected format, an exception
696 will be thrown. <em>Since Ant 1.6.</em></td>
697 <td align="center" valign="top">no</td>
698 </tr>
699 <tr>
700 <td valign="top">asofdateformat</td>
701 <td valign="top">java.util.SimpleDateFormat compatible string used
702 to parse the <code>asofdate</code> attribute. <em>Since Ant
703 1.6.</em></td>
704 <td align="center" valign="top">no</td>
705 </tr>
706
707 <tr>
708 <td valign="top">recursive</td>
709 <td valign="top">Indicates if subfolders should be searched for files to list. Defaults to "true".</td>
710 <td align="center" valign="top">no</td>
711 </tr>
712 <tr>
713 <td valign="top">listuncontrolled</td>
714 <td valign="top">if true, any files or folders NOT in StarTeam will be included in the listing.
715 If false, they won't. Defaults to "true".</td>
716 <td align="center" valign="top">no</td>
717 </tr>
718
719 <tr>
720 <td valign="top">preloadfileinformation</td>
721 <td valign="top">The StarTeam server has the ability to preload file metadata for an
722 entire tree prior to beginning action on that tree. Doing so can in some instances
723 lead to substantially faster actions, particularly over large trees. Setting this
724 to "yes" (default) engages this functionality, setting it to "no" turns it off.</td>
725 <td align="center" valign="top">no</td>
726 </tr>
727
728</table>
729<h3>Examples</h3>
730
731<pre>
732
733 &lt;stlist url="WASHINGTON:49201/build"
734 username="auser"
735 password="secret"
736 /&gt;
737</pre>
738
739The above command might produce the following listing:
740
741<pre>
742 [stlist] Folder: Build (Default folder: C:/work/build)
743 [stlist] Folder: dev (Default folder: C:/work/build/dev)
744 [stlist] Out of date Sue Developer 1/1/02 7:25:47 PM CST 4368 build.xml
745 [stlist] Missing George Hacker 1/1/02 7:25:49 PM CST 36 Test01.properties
746 [stlist] Current 1/1/02 7:25:49 PM CST 4368 build2.xml
747 [stlist] Folder: test (Default folder C:/work/build/dev/test)
748 [stlist] Missing 1/1/02 7:25:50 PM CST 4368 build2.xml
749</pre>
750
751while adding a <i>rootlocalfolder</i> and an <i>excludes</i> param ...
752
753<pre>
754
755 &lt;stlist url="WASHINGTON:49201/build"
756 username="auser"
757 password="secret"
758 rootlocalfolder="srcdir2"
759 excludes="*.properties"
760 /&gt;
761</pre>
762
763might produce this listing. The status is missing because we are not going against the default folder.
764
765<pre>
766 [stlist] overriding local folder to srcdir2
767 [stlist] Folder: Build (Local folder: srcdir2)
768 [stlist] Folder: dev (Local folder: srcdir2/dev)
769 [stlist] Sue Developer 1/1/02 7:25:47 PM CST 4368 build.xml
770 [stlist] 1/1/02 7:25:49 PM CST 4368 build2.xml
771 [stlist] Folder: test (Local folder: srcdir2/dev/test)
772 [stlist] 1/1/02 7:25:50 PM CST 4368 build2.xml
773
774
775</pre>
776
777<hr></hr>
778
779<a name="starteam">
780<h2>Starteam</h2></a>
781<h3><i>Deprecated</i></h3>
782<p><i>This task has been deprecated. Use the <a href="#stcheckout">STCheckout</a> task instead.</i></p>
783<h3>Description</h3>
784
785Checks out files from a StarTeam project.
786
787<p>
788The <i>includes</i> and <i>excludes</i> attributes function differently from
789other tasks in Ant. Multiple patterns must be separated by spaces, not
790commas. See the examples for more information.</p>
791
792<h3>Parameters</h3>
793<table border="1" cellpadding="2" cellspacing="0">
794 <tr>
795 <td valign="top"><b>Attribute</b></td>
796 <td valign="top"><b>Description</b></td>
797 <td align="center" valign="top"><b>Required</b></td>
798 </tr>
799 <tr>
800 <td valign="top">username</td>
801 <td valign="top">The username of the account used to log in to the StarTeam server.</td>
802 <td align="center" valign="top">yes</td>
803 </tr>
804 <tr>
805 <td valign="top">password</td>
806 <td valign="top">The password of the account used to log in to the StarTeam server.</td>
807 <td align="center" valign="top">yes</td>
808 </tr>
809 <tr>
810 <td valign="top">servername</td>
811 <td valign="top">The name of the StarTeam server.</td>
812 <td align="center" valign="top">yes</td>
813 </tr>
814 <tr>
815 <td valign="top">serverport</td>
816 <td valign="top">The port number of the StarTeam server.</td>
817 <td align="center" valign="top">yes</td>
818 </tr>
819 <tr>
820 <td valign="top">projectname</td>
821 <td valign="top">The name of the StarTeam project.</td>
822 <td align="center" valign="top">yes</td>
823 </tr>
824 <tr>
825 <td valign="top">viewname</td>
826 <td valign="top">The name of the view in the StarTeam project.</td>
827 <td align="center" valign="top">yes</td>
828 </tr>
829
830 <tr>
831 <td valign="top">targetfolder</td>
832 <td valign="top">The folder to which files are checked out. What this precisely means is determined by the <i>targetFolderAbsolute</i> param.</td>
833 <td align="center" valign="top">yes</td>
834 </tr>
835 <tr>
836 <td valign="top">targetFolderAbsolute</td>
837 <td valign="top">Determines how <i>targetfolder</i> is interpreted, that is, whether the StarTeam "default folder" for the project is factored in (false) or whether <i>targetFolder</i> is a complete mapping to <i>foldername</i> (true).
838 If "true", the target tree will be rooted at <i>targetfolder+"default folder"</i>. If false, the target tree will be rooted at <i>targetfolder</i>. Defaults to "false". </td>
839 <td align="center" valign="top">no</td>
840 </tr>
841 <tr>
842 <td valign="top">foldername</td>
843 <td valign="top">The subfolder in the project from which to check out files.</td>
844 <td align="center" valign="top">no</td>
845 </tr>
846 <tr>
847 <td valign="top">force</td>
848 <td valign="top">Overwrite existing folders if this is set to "true". Defaults to "false".</td>
849 <td align="center" valign="top">no</td>
850 </tr>
851 <tr>
852 <td valign="top">recursion</td>
853 <td valign="top">Indicates if subfolders should be searched for files to check out. Defaults to "true".</td>
854 <td align="center" valign="top">no</td>
855 </tr>
856 <tr>
857 <td valign="top">verbose</td>
858 <td valign="top">Provides progress information. Defaults to "false".</td>
859 <td align="center" valign="top">no</td>
860 </tr>
861 <tr>
862 <td valign="top">includes</td>
863 <td valign="top">Only check out files that match at least one of the patterns in this list. Patterns must be separated by spaces. Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
864 <td align="center" valign="top">no</td>
865 </tr>
866 <tr>
867 <td valign="top">excludes</td>
868 <td valign="top">Do not check out files that match at least one of the patterns in this list. Patterns must be separated by spaces. Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
869 <td align="center" valign="top">no</td>
870 </tr>
871</table>
872
873<h3>Examples</h3>
874
875<pre>
876 &lt;starteam servername="STARTEAM"
877 serverport="49201"
878 projectname="AProject"
879 viewname="AView"
880 username="auser"
881 password="secret"
882 targetfolder="C:\dev\buildtest\co"
883 /&gt;
884</pre>
885
886The minimum necessary to check out files out from a StarTeam server. This will
887check out all files in the <i>AView</i> view of the <i>AProject</i> project to
888<code>C:\dev\buildtest\co</code>.
889
890<pre>
891 &lt;starteam servername="STARTEAM"
892 serverport="49201"
893 projectname="AProject"
894 viewname="AView"
895 username="auser"
896 password="secret"
897 targetfolder="C:\dev\buildtest\co"
898 foldername="\Dev"
899 excludes="*.bak *.old"
900 force="true"
901 /&gt;
902</pre>
903
904This will checkout all files from the <i>Dev</i> folder and below that do not
905end in <i>.bak</i> or <i>.old</i>. The force flag will cause any existing files to be
906overwritten by the version in StarTeam.
907
908<pre>
909 &lt;starteam servername="STARTEAM"
910 serverport="49201"
911 projectname="AProject"
912 viewname="AView"
913 username="auser"
914 password="secret"
915 targetfolder="C:\dev\buildtest\co"
916 includes="*.htm *.html"
917 excludes="index.*"
918 /&gt;
919</pre>
920
921
922
923This is an example of overlapping <i>includes</i> and <i>excludes</i> attributes. Because
924<i>excludes</i> takes precedence over <i>includes</i>, files named <code>index.html</code> will
925not be checked out by this command.
926
927
928<pre>
929 &lt;starteam servername="STARTEAM"
930 serverport="49201"
931 projectname="AProject"
932 foldername="src/java"
933 viewname="AView"
934 username="auser"
935 password="secret"
936 targetfolder="C:\dev\buildtest\co"
937 targetfolderabsolute="true"
938 /&gt;
939</pre>
940<br></br>
941<pre>
942 &lt;starteam servername="STARTEAM"
943 serverport="49201"
944 projectname="AProject"
945 foldername="src/java"
946 viewname="AView"
947 username="auser"
948 password="secret"
949 targetfolder="C:\dev\buildtest\co"
950 targetfolderabsolute ="false"
951 /&gt;
952</pre>
953<br></br>
954<pre>
955 &lt;starteam servername="STARTEAM"
956 serverport="49201"
957 projectname="AProject"
958 foldername="src/java"
959 viewname="AView"
960 username="auser"
961 password="secret"
962 targetfolder="C:\dev\buildtest\co\src\java"
963 targetfolderabsolute="true"
964 /&gt;
965</pre>
966
967In the preceding three examples, assuming that the AProject project has a default folder of
968"AProject", the first example will check the files located in starteam under src/java out to a tree rooted at C:\dev\buildtest\co,
969the second to a tree rooted at C:\dev\buildtest\co\AProject\src\java and the third to a tree rooted at C:\dev\buildtest\co\src\java.
970
971<hr>
972<p align="center">
973Copyright &copy; 2001-2004 The Apache Software Foundation. All rights Reserved.
974</p>
975
976</body>
977</html>
Note: See TracBrowser for help on using the repository browser.