stcmd.exe, stcmdEX.jar and the CommandProcessor Object

Use the stcmd executable from a command line, such as Microsoft Windows Command Prompt. stcmd.exe runs an in-process java program called the client. This client starts up or connects to an already running out-of-process java program called the server. The client and the server then communicate over TCP/IP. The level of indirection is necessary to support stateful commands (commands where a connection to StarTeam Server is created and retained across the scope of all subsequently issued stcmd commands). Using stcmd from a command line requires adding stcmd in front of each command on the command line. This will enable the stcmd executable to drive the CommandProcessor engine.

Stcmd.exe is a 32-bit executable that launches stjava.exe out-of-process. On 32 bit machines, it launches the 32-bit version. On 64-bit machines, it launches the 64-bit version.

The SDK runs in the (32/64 bit version) JRE spawned by stjava.exe, independent of stcmd.exe. Stcmd.exe is a pure java solution, the choice of class path determines the choice of JRE.

In this topic:

stcmd Path Specification

stcmd path specifications must use Java conventions (not Microsoft Windows). For example, the following will throw an IndexOutOfBounds exception:

stcmd co -rp "c:\temp" -p "Administrator:Administrator@localhost:49201/StarDraw/StarDraw" *

The following will work correctly on all platforms that support the java virtual machine (Microsoft Windows, Unix, and Mac):

stcmd co -rp "c:/temp" -p "Administrator:Administrator@localhost:49201/StarDraw/StarDraw" *

Back to top

stcmdEx

When running the command line as a stateless batch process (using the -p or the -s parameters), an alternative approach is to use stcmdEx.

stcmdEx.jar runs a java program that takes the command and input parameters, and then loads and invokes the StarTeam SDK in process. There is no additional overhead of a separate out-of-process server, but as a consequence, there is no possibility of retaining state across invocations.

stcmdEx will only work with stateless commands, or commands which rely upon -p to specify connectivity, credentials, project and view.

stcmdEx does not support the following commands: status, statusAll, shutdown, and shutdownAll. These are not commands, rather, they are tracking methods for the local client/server stcmd processes.

Additionally, stcmdEx does not support help queries. For example: -?.

stcmdEx is not meant to be used in an interactive environment. It is targeted at (concurrent) batch processes and services set up to run with no human intervention.

Since stcmdEx launches and runs the SDK in process, multiple parallel invocations of the script will each run in their own process spaces (JRE runtimes), thereby supporting batch parallelism. stcmdEx jobs can be run in parallel on the same physical workstation.

stcmdEx can be directly integrated into existing Microsoft Windows batch files (or Unix shell scripts) using the following syntax:

java.exe -jar stcmdEx.jar command-line-command-with-parameters

"C:\Program Files\Micro Focus\Java\Oracle1.8.0_91\bin\java.exe" -jar "C:\
Program Files\Micro Focus\StarTeam SDK <version>\lib\stcmdEx.jar" co /p 
\"Administrator:Administrator@localhost:49201/Project Name/View Name\" /is 
/rp \"c:\temp\" /filter \"GIMOU\" /o /vb >c:\temp\output.txt

On Microsoft Windows platforms, stcmdEx can be incorporated into its own .bat file if necessary. Add the next two lines to a .bat file (stcmdEx.bat):

@echo ON
"C:\Program Files\Micro Focus\Java\Oracle1.8.0_91\bin\java.exe" -jar "C:\Program Files\Micro Focus\StarTeam SDK <version>\lib\stcmdEx.jar" %*

This approach uses the standard MS-DOS command line execution and parameter passing technique. Then call this .bat file from a containing batch script:

CALL stcmdEx.bat co -p "Administrator:Administrator@localhost:49201/Project Name/View Name" -is -rp "c:\temp" -filter "GIMOU" -o -vb >c:\temp\output.txt

Back to top

Using CommandProcessor Natively

Application developers who need to incorporate command line functionality natively into Ant, Hudson, or other scripts can directly load the SDK .jar and instantiate the CommandProcessor object without any of the stcmd shell overhead.

Each CommandProcessor object represents an instance of a different StarTeam Server connection. The actual object signature and usage pattern can be invoked from JavaScript, Jython, etc.

Back to top

SDK Object Example

Below is an example of using the SDK object.

CommandProcessor cp = new CommandProcessor();
cp.execute(“connect localhost:49201@Administrator:Administrator”);
cp.execute(“set project = StarDraw view = StarDraw”);
cp.execute(“select name,status,dotnotation from changerequest into queryoutput.txt where folder = \"Sales Material\" recurse order by name”);
cp.execute(“disconnect”);

The full CommandProcessor interface documentation is available as part of the SDK javadocs.

Back to top