Check Out Files: co

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.

Note: The functionality of the bulk checkout utility (BCO) has been fully added to co. BCO is no longer distributed with this version of StarTeam.

Syntax

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] [-iip]
[-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 | NCX]
[-ts] [-eol [ on | off | cr | lf | crlf | platform]] [-fs] [-q | -vb | -pf
"filterName"]
[-ofp "resultsOutputFilePath] [-uv] [-iip] [-cr | -req | -task ] processItemPath]  [-fileid file viewmemberid [-filedot filedotnotation]]  [files...]

Parameters

For information about the command parameters, refer to Operation Parameters.

In addition:

Parameter

Description

‑cacheAgentThreads The number of threads allocated to the checkout.
‑useMPXCacheAgent Ir true, and if a cache agent is available, then use it.
useCA

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.

autlocate StarTeam automatically gets the cache agent.
-frp Forces the specified relative path. When used, the -frp parameter ensures that the entire folder tree is successfully checked out relative to the root folder, either with the default or via the -rp root path override.

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.

-iip Ignore invalid path, specifically when describing rolled back or labeled configurations.
-e If specified, -e throws an exception if -filter includes M, G, or U and any of the identified file statuses match Merge, Modified, or Unknown. The thrown exception will prevent all other files from being checked out as well.
-attached May be specified, but only in conjunction with -vl "label name". When -vl is specified, and if -attached is also specified, then only those files which are attached to the label (identified by -vl) will be checked out, and specifically at the tip revision.

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.

-chgpkgid

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 <pattern> | #<patternFile>

Exclude files or folders whose names match a pattern (or set of patterns). 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".

In all cases, the # symbol precedes the double quotes and pattern file names must be enclosed in double quotation marks "…".

In all cases, you must have a space between the # and the pattern file path. For example: -exclude # "c:/temp/exlcudefile.txt"

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.

Note: Note: To exclude a folder tree containing files and sub-folders, append /* to the 'root' of the tree. For example, if your folder tree is /StarDraw/External resource/Documentation, and you want to exclude the tree rooted at 'External resource', specify /External resource/* in the pattern file.

Note: When using stcmd.exe, always encase the entire pattern #patternFile in double quotes. For example, "#c:/folder/folder too/file"When using stcmdEx.jar, encase just the patternFile in double quotes. For example, #"c:/folder/folder too/file"

-cwf Create working folders from StarTeam folders, even if they do not contain any files.

Note: Note: -cwf will only create the working folder for the specified folder. Use -is with -cwf to create working folders for all child folders.

-f NCO Specifies the check-out of any file whose status is Missing or Out of Date. NCO stands for “needs check-out.” No other files are selected for check-out.

-f NCO is ignored if -filter is used.

Note: -f NCO and -f NCD are mutually exclusive.

-f NCD Specifies the check-out of any file whose status is Missing or Out of Date and the deletion of all not-in-view files in the workspace. NCD stands for "needs check-out and delete".

-f NCD is ignored if -filter is used.

Note: -f NCD and -f NCO are mutually exclusive.

-f NCX Specifies the check-out of any file whose status is Missing or Out of Date and the deletion only of those local files which have been deleted on the StarTeam server.
-ts Sets each working file’s time stamp to the check-out time. Without this option, the file is given the same time stamp as the checked-in revision of the file.
-fts Sets each working folder time stamp to the check-out time. Without this option, the folder is given the same time stamp as the checked-in revision of the folder.
-fs Prevents file statuses from being remembered after the check-out occurs. Subsequent status values for these files will be incorrect and indeterminate. Use this option where a file’s status is irrelevant. For example, if you routinely delete the working folders before checking out files for a build, there are no files and their statuses do not matter.

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.

-vb Verbose mode kept for backward compatibility with bulk check out. If -vb is specified, the list of all files considered for checkout is returned with the per file number of bytes checked out, the time taken for the checkout, and whether a specified cache agent could be leveraged to check the content out. In addition, if the file was not current prior to the checkout, the file status on disk is also recorded.
-uv If this parameter is specified, then only user-visible folders on the local client machine (set via the StarTeam Cross-Platform Client) will be checked out.
-filedid If this parameter is specified then the file with the specific viewmeberid will be checked out directly to the path specified by -fp or -rp. Note that in this case, the actual folder tree path in the StarTeam folder hierarchy is ignored.
-filedot If this parameter is optionally specified (concomitant to -fileid being specified) then the file revision associated with the historical dot notation will be checked out from history.

Note: The fundamental difference between -vX and -cfgX. The -cfgX set of parameters open a view configuration based on a time associated with X.

Therefore, -cfgl opens a configuration based on the label time, and the checkout command checks out all the files in the view at that time. (a rolled back snapshot)

Conversely, -vl checks out exactly and only the set of files attached to the label at the revisions they are attached (unless -attached is specified, in which case, it checks out the tips).

Examples

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

This example checks out a single file content by viewmemberid to the explicit folder specified by -rp. The content is rolled back to the revision at dotnotation 1.4:

stcmd co -p "JMarsh:password@Orion:1024 /StarDraw" -rp "c:\temp\" -fileid 12345 -fieldot "1.4"