Update: update

Use update to update all items that satisfy the where clause. The syntax of the where clause is identical for select, update and delete, and is fully described in the select command section. Values that contain spaces should be enclosed in double quotes. This command has been modeled on the standard SQL update syntax.

Note: Only user modifiable properties can be specified for a value update. Run the describe type command to identify the set of user modifiable properties.

Syntax

The syntax for this command is:

stcmd{Ex} update type 
[{set
propertyName = value,
propertyName = value,
where {{ 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 ...}} |
{ ( propertyName1, propertyName2, . . . propertyNamen ) } from fileName
{ join propertyName }] {output* | {propertyName,...} | 
filter='myFilter' into "outputFilePath"
{ separator ‘fieldSeparator’} {-pattern "pattern"}} 
[–epwdfile “passwordfilepat”] 
[-p "userName:password@hostName:endpoint/projectName/[viewName/]
[folderHierarchy/]"]

Relation in {=, <, <=, >, >=, <>, !=}.

As an alternative to the set … where … syntax, you can use the (propertyName 1..n ) from filename { join propertyName } syntax. This is useful for updating types with values from a comma separated file on disk (see the Examples below).

A special null value is recognized as an allowed value of an Enumerated Property This permits the syntax:

update ChangeRequest set status = null where status = New -p "user:pwd@host:port/project/view" 
(In this example, an assigned status is unassigned).
update ChangeRequest set status = New where status = null -p "user:pwd@host:port/project/view" 
(In this example, an unassigned status is re-assigned).
Parameter
Description
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/.

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.

recurse
Designates all descendants from the folder specified.
.

Implies the current working folder, requiring the tool to find StarTeam folders with paths mapping to the current working folder.

The Command processor must be running inside the StarTeam folder hierarchy.

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.

propertyName
Specifies the subset of properties for the type.
type
Specifies the StarTeam item type by name. Types are mutually exclusive.
-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".
-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" "*"
Important:

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

-p user@hostname:port/projectName.viewName -epwdfile "pathToPasswordFile"
-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.

-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.

-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.

Property Values

The following are the property values for the command:

Property Type
Value
Text
Literal string.
Integer
A string in the form of an integer like "1234".
Double
A string in the form of a double like "1234.5678".
Long
A string in the form of a long like "1234567890".
Boolean
The string "true" or "false" - case insensitive.
Date
String format yyyy-mm-dd, 4 digit year, 1 <= mm <= 12, 1 <= dd <= 31.
DateTime
If -pattern "pattern" is specified, then it is parsed using java.text.SimpleDateFormat, localized pattern set to "pattern". See http://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html.
If -pattern is not specified, attempt to match patterns using java.text.DateFormat {SHORT, MEDIUM, LONG, FULL} in that order. See http://docs.oracle.com/javase/7/docs/api/java/text/DateFormat.html.
If all else fails, try ISO8601 parsing e.g.: yyyy-mm-ddThh:mm:ssZ (ignore fractional content after seconds).
TimeSpan
String format [ws][-][d. |d]hh:mm:ss[.ff][ws], items in brackets optional. See com.starteam.util.TimeSpan. ws whitespace, d days, ff fractional second, hh hours, mm minutes 0 <= mm <= 59, ss seconds 0 <= ss <= 59.
Enumerated
String. Enumerated value specified may be internal name, display name, or string representation of integer enumeration code. If the Enumerated property is multi-selectable, two or more enums may be specified as values. In this case, they must be separated by a period. For example: 101.102.103. Here are some examples:
stcmd insert into story (name, tag) values ("This is a story name", 101.103)
stcmd update story set tag = 102.103 where viewmemberid = 1234
Object
User string
Value specified may be user name or string representation of integer user id.
Group string
Value specified may be group name or string representation of integer group id.
Label string
Value specified may be label name or string representation of integer label id.
LinkValue
A string in the form of an integer like "1234" which represents the viewmemberid of the source or target link of a trace.
Note: The update command can be used to assign a new revision comment to the tip revision of a selected set of items of a given type using the special property keyword revisionComment. revisionComment should not be used in conjunction with any other property updates. For example:
stcmd update changeRequest set revisionComment = "Now is the time for all good men" where query = "Status = Open" -p …

Simple Example

The following example sets the synopsis to the value foo for all change requests with an Open status.

stcmd connect localhost:49201 // OR
stcmd connect localhost:49201 // attempts an autologon via the toolbar & cached credentials
stcmd set project = ‘StarDraw’ view = ‘StarDraw’
stcmd update changerequest set synopsis = "foo" where query = "Status = Open" disconnect

Example Using a Text File for Changes

The following example will update the set of all change requests in the file crsForUpdate.txt, properties as specified in the comma separated list, values in the file spread across several lines, 1 per change request, order of the values matching the order of the properties in the command syntax.
stcmd update ChangeRequest (ChangeNumber, Synopsis, usr_SomeText, Component) from c:\\somepath\\crsForUpdate.txt separator , 
-p “Administrator:Administrator@localhost:49201/TestUpdate”

If the property names are not specified in the command syntax, they must be specified as the first line of the file. The default separator for the command line is the | symbol. Command authors can override the separator by providing a different separator in the syntax, e.g. separator , meaning, the file uses comma as the property value separator.

One and only one column in the file must be the column used to match each row to an item in StarTeam. This match will be made on the primary descriptor (e.g. CR Number) or the viewmemberID (the default), provided they are also specified in the file.

If neither property is found, then the command author must specify the join propertyName in the syntax. In this case, the join property column is expected to be in the file.

The file content (property values) must match the order of the properties specified in the update syntax, and separated by a ,. Each change request must be on a separate line.

The property ChangeNumber is the key that matches the data in the file to change requests in the server. It can behave as a key because it is a read-only property, and it is also the primary descriptor for the change request type. You could equally well have used ViewMemberID as the key, specified that instead of ChangeNumber, and provided view member id's in the file.

Properties Synopsis and Component are user modifiable text properties.

Property usr_SomeText is a custom property added to the type by the customer (that's why it's name starts with usr_).

By definition, all custom properties on a type are user modifiable.

Type and property names are case insensitive and all command line syntax is expected to be in lower case however, project, view, folder, file names may or may not be case sensitive, depending upon the platform.

Matching the example above, the file crsForUpdate.txt would have the format:

1234,"this is a 1234 foo","special text for the custom property usr_SomeText","software component" 5678,"this is a 5678 bar","other text, that is relevant, to a bar","hardware component"

From the example, 1234 & 5678 are change numbers for which change requests must already exist in the server, in the selected project and view.

If you specified a different separator (for example: |), then the data in the file would be separated by |.

1234|"this is a 1234 foo"|"special text for the custom property usr_SomeText"|"software component"

You may specify any consecutive data values in the file, provided that the order and type of the data values match the order and type of the property names specified in the command, and that these properties are user modifiable.