Use co to check out files from a StarTeam repository (or vault) to your working folder using the command line. Unless you use -o, this command pauses at each file with a Modified, Merge or Unknown status to let you know that the file will not be checked out.
The syntax for this command is:
stcmd{Ex} co [-p ["projectSpecifier"] [-epwdfile |-epwdfile "filename"]
[-cmp] [-encrypt RC4, RC2_ECB, RC2_CBC, RC2_CFB] [-cacheAgentThreads number]
[—useMPXCacheAgent | -useCA host:port | autolocate]] ]
[-cfgl "label" | -cfgp "promotion state" | -cfgd "date"] [-is]
[-pattern "datepattern"] [-rp "directory" | -fp "directory"] [-frp]
[-filter "filter"] [-o] [-e] [-l | -u | -nel] [-break] [-ro | -rw]]
[-vl "name" [-attached] | -vd "date" | -vn number | -vp "name"] [ –chgpkgid 1234567 ]
[-cp "name"] [-exclude <pattern> | #<pattern file>] [-cwf] [-f NCO | NCD]
[-ts] [-eol [ on | off | cr | lf | crlf | platform]] [-fs] [-q | -vb | -pf
"filterName"]
[-ofp "resultsOutputFilePath] [-uv] [-iip] [files...]
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.
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.
Provides an address. host:port specifies the actual known address of the cache agent. useCA either can be used in the context of a known cache agent address port or turns on autolocate.
"12/29/13 10:52 AM"
"December 29, 2013 10:52:00 AM PST"
"Monday, December 29, 2013 10:52:00 AM PST"
When used with add or ci, the command recursively visits all modified files in all sub-folders and checks them in.
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.
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.
For example, if the default root folder path is c:\stardraw, then the command co -p "Administrator:Adiministrator@localhost:49201"/StarDraw -is -frp checks out the entire folder tree recursively to c:\stardraw.
If the path is overridden using the -rp command, such as co -p "Administrator:Adiministrator@localhost:49201"/StarDraw -is -rp "c:\temp" -frp, the entire stardraw folder tree gets checked out to c:\temp.
-frp does nothing if the entire folder tree is already relative to the root folder.
However, consider the StarDraw example. If the sub-folder Source Code default path is set to a mapped drive on a machine, for example, e:\\StarDraw or a UNC path (\\MicroFocus Build Server\) and you run the command line on a different machine from where the mapped drive or the UNC path is unreachable, the co command without -frp will throw an exception.
With -frp, the command will succeed, the Source Code folder and all descendant sub-folders are created relative to its parent, and the files in the folder hierarchy are checked out.
If -attached is not specified, its default value is always false.
-attached used in conjunction with -vl "label name" alters the fundamental behavior of the co command.
If -attached is false (the default), the files to be checked out are identified by the file(s) pattern specified by the co command, -vl specifies the revisions of the subset of files attached to the label.
If specified, the checkout is based on a committed change package, with the specified view member ID.
All files attached to that change package are checked out at the revisions they were at when the change package was committed. A change package checkout is a targeted sub-set of files checked out from history, at a revision timestamp equal to the change package commit time.
Exclude files or folders whose names match a pattern (or set of patterns). This is supported for compatibility with bulk check out. You can either specify the pattern inline -exclude <pattern> or you can specify a set of patterns in a file -exclude#patternFile.
A pattern can be an exact file or folder name or it may contain wildcard characters (e.g., '*.class').
To specify a folder name, precede the pattern name with a forward-slash (e.g., '/ bin'). A single pattern can be provided with -exclude. Alternatively, one or more patterns can be specified on separate lines of the given <pattern file> (prefixed with # ).
Pattern file names may be fully qualified with their path on the file system, e.g. #"c:\temp\patternfile.txt" or relative to the current folder e.g. #"patternfile.txt".
If executed from stcmd.exe, the entire string #pathToPatternFile must be placed inside "" e.g "#c:/temp/patternfile.txt" or "#patternfile.txt".
If executed through stcmdEx.jar, then the # symbol precedes the double quotes.
In either case, pattern file names must be enclosed in double quotation marks. "…"
If the pattern matches a folder path, then all files in that folder path will be excluded.
Finally, a pattern may also be a fully or partially qualified path to a file in StarTeam without wildcards, e.g. /StarDraw/External Resources/StarDraw.ico
If the pattern matches an exact file name, then all instance of that file name, no matter where they are in the folder tree, will be excluded.
In this case, only the file that exactly matches the parent folder path will be excluded.
When using stcmdEx.jar, encase just the patternFile in double quotes. For example, #"c:/folder/folder too/file"
This syntactic difference arises from the way special characters (such as #) are handled in C/C++ as opposed to Java, in the context of the Windows Operating System.
-f NCO is ignored if -filter is used.
-f NCD is ignored if -filter is used.
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).
Additionally, with per folder status repository in use on the local machine, if files are checked out to empty working folders, empty .sbas folders will not be left on disk.
Be aware that the file statuses may never be known, even if you use the update-status command later. You can do a force check out without the -fs option to obtain current files with correct statuses.
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.
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".
Several special characters can be used in the file specification:
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 (\).
The following example uses co to lock and check out .doc files from User Manual, a child of the root folder StarDraw (in the StarDraw view of the StarDraw project):
stcmd co -p "JMarsh:password@Orion:1024/StarDraw/StarDraw/User Manual" -l "*.doc"
The next example uses co to merge a readme file:
stcmd co -p "NTesla:@10.50.5.179:49201/WebDev/WebDev" -encrypt RC4 -fp "/export/home0/johnson/working" -merge "README"
Either use the -p with co (as above) or the stateful connect and set commands (below) to set the context of the project/view/parent folder:
stmcd connect JMarsh:password@Orion:1024 stcmd set project = StarDraw view = StarDraw folderHierarchy = " StarDraw/User Manual" stcmd co -l "*.doc" stcmd disconnect
stcmd supports both stateless (using -p) and stateful (connect…, set…, {commands}, disconnect) models.
The stateless approach causes each command to connect, set the project, execute the command, and then disconnect.
The stateful approach requires the script author to manage the connect, set and disconnect. However, this has the advantage of supporting multiple commands for execution within the context of a given connect, set, and disconnect session.
The next example uses stcmd co to checkout all files, recurse through the entire folder tree (-is) and return (for the set of checked out files) the set of all property values described by the property filter -pf:
stcmd co -p " JMarsh:password@Orion:1024 /StarDraw" -is -pf \"<All Files By Status>\"
This example checks out files from a historical point in time, rolled back to a view configuration based on the label label abc:
stcmd co -p " JMarsh:password@Orion:1024 /StarDraw" -cfgl "label abc" -is -pf \"<All Files By Status>\"