Using the new STCMD tool
Eight SQL like commands have been introduced into stcmd since the 12.0 release. They are CONNECT, DISCONNECT, SET, DESCRIBE, SELECT, INSERT, UPDATE and DELETE.
Unlike commands carried forward from 11.0, the new commands have no requirements to satisfy preexisting syntax for backward compatibility. As a result, these commands are part of the new class of stateful commands, i.e. they retain their connection across invocation.
The CONNECT command sets up a connection to a StarTeam server. Once the connection has been set up, it will not be released until an explicit DISCONNECT command is issued. The simplest usage of the CONNECT command is
connect username:password@address:port (e.g. stcmd connect Administrator:Administrator@localhost:49201)
connect username@address:port passwordFromFile “full path to passwordfile”
e,g. stcmd connect Administrator@localhost:49201 passwordFromFIle “c:\securelocation\adminpasswordfile”
The SET command is used to identify a project and view in whose context subsequent commands will be issued. The simplest usage of the SET command is
stcmd set project=projectName view= viewName (e.g set project=StarDraw view = “Release 1.0 Maintenance”
Note: whenever parameter values have spaces embedded in them, they must be enclosed within double quotes. Note however that white space in the command syntax may be optional. i.e. project=StarDraw is the same as project = StarDraw
Note that across the life of a command line session, a user can change projects and views using SET, all the while keeping the connection open. For example, the following script is legal
stcmd connect Administrator@localhost:49201
stcmd set project = StarDraw view = StarDraw
stcmd select * from ChangeRequest
stcmd set project = StarDraw view = “Release 1.0 Maintenance”
stcmd select * from Task
Note: preexisting commands from 11.0 like ci, co, etc. can also be used with CONNECT and SET. If this case, the –p syntax of the command is ignored.
Note: For the subsequent commands to succeed, the connect and the set commands must already have been executed)
The DESCRIBE command is useful to identify the set of available types in your configuration, a pre-requisite for using the SELECT, INSERT, UPDATE or DELETE commands. It returns multiple rows, each with 5 columns, which are
typeName, typeID, branchable, attachment container, component, supportsMPX
For each row returned, the 1st column is the name of the Type, which can be used in the ‘from’ clause of the SELECT command, provided the value of component is true for that type.
e.g. stcmd select * from File will succeed but stcmd select * from ItemReference will fail.
The DESCRIBE command can also be run for a specific Type, a pre-requisite for using property names in SELECT, INSERT, UPDATE or DELETE commands. When run with a Type Name as a parameter, DESCRIBE returns 16 columns, which are
typeName, typeID, propertyName, propertyOID, propertyTypeName, …
For each row returned, only the value of the 3rd column may be used as a propertyName in a SELECT query. Note: property display names cannot be used as property names in SELECT queries.
stcmd describe ChangeRequest
The SELECT command has a very rich grammar, and provides the framework for a generalized report generation StarTeam language.
Below are examples of the use of the SELECT query.
stcmd select * from File (returns all properties of all files in the view)
stcmd select ID, Modified, Folder from File (returns Object ID, File Time Stamp At Check In, parent folder name of all files in the view)
stcmd select * from File into “c:\temp\File.txt” (saves the results of the query into a file called File.txt in the c:\temp\ folder). The first row contains the command, the second row contains the column names, the third row onwards contains the data.
stcmd select filter=”<All Files By Status>” from File (returns the set of properties defined by the filter <All Files By Status>”. Note: Filter and Query Names are case sensitive. If names have embedded white spaces in them, they must be enclosed within double quotes.
stcmd select * from File where query=”Flagged Items” (returns a subset of rows constrained by the query “Flagged Items”
stcmd select * from File where query=”Flagged Items” and folder = “User Manual” (returns a subset of rows constrained by the query “Flagged Items”, further constrained to the folder “User Manual”
stcmd select * from File order by ID (returns the results sorted by the specified property name(s))
Note: all keywords such as select, where, from, filter, query, folder, … are required to be lower case.
Note: INSERT, DESCRIBE ad DELETE are similar to SELECT in their use of the “from” clause, property names, etc.
One final useful command, also new to 12.0+ is the VERSION command
identifies the version of the command line being executed right now, and is very useful to ensure that the correct or expected version is in the path. (a problem when 12.0, 12.5 &/or 13.0 SDK versions are installed on the same machine.)