Operation Parameters

This topic describes the parameters that can be used with the StarTeam command-line operations. The parameters supported by the operations are listed in the syntax for each operation.

Parameters that are specific to certain operations are listed alongside those operations.

Parameter Description
active The active process item.
all Specifies that the label will be detached from all items it is attached to.
break Breaks the current lock by another user if you have the access rights to break locks.
cfgd Configures the view as of the specified date/time. Examples include:

"12/29/13 10:52 AM"

"December 29, 2013 10:52:00 AM PST"

"Monday, December 29, 2013 10:52:00 AM PST"

cfgl Configures the view using the specified label. Without -cfgl, -cfgp, or -cfgd, the view’s current configuration is used.
cfgp Configures the view using the specified promotion state.
charset

If -charset is not specified, the default platform encoding is used to read file content from the xml file. Otherwise, the xml file will be read using the specified encoding. Valid charset examples are: UTF-8, Shift_JIS, ASCII, Windows-1250, and etc.

cmp

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.

cp Name of the code page used for localization and internationalization of the content, file and folder names, keyword expansion, etc. Supported code page names are US-ASCII (the default), UTF-8, UTF-16, windows-1252, ISO-8859-1, ISO-8859-9, ISO-8859-15, windows-31j, EUC-JP, Shift_JIS, ISO-2022-JP, x-mswin-936, GB18030, x-EUC-CN, GBK.
cr, req, task

Complete path from the project view's root folder to the change request, requirement, or task number to be used as a process item. Use the forward slash (/) as a delimiter between folder names.

For out-of-view process items, specify the project name and view name in front of the complete folder path. For example:

-cr MyProject/RootView/RootFolder/SourceCode/37

This specifies change request 37 in the SourceCode folder (under the root folder) of the ChildView view in the MyProject project.

Note: For in-view process items, as long as the change request, requirement, or task numbers are the unique primary descriptors of their types (true by default), it is sufficient simply to specify the number, with no path. The project and view names are assumed from -p.

If a process item is specified, then the files being checked in are attached to the process item and follow the project process rules.

-cr, -req or -task are mutually exclusive. If any one of them is specified, -filter/-f are ignored.

csf

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.

d A user specified Description. However, we continue to support -r as an alternate to -d for the description, but strictly for backward compatibility.
df Deletes the user’s working file. Without this option the working file remains in the working folder on your workstation.
displayName A name for a type that can be translated to the supported languages.
description A user specified Description.
encrypt

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:

  • RC4. RSA RC4 stream cipher (fast).

  • RC2_ECB. RSA RC2 block cipher (Electronic Codebook)

  • RC2_CBC. RSA RC2 block cipher (Cipher Block Chaining)

These encryption types are ordered from fastest to slowest. Each of the slower encryption types is safer than the one preceding it.

Note: For platforms other than Microsoft Windows, the public and private keys used in the encryption process are not created automatically. They are stored in a file in the user’s home directory. This options file is named .starteam. It contains a variable or shell variable called keyfile. The keyfile variable specifies the location of the file that contains the public and private keys. If you do not specify the keyfile variable, an error occurs. When you specify the keyfile variable, but the file does not exist, the StarTeam Cross-Platform Client generates a random pair of keys, creates the file, and stores the keys in it. Be sure to secure this file. For example, in UNIX, only its owner should be able to read it.

eol Automatically convert end-of-line markers. Use [cr|lf|crlf|off|platform].

When on, text files are transferred from the StarTeam Server’s repository to the workstation’s working folder with the end-of-line convention for the platform executing the command as determined by the Java VM.

When off, the default, no end-of-line conversion is performed. Using off is the same as not using -eol at all.

For Microsoft Windows clients, the end-of-line marker is a carriage return/line feed (crlf) combination. For UNIX platforms, it is a line feed (lf). For MAC systems, a carriage return (cr).

You would set this option to on or lf, for example, when you compare a file from the repository and a working file on a UNIX system (if the repository stores text files as crlf).

Note:  

  • If a file has a fixed EOL value set in StarTeam, then cr, lf and crlf are all ignored, and the file is always checked out using the set (fixed) eol value. To override this behavior, pick -eol platform.
  • When -eol platform is selected, then all files are checked out using the platform specific eol, whether or not they are marked fixed for a different platform.

epwdfile

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.

Note: When -epwdfile is used, a password should not be specified as part of the -p or -sparameter

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"

Use the following syntax to include the encrypted password in the command as clear text.

Note: This action does not access the network with the clear value.

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" "*"

Note: If -p or -s and -epwdfile are used together, the parameter :password must be omitted from -p. Example:

-p user@hostname:port/projectName.viewName -epwdfile "pathToPasswordFile"

ex

Indicates the exclude lists to be used by this new folder. Exclude lists exclude certain files or types of files from visibility. If a working file in this folder’s working folder would have the status Not In View but it matches a file specification in one of the exclude lists, the application does not display it at all. It is as though the file did not exist.

For example, suppose you are creating files in an application that makes automatic backup copies of each file (with the extension .bak) every time you save a file. Your working folder might contain several .bak files, but you have no reason to add them to the project view. From the application, it is annoying to see these .bak files as possible candidates, so you exclude them. Excluding files is done on a per-folder basis. However, exclude lists can be inherited from parent folders.

The full syntax is: -ex excludeType

The types include:

  • inherit. This folder will inherit any exclude lists used by its parent folder and use the exclude list specified with either -exfile or -exlist (if one is created). This is the default.

  • local. This folder will use only the exclude list specified with either-exfile or -exlist.

  • none. This folder will use no exclude lists, regardless of what you specify with either -exfile or -exlist.

exfile Specifies the path to the file that contains the local exclude list for this folder. See -exlist for a description of the exclude list’s contents.
exlist

Specifies the local exclude list for this folder. Use a maximum of 254 characters. Enter one or more file specifications (using the standard * and ? wild cards), separated by commas, spaces, or semicolons. To include a comma, space, or semicolon as part of the specification, enclose the specification in double quotation marks: *.exe,*.dll p*z.doc;*.t?t "test *.*"

If you are using double-quotation marks in your exclude list or have a lengthy exclude list, we recommend that you use the -exfile option. With -exlist, each quotation mark in the exclude list needs to be preceded by the escape character for your system or shell. For example, the caret (^) works on NT systems. With-exfile , you do not need to use escape characters.

f NCI

Specifies the check-in of any file whose status is Modified. NCI stands for “needs check-in.” No other types of files are selected for check-in.

-f NCI is ignored if -filter is used.

filePath

The path to a file containing multiple items whose values will be inserted.

Each row is separated by a new line. Each column is separated by the specified fieldSeparator or "|" if a separator is not specified.

files...

Specifies the files to be used in the command by name or by file name-pattern specification, such as "*.c". All options are interpreted using the semantic conventions of UNIX instead of Windows because UNIX conventions are more specific. This means that "*", rather than "*.*" means “all files.” The pattern "*.*" means “all files with file name extensions.” For example, “star*.*” finds starteam.doc and starteam.cpp, but not starteam. To find all of these, you could use "star*".

Without this option, the default is "*". When used, this option must always be the last option. Any options after it are ignored.

If you use *, rather than "*" to indicate all files, a UNIX shell expands it into a series of items and passes this series as a group of options to the stcmd command. This can cause problems, for example, when you are checking out missing files, so it is best to use "*" to avoid unwanted complications.

If you use a set of file patterns, each pattern should be enclosed in its own set of quotation marks. For example, you can use "*.bat" "*.c", but you cannot use "*.bat *.c".

Note: Always enclose this option in quotation marks. Failure to do so can result in unpredictable consequences on all supported platforms.

Several special characters can be used in the file specification:

*Matches any string including the empty string. For example, * matches any file name, with or without an extension. "xyz*" will match "xyz" and "xyz.cpp" and "xyzutyfj"
?Matches any single character. For example, "a?c" will match "abc" but NOT "ac"
[...]Matches any one of the characters enclosed by the left and right brackets.
-A pair of characters separated by a hyphen (-) specifies a range of characters to be matched.

If the first character following the right bracket ( [ ) is an exclamation point (!) or a caret ( ^ ), the rest of the characters are not matched. Any character not enclosed in the brackets is matched. For example, "x[a-d]y" matches "xby" but not "xey". "x[!a-d]y" matches "xey" but not "xby".

A hyphen (-) or right bracket ( ] ) may be matched by including it as the first or last character in the bracketed set.

To use an asterisk (*), question mark (?), or left bracket ( [ ) in a pattern, you must precede it with the escape character (which is the backslash (\)

filter

Specifies a string of one or more characters, each of which represents a file status. Never include spaces or other white space in this string. Only files that currently have the specified status(es) will be actioned. Does not apply to files that are Not In View.

C = Current
M = Modified
O = Out of date
N = Not In View
I = Missing
G = Merge
U = Unknown

For example, using CM applies a command only to files with a status of Current or Modified.

-filter takes precedence over -f NCI. If you use G, O, or U, you must also specify -I or -o. Otherwise the G, O, or U is ignored.

-filter also takes precedence over -f NCO. If you use G, M, or U, you must also specify -o to force the checkout operation. Otherwise, the G, M, or U is ignored.

fp

Overrides the specified StarTeam folder’s working folder or working directory. This is equivalent to setting an alternate working path for the folder.

While this option allows you to use a different working folder than the one specified by the StarTeam view, its critical importance is to provide cross-platform compatibility. For example, UNIX and Microsoft Windows systems specify drive and directory path names in incompatible ways.

While the path D:\MYPRODUCT\DEVELOPMENT\SOURCE is understood on a Microsoft Windows platform, it is not understood on a UNIX platform. Use this option to define the working path if your platform does not understand the path specified in the StarTeam project.

A backslash (\) is interpreted as an escape character when it precedes quotation marks. As a result, an error occurs in the following example:

stcmd ci -p "xxx" -fp "C:\" "*"

which is interpreted as:

stcmd ci -p "xxx" -fp "C:" *"

To avoid a situation like this, escape the final character in "C:\" as follows:

stcmd ci -p "xxx" -fp "C:\\" "*"

Or avoid it as follows when the -rp path doesn’t end with the root folder as in C:\orion\:

stcmd ci -p "xxx" -fp "C:\orion" "*"

The full syntax is: -rp "folderName".

Folder is the Microsoft Windows term and appears in the StarTeam user interface. Directory is the correct term for the UNIX platform.

help Invokes help. -help works with each command, although not shown in the syntax.

Note: -help and -I are only supported by stcmd. Neither is supported by stcmdEx.

i Prompts user to confirm check-in or check-out (depending on command used) when file status is Merge, Out of Date, or Unknown. The user can ignore the file.
id Specifies the unique item (view member) ID of the item. Look in the property lists of the CPC or query using the select command to find the View Member IDs. -id can also specify the primary descriptor of the item; e.g. file name, folder name, change request number.
ifp

Specifies a fully qualified path to a file which contains a list of item IDs. The items associated with item IDs are associated to the label. If -ifp is specified, -filter "fileStatus" cannot be specified.

iip

Ignores invalid path. If this parameter is specified, and if the folder path in the command is specified and invalid, then the command will exit successfully without throwing an exception.

is Applies the command to all child folders. Without this option, the command applies only to the specified folder. When this option is used with add-folder, you can add an entire branch of folders to the StarTeam folder hierarchy.

When used with add or ci, the command recursively visits all modified files in all sub-folders and checks them in.

l | u | nel Locks the item(s). -l is exclusive lock, -u is unlocked, and -nel is non exclusive lock. These items are mutually exclusive and an optional parameter.
lbl Specifies the label name on which to perform the action. This option can be used more than once. The application action is for all of the labels on the specified file or revisions.
mark

Indicates that, if all the files are successfully added, the process item’s status will be changed to fixed (for a change request), finished (for a task), or complete (for a requirement). The files are pinned to the revision with the new status. The item is not marked as fixed, finished, or complete unless all the files are successfully added.

myFilter Specifies a filter by name, whose properties are written to the output file.

myFolder

Specifies the StarTeam folder name in the current view.

If there are multiple folders with the same name, the command performs the action on all folders with that name.

MyFolderHierarchy

Specifies the folder hierarchy in the "/" format.

Start from the root folder and end in a branch folder. For example: /StarDraw/SourceCode/On-line Help/

name Specifies the name. Maximum of 254 characters.
nivf If -nivf is included, then files in Not in View folders are also included in the action.
nomove Do not move labels if already attached.
o Forces a check-in/check-out depending on which command is used. -o is supported with -filter and -f NCD, but not with -f NCO.
ofp

Provides a file name with a fully qualified path into which to write the command output. By default, a "|" character separates each column in the output. A new line separates each row. The first row is the command name. The second row has the property names. All subsequent rows contain the data. If the file already exists, the output is appended to the end of the file.

It is possible to override the "|" character separator by specifying separator = fieldSeparator as a parameter to the connect command.

For example, separator = ;; specifies two adjacent semicolons ( ; ) as the column separator.

output Turns on logging of the command to a log file specified by INTO.

The INSERT, DELETE, and UPDATE commands log the selected properties of the inserted items to a log file. The property values are separated by the specified fieldSeparator, or "|" if a separator is not specified.

p

Indicates the view or folder to be used. It also provides the user name and password needed to access the server. -p is retained for backward compatibility. Commands using -p continue to work, but are stateless. Each command opens a connection, executes the command syntax, and closes the connection. (New command line scripts may take advantage of the command line's stateful nature. See connect and set for examples. Old scripts may be migrated to the new command line syntax.) Stateless commands cause more client server traffic than stateful commands.

Note: If the clear text password contains the @ or the : symbols, then it cannot be specified through -p using the syntax username:password@host:port. The @ or :symbols will conflict with the syntax and cause the command to fail. In general, passwords with special characters in them such as @, :, ,, must be stored in the password file using the store-password command. Additionally, the password, when specified for storage in the encrypted file, must be quoted. For example: stcmd store-password -password "foo@bar" -epwdfile c:\tmp\pwdfl. Passwords stored in an encrypted password file can be used in conjunction with -p or the connect command as documented.

The full syntax is:

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

For example:

stcmd -p “bsmith:rocketfive@orion:49201/StarDraw/StarDraw/SourceCode/”

  • If the user name is omitted, the current user name is used.

  • If the password is omitted, the user is prompted to enter the password. When the user types a password, the characters are not displayed on the screen.

  • If the host name is omitted, the default is localhost.

  • Entering an endpoint (port number) is required. The default is 1024.

  • The project name is always required.

  • A view hierarchy should be used to identify the view. Use the colon (:) as a delimiter between view names. The view hierarchy should always include the root view. For example, "StarDraw:Release 4:Service Packs" indicates that the view to be used is the Service Packs view, which is a child of the Release 4 view and a grandchild of the StarDraw root view. If the view name is omitted, the root view is used. If the view is the only view in that project with that name, you can use only the view name. Doing this is not recommended, however, because another view with that name could be created at a later date.

  • A folder hierarchy should be used to identify the folder. Use the forward slash (/) as a delimiter between folder names. The folder hierarchy never includes the root folder. Omit the folder hierarchy if the file is in the view’s root folder. For example, if the root folder of the view is StarDraw, and the hierarchy to your files is StarDraw/SourceCode/Client, use only "SourceCode/Client".

parentEnum If the property is a hierarchical property, then a parent enum name may be optionally specified.
pattern

Qualifies the datetime. It can be specified wherever a date-time is specified, such as -cfgd, -vd, etc. The pattern must match any valid pattern supported by the java JDK in java.text.SimpleDateFormat.applyLocalizedPattern(String). The pattern may be localized.

For every command that takes a -pattern parameter, a -locale parameter is optionally available. This is the "two character country code".

pf

Specifies the filter name whose associated filter properties produce the columns in the output matrix. Each command returns a result matrix. -pf determines the matrix columns. See -ofp for more information. If not specified, the primary descriptor property of the Type is returned as the command output.

-pf does not apply to the select query command.

predecessorEnum

The internal or display name of the enum that will be positional prior to this enum in a logical sort.

Place (position) this Enumerated Value immediately after the specified predecessor. An exception will be thrown if this Enumerated Value and the specified predecessor belong to different hierarchies. If the context of the owning EnumeratedProperty is known to this and its predecessor, then the sort order of the entire list of values is realigned in accordance with this assignment. If not, then the sort order of this object alone is reassigned.

property The name of the enumerated property.
propertyName Specifies the subset of properties for the type.
q

Enables quiet mode. The -q option is retained for backward compatibility with the old command line. If -q is specified, then -pf cannot be specified. The command will return no results.

query='myQuery'

Specifies the saved StarTeam query name for the type.

It acts as the equivalent of a compound where clause of a SQL statement, such as combinations of relations and operators.

If no query name is specified, the command performs the action on all objects of the type.

recurse Designates all descendants from the folder specified.
revisions Treats the contents in the file as a set of revisions of the same item. Accordingly, the first (oldest) revision is added to and all subsequent revisions are updated in sequence.

In this case, the content is expected to be presented so that the oldest revision is the first row of the file and the newest revision is the final row of the file. The revisions syntax provides customers a mechanism to make one-off copies of items (with history) from non-StarTeam to StarTeam repositories or to make copies of StarTeam assets across projects/repositories.

d | r Description or reason for check-in. If -d or -r is used, -rf cannot be used. The reason should be enclosed in double quotation marks and should not exceed 254 characters in length.
rf Specifies the file name that contains the check-in reason. This is useful if the same reason should be applied to all check-ins across multiple command line runs.
ro Makes the working file read-only after this operation. Without this option, the file remains as it was prior to the operation. Usually, you use -ro to prevent yourself from editing a file that is not locked by you. -ro must be used with -l or-u or -nel. If you use -ro, you cannot use -rw.
rolluplabels

Specifies a path to a file containing a list of revision label names. The label names must be on separate lines in the file, and must match the names of labels in the target view.

-sourceview and -rolluplabels are mutually exclusive. If -sourceview is specified, -rolluplabels should not be specified and vice versa.

rp

Overrides the working folder or working directory for the StarTeam view’s root folder.

While this option allows you to use a different working folder than the one specified by the StarTeam view, its critical importance is to provide cross-platform compatibility. For example, UNIX and Microsoft Windows systems specify drive and directory path names in incompatible ways.

While the path D:\MYPRODUCT\DEVELOPMENT\SOURCE is understood on a Microsoft Windows platform, it is not understood on a UNIX platform. Use this option to define the working path if your platform does not understand the path specified in the StarTeam project.

The UNIX shell interprets a backslash (\) as an escape character when it precedes certain characters, such as quotation marks. As a result, an error occurs in the following example:

stcmd ci -p "xxx" -rp "C:\" "*"

which is interpreted as:

stcmd ci -p "xxx" -rp "C:" *"

To avoid a situation like this, escape the final character in "C:\" as follows:

stcmd ci -p "xxx" -rp "C:\\" "*"

Or avoid it as follows when the -rp path doesn’t end with the root folder as in "C:\orion\":

stcmd ci -p "xxx" -rp "C:\orion" "*"

The full syntax is: -rp "folderName" .

Folder is the Microsoft Windows term and appears in the StarTeam user interface. Directory is the correct term for the UNIX platform.

rw

Makes the working file read-write after this operation. Without this option, the file remains as it was prior to the operation. -rw must be used with -l or -u or -nel. If you use -rw, you cannot use -ro.

s

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.

sortOrder A positional sort order may be specified, or a predecessor enum may be specified as an alternate. If neither sort order nor predecessor enum are specified, then the natural sort order is assumed.
sourceview It can describe a view within the project or a view from a different project. To specify cross-project views, the source view value can optionally take a project name followed by a / followed by the view name. Source view may also specify the target view name, for in view label merges.
tfp

Describes the folder path to which to move. If a folder name is specified, then this name must be unique across the folder tree. Otherwise, a fully qualified folder path is required, starting from the root folder of the view down to the leaf folder into which the move must be created.

If -tfp is not specified, then the move will be created in the root folder of the target view - tv.

tv Describes an optional specific target view into which to move. If not specified (and -tp is not specified), then the item will be moved into the source view described by -p.
type

Specifies the type of item. The type is one of the stock type names, such as changerequest, task, requirement, sprint, story, plan or any custom type name that is applicable to the command.

Types are mutually exclusive.

type.property The name of an enumerated property on the specified type. For example: Story.Tag. If type is specified without {.property} then all properties of the type are listed. When type.property is specified, and property is an enumerated property, then all the enumerated values of that enumerated property are listed.
useTLS Use TLS protocol to connect to the given StarTeam server. While this is optional, it is recommended for quicker connectivity.
vd

Specifies the as-of date/time used to identify the revisions to be checked out. The last revision before the specified date/time is the one checked out for each file. See the date/time examples for -cfgd.

vl Specifies a label (created using stcmd label) to be applied to the checked-in files. The label is enclosed in double quotation marks. This option can appear in the command more than once. The label may be either a view or revision label for checkout operations. For add or check-in operations, the label can only be a revision label.
vn Specifies the revision number.
vp Specifies the promotion state.
xml | xmlfile The XML definition must be specified. It can be inline via the -xml parameter, or provided via a file (the -xmlfile parameter).