Keywords in IBM Rational Synergy
Keywords in IBM Rational Synergy
Keywords are used to automatically embed an IBM Rational Synergy attribute or a string in a file. Attributes commonly used include: owner, create time, etc.
Synergy keywords are placed in the source file template of a particular object type. This document describes how to enable keyword expansion at check in, the default Synergy keywords, how to add new keywords to the list of available keywords, how to embed keywords in products of a build, and miscellaneous keyword usage issues.
Synergy keywords are expanded on checking out an object or on creating a new object version. When objects are migrated into Synergy or when the create command is used to create an object which already exists in the work area, Synergy keywords are not expanded. Synergy keywords are also not expanded when a new object is checked out as the result of a reconcile operation. If you edit a static object off-line and then reconcile the project to check out a new object version, Synergy keywords in the object will not be expanded.
As of Synergy 6.2sp1, keywords can also be expanded when an object is checked in (please see the section "Keyword Replacement on Check in" below). There are two different keyword forms that can be used in an objects source, the %keyword% form and the %keyword:<space>% form. The %keyword% form permanently replaces the keyword with the attribute value when you initially create the object. The %keyword:<space>% form is appended with the attribute value each time you create or check out/in the object. Also the %keyword% form is completely replaced in the object when expanded, but the %keyword:<space>% form in only partially replaced; the keyword itself still remains in the object.
Source file template contains the following two keywords:
%name% %created_by: %
After checkout/in the keywords are replaced as:
one.c %created_by: cweber%
Keyword Replacement on Check in
As of Synergy 6.2sp1, keyword replacement is also possible at the time of check in. To enable this, an attribute must be created on the ascii cvtype as follows:
ccm set role ccm_admin
ccm query -n ascii -t cvtype
ccm attr -c expand_on_checkin -t boolean -v TRUE @1
Default Synergy Keywords
The Synergy keywords are stored in the "keywords" attribute of an object type in the database. The "keywords" attribute is a text attribute which has one line for each keyword in the following format.
<keyword name><white space><attribute name or value>
These are the default Synergy keywords defined in the keywords attribute:
|Keyword||Replace by attribute value||Example|
|created_by||creator of object||jsmith|
|derived_by||owner of object||cweber|
|cvtype||name of object type||csrc|
|date_created||creation date||Mon Aug 24 12:05:11 1998|
|full_name||four-part object name||1/csrc/foo.c/2.1|
|name||name of the object||foo.c|
|state||state of the object||working|
|instance||instance of the object||1|
|version||version of the object||2.1|
|display_name||name of the object("." is replaced by "_")||foo_c|
|full_filespec||four-part object spec||foo.c-2.1:csrc:1|
Adding new keywords to the list of available keywords
New keywords can be added to the list of available keywords.
The following items are eligible as new keywords:
- For expand on check-out/create, keywords can ONLY be Single Line attributes such as type string or time attributes. NO text or multi-line attributes will work.
- For expand at check-in, keywords can also be Text or Multi-Line attributes (as of 6.2sp1) as well as any type described above.
In any case, you CANNOT define a keyword based on a Synergy relation, such as a related task, etc. they must be based on attributes. This statement was still valid when IBM Rational Synergy 7.1 was released.
Any user with the ccm_admin role can modify the list of available keywords. Below are the steps to add the keyword 'release' to the list of available keywords.
1. Synergy session running with your role set to ccm_admin.
2. Query for the object type in the database.
ccm query -t attype -n ascii
3. Use the ccm attr command to modify the keywords attribute of the ascii attype object returned from the query.
ccm attr -m keywords @
4. Add a line for the new keyword.
5. Modify the source file template of the object type you want to contain the new release keyword:
- From the Admin menu select Type Definition.
- Select Browse Types from the Type Definition dialog to select the type.
- From the Type menu select Edit Source File Template.
- Add the keyword as described in the Command Reference manual.
- Save the changes and update the type.
6. Restart your Synergy session for the changes to take effect
Embedding Synergy keywords in a product of a build
Synergy keywords are most commonly used in the header section of ascii based objects, but you can also embed Synergy keywords in your compiled products. There are two ways to embed Synergy keywords in a product of a build, both involve adding keywords to the source files of a build. First way is use the #ident directive and second way is use the @(#) notation in a static char definition. If your compiler supports #ident, then add lines such as the following to your source files:
#ident "%full_filespec: %"
#ident "%created_by: %"
#ident "%date_created: %"
Then use the command mcs -p to display the keyword information.
If the #ident directive is not supported, then you can use a static string syntax in your source files:
static char *_ident = "@(#) %full_filespec: %";
Then use the 'what' command to display the keyword information.
Miscellaneous Keyword Issues
Keyword values might not always match the actual attribute value on the object. For example, you check out an object with the 'version' keyword expanded in the object, you then change the version string sometime prior to checking in the object. In this case the expanded 'version' keyword in the object will not match the actual version of the object.
Certain keywords will only be expanded on check out of an object, not when a new object is created. Release and platform are two attributes that if used as keywords will only be expanded when a object version is checked out. Keyword expansion on check in also does not work for these attributes.
The %state% keyword is not very useful since the only value it will be expanded to is working. Keyword expansion on check in does not work for this keyword. By default, as of Synergy versions 220.127.116.11 and 7.2, when you check out a file Synergy scans the first 20480 characters of the file and replaces keywords with their value. This default setting works well if you have the keywords in the header area of the file. If the keywords are spread throughout your file, you will need to change the number of characters scanned so that the keyword expansion can be done throughout the file.
The range_for_keyword_expand variable determines the number of characters to be scanned. This will have an effect on the time it takes to check out a new version of this type. Set this variable in either the system or personal ccm.ini file or in the database's ccminit file.
Sample ccm.ini entry:
range_for_keyword_expand = 5000
Sample /lib/ccminit entry (For Synergy 7.1 and newer, the ccminit file can be found in /etc/ccminit):
set range_for_keyword_expand 5000
More support for:
Software version: 6.3, 6.4, 6.5a, 6.5, 6.6a, 7.0, 7.1a, 7.1, 18.104.22.168, 22.214.171.124
Operating system(s): AIX, HP-UX, Linux, Solaris, Windows
Reference #: 1325173
Modified date: 11 March 2011