Question & Answer
Question
Answer
The ccm query command can be used to retrieve a variety of information about objects in a database. This document gives examples of some of the commonly used query commands.
Details
The ccm query command is used extensively to retrieve information about objects in a Synergy database that meet particular criteria. In its simpler form, it can be used to retrieve objects that have an attribute (e.g. name) that match a certain value. In its more complicated format, it can be used to retrieve all objects that are members of one project but not another or it can retrieve all objects that are related to a particular problem or task.
Note: This document is not intended to serve as a reference for the ccm query command. For a list of all options that are supported for ccm query, you should refer to the Online Help. This document is also not intended to provide a comprehensive list of all the various ccm query commands that can be executed. Instead, this document was written to provide a representative list of sample queries that may be useful.
General Information
Many of the query examples listed below are simple single operation queries. You can refine queries further by combining multiple single operation queries using the ‘and’ and ‘or’ operators. For example, if you would like to query for all members of either project proj1 or proj2 that have an attribute called ‘abc’ matching ‘*aaa*’ and is not a product, you can execute the following query:
% ccm query “(is_member_of(‘proj1-version’) or is_member_of(‘proj2-version’)) and abc match ‘*aaa*’ and not is_product=TRUE”
Many of the examples below also contain object_name as part of the query. The object_name should be replaced with the four-part-name of the desired object. The format of the four-part-name is name-version:type:instance . You can retrieve objects in object_name format using ccm query as follows:
% ccm query “query string”–f “%objectname”
Also, please note that all of the examples below assume that the version delimiter is a “-“ (dash/hyphen). If your version delimiter is something other than “-“, you will need to replace the examples that make use of the “-“ with your version delimiter.
General Queries
- How do you query for all objects that have an attribute called “abc”?
% ccm query “has_attr(‘abc’)” - How do you query for all objects which have an attribute called ‘abc’ with the exact value ‘test’?
% ccm query “abc=’test’” - How do you query for all objects which have an attribute called ‘abc’ that has a value with the string ‘test’ in it?
% ccm query “abc match ‘*test*’”
Please note that the above query will only find objects if the string ‘test’ is contained within the first 64 characters of the attribute ‘abc’. Any character values after 64 characters will be ignored in such a string search. This 64 character limit is fixed and cannot be changed. - How do you query for all members of a project?
% ccm query “is_member_of(‘projname-version’)” - How do you query for all members of a project including all members of any subprojects?
% ccm query “recursive_is_member_of(‘projname-version’,’none’)” - How do you query for all the members of a directory within a project?
% ccm query “is_child_of(‘object_name’,’projname-version’)”
In the above example, a directory object can be in more than one project. Also, in each project, the members of the directory may be different. As a result, both the four-part-name of the directory object ( ‘object_name’ ) as well as the project name ( ‘projname-version’ ) must be entered. - How do you query for all working objects in a project?
% ccm query "is_member_of(`projname-version') and status='working'" - How do you query for all objects with a name that starts with "aaa"?
% ccm query "name match 'aaa*'" - How do you query for all projects, which contain a particular object?
% ccm query "has_member('object_name')"
Alternatively, you can use the "ccm finduse" command to retrieve the same information. - How do you query for all objects in a project that are products?
% ccm query "is_member_of('projname-version') and is_product=TRUE" - How do you query for all objects that have a release value set to ‘2.2’?
% ccm query "release='2.2'" - How do you query for the directory object in a project to which a particular object belongs?
% ccm query "has_child('object_name','projname-version')" - How do you query for all objects in a project that do not have any successors?
% ccm query “is_member_of(‘projname-version’) and is_hist_leaf()” - How do you query for all objects that were initially migrated into project "aaa"?
% ccm query "project='aaa'"
Please note that the project attribute is created and set to the name of the project in which the object is created. It does not necessarily reflect the project that the object is currently contained in. - How do you query for the predecessors of an object?
% ccm query “is_predecessor_of(‘object_name’)” - How do you query for the successors of an object?
% ccm query “has_predecessor(‘object_name’)” - How do you get the cvid of object aaa.c-1:csrc:2?
% ccm query -n aaa.c -v 1 -t csrc -i 2 -f "%cvid" - How do you query for all objects that are members of project "aaa-1" and not members of project "aaa-2"?
% ccm query "is_member_of('aaa-1') and not is_member_of('aaa-2')" - How do you query for all unbound objects in a database?
% ccm query "not is_bound() and type!='project' and has_attr('source')"
Problem(CR)/Task/Folder Queries
Note: In IBM Rational Change we refer to a 'Change Request' or a CR. In the underlying Synergy database these are defined as 'problem' objects.
- How do you query for the task that is associated with an object?
% ccm query –type task "has_associated_object('object_name')" - How do you query for all objects associated with a task (e.g. task20)?
% ccm query "is_associated_object_of('task20-1:task:probtrac')" - How do you query for all tasks which have no associated objects?
In CM 6.3 and later:
% ccm query -t task "has_no_associated_cv()"
In CM 6.2 and earlier:
% ccm query -t task "not has_associated_cv(cvtype!='task')"
- How do you query for all tasks associated with a problem(CR) (e.g. problem20)?
% ccm query –type task "is_associated_task_of('problem20-1:problem:probtrac')" - How do you query for all the problems(CRs) associated with a task (e.g. task20)?
% ccm query –type problem "has_associated_task('task20-1:task:probtrac')" - How do you query for the folder object if you know the description?
% ccm query –type folder “description match ‘*text of description*’”
Time-Based Queries
The below examples all make use of the “time(‘time_string’)” format in the queries. The value ‘time_string’ consists of a date in a UNIX-compatible time format. The date may be specified as an absolute date and/or time or as a time relative to midnight at the start of the current day. A relative time is specified in the following form:
+/-days:hours:minutes:seconds
For example, if you enter ‘-1:12:0:0’ as a relative time, the time will be one day and 12 hours before midnight at the start of the current day. You can also use absolute date values. Examples of absolute values include ‘Dec 10’ , ‘Dec 10, 1997’ , and ‘12/10/97’ .
- How do you query for all objects that were created in the last 10 days?
% ccm query "create_time > time('-10:0:0:0')" - How do you query for all objects that were created in the last 4 hours and 30 minutes (from midnight at the start of the current day?
% ccm query "create_time > time('-0:4:30:0')" - How do you query for all objects in a project that were created after December 10?
% ccm query "is_member_of('projname-version') and create_time > time('Dec 10, 1997')" - How do you query for all objects that have been modified after December 10?
% ccm query "modify_time > time('Dec 10, 1997')"
Please note that the above query will only return objects in which attributes other than the source have been modified since the specified date. Therefore, if an object has been checked in later than Dec 10, meaning the status attribute has been modified, that object will be returned in the query. However, if only the source of an object has been modified, that object will not be returned by the query. - How do you query for all objects that were created since December 10, 1997 at 10:00 AM?
% ccm query “create_time > time(‘12/10/97 10:00’)”
Nested Queries
A nested query is a query within a query. The inner query is performed first, the outer query is based on the results of the inner query. Nested queries were first introduced in CM 5.x. See the Online Help for more examples.
- How do you query for all objects which have no task associated with them?
In CM 6.3 and later:
% ccm query "has_attr('source') and is_no_associated_cv()"
In CM 6.2 and earlier:
% ccm query “has_attr(‘source’) and not is_associated_object_of(cvtype = ‘task’)” - How do you query for all CRs which have a task assigned to a particular user:
% ccm query -t problem "(has_associated_task(cvtype='task' and status ='task_assigned' and resolver='user_name'))"
In the above example substitute user_name with the actual user name.
Formatting Query Results
The ccm query command can also be used as a pseudo-reporting tool to report desired information on all objects returned by a query. The list of information returned for each object can be specified using the “-f” option to the query command. For example, if you wish to display the following information on each object:
name-version owner status release platform
Here is the format of the query command:
% ccm query “query string”–f “%name-%version %owner %status %release %platform”
Detailed below is a commonly used list of keywords and attributes that are used as arguments to the –f option:
%name name of the object
%version version of the object
%instance instance of the object
%type type of the object
%owner owner of the object
%status status of the object
%release value of the release attribute
%platform value of the platform attribute
%project project in which the object was created
%create_time time the object was created
%modify_time time the object was last modified (not including the source attribute)
%cvid cvid of the object
%objectname the four-part-name of the object in the format name-version:type:instance
%wa_path the workarea path for project objects
%<attr_name> the value of the attribute <attr_name>
Here are some additional examples for formatting output:
- I would like to see the four-part-name and cvid for each queried object.
% ccm query “query string”–f “%objectname %cvid” - I would like to see the name, version, owner, and status of each object queried.
% ccm query “query string”–f “%name %version %owner %status” - I would like to see the name-version, type, instance, and modify time for each object queried.
% ccm query “query string”–f “%name-%version %type %instance %modify_time”
The Synergy Web Mode CLI released with Synergy 7.0 provides much more extensive formatting options than the Classic CLI for the output from query and similar commands, and is capable of producing nicely formatted reports. Here are some of the formatting options available.
- Strings can be formatted using either Java MessageFormat or printf styles.
- You can use escape sequences to embed special characters in the output, such as newline (\n), tab (\t), and backslash (\\).
- You can format dates using the –format option of the query command, and dates are sorted by value rather than alphanumerically. For example:
> ccm query ... -f "%{completion_date[dateformat=\"H.mm a 'on' EEEE, MMMM dd yy\"]}"
1) 8.14 AM on Friday, September 12 08
2) 21.56 PM on Sunday, September 14 08
3) 18.22 PM on Monday, September 15 08
4) 14.24 PM on Tuesday, September 16 08
5) 15.08 PM on Wednesday, September 17 08 - String fields such as task numbers and release numbers sort numerically, rather than alphanumerically; for example, when sorting by task number, task 8 no longer appears after task 12.
- You can sort in ascending or descending order; you can sort by multiple fields; and you can sort by fields not shown in the output. The following example shows sorting by multiple fields.
> 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 - A new –groupby option enables you to group query output by values such as the resolver.
> 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 - String or text fields can be truncated to a certain column length, or wrapped to fit within that field length.
See the online help for more information on formatting.
Related Information
Was this topic helpful?
Document Information
Modified date:
01 September 2022
UID
swg21325217