Use the
insert command to execute a single item insert of the specified values.
The insert statement executes a single item insert if the values are specified in-line or a transacted set of inserts if the values are specified though an input file.
The value clause specification should match that of the property list specification, whether in line or provided through the input file. The types and the number of values should match their corresponding property specifications.
The items are created in the folder described in the folder hierarchy argument of the set statement. If no folder hierarchy is provided, the items are created in the root folder of the selected view. The items are created and saved to the
StarTeam Server in a server transaction. All the items are successfully created or none are created. If the insert succeeds, a check-in change package is created, which records the newly created items and their property values. Values that contain spaces should be enclosed in double quotes. This command has been modeled on the standard SQL
Insert 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} insert into type ( propertyName, propertyName,... )
revisions | values [ ( value, value,... ) |
from ‘filePath’ { separator ‘fieldSeparator’} {-pattern "pattern"} ]
{output* | {propertyName,...} | filter='myFilter' into "outputFilePath"
[-p "userName:password@hostName:endpoint/projectName/[viewName/][folderHierarchy/]"]
- Parameter
- Description
- propertyName
- Specifies the subset of properties for the type.
- 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.
- 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.
- -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".
- 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.
- myFilter
- Specifies a filter by name, whose properties are written to the output file.
- -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".
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.
Example
The following is an example of insert from file:
stcmdEx insert into story (name, tag) from c:\temp\story.csv separator “|”
The contents of
story.csv would look like this
"This is a story name"|101.103
"This is a second story"|105
Whatever the user modifiable property names you specify in the command must match up in order with the content of the CSV file. Note that the separator in the file must match what you tell the command as the separator.