Use
label to create or update a view or revision label. A view label can be designated as a build label. By default, view labels are automatically applied to every folder, file, change request, requirement, topic, and task in the view. By default, revision labels are not applied to any items.
You can use
apply-label to apply labels created with
label to specified files. You can also use the label option (-vl) in
ci to attach your new label to files as you check them in.
Syntax
The syntax for this command is:
stcmd{Ex} label -p "projectSpecifier" -nl "labelName" [-vl "labelName" |
-vd "asOfDate" | -vp stateName] [-d "description"] [-b | -r] [-f] [-u]
[–pattern “date-pattern”] [-ps promotionStateName ]
- Parameter
- Description
- -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".
- -nl
- Specifies the new label’s name. If not found, a new label will be created. If found, the existing label description will be updated and the label will be marked frozen or unlocked.
- -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 can be either a view or revision label, but it must already exist in the application.
- -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.
- -vp
- Specifies the promotion state.
- -d
- A user specified Description. However, we continue to support
-r as an alternate to
-d for the description, but strictly for backward compatibility
- -b
- Specifies that the new label is a build label. Without either-b or
-r, the label is a view label. View labels (and a build label is a special type of view label) are immediately and automatically applied to every folder, file, change request, task, and topic in the view.
- -r
- Specifies that the new label is a revision label. You can use the new label to label files that you check in. This command does not attach the new label to any items unless you create the label by copying an existing revision label that is attached to one or more items. See the
-vl option.
- -f
- Creates the new label as a frozen label or updates an existing label and marks it as a frozen label.
- -u
- Creates the new label as an unlocked label or updates an existing frozen label and marks it unlocked.
- -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".
- -ps
-
When
-ps is specified, the label is assigned to the promotion state specified by -ps. If the label name does not exist, then a new label is created following existing rules. If the label name already exists, then it is simply assigned to the promotion state.
Note: If none of
-vd,
-vl or
-vp are specified, then the created label is based on the current server time.
Example
The following example uses label to create a new build label named
Beta for the
StarDraw view of the
StarDraw project.
Use the
-p with
label or the stateful
set command to set the context of the project/view/parent folder.
stcmd label -nl "Beta" -b