stcmd - the stateful command line engine

over 4 years ago

The 14.0 stcmd continues to work as-is for backward compatibility
i.e. it supports the old stateless connect-execute-disconnect api's characterized by 
-p user:password@server:port/project/view

It is important to note that the stateless commands are executed through stcmdEx.jar; i.e. stcmd.exe invokes the jre directly and launches stcmdEx.jar. To satisfy this model, it is necessary to have a recent version of the JRE ( or later) downloaded and installed from the oracle/sun java website, or to set the PATH variable to include the path to the JRE installed with the SDK; e.g.

set PATH = "c:\program files\micro focus\java\oracle1.8.0_102\bin"

Additonally, the 'new' command line also incorporates a stateful connect which leaves the server connection open until an explicit disconnect.

connect [username[:password]@]address:port [passwordFromFile passwordFile] 
[storePasswordToFile passwordFile] [caseSensitiveFolders | -csf]
[encryption = RC4|RC2_ECB|RC2_CBC|RC2_FCB][compression | -cmp] 
[mpx=on|off (default ON) profile=profileName [cacheAgent@address:port (default autoLocate] | =off] 
[-mode [lock | exlock | unlock]]

Once connected, a command line script may switch between projects or views using the set command

set project=projectName [view=viewName | viewHierarchy=viewName:viewName:…] [folderHierarchy=folderName:folderName:....] [-cfgl "label" | -cfgp "promotion state" | -cfgd "date"]

Once connected, all existing commands will execute in the context of the prepared connection; 
-p parameters will be ignored.

The implementation of the checkout (co) command has been augmented to support the features and parameters provided by the bulk checkout (bco) tool. As a result, bco is no longer supported, being fully subsumed into co.

This version of the command line offer 40 commands, and is growing as new requirements are identified.

Specifically, 4 new commands have been introduced in the 14.0 command line, namely,  SELECT, INSERT, UPDATE & DELETE.
These commands create the illusion that StarTeam types are database tables.

For example, the SELECT syntax is

select * | access-rights | changes | linked-items | lifecycle | links | workrecords | agile-breakdown | scope-change | differences | historical-revisions | {propertyName, propertyName,...} | filter = 'filename'

from 'typeName' {history} {deleted} {backlog}

{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}


{{ 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/]"]

typeName in {File | Folder | ChangeRequest | Requirement | Task | Topic | ChangePackage | Trace | CustomComponent}

The select clause of the query specifies the set of columns returned in the result set.

The from clause defines the type and additionally imposes constrainst such as (rolled back) view configurations.

The where clause provides a mechanism to constrain the results returned based on some specific pre-defined query, or dynamically specified property value tuples, inconjunction with a subset of selected folders.

The results may be written out to  file using the standard (|) or overridden field separator.

The grammar for INSERT is

insert into type ( propertyName, propertyName,... )

revisions | values

[ ( value, value,... ) | from ‘filePath’ { separator ‘fieldSeparator’} {-pattern "pattern"} ]
{output* | {propertyName,...} | filter='myFilter' into "outputFilePath"

[-p "userName:password@hostName:endpoint/projectName/[viewName/][folderHierarchy/]"]


Note of interest here is the difference between values and revisions.

values implies that each row in the input file produces a new item of the appropriate type.

revisions implies that each rows in the input file produces a new historical revision of the same item of the given type. In this context, the input data is best sorted by modified time descending (oldest first). If the modified time and modified user properties are part of the data, then the insertion impersonates both user and time to produce results that are contextually no different than if they had been inserted/updated by that user at that time.

The UPDATE and DELETE commands follow reasonably similar patterns. 

In all cases, -p is irrelevant in a stateful model (the connection was made with connect, the project and view were selected with set) and vice-versa, connect/set should not be called in a stateless model that depends upon -p.

The command line functionality is completely integrated into the SDK, directly available through the core SDK, CommandProcessor class. This allows application developers to use the command line via the SDK natively in java scripting environments such as Ant or Hudson, completely bypassing the stcmd shell, fully leveraging native 32 or 64 bit platforms. (stcmd itself is a windows command prompt shell executable that invokes the CommandProcessor class in the SDK). Invoking the CommandProcessor class, at its simplest, requires repeated use of the execute() method... e.g.

CommandProcessor cp = new CommandProcessor();

cp.execute("connect Administrator:Administrator@localhost:49201);

cp.execute("set project=stardraw view=stardraw");

cp.execute("select * from changerequest where query='Status = Open'");



An optional -p "server/project specifier" allows the command to be executed in stateless mode as well. The command line object model now supports all commands being executed in stateless or stateful modes.

For more on the new command line, download the command line help .pdf from here


When executed, command line commands consume as much memory as the data that are required to process. The more the data, the more the memory.

If command execution runs out of heap memory, you may increase it subject to availability on your machine.

32 bit platforms cannot exceed 2GBs. 64 bit platforms cannot exceed the physical memory available.

to run an stcmd command with memory management, use

stcmd -Xmx{nnnn}m   "command"

where {nnnn} could be 1024, 2048, 4096, 8192 etc


How To-Best Practice
Comment List
Related Discussions