The select command may be executed directly through the SDK's CommandProcessor class, or indirectly through either stcmd or stcmdEx. The syntax of the command is
The syntax for this command is:
select * | all | access-rights | changes | linked-items | changed-files |
enhanced-links | lifecycle | links | workrecords |
agile-breakdown | scope-change | differences | historical-revisions | attached-labels |
unlabeled-revisions | merge-counts | attachments |connections-log | duplicate-shares | missing-artifacts | non-tip-artifacts | behavior | {propertyName, propertyName,...} | filter = 'filtername'
from 'typeName' | starteam {history} {deleted} {backlog} {workspace}
{between-labels labelname1 and labelname2}
{attached-to-label labelname }
{at [label = "label" | promotionstate = "promotion state" | datetime = "date" {-pattern "pattern"}]
into fileName { separator 'field separator' } {newline newlineSeparator} {headers 'on' | 'off' | sqlnames} {toExcel}
{-pattern "datetimepattern"} {-locale "localecode"}
where
{{ attached-label = 'labelName' } | { query = 'myquery' } |
propertyName relation value and/or propertyName relation value and/or...}
{for} {folder = 'myfolder' {recurse} or folder = 'myfolderhierarchy' {recurse} or folder = . {recurse}} or ...}
order by {propertyName, propertyName,...} | orderFilter = 'myOrderFilter'
[–epwdfile “passwordfilepath”] [-p "userName:password@hostName:endpoint/projectName/
[viewName/][folderHierarchy/]"] | [-s "userName:password@hostName:endpoint]
Use the select command to invoke StarTeam meta-queries. The combination of options determines the type of query, which could be over a file, folder, change request or etc., and the saved filters for the type. Values that contain spaces should be enclosed in double quotes. This command has been modeled on the standard SQL SELECT syntax. Cross type joins are not supported. If folder identification clauses are not specified, the tool assumes the folderHierarchy is set through the setProject command or the root folder of the view, with recurse ON (that is, all descendants or depth == -1). The WHERE clause is constrained to a query and a possible set of folders. Folders may be combined with an OR, but cannot be joined with an AND. Folders act as a further constraint to a query. Folders potentially reduce the subset of results obtained from the query to the items that reside within the specified folders. When a folder hierarchy is specified in the WHERE clause of a select, update or delete statement, the path must start with the root folder and traverse the folder tree all the way down to the leaf folder of interest. It must be explicitly terminated by a \. However, the root folder path must not start with a \. / and \ are interchangeable.
Simple dynamic queries support either chained OR clauses or chained AND clauses. However, they do not support a mix of OR and AND conditions. Complex queries are supported but only as saved queries, for example: where query = 'mySavedQueryname'.
If a property name in the where clause identifies a text property, the relation is '=' and the value starts with a "*", then the * is treated as a wildcard targeted for expansion. This query returns all items whose property values end with the text of the query value. For example, the following returns all files in the view whose names end in .doc.
Only * is supported as a wildcard, and can exist contextually at the start of, at the end of or surrounding a phrase. In other words, "*.doc", "doc*", or "*.*" will all expand the * out to mean - any set of characters.
No other wildcard characters are supported. "." itself is treated as a literal character, no different than (say) a, b or c.
Overrides properties. If specified, it generates an agile breakdown report.
if historical-revisions is specified, then the where clause is ignored.
If the differences keyword is specified, then between-labels 'labelname1' and 'labelname2' must be specified, (and overrides the where clause)
describes a rolled back view configuration. It may be one of label, promotion state or datetime. If specified, the query is run at the rolled back configuration.
datetime may be further qualified by a pattern. The pattern must match any valid pattern supported by the java JDK in java.text.SimpleDateFormat.applyLocalizedPattern(String) and ensure that embedded date/ time strings strictly adhere to that pattern. If a pattern is specified, a 2 character country code locale may also be optionally specified.
If there are multiple folders with the same name, the command returns all folders with that name.
Or specify the folder hierarchy in the "/" format.
Start from the root folder and end in a branch folder. For example: /StarDraw/SourceCode/On-line Help/.
Implies the current working folder, requiring the tool to find StarTeam folders with paths mapping to the current working folder.
The Command processor must be running inside the StarTeam folder hierarchy.
If newline separator is specified, then embedded new lines inside text fields are replaced by the provided separator. If not specified, then embedded new lines are replaced by their character string equivalents, specifically, "\r" and/or "\n".
String format [ws][-][d. |d]hh:mm:ss[.ff][ws], items in brackets optional. see com.starteam.util.TimeSpan. ws whitespace, d days, ff fractional second, hh hours, mm minutes 0 <= mm <= 59, ss seconds 0 <= ss <= 59.
Value specified may be user name or string representation of integer user id.
It expands into a subset of properties for the type, which is used for sorting.
myFilter and myOrderFilter can be different. The properties specified in MyOrderFilter should not be set for grouping. If a set of property names is specified instead of the order filter, the sort criteria default to ascending order, sort by text is set for text properties, and sort by date is set for Date/DateTime Properties. If you need more specific sorting, specify an existing saved filter.
The full syntax is:
stcmd -p "userName:password@hostName:endpoint/projectName/[viewName/][folderHierarchy/]"
For example:
stcmd -p “bsmith:rocketfive@orion:49201/StarDraw/StarDraw/SourceCode/”
The -epwdfile keyword specifies the path to the file that contains the encrypted password. Like -pwdfile , -epwdfile replaces the password being used as part of the -p or -s option, preventing others from seeing the user's password on the command line. The full syntax is: -epwdfile "filePath" .
The -pwdfile is supported for backward compatibility. Un-encrypted passwords stored using older versions of stcmd are read. However, passwords cannot be stored to files using -pwdfile anymore.
In this case, the syntax of -p or -s reduces to -p "username@hostname:port/... -epwdfile "fullyQualifiedPathToPasswordFile"".
The following is the syntax of the commands that can be used to store an encrypted password.
Use the following syntax to be prompted for the password that will be encrypted and stored in a file.
stcmd store-password -epwdfile "filePath"
stcmd store-password -epwdfile "filePath" -password "password"
After an encrypted password is stored, other stcmd commands can specify -epwdfile "filePath"' as parameters. For example:
stcmd delete-local -p "JMarsh@Orion:1024/StarDraw/StarDraw/SourceCode" -epwdfile "C:\estuff\myfile.txt" -filter "N" "*"
Compresses all the data sent between the workstation and the server and decompresses it when it arrives. Without this option, no compression takes place.
Compression speeds transmission across the network, but it takes time on the front end to compress the data and at the back end to decompress the data.
This is an optional parameter. If not specified, then the platform default is not to compress.
When the command maps the folder specified in the -p option to the underlying StarTeam folder, using -csf causes the command to differentiate StarTeam folders based on the case-sensitive spelling of their names This option does not apply to the case-sensitivity of filenames in the folders. For example, with -csf, StarTeam folders named doc and Doc are recognized as different folders. Without this option, either folder could be recognized as the doc folder.
The default is that StarTeam folders are not differentiated based on the case of letters in their names.
With or without -csf, if folder names are ambiguous, an error occurs. For example, when you use -csf, the names of two folders are ambiguous if both a Doc and doc folder exist. When you do not use -csf, folder names are ambiguous if they are spelled identically.
Encrypts all data sent between the workstation and the server and decrypts it when it arrives. Without this option, no encryption takes place. Encryption protects files, data and other project information from being read by unauthorized parties over unsecured networks.
This is an optional parameter. If not specified, then the server and the command line negotiate the encryption required by the server.
The full syntax is: -encrypt encryptionType.
The types of encryption are:
These encryption types are ordered from fastest to slowest. Each of the slower encryption types is safer than the one preceding it.
Identifies the StarTeam Server. The full syntax is: -s "userName:password@host:portNumber"
For example: -s "JMarsh:password@orion:49201"
If the user name is omitted, the current user name is used. The user name in the example is “JMarsh”.
If the password is omitted, the user is prompted to enter the password. The password in the example is “password”. If the host name is omitted, the default is localhost. The host name in the example is “orion”.
The port number is required. The default port number, 49201, is used in the example.
In general, the select grammar is positional. It is best to follow the position of the syntax as outlined in the command description above.
select * from File where query = "Status = Current" order by orderfilter = "All Files By Status" -p "Administrator:Administrator@localhost:49201/StarDraw/Release 1.0 Maintenance"
The following example shows how to use the differences keyword. It selects all properties of all change requests and writes them into a file called QueryOutput.txt.
select differences from file between-labels 14.0.3.21 and 14.0.3.27 into "c:/temp/differencesReport.txt" separator | -p "username:password@hostname:port/project/view"
select * from changerequest into "c:/temp/QueryOutput.txt"
select linked-items from ChangeRequest where AddressedIn = "Next Build" or select linked-items from ChangeRequest where AddressedIn = "-2"
The example below selects three properties, Name, Status, and File Time Stamp at check in, for all files, which satisfies the built in query Files to Checkin.
select Name, Status, Modified from file where query = "Files to CheckIn"
The example below selects all tasks from the Sales Materials folder or the Marketing Materials folder and its descendants. It returns a result set containing only the task properties described by the "By Status and Responsibility" filter. select * from task where filter = "By Status & Responsibility"
select filter = "By Status and Responsibility" from task where folder = "Sales Materials" or folder = "Marketing Materials" recurse
The following examples show how to use select with change requests and change packages.
select linked-items from ChangeRequest into fullyQualifiedPathToOutputFile where ChangeNumber = 1234 -p "username:password@host:port/project/view"
select changes from ChangePackage where name = "Workspace Changes on 2013-10-15@22-43-00Z"
This example shows how to use the select command with the lifecycle parameter.
select lifecycle from File into fullyQualifiedPathToOutputFile where FileName = Server.java -p "username:password@host:port/project/view"
This example shows how to generate a workrecords report:
select workrecords from task where StTaskNumber = 88
This examples shows how to generate an agile-breakdown report:
select agile-breakdown from sprint into c:/temp/agileReport.txt separator "|" where SprintID = 1234 -p "user:password@host:port/project/view"
The following example shows you how to select rows in a range:
select "*" from changerequest into "c:/temp/stout.txt" where changenumber ">" 50000 and changenumber "<" 50100 -p "user:password@host:port/project/view"
The next example uses a date range on the ModifiedTime property:
select "*" from ChangeRequest into "c:/temp/stout.txt" pattern = "M/d/y" where modifiedtime ">" 1/1/2014 and modifiedtime "<" 8/30/2014 -p "user:pwd@host:port/project/view"
The following example produces history results similar to the deprecated hist command:
select revisionnumber, viewid, modifieduserid, modifiedtime, comment from file history -p "Username:Password@host:port/project/view/[folderhioerarchy]/" where name = "filename"
The next example shows the use of historical-revisions
select historical-revisions from file attached-to-label "label name" -p "user:password@host:port/project/view"
The next two examples show the use of wildcards and fully qualified folder paths
select folder, name from file where name = "*.doc" for folder = "StarDraw\Source Code\External Resources\"
select viewmemberid, name, description from file where name = "*.doc"
The next few examples show different usage of property relation values:
select * from ChangeRequest pattern = "M/d/y" where ModifiedTime > 12/14/1999 and modifiedtime < "2/16/1999"
select * from ChangeRequest where ChangeNumber in (10298, 10310, 10316, 10320)");
select * from ChangeRequest where ChangeNumber = 10298 select * from ChangeRequest where ChangeNumber ">=" 10298 and ChangeNumber "<=" 10320 select * from File where name = "GNUmakefile.build*" select * from File where name = "*.buildinfo" select * from File where name = "*ranching release views.doc*" select * from ChangeRequest where Responsibility = "Alan Kucheck"
Note that ">=" can be replaced by gte without the double quotes around it,
= can be replaced by eq, etc.
This example shows the use of date patterns driving the format of output date time property values:
select name, modifiedtime from file -pattern "yyyyMMddHHmmss" where name = "*.java" order by name -p "user:pwd@host:port/project/view"
This example queries the path of all files which are exclusively locked by a user:
select Path from file where exclusivelocker <> ""
select connections-log from starteam into "c:/temp/connections.log" -s "user:password@host:port"
This example reports on custom properties, and uses them to drive the query.
select changenumber, usr_projecttype, usr_dateclosed from changerequest into custom.cr.output.txt headers off pattern = "M/d/y" where USR_DATECLOSED gte 1/1/2015 and USR_DATECLOSED lt 1/1/2016
This same query with greater precision:
select changenumber, usr_projecttype, usr_dateclosed from changerequest into custom.cr.output.txt headers off pattern = "M/d/y H:m:s" where USR_DATECLOSED gte "1/1/2015 0:0:0" and USR_DATECLOSED lt "12/31/2016 23:59:59"