IBM® Rational® Synergy
Migrating to the Rational Synergy CLI
Introduction
The Rational Synergy 7.2 CLI was designed for compatibility with the previous CLI (the
Classic CLI) and for improved performance over a wide area network (WAN).The Rational
Synergy CLI was also enhanced to be more consistent, and to provide more flexible and
powerful features. The Rational Synergy CLI is the only supported command line
interface.
This document provides specific details and guidance to migrate scripts to use with the
Rational Synergy CLI. Rational Synergy 7.2 must use the Rational Synergy CLI.
Summary of changes
Commands that start with ccmdb, ccmadm, or ccmsrv have not changed. The Rational
Synergy CLI relates only to commands that start with ccm.
Scripts using features that are not yet implemented in the Rational Synergy CLI must be
adapted to use a supported method. Specifically, a script that uses and depends on any of
the following methods is cannot be used:
•
Interactive mode - In the previous CLI, if a ccm command was executed without
options or arguments, a ccm wrapper started. The ccm wrapper remained present
and prompted for and read commands on its stdin stream until it was stopped. The
Rational Synergy CLI does not support this mode. Scripts that pipe commands into
ccm wrapper must run each command as a ccm command.
•
Retired/obsolete commands - These represent features that are no longer available.
•
Contributory or custom code that is implemented in ACcent and loaded with ccm load
or defined with ccm define or executed with ccm accent.
•
Cross platform usage - The Rational Synergy CLI requires that all commands are run
on the same machine that was used to start the session.
Most commands are implemented with a syntax that is compatible with the previous CLI.
However, there are some commands with syntax changes or changed functionality that
might require scripts to be modified to use the Rational Synergy CLI. See Commands with
significant changes for more information.
Migrating from the classic CLI to the Synergy CLI
1
IBM® Rational® Synergy Migrating to the Rational Synergy CLI
Session management and monitoring
The following table shows the type of sessions shown by the ccm status command.
Table 1.
Displayed session type
Description
Command interface
Rational Synergy CLI session. If you start a
session, you can connect to it from the same
machine.
Graphical interface
Rational Synergy GUI session.
Shared session
An ACcent interface process running on the
Rational Synergy server. It is part of the pool of
shared back-end sessions and serves all
Rational Synergy web mode clients. You cannot
connect a CLI to these sessions.
Change session
An ACcent interface process running on the
Rational Synergy server. It is part of the pool of
shared back-end sessions used by Rational
Change. You cannot connect a CLI to these
sessions.
Starting CLI sessions
Scripts that start CLI sessions must include a -s serverURL option on the ccm start
command, as shown in the UNIX shell script example:
export CCM_ADDR=`ccm start -d databasePath -s serverURL -m -q`
If the -s serverURL option is not specified, the Rational Synergy CLI tries to identify the
correct server to use based on a registry of databases held by the router process. In many
cases, this works as expected. However, if your DNS or firewall requires a different server
hostname to resolve the name correctly, you must explicitly specify the correct server with
the -s serverURL option.
The Rational Synergy CLI requires an absolute database path when starting a session. A
Windows server must use a UNC path. Additionally, a password must be provided when
starting a Windows or UNIX session.You may do any of the following:
•
2
Specify a -pw password option with the ccm start command. Be aware that on UNIX
machines, users can list processes, including their command arguments. This might
Migrating from the classic CLI to the Synergy CLI
expose a user's Rational Directory Server (RDS) password as clear text if specified
with this option.
•
Specify a -pwprompt option to the ccm start command. This prompts the user for a
password at start time, and the password is not shown to the user.
•
Use the ccm set_password command to define a default password, either for a
specific server URL or as an overall default. The ccm set_password command is
supported on all Rational Synergy platforms.
In the Rational Synergy CLI, the default role is developer and is not dependent on the
order of roles defined for a user. If you have users that do not have the developer role
available, or have scripted usage that depends on the default role being something other
than developer, you must change the ccm.cli.start.defaultrole preference in the
%USERPROFILE%\ccm.user.properties file on Windows or $HOME/
.ccm.user.properties file on UNIX.
When a CLI session is started without a -m option, the CLI stores the session address in a
ccm address file. In 7.2, the name of the address file includes the client's hostname. See
Cross platform usage for more information.
Note:
Scripts that start CLI sessions should use the -m option and
explicitly set the CCM_ADDR environment variable. The
settings insulates the script.
Cross platform usage
The Rational Synergy 7.2 CLI requires that the commands must be from a ccm wrapper
that is running with the same operating system user and on the same client machine as
the ccm wrapper that was used to start that CLI session. For example, for multiple UNIX
client machines, if you start a CLI session on one machine, you can only send commands
to it from that machine. For this reason, the name of the address file in which the default
session address was stored on startup without a -m option now includes the client
machine's hostname.
Previous versions of Rational Synergy did not support sessions running on UNIX for a
database hosted on Windows. The Rational Synergy interfaces do support this, as well as
the previously-supported sessions on Windows for a database hosted on UNIX.
Migrating from the classic CLI to the Synergy CLI
3
IBM® Rational® Synergy Migrating to the Rational Synergy CLI
Database entity specifications
The Classic CLI supported various types of specifications that reference objects in a
Rational Synergy database:
•
•
•
•
•
•
•
•
change_request_spec
file_spec
folder_spec
folder_template_spec
process_rule_spec
project_grouping_spec
project_spec
task_spec
The Rational Synergy CLI supports most of the forms of these specifications that were
supported by the Classic CLI, as well as some additional ones:
•
•
•
•
•
database_spec
object_spec
process_spec
release_spec
transfer_set_spec
In most cases, scripts using argument values or option values using such specifications
should continue to work. The Rational Synergy CLI accepts the kinds of values that the
Classic CLI accepted, with one notable exception. For commands accepting a
change_request_spec, folder_spec or task_spec a script might have placed one or more
values in a file and specified the path to that file as the argument or option value. For
example:
ccm task -show information 5
If a file named 5 existed in the current directory, the contents of that file are read and used
for the task specifications for the command. The Classic CLI shows either information
about task 5 or shows information about some set of tasks if a file named 5 exists in the
current directory.
The Rational Synergy CLI supports using the contents of a file to provide specifications
using the syntax @:filePath. If you have scripts that use this feature, you must update
your scripts to use the new @:filePath file contents form.
Some scripts might use the version delimiter to construct project specifications or object
specifications. A standard example in the Classic CLI is:
versionDelimiter=`ccm delimiter`
objectSpec=$name$versionDelimiter:$cvtype:$instance
This technique works with the Rational Synergy CLI. The Rational Synergy CLI also
accepts the colon sign (:) where the version delimiter was previously used. Using a colon
4
Migrating from the classic CLI to the Synergy CLI
sign (:) in your scripts instead of the version delimiter has the advantage that it always
specifies a completely unambiguous form. The previous example can easily be updated to
use this new feature:
versionDelimiter=":"
objectSpec=$name$versionDelimiter:$cvtype:$instance
The Rational Synergy CLI also accepts the global forms such as four-part objectnames
and query selection set references in all database entity specifications.
Scripts that operate on release definitions, DCM database definitions, and transfer sets
accept the more restrictive set of values that were supported by the Classic CLI. However,
you may find it more convenient or efficient to use the new forms in your scripts.
Some Rational Synergy operations require a context project. For example, when checking
out a file, Rational Synergy needs to identify the project containing the file to be checked
out. Some forms of database entity specifications allow such a context project to be
specified. In prior releases, the work area reference form and the project reference spec
form could provide such a context project. However, in those prior releases, four-part
objectname forms (e.g. example-1:ascii:1), cvid reference forms (e.g. @=1234), and
selection set reference forms (e.g. @1) did not provide an explicit context project. The
Rational Synergy CLI allows a context project to be specified in all those forms by adding
@two_or_four_part_projectspec. For example, the specification "@1@example-1"
means reference the first member of the selection set using the context project for project
"example-1". Some scripts may benefit from taking advantage of these extended forms of
specifications.
Backslash encoded arguments
In argument and option values that represent free-format text, the Rational Synergy CLI
accepts strings that contain backslash-encoded character sequences. For example, when
specifying a task description, you can use \n to represent the newline character, \t to
represent a tab character, \uXXXX to represent a 4-byte Unicode value, or \UXXXXXX to
represent a 6-byte Unicode value. This makes it convenient to enter newlines and
Unicode character sequences. This is a new feature.
If you have a script that uses the backslash character itself, the backslash must be
represented by two backslashes \\ when used in a free-format text value. Note that this
only applies to specific values in the Rational Synergy CLI that represent free-format text.
Values that represent work area paths for work area related commands or options, for
example, accept strings that include backslash characters without such encoding. For
example:
ccm wa -setpath C:\ccm_wa\mydatabase projectname-1
In this example, the string "C:\ccm_wa\mydatabase" is taken as-is without any
interpretation. However, consider the following example:
ccm attr -m wa_path -v C:\ccm_wa\mydatabase -p projectname-1
Migrating from the classic CLI to the Synergy CLI
5
IBM® Rational® Synergy Migrating to the Rational Synergy CLI
The value for the -v|-value option is free-format and the low-level ccm attr command
does not understand the meaning of specific attributes. The value is treated as a
backslash encoded string, and since \c is not a valid backslash sequence, this would be
reported as an error in the Rational Synergy CLI.
The above example is also unsupported. The documented and supported method of
changing the work area path is to use ccm wa -setpath. The direct modification of work
area related attributes is not documented or supported and is likely to lead to fragile and
non-portable scripts.
Retired/obsolete commands
The commands listed below are no longer supported in Rational Synergy 7.2. Alternative
operations are given where appropriate.
Table 2.
Command
Notes
ccm accent
None.
ccm clean up
You can define a scope for use with the Save
Offline and Delete operation to perform a similar
clean-up.
ccm collapse
You can use the Save Offline and Delete
operation to remove unwanted objects and
collapse the history
ccm define
None.
ccm load
None.
ccm messageview
None.
ccm reconfigure_properties
ccm update_properties
All projects now use a process rule to define
their update behavior.
ccm license
None.
ccm project
The command used in the Classic CLI to show
the Project View is retired.
A new ccm project command is supported in
the Rational Synergy CLI that identifies any
project associated with the current working
directory or a specified file system path.
6
Migrating from the classic CLI to the Synergy CLI
Table 2.
Command
Notes
ccm resync
You can use the ccm reconcile -udb
command to perform a similar operation.
ccm source
None.
ccm db_update
The ccmdb upgrade command remains
supported and performs the steps required
when upgrading Rational Synergy databases.
ccm win_fixup
None.
ccm depend
None.
ccm expand
None.
ccm groups -edit
The membership of groups is easily modified by
scripts using the new ccm groups -modify
command.
ccm dcm -change
-dir_project_instance
None.
Commands with significant changes
Some Rational Synergy CLI commands have changed functionality in this release. The
following sections detail those changes where scripts might be affected. Scripts should be
reviewed and updated to match new functionality.
The new use is documented first, then any pertinent history is provided.
ccm attr
The ccm attr -show command cannot be used to show the source attribute of projects,
files or directories in the Rational Synergy CLI. Files might be stored on the Rational
Synergy server with different encodings. The proper handling of file encodings can only be
performed when Rational Synergy transfers files for work areas and for temporary copies.
The ccm cat or ccm type command should be used to show the source attribute of
projects, files or directories.
Migrating from the classic CLI to the Synergy CLI
7
IBM® Rational® Synergy Migrating to the Rational Synergy CLI
ccm baseline
The ccm baseline -show build command identifies each baseline argument processed
in each line output. Thee Classic CLI showed the build number, if available.
The ccm baseline -show projects|tasks|objects|change_requests|pcr|fcr
command identifies each baseline before showing its related objects. This allows you to
view which related objects are in each baseline when multiple baselines were specified.
The baseline -create command uses a default baseline state of test_baseline.
Although this was the documented behavior of the Classic CLI, the implementation did not
match the intended design. Scripts that explicitly use the -state option are not affected.
ccm checkin
The Rational Synergy CLI prompts once per checkin command rather than once per
object. This is not conditional if any of the objects have or do not have existing comments.
A prompt is issued when options other than -comment, -commentedit, -commentfile or nocomment are specified. Only one text editor is invoked when -commentedit is specified.
The Classic CLI prompted you for a comment individually for each file, unless a comment
was provided or the -nocomment option was specified. If the -commentedit option was
specified, a text editor was invoked individually for each object.
ccm checkout
In the Rational Synergy CLI, only one text editor is invoked when -commentedit is
specified.
In the Classic CLI, if -commentedit was specified, a text editor was invoked individually
for each object.
ccm copy_project
The -reconf option is not available because object status-based update is not supported.
In the Rational Synergy CLI, the -release option no longer accepts the meta-value none.
All projects must have a specific release value.
In the Rational Synergy CLI, only one text editor is invoked when -commentedit is
specified. In the Classic CLI, if -commentedit was specified, a text editor was invoked
individually for each project.
The -no_links and -links options are not supported in the Rational Synergy CLI. In the
Classic CLI, the options -no_links and -links were supported but undocumented
alternatives to the documented -relative and -not_relative options respectively.
8
Migrating from the classic CLI to the Synergy CLI
ccm create
The -reconf option is not available when creating projects because object status-based
update is not supported.
In the Rational Synergy CLI, only one text editor is invoked when -commentedit is
specified. In the Classic CLI, if -commentedit was specified, a text editor was invoked
individually for each object.
The -no_links and -links options are not supported in the Rational Synergy CLI. In the
Classic CLI, the options -no_links and -links were supported for ccm create -t
project but undocumented alternatives to the documented -relative and not_relative options respectively.
ccm dcm
The use of ccm dcm -generate -lg current is not supported in the Rational Synergy
CLI. This usage has been replaced with a specific ccm dcm -mark_up_to_date
command. As part of the set-up of a mirrored database, the Classic CLI supported the
use of a DCM generate as a means of marking a transfer set up-to-date for a specified
destination database.
The ccm dcm -show -dbid -all command uses numbered output by default and sets
the query selection set. The Rational Synergy CLI supports standard formatting options for
this command so you can use the -u option to suppress the numbering.The Classic CLI
showed only the DCM database identifiers and did not provide any means of specifying a
display format.
The ccm dcm -show -ts -all command uses numbered output by default and sets the
query selection set. The Rational Synergy CLI supports standard formatting options for
this command so you can use the -u option to suppress the numbering. The Classic CLI
showed only the transfer set names and did not provide any means of specifying a display
format.
ccm export
The Rational Synergy CLI supports a new ccm export command that creates an import
package on a user-specified client file system path. The format of these packages is
implementation private in 7.2. This allows the objects in the import package to be imported
into other databases at the same release and patch level of Rational Synergy. See “ccm
import” on page 11 for cautions on such usage.
In the Classic CLI, the ccm export command allowed you to export specified objects so
that they might be imported into other databases, or later imported back into the same
database. This command is not supported in Rational Synergy 7.2.
Migrating from the classic CLI to the Synergy CLI
9
IBM® Rational® Synergy Migrating to the Rational Synergy CLI
ccm folder
The format for showing specific properties of folders using ccm folder -show is different
in the Rational Synergy CLI. The folder is identified using its folder identifier
(displayname) only. In the Classic CLI, the identification also included the folder
description. This change makes it more consistent with other commands.
The ccm folder -show tasks|objects command identifies each folder before showing
its related objects. In the Classic CLI, it was impossible to know which related objects went
with each folder when multiple folders were specified.
The -usable option for ccm folder -create and ccm folder -modify is no longer
supported. The option is accepted with a value but ignored.
The default task query is always all_my_assigned_or_completed when the
default_task_query setting is not set, regardless of the user role. In the Classic CLI, the
default was different for users in build_mgr role than developer role.
The -related option for the ccm folder -modify command is not supported in the
Rational Synergy CLI. There is no direct alternative.
ccm folder_template
The format for showing specific properties of folders using ccm folder_template -show
is different in the Rational Synergy CLI. The folder template is identified using its folder
identifier (displayname) only. In the Classic CLI, there was no identification of the folder
template associated with each line of output. This change makes it more consistent with
other commands.
The -usable option for ccm folder_template -create and ccm folder -modify is not
supported. The option is accepted with a value but ignored.
For the ccm folder_template -create command, when the -mode option is not
specified, the default mode of the folder is query-based when any of the query expression
related options (-custom, -database_id, -platform, -release, -subsystem, task_scope) are specified,. If none are specified, manual is the default. This change
makes it more consistent with other commands.
ccm groups
In the Rational Synergy CLI, the ccm groups -assign command accepts objects that are
eligible for user-group based security only. Eligible objects are projects, directories, files,
tasks, folders, release definitions, and process rules. The Classic CLI had no such
restrictions.
The ccm groups -assign command requires that the -value option be specified. In the
Classic CLI, it was optional, and if omitted, resulted in a text editor being invoked for every
object. Such usage is not supported in the Rational Synergy CLI.
10
Migrating from the classic CLI to the Synergy CLI
ccm help
In Rational Synergy 7.2, the help is integrated into one document for all clients, and is
organized in a task-oriented manner. In the Rational Synergy CLI, the ccm help command
does not accept a help topic.
In the Classic CLI, the ccm help command accepted an optional help topic argument. It
launched a web browser. If a help topic was specified, the browser was opened at the
specified help topic.
ccm import
The Rational Synergy CLI supports a new ccm import command that imports the objects
contained in an import package on a client file system. The main use of this command is to
import packages created by the new migrate feature. The format of these packages is
implementation private in Rational Synergy 7.2.
In the Classic CLI, the ccm import command allowed you to import specified objects that
had been previously exported with the ccm export command. That usage is not longer
supported.
Caution:
Importing objects into a DCM-initialized database that were
exported from a non-DCM-initialized database, or importing
objects into a non-DCM-initialized database that were
exported from a DCM-initialized database is invalid and
unsupported. Such usage is not detected or prevented but
may cause subsequent problems.
Caution:
Import packages created by ccm export must be created
by the same release and patch level of Rational Synergy as
the database into which those packages are to be imported.
The ccm export and ccm import commands must not be
used to transfer data between Rational Synergy databases
at different releases or patch levels. Such usage is not
detected or prevented but may cause subsequent
problems.
Caution:
The ccm export and ccm import commands must not be
used as a replacement for DCM. DCM provides
functionality to ensure object name uniqueness and
prevent the controlling copies of objects from being
overwritten. Performing a ccm import in the role of
ccm_admin can overwrite or modify static objects.
Migrating from the classic CLI to the Synergy CLI
11
IBM® Rational® Synergy Migrating to the Rational Synergy CLI
ccm migrate
Rational Synergy 7.2 provides a completely new design for migrating data into Rational
Synergy. The Rational Synergy CLI ccm migrate command is a new command. If you
have scripts that used the old ccm migrate command, you must update them to use the
new design and command syntax.
The migrate rules used with the Classic client migrate operation are no longer supported
in Rational Synergy 7.2. Instead, Rational Synergy 7.2 supports a new design of mapping
rules that are used by migrate, when creating new objects without specifying a type, and
when reconciling work area conflicts. These new mapping rules are significantly more
powerful and flexible than the Classic client migrate rules in previous Rational Synergy
releases. See IBM® Rational® Synergy Mapping Rules for more information.
ccm process_rule
For the ccm process_rule -modify command, the -lbp|-latest_baseline_projects
option, the -pb|-prep_baseline option, and the -nopb|-noprep_baseline option
continue to be supported. However, the semantics have changed from previous releases.
•
•
•
•
If -lbp and -pb are specified, the baseline selection mode is set to the latest static
or build management projects.
If -lbp is specified without -pb or -nopb, the baseline selection mode is set to the
latest static projects.
If -pb is specified without -lbp, the current selection mode of the specified
process rule is examined. If it is either the latest static projects, or latest static or
build management projects, the selection mode is set to the latest static or build
management projects. Otherwise, an error is reported and the command fails.
If -nopb is specified without -lbp, the current selection mode of the specified
process rule is examined. If it is either the latest static projects, or latest static or
build management projects, the selection mode is set to the latest static projects.
Otherwise, an error is reported and the command fails.
ccm project_grouping
In the Rational Synergy CLI, the ccm project_grouping
-ubt|-update_baselines_and_tasks command accepts the previous options of -rbt
and -refresh_baseline_and_tasks. Scripts using these options do not need to be
changed, but it can be beneficial to update them to use the new option names.
12
Migrating from the classic CLI to the Synergy CLI
ccm query
In the Rational Synergy CLI, the -task option accepts a task specification or a list of task
specifications. The -db option has been retired and is not supported. This makes its usage
consistent with other commands and delivers the expected results in DCM initialized
databases. For example, to query for task A#5, specify -task A#5.
In the Classic CLI ccm query command, the -task option specified a task number and not
a task identifier. Thus in DCM initialized databases, it might not have given the expected
results. The -db option could be used to specify the database for the task. However that
usage was not consistent with all the other commands that accepted a task identifier. For
example, in order to query for task A#5 a user would specify -task 5 -db A.
ccm reconcile
In the Rational Synergy CLI, the -p|-project option must be specified in order to use
project specifications. If the option is omitted, the arguments are taken as file
specifications. This makes the command consistent with other commands and avoids
potential ambiguities.
If you have scripts that use the ccm reconcile command with projects, update the scripts
to ensure that the -p|-project option is specified.
In the Rational Synergy CLI, the -task and -comment options are only permitted for the
ccm reconcile -udb|-update_database command. If you have scripts that erroneously
use these options for the other usages of the ccm reconcile command, you should
remove those options from those commands.
In the Classic CLI, the -task and -comment options were permitted for the ccm
reconcile command. However, they only applied and had an effect with the ccm
reconcile -udb|-update_database command.
In the Classic CLI, the ccm reconcile command supported a -rpt option that could be
used to get a report of the work area conflicts. The format of that report was hard coded
and could not be customized by users. This option is not supported in the Rational
Synergy CLI. Instead, you can use standard formatting options to control how work area
conflicts are reported and redirect the stdout stream to a file.
ccm relate -s|-show
In the Rational Synergy CLI, the ccm relate -s|-show command requires that either the
source object is specified with the -f|-from option or that the destination object is
specified with the -t|-to option, or both.
In the Classic CLI, the options -n|-name, -f|-from and -t|-to were optional with the
ccm relate -show command.
In the Classic CLI, the -fmt|-format option value was a format string of the form
"fromFormat:toFormat". This format is not supported in the Rational Synergy CLI.
Migrating from the classic CLI to the Synergy CLI
13
IBM® Rational® Synergy Migrating to the Rational Synergy CLI
Instead, the Rational Synergy CLI supports a more general way of specifying the
information to be reported.
ccm status
In the Rational Synergy CLI, the default Synergy username is the operating system user
name when run outside of a session. The -u|-user option can be specified to explicitly
specify a Synergy username.
In some earlier Rational Synergy releases, the ccm status command used data in the
user’s personal ccm.ini file to determine the default Synergy username if it was run
outside of a running CLI session.
ccm typedef
The ccm typedef command supports operations to create and modify type definitions. In
Rational Synergy 7.2, the type definition feature has been redesigned to simplify usage
and add capabilities available through the CLI. This includes the ability to mark a type
definition as inactive so that users are encouraged to migrate to an alternative preferred
type.
The Rational Synergy CLI implements a number of ccm typedef commands. These
should be regarded as new commands. Scripts that used the old ccm typedef command
must be reviewed and updated to use the new command.
The ccm typedef command supports:
•
•
•
•
•
•
Creating new type definitions with ccm typedef -create.
Modifying existing type definitions with ccm typedef -modify.
Listing type definitions with ccm typedef -list.
Showing information about a type definition with ccm typedef -show.
Exporting a type definition with ccm typedef -export.
Importing a type definition with ccm typedef -import.
ccm users
The Rational Synergy CLI supports a number of new ccm users commands to replace
this functionality:
•
•
•
•
14
The ccm users
The ccm users
more users.
The ccm users
database.
The ccm users
database.
-add command adds one or more users to the database.
-modify command modifies the set of available roles for one or
-remove command removes one or more users from the
-list command lists the users who are authorized to use the
Migrating from the classic CLI to the Synergy CLI
•
•
The ccm users -show roles command shows the available roles for one or
more users.
The ccm users -export and ccm users -import commands export user data.
This allows you to externally store, manage, or import it back into the same
database or other databases.
In the Classic CLI, the ccm users command invoked a text editor so that an administrator
could add, modify, or remove users and their available roles from the database. Syntax
errors were only reported later when users attempted to start client sessions on that
database. Because a text editor was invoked, it was problematic for scripts to automate
user management.
ccm wa
In the Classic CLI, the options -no_links and -links were supported but undocumented
alternatives to the documented -relative and -not_relative options respectively.
These undocumented options could be confused with the work area options for copybased and link-based work areas. They have been retired in 7.2 and are not supported in
the Rational Synergy CLI.
The ccm wa -find command finds and optionally updates projects whose work area path
is obsolete. The most common use case is when a database is copied to a new location
such that the original and the copy might reference the same work area. The Classic CLI
supported a -scope option and -p option. Both options have been retired in the Rational
Synergy CLI. Instead, at least one project specification must be specified. Users can
perform a query and use a query selection set reference. The command syntax has been
changed slightly to make the usage clearer and consistent with other commands. The reg|-regexp option remains supported but the regular expression is treated as a Java
regular expression, not as an ACcent regular expression as used by the Classic CLI.
Differences in regular expression treatment are unlikely to cause problems for typical
usage.
The ccm wa -dbpath command finds and optionally updates projects whose work area
references an obsolete database path. The most common use case is when a database is
moved to a new location. The Classic CLI supported a -scope option and -p option. Both
options have been retired in the Rational Synergy CLI. Instead, at least one project
specification must be specified. Users can perform a query and use a query selection set
reference. The command syntax has been changed slightly to make the usage clearer and
consistent with other commands.
Migrating from the classic CLI to the Synergy CLI
15
IBM® Rational® Synergy Migrating to the Rational Synergy CLI
Date strings
Date strings on output
The Classic CLI converted date/time values to date strings using a locale-specific format.
It was not easy to change these data formats.
The Rational Synergy CLI performs all conversions from date/time values to strings on the
client using the client's locale, time zone and default date format by default. Some date
strings shown in output from commands such as ccm query and ccm attr -s
timeAttributeName may be in a different format or time zone from those shown by the
Classic CLI if the server time zone is different from the client time zone.
Scripts that parse such date strings can be fragile and non-portable. Conversion of date
strings back to date values can be problematic. If you have scripts that require a specific
date format on output, you can:
•
•
Specify an alternate date format in your [.]ccm.user.properties file using the
preference key ccm.cli.format.date. Note that this also changes the input date
format.
In format strings, use a dateformat property format specification set to the format
for a specific attribute or property. For example:
ccm properties \
-f "%{create_time[dateformat='MMMM d yyyy']}" object_spec
Date strings on input
Input date strings are used with the CLI in two contexts:
1. As a value for an attribute. For example, you might modify an attribute of type time
with the ccm attr -m attributeName -v dateString object_spec command.
Such date strings are always converted on the client machine.
For portability, scripts taking date strings from CLI output and applying them as input
values must use an explicit date format, such as the ISO 8601 date format, that
includes full time precision to seconds.
2. As part of a query expression. For example, to query for objects created since some
date you might use the command ccm query "create_time>time('dateString')".
Such query-embedded date strings are always converted on the machine where the
ACcent engine process is running.
The time() operator in query expressions operates the same when used through the
Rational Synergy CLI as was used through the Classic CLI. However, times are
evaluated on the Rational Synergy server using the locale, time, and time zone of that
server.
See Dates accepted as input to the CLI for more information.
16
Migrating from the classic CLI to the Synergy CLI
CLI output
Format
Output from the Classic CLI can be categorized as follows:
1. Intentional output that may be parsed or used by scripts
2. Intentional output designed for human consumption
3. Error and warning messages
4. Incidental output such as progress messages
The Rational Synergy CLI attempts to preserve the format of (1) to preserve compatibility.
For example, when creating a task a script might do something like:
taskId=`ccm task -create -synopsis test -release 1.0 -resolver me -q`
With the -q option, the output consists solely of the task identifier of the created task. It is
important that the Rational Synergy CLI preserves the output format since the output is
intended for use in scripts.
Another example concerns the output of ccm update. Although this output is primarily
intended for a human audience, scripts do sometimes use and parse output because it is
the only way to determine what has changed during the update members operation.
However, with the other forms of output, the Rational Synergy CLI takes the approach that
the output should be designed for maximum usability and consistency. In many cases, the
output format of commands intended for human consumption has been redesigned. The
Rational Synergy CLI often supports formatting options to allow a user or script to explicitly
specify the output format of the command.
For example, in the Classic CLI, the ccm properties command showed a formatted set
of information about one or more objects. However, apart from any custom attributes, the
information was the same regardless of whether the object was a file, project, task, folder,
and so on. If a task was shown, its output was different from that shown by the ccm task
-show information command. In the Rational Synergy CLI, for a task, the information
shown is the same regardless of whether the command is ccm properties or ccm task
-show information.
Scripts that depend on or attempt to parse output that was not intended for scripted usage
are likely to be fragile and nonportable. If you have scripts of this nature, you must either
modify them for the new formats used by the Rational Synergy CLI, or, where possible,
explicitly use the -f|-format option to use a format specified by the script.
Streams and ordering
The Classic CLI displayed error and warning messages mostly on the ccm wrapper's
stdout stream. This made it difficult for scripts to separate intentional output from error
messages.
Migrating from the classic CLI to the Synergy CLI
17
IBM® Rational® Synergy Migrating to the Rational Synergy CLI
The Rational Synergy CLI takes a more consistent approach. Intentional output continues
to be sent to the ccm wrapper's stdout stream. Error messages from the client itself are
sent to the ccm wrapper's stderr stream. However, messages from back-end sessions
running on the server (which may include progress messages, warnings and errors) are
sent to the ccm wrapper's stdout stream since the client has no means of knowing which
strings represent error messages. Error reporting uses a format that is consistent with the
Rational Synergy GUI.
Because the Rational Synergy CLI uses different streams for error reporting and normal
output, it's possible that the messages might appear in a different order than seen from the
Classic CLI. Scripts that redirect stderr and stdout together and process the combined
output, and that depend on the ordering of error messages relative to normal output, are
likely to be fragile. Such scripts should be updated to avoid dependence of ordering of
normal output versus error messages.
For progress messages, the Classic CLI often output messages throughout an operation.
With the Rational Synergy CLI, progress reporting is managed in such a way as to avoid
too many frequent progress reports. If an operation completes quickly, progress
messages might be suppressed altogether for that operation. Scripts that depend on the
ordering of progress messages relative to normal output are likely to be fragile and may
need updating.
Sorting
Some CLI commands perform sorting of their output. For example, by default, the ccm
query command sorts its output. In the Classic CLI, the order of sorting was based on an
alphanumeric sort of the entire string in each line of output. When the Rational Synergy
CLI performs sorting, by default, it performs an ascending sort based on the real values in
any implicitly or explicitly specified format string. String sorting is performed using the
correct collation sequence for the client locale, which may be different from the sorting
based on ascii code ordering used in the Classic CLI. Hence the ordering of such sorted
output may be different using the Rational Synergy CLI than with the Classic CLI. This is
unlikely to affect scripts but is mentioned here for completeness.
End of line conventions
The Classic CLI used UNIX-style end of line formatting on all platforms. This meant that
on Windows, output did not conform to Windows end of line conventions. The Rational
Synergy CLI uses the appropriate end of line format for the client platform. This means
that on UNIX, each line is terminated by a newline (line feed) character, and on Windows,
by a carriage return and line feed character sequence.
18
Migrating from the classic CLI to the Synergy CLI
Exit status codes
For most commands on the Classic CLI, an exit status code of zero meant success and
non-zero meant a failure of some kind. For maximum portability, scripts should only
differentiate between zero and non-zero outcomes. If you have scripts written in this way,
they should continue to work with the Rational Synergy CLI.
Settings
The Classic CLI used options and preferences from a number of places:
•
Your personal ccm.ini (Windows) or .ccm.ini (UNIX) file.
•
The ccm.ini system preferences file from your Rational Synergy installation area.
•
Personal preferences defined in the database for a specific user.
•
System preferences defined in the database for all users.
The Rational Synergy CLI does not use ccm.ini files. Instead, it uses a personal
ccm.user.properties (Windows) or .ccm.user.properties (UNIX) file, and the
ccm.properties from the Rational Synergy client installation area. If you have scripts that
depend on specific preferences that were previously defined in a ccm.ini file, you must
apply those preferences to the corresponding entries in either your personal property file
or the installation property file. See "IBM® Rational® Synergy Default Settings"for more
information.
Database administration or maintenance scripts
With the Classic CLI, scripts that needed exclusive access to databases for administration
or maintenance might have done something like:
ccmdb shutdown databasePath
ccmdb unprotect databasePath
export CCM_ADDR=‘ccm start -d databasepath -m -q -nogui‘
ccmdb protect databasePath
...admin operations...
ccm stop
ccmdb unprotect databasePath
This technique does not work with the Rational Synergy CLI because the ccmdb protect
command prevents any back-end sessions on the server from being used or started.
The Rational Synergy CLI supports a new single user admin mode. A single user admin
mode session is started by specifying the -single|-single_user reason option to the
ccm start command. Only users with administrator privileges are allowed to start in
single user admin mode. The reason option value is used to specify a reason for the
exclusive access so that other users can be informed why they cannot use the database.
Migrating from the classic CLI to the Synergy CLI
19
IBM® Rational® Synergy Migrating to the Rational Synergy CLI
Once a database is in single user admin mode, other users cannot start new client
sessions using that database. Any existing clients that are using that database remain
connected, but are not allowed to perform any database operations until the single user
admin mode is terminated.
If you have scripts that require exclusive database access for administration or
maintenance reasons, they must be updated to use the new single user admin mode. For
example:
export CCM_ADDR=‘ccm start -d databasepath -m -q \
-single "General maintenance, will be available again at 14:00."‘
...admin operations...
ccm stop
Taking advantage of new features
The Rational Synergy CLI provides significantly more powerful and consistent ways of
performing operations.
When specifying objects in a Rational Synergy database you can:
•
•
•
use ":" instead of the version delimiter. This leads to more robust scripts
especially when the allow delimiter in name feature is enabled.
use the file contents form to process a list of objects for most types of database
entity specifications where the command accepts multiple objects.
explicitly specify a context project for new forms of specifications such as four part
objectname form, selection set reference form and cvid reference form.
Many more commands accept multiple objects as arguments. In some cases, scripts have
fewer commands to execute and can execute faster.
The Rational Synergy CLI provides a considerably improved ability to control the format of
command output:
•
•
•
20
It provides consistent and controllable sorting and grouping. Sorting is based on
the real underlying data values, not their string representation. For example, dates
are sorted in correct date order. Sorting of strings is based on the correct collation
sequence for the client locale.
It supports control over the formatting of attribute and property values, especially
Boolean and date values. This includes truncation, character wrapping and word
wrapping.
Many more commands accept the -f|-format option so scripts can specify an
output format that might be more convenient or efficient to process.
Migrating from the classic CLI to the Synergy CLI
For example, you can now control the date format of specific properties that represent
dates:
ccm query –t task "resolver='fred' and \
completion_date>time('-60:0:0:0')" \
–f "%displayname %{completion_date[dateformat='MMMM d yyyy']}"
1) J#12254 August 11 2008
2) J#12255 August 11 2008
3) J#12257 August 11 2008
4) J#12327 September 10 2008
5) J#12330 September 12 2008
6) J#12340 September 15 2008
In the above example, the output is sorted in ascending order of the underlying date
values and not the string representation of the dates.
String data that contains integer strings are sorted using the integer value:
ccm query ... -format "%displayname %resolver %release"
1) 101 joe 1.0
2) 102 fred 1.0
3) 1000 fred 1.1
4) 1003 joe 2.0
The Rational Synergy CLI allows you to explicitly specify sorting order as ascending or
descending, and to specify sorting independently from the data being shown:
ccm query ... -format "%displayname %resolver %release" \
–sortby +release+resolver
1) 102 fred 1.0
2) 101 joe 1.0
3) 1000 fred 1.1
4) 1003 joe 2.0
ccm query … -format "%displayname %resolver" –sortby +release+resolver
1) 102 fred
2) 101 joe
3) 1000 fred
4) 1003 joe
The Rational Synergy CLI also supports grouping using a new -groupby
groupby_format option. This sorts the data and uses the groupby_format as a grouping
header between items that have the same values for the properties in the specified format:
ccm query … -format "%displayname %task_synopsis" \
–groupby "Resolver: %resolver"
Resolver: fred
1) 101 Fix defect M#12345
2) 1000 Implement sorting
Resolver: joe
3) 102 Implement date formatting
4) 1003 Extend grouping feature
Migrating from the classic CLI to the Synergy CLI
21
IBM® Rational® Synergy Migrating to the Rational Synergy CLI
A new -ch|-column_header option shows column headers:
ccm query –ch –f "%displayname %task_synopsis" ...
Displayname Task_synopsis
1) 100
Fix defect M#1234
2) 102
Implement sorting
Each property specified in a format string can specify various property formatting controls.
These examples show truncation, character wrapping and word wrapping:
ccm query ... \
-format “%displayname %{task_synopsis[truncate=20]} %release”
1) 101 Fix defect Mar#12345 1.0
2) 102 Implement date fo... 1.0
3) 1000 Implement sorting
1.1
4) 1003 Extend grouping f... 2.0
ccm query ... \
-format “%displayname %{task_synopsis[wrap=20]} %release”
1) 101 Fix defect Mar#12345 1.0
2) 102 Implement date forma 1.0
tting
3) 1000 Implement sorting
1.1
4) 1003 Extend grouping feat 2.0
ure
ccm query ... \
-format “%displayname %{task_synopsis[wordwrap=20]} %release”
1) 101 Fix defect Mar#12345 1.0
2) 102 Implement date
1.0
formatting
3) 1000 Implement sorting
1.1
4) 1003 Extend grouping
2.0
feature
The Rational Synergy CLI provides CLI support for some task operations that were
previously supported only in the Rational Synergy GUI. You can explicitly check for
parallels on a task using ccm task -show parallels. This check can also be performed
when completing a task with ccm task -complete. Successful task completion can be
made dependent on the absence of such detected parallels.
Scripts to find the context project for a work area path can now use the new ccm project
command. Previously scripts would have to use the ccm status command and parse the
output to extract that information.
Scripts to find the relative path of a file, directory or subproject within a project may have
used the ccm finduse command, then filtered and parsed the output to extract the
required information. Such scripts are potentially fragile because the output of ccm
finduse was intended for human consumption and not machine parsing. Also, since ccm
finduse found the details of all the projects using the object, this was not a very efficient
way to determine the relative path within a single specified project. Such scripts can
benefit from the new ccm show -relative_path command in the Rational Synergy CLI.
22
Migrating from the classic CLI to the Synergy CLI
The command shows the relative path and avoids the need for parsing of the output. Its
use makes such scripts more robust and efficient.
The Rational Synergy CLI includes an online help facility that allows you to get the usage
summary for one or more commands using a new -help option. For example:
Table 3.
Command
Description
ccm task -help
Show the usage for all of the ccm task
commands.
ccm task -create -help
Shows the usage for the ccm task
-help command.
If you are executing Rational Synergy CLI commands interactively as a prelude to
including them in a script, you can see a history of CLI commands entered using the new
ccm cmdhistory command. This may help in the development of the script.
The Rational Synergy CLI supports the ccm select command that allows you to see,
modify, save, and restore query selection sets. Similar functionality was available for the
Classic CLI, but was not installed as a standard product feature.
The ccm set command supports a number of new read-only settings that allow scripts to
get information such as the known platform names, task resolvers, task subsystems,
default encoding, and locale. Scripts may have been unable to get this information before
and had to hard code assumptions. Such scripts can be made more robust if they use the
new read-only settings.
The new Rational Synergy CLI command ccm get_debug_logs copies server-side logs to
the client. This is useful when sending information to Rational Customer Support.
You do not have to change your scripts to use these features for compatibility reasons.
However, it could be worth reviewing your scripts to see if they can use any of these new
features to make them simpler or more efficient.
Migrating from the classic CLI to the Synergy CLI
23
Notices
Notices
© Copyright 2000, 2011
U.S. Government Users Restricted Rights - Use, duplication, or disclosure restricted by
GSA ADP Schedule Contract with IBM Corp.
This information was developed for products and services offered in the U.S.A. IBM® may
not offer the products, services, or features discussed in this document in other countries.
Consult your local IBM representative for information on the products and services
currently available in your area. Any reference to an IBM product, program, or service is
not intended to state or imply that only that IBM product, program, or service may be used.
Any functionally equivalent product, program, or service that does not infringe any IBM
intellectual property right may be used instead. However, it is the user's responsibility to
evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in
this document. The furnishing of this document does not grant you any license to these
patents. You can send written license inquiries to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte character set (DBCS) information, contact the
IBM Intellectual Property Department in your country or send written inquiries to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106-0032, Japan
The following paragraph does not apply to the United Kingdom or any other country
where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS
MACHINES CORPORATION PROVIDES THIS PUBLICATION “AS IS” WITHOUT
WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not
allow disclaimer of express or implied warranties in certain transactions. Therefore, this
statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are
periodically made to the information herein; these changes will be incorporated in new
24
Migrating from the classic CLI to the Synergy CLI
editions of the publication. IBM may make improvements and/or changes in the product(s)
and/or the program(s) described in this publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only
and do not in any manner serve as an endorsement of those Web sites. The materials at
those Web sites are not part of the materials for this IBM product and use of those Web
sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes
appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of
enabling: (i) the exchange of information between independently created programs and
other programs (including this one) and (ii) the mutual use of the information which has
been exchanged, should contact:
Intellectual Property Dept. for Rational® Software
IBM Corporation
5 Technology Park Drive
Westford Technology Park
Westford, Massachusetts 01886
U.S.A.
Such information may be available, subject to appropriate terms and conditions, including
in some cases, payment of a fee.
The licensed program described in this document and all licensed material available for it
are provided by IBM under terms of the IBM Customer Agreement, IBM International
Program License Agreement or any equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment.
Therefore, the results obtained in other operating environments may vary significantly.
Some measurements may have been made on development-level systems and there is
no guarantee that these measurements will be the same on generally available systems.
Furthermore, some measurements may have been estimated through extrapolation.
Actual results may vary. Users of this document should verify the applicable data for their
specific environment.
Information concerning non-IBM products was obtained from the suppliers of those
products, their published announcements or other publicly available sources. IBM has not
tested those products and cannot confirm the accuracy of performance, compatibility or
any other claims related to non-IBM products. Questions on the capabilities of non-IBM
products should be addressed to the suppliers of those products.
This information contains examples of data and reports used in daily business operations.
To illustrate them as completely as possible, the examples include the names of
individuals, companies, brands, and products. All of these names are fictitious and any
similarity to the names and addresses used by an actual business enterprise is entirely
coincidental.
Migrating from the classic CLI to the Synergy CLI
25
Notices
If you are viewing this information softcopy, the photographs and color illustrations may
not appear.
26
Migrating from the classic CLI to the Synergy CLI
Copyright license
This information contains sample application programs in source language, which
illustrate programming techniques on various operating platforms. You may copy, modify,
and distribute these sample programs in any form without payment to IBM, for the
purposes of developing, using, marketing or distributing application programs conforming
to the application programming interface for the operating platform for which the sample
programs are written. These examples have not been thoroughly tested under all
conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function
of these programs.
Each copy or any portion of these sample programs or any derivative work, must include a
copyright notice as follows:
© (your company name) (year). Portions of this code are derived from IBM Corp. (Sample
Programs.) © Copyright IBM Corp. 1992 - 2011.
Migrating from the classic CLI to the Synergy CLI
27
Notices
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International
Business Machines Corp., registered in many jurisdictions worldwide. Other product and
service names might be trademarks of IBM or other companies. A current list of IBM
trademarks is available on the Web at www.ibm.com/legal/copytrade.html.
Microsoft, Windows, Windows NT, Windows XP, Windows Vista and the Windows logo are
trademarks of Microsoft Corporation in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Other company, product or service names may be trademarks or service marks of others.
28
Migrating from the classic CLI to the Synergy CLI
Migrating from the classic CLI to the Synergy CLI
29