ClearCase Environment – How do I
Soft - is your software and documentation Asset - is something that must be protected Management - is what we do Enterprise - is the capability
Computing - is the power Services - are what we provide
ClearCase Environment – “How do I”:(Last update 12-Dec-12) Anti-virus software and ClearCase – recommendations, etc... Server processes – lockmgr (redundancy in v7) & new vob_almd_params file, stopping and starting (windows & remotely), etc... ClearCase Registry – commands requiring the registry password, etc... Multi Version File System (MVFS) layer – understanding, debugging, flushing the cache, etc... LDAP and Active Directory services – issues, etc... Shell access – understanding, etc... Network Attached Storage devices - root permissions and, chown_pool & chown_container, etc... Storage – default location for Views on windows, etc... .NET issues – understanding etc,... Regions – Tags, etc... Email – configuring, etc... Problems and Issues - “The Evil twins” , eclipsed files, protectvob and, etc... Installation and patching of ClearCase - including silent install, patching, uninstalling, feature differences ClearCase and ClearCase LT etc... Firewalls – ClearCase and etc... Upgrading and compatibility issues between major versions, preserving installs, etc... Plugins & integrations for ClearCase - Eclipse, ClearCase Automation Libraty (CAL), Source Code Control provider (changing), etc... ClearCase context menus – configuring etc... Temporary files – created by and used by ClearCase, etc... Virtualisation – support policy Interop environment between Windows and UNIX – usernames & groups, VOB & View creation in, SaMBa configuration, issues, CLEARCASE_GROUPS, etc... Licensing – commands that don’t take a license, etc... Permissions executables and 770 directories, Support policies – Linux, DFS, Alteris, etc Caching – ClearCase cache directory, etc... ClearCase environment – firewalls, . (dot) files, temporary files, services, magic files, ASP .net framework, name conventions, clearmenuadmin, cache files, encryption software,etc... ClearCase scheduler – using without NIS, groups and, etc... Anti-virus software and ClearCase – recommendations, etc... Page 1 of 341
ClearCase Environment – How do I
Table of contents
CLEARCASE ENVIRONMENT – “HOW DO I”:(LAST UPDATE 12-DEC-12) ...... 1
TABLE OF CONTENTS ...... 2 ANTI-VIRUS SOFTWARE ...... 12 1. How do I – understand the support Policy for Anti-Virus software and ClearCase ...... 12 RELATED INFORMATION ...... 13 2. How do I – understand the RPC: Remote system error - [WINSOCK] No buffer space available issue ...... 13 SERVER PROCESSES ...... 14 3. How do I – understand about the albd_rt_params.conf file ...... 14 4. How do I – understand about Rational ClearCase server processes ...... 15 MultiVersion File System MVFS (MultiVersion File System) is not a server process, it loads a kernel driver that presents a file system to the user through a standard interface; see technote 1230196...... 16 5. How do I – understand the Lock Manager process post and pre ClearCase v7 16 6. How do I - monitor the Lock Manager status on Windows ...... 18 7. How do I - Monitor the Lock Manager status on UNIX and Linux ...... 20 8. How do I - diagnosing Lock Manager registry settings on Windows ...... 20 9. How do I – understand about the db.conf configuration file ...... 21 10. How do I – understand about deadman lock time-outs ...... 21 11. How do I – resolve a this client was launched with different lockmgr parameters than those now in the almd file issue ...... 22 12. How do I - start and stop ClearCase from the Windows command line ...... 22 13. How do I - starting and stopping ClearCase services remotely ...... 23 14. How do I – understand the unable to contact albd_server issue ...... 23 15. How do I – understand how ALBD RPC calls can cause significant performance degradation under very high load ...... 23 16. How do I – understand why Rational ClearCase operations hang with the error message of "timed out trying to communicate with ClearCase remote server. " 23 SYMPTOM ...... 23 CAUSE ...... 24 ENVIRONMENT ...... 24 RESOLVING THE PROBLEM ...... 25 17. How do I – understand about RPC services and ClearCase on UNIX and Linux 25 CLEARCASE REGISTRY ...... 26 18. How do I - manually restoring the primary registry server files from backup 26 19. How do I – get a non-root UNIX account to run rgy_passwd ...... 28 20. How do I – understand the ClearCase commands that require a ClearCase registry password ...... 28 21. How do I – deal with the ClearCase 7.0.1 registry files on UNIX and Linux hosts moving from 'rgy' directory to the 'config' directory...... 29 22. How do I - set or change the ClearCase registry password ...... 30 23. How do I – understand how a non-root UNIX account can run rgy_passwd... 30 24. How do I – understand the computer is not a valid registry server problem . 31 25. How do I - Improve lsview -host and lsvob -host performance ...... 32 MVFS ...... 33 26. How do I – understand why the ClearCase start script prevents MVFS from being unloaded from kernel under some conditions ...... 33 Page 2 of 341
ClearCase Environment – How do I 27. How do I – understand about the MVFS cache values in ClearCase Control Panel and cleartool getcache ...... 34 28. How do I – why the iInstallation of ClearCase 7.1 fails during post-install phase and logs MVFS errors: Trouble mounting the viewroot "/view" ...... 36 29. How do I – understand why you are unable to load MVFS on UNIX or Linux after install ...... 37 30. How do I – understand why a ClearCase installation on Linux x86 fails because MVFS cannot be loaded...... 37 31. How do I – understand about the MultiVersion File System (MVFS) ...... 38 32. How do I – run MVFS Debugging ...... 38 33. How do I – understand about cleartext lookup and flushing the mvfscache .. 39 34. How do I – understand the MVFS Scaling Factor on Windows ...... 40 35. How do I – Understand the invalid MSDOS Function error on Windows copying a file from a UNIX or Linux VOB ...... 42 36. How do I - install or uninstall the MVFS on Windows ...... 43 37. How do I – known the limitations for the MVFS on Microsoft Windows ...... 44 38. How do I - rebuild the mvfs module for use with ClearCase 7.0.x ...... 44 39. How do I – understand why Rebuilding of MVFS modules with kernel symbol exports fails but installation of ClearCase is successful ...... 44 40. How do I – configure the MVFS settings for use with eclipse based Rational products and dynamic views ...... 45 LDAP & ACTIVE DIRECTORY...... 45 41. How do I – understand the support Policy for LDAP and ClearCase ...... 45 42. How do I – use Active Directory Universal Groups and ClearCase ...... 46 43. How do I – understand about Windows Active Directory Distribution and Security groups ...... 46 44. How do I – understand why ClearCase fails to use LDAP authentication on 64- bit Linux ...... 47 SHELL ACCESS & EMULATIONS ...... 48 45. How do I – understand why SSH connection hangs when attempting to exit after starting ClearCase ...... 48 46. How do I – understand the support Policy for Shell Access and ClearCase ..... 48 47. How do I – understand the support Policy for Xwindows xterm emulators and ClearCase ...... 48 NETWORK ATTACHED STORAGE (NAS) DEVICES ...... 49 48. How do I – understand about Root permissions on Network Attached Storage and ClearCase ...... 49 49. How do I – understand the chown_pool and chown_container support on Linux 50 50. How do I - run cleartool protectvob for VOBs stored on NAS ...... 51 STORAGE...... 52 51. How do I – understand the storage device support for ClearCase ...... 52 52. How do I – understand the ClearCase default storage locations for views on Windows ...... 52 53. How do I – understand about ClearCase Server Storage locations ...... 53 .NET ISSUES ...... 54 54. How do I – understand the Visual Studio.NET metadata files and the function they serve when integrated with ClearCase ...... 54 55. How do I – set up and use the Rational Modelling Extension for Microsoft.NET - Rational ClearCase Integration ...... 55 56. How do I – understand about Microsoft Visual Studio.NET bindings and ClearCase ...... 56 57. How do I - add existing ASP.NET 2005 Framework 2.x Web Applications to source control with Rational ClearCase ...... 58
Page 3 of 341
ClearCase Environment – How do I 58. How do I – understand the procedure to integrate ClearCase and VS.NET 2005 and 2003...... 63 59. How do I – understand about Security settings with Microsoft .NET 2.0 Framework projects under ClearCase control ...... 65 60. How do I - create new ASP.NET Framework 1.x Web Applications while under source control with Rational ClearCase ...... 68 61. How do I - add existing Microsoft ASP.NET Framework 1.x Web Applications to source control with Rational ClearCase ...... 71 62. How do I – understand the ClearCase checkin default options and VS.NET integration ...... 73 63. How do I – improved handling of the Open from Source Control function within Microsoft Visual Studio .NET ...... 75 64. How do I – understand the procedure to integrate ClearCase and VS.NET 2005 75 65. How do I – understand the possible corruption caused editing files from Visual Studio.NET using remote dynamic views ...... 79 66. How do I - FIX: The IBM Rational ClearCase remote view may cause file corruption in Visual Studio .NET 2003 ...... 79 67. How do I - add existing Microsoft ASP.NET Framework 1.x Web Applications to source control with Rational ClearCase ...... 80 68. How do I - create new ASP.NET Framework 1.x Web Applications while under source control with Rational ClearCase ...... 83 69. How do I - move a Visual Studio.NET project under SourceSafe to ClearCase while retaining history ...... 86 70. How do I – understand about an error occurred during the parsing of a resource required to service this request ...... 91 71. How do I – understand why a project must be in a view error when adding VS.NET solution to source control ...... 94 REGIONS ...... 95 72. How do I – understand the VOB tags are still displayed in the GUI after changing regions issue ...... 95 73. How do I – understand the requirement to tag a VOB in the default region on the VOB and view server ...... 97 EMAIL ...... 97 74. How do I - configure fully qualified domain names in e-mail notifications using SMTP ...... 97 PROBLEMS AND ISSUES ...... 98 75. How do I – understand why cleartool checkvob –evil_twin
ClearCase Environment – How do I 86. How do I – resolve a ClearCase Explorer crashes after switching registry servers on host issue ...... 109 87. How do I – understand the cleartool space output versus du output differences ...... 110 88. How do I – understand about the Microsoft Word Tracked Changes feature and ClearCase ...... 111 89. How do I – understand the adjusting the MVFS cache size when ClearCase is running may cause a kernel panic issue ...... 112 90. How do I – understand the unsupported Features of Solaris 10 with Rational ClearCase and ClearCase LT issue ...... 113 91. How do I – understand why the limit of file descriptors (ulimit -n) is changed after setview ...... 113 92. How do I – resolve the can't check out, or merge elements through xclearcase issue...... 114 93. How do I – understand about XML and the Windows 1252 encoding scheme issue 114 94. How do I – understand the ClearCase magic file changes needed to handle .csproj files with the XML type manager ...... 115 95. How do I – understand the reports are not visible in Report Builder issue ... 116 96. How do I – understand the empty derived objects not showing up in the config record issue ...... 117 97. How do I – understand the PK27439: SORTING CLEARCASE EXLORER issue 117 98. How do I – understand the nable to rename
ClearCase Environment – How do I 114. How do I – understand why the Daily Scheduled Jobs do not run by default in ClearCase 7.1.x ...... 137 115. How do I – understand comparing pre-7.1 install technologies to new technologies in 7.1 for achieving enterprise deployment on Windows systems ...... 141 116. How do I – understand about the pathname limitation on Windows and its affect on ClearCase ...... 142 117. How do I - deploy the ClearCase and ClearQuest Help systems on an intranet server 146 118. How do I - enable debugging for ClearCase and ClearQuest installs using Installation Manager ...... 152 119. How do I – understand the knowledge Collection: Available White Papers for the ClearCase Family of Products ...... 152 120. How do I – understand the White paper: ClearCase Registry server Performance Enhancements for version 7.1 ...... 154 121. How do I – understand why the installation of ClearCase 7.1 fails during post- install phase and logs MVFS errors: Trouble mounting the viewroot "/view" ...... 154 122. How do I – understand why applying the latest Fix Pack may yield error: zip com.ibm.rational.team.write.runonce.key 1.0.0.v200810242053 not found ...... 154 123. How do I – understand the ClearCase 7.1 equivalent to installing by siteprep in pre 7.1 versions ...... 155 124. How do I - configure ClearCase on a mobile computer that is disconnected from and then reconnected to the network ...... 156 125. How do I - install ClearCase v7.1.x on a platform that does not use the GUI 160 126. How do I - update the Windows ClearCase ALBD Password ...... 162 127. How do I – understand why package IBM Rational ClearCase is already installed. This package can only be installed in one location error reported when recording a response file using -skipinstall ...... 163 128. How do I – understand why after restarting the ClearCase host the CM server does not automatically restart ...... 163 129. How do I – understand why the Next button is disabled when installing ClearCase and ClearQuest at the same time ...... 164 130. How do I – understand the compatible ClearCase server and client iFix and Fix Pack levels ...... 164 131. How do I – understand the Knowledge Collection: Manually uninstall ClearCase ...... 164 132. How do I – understand about the IBM Rational ClearCase Windows release area 165 133. How do I – understand about the ALERT: albd service unexpectedly installed during a ClearCase 7.1 Client Only Installation on Windows ...... 166 134. How do I – understand the clarification on the alert issued for RHEL 4 Update 5/6 and RHEL 5 and support for ClearCase VOB hosts with Network Attached VOB storage ...... 167 135. How do I – understand the issue of db_server or vobrpc_server processes on a RedHat Enterprise Linux VOB server consume 100% CPU when using NAS storage for VOBs ...... 168 136. How do I – understand the NFS locking problems impact performance on a RedHat Enterprise Linux VOB server when using NAS storage for VOBs...... 169 137. How do I – understand the system Requirements for ClearCase 7.x ...... 169 Check the ClearCase System Requirements link for the latest system requirements. 169 138. How do I – understand about the available iFixes and FixPacks for ClearCase Family 7.x ...... 169 139. How do I – understand the ClearCase 2003.06.00 and 7.0 release and patch mappings...... 169
Page 6 of 341
ClearCase Environment – How do I 140. How do I – understand the changes made to the behavior of the install_release Reset Selections option in ClearCase 7.0 ...... 169 141. How do I – understand the issue when only root can run cleartool commands issue 175 142. How do I – understand about ClearCase and allow_non_root_installation.... 175 143. How do I – do a silent Install and Uninstall of ClearCase on UNIX ...... 175 144. How do I - remove the ClearCase patch subdirectories ...... 176 145. How do I – remove ClearCase patches from a release area ...... 176 146. How do I – resolve the multitool -ver and cleartool –ver not accurately reflection the patched state of a system ...... 177 147. How do I - manually uninstall ClearCase on Linux ...... 177 148. How do I - manually uninstall ClearCase on Solaris ...... 178 149. How do I - Manually uninstall ClearCase on HP-UX ...... 178 150. How do I - manually uninstall ClearCase on Windows ...... 179 151. How do I – conduct a silent install of a Rational Software Development Platform desktop products ...... 180 152. How do I - use Microsoft SMS to deploy ClearCase 7.x installations ...... 181 153. How do I – deploy a customized Enterprise Installation of IBM Rational ClearCase using CCRC ...... 181 154. How do I – understand the feature differences between ClearCase and ClearCase LT ...... 181 155. How do I – understand the Supplement to the ClearCase 7.0.0 Administrator's Guide about configuring ClearCase on a ClearQuest server ...... 183 156. How do I – understand why the installation of ClearCase 7.0.0.1_IFIX04 and 7.0.1.0_IFIX01 on RHEL 5 do not update the updated.config file properly ...... 183 157. How do I – understand the “Address already in use” error ...... 184 158. How do I – understand about the Stand Alone configuration for Rational ClearCase ...... 184 159. How do I – understand about ClearCase File Server (CCFS) ...... 185 160. How do I – understand how the ClearCase File Service (CCFS) can be disabled on an IBM® Rational® ClearCase® VOB server? ...... 186 FIREWALLS ...... 187 161. How do I – understand about Firewalls and ClearCase ...... 187 UPGRADING AND COMPATIBILITY ISSUES ...... 188 162. How do I - update an IBM Rational 7.1.x install through IBM Installation Manager ...... 188 163. How do I – understand ClearCase Compatibility Across Releases ...... 195 164. How do I – understand about upgrading ClearCase and ClearQuest to version 7.0.1 195 165. How do I – understand why db_server process on VOB server consuming 100% of a CPU after upgrading to RHEL 4 Update 5 ...... 196 166. How do I – upgrade ClearCase between major version numbers ...... 196 167. How do I - preserve files when upgrading ClearCase on UNIX and Linux ...... 197 168. How do I – resolve an Incompatible versions of ClearCase software and/or databases issue ...... 198 169. How do I – resolve a ClearCase GUIs fail on 64 bit Linux and Solaris operating system issue ...... 199 170. How do I - understand why the ClearCase GUIs fail on Linux and Solaris operating system ...... 199 171. How do I – understand upgrading to version 7.0 of Rational Software Development Platform - Team products ...... 202 PLUGINS & INTEGRATIONS ...... 203 172. How do I - integrate Microsoft Word 2007 with ClearCase 7.0 ...... 203 173. How do I – understand how the IBM Rational ClearCase SCM Adapter adds ClearCase functionality to the Eclipse workbench...... 206 Page 7 of 341
ClearCase Environment – How do I 174. How do I – understand about base ClearCase and ClearQuest V2 integration Setup and FAQ ...... 207 175. How do I – understand why the ClearCase menu options bundle is not visible in the menu ...... 209 176. How do I – understand the setting up and using the Rational Method Composer - Rational ClearCase Integration ...... 209 177. How do I - enable tracing for the V2 Base ClearCase-ClearQuest Integration 212 178. How do I – understand the issue “ClearCase SCM Adapter and Eclipse 3.4.1 with the Java EE Bundle is not visible in the menu” ...... 213 179. How do I – display the settings for the base ClearCase-ClearQuest integration 213 180. How do I – get the Eclipse plugins ...... 216 181. How do I – understand about Eclipse plug-in compatibility and version support for the ClearCase SCM Adapter ...... 216 182. How do I - install the SCM Adapter for Eclipse version 3.4.1 ...... 217 183. How do I – understand the supported Rational integrations with ClearCase and ClearQuest ...... 218 184. How do I – understand the Permission denied error accessing a dynamic view through Apache on Windows issue ...... 220 185. How do I – understand about the ClearCase 7.0 integration with Apache Ant 221 186. How do I - integrate Microsoft Word 2007 with ClearCase 7.0 ...... 221 187. How do I - remove the ClearCase integration with Microsoft Word ...... 224 188. How do I - disable the PowerPoint or Excel integrations with ClearCase ...... 225 189. How do I – understand why the ClearCase Menu option does not appear on the Menu Bar in Microsoft Word or Excel ...... 226 190. How do I – understand about ClearCase variables run within a batch file .... 227 191. How do I - change the XML Diff/Merge Type Manager ...... 228 192. How do I – use the ClearCase Automation Library (CAL) ...... 232 193. How do I – understand the example of the Rational ClearCase Automation Library (CAL) from a Rational Rose script ...... 233 194. How do I – understand the location of the ClearCase ClearQuest integration Perl triggers...... 235 195. How do I – understand central caching in the ClearCase and ClearQuest V2 integration ...... 235 196. How do I - use the cleartool schedule command to run the Cache manager 235 197. How do I – understand the ClearCase could not get an object ID (OID), error when checking in a new element version when using the V2 Base ClearCase and ClearQuest integration issue ...... 236 198. How do I - setup the V2 ClearCase ClearQuest integration to list out all records on a check out or check in ...... 236 199. How do I - display the record ID from the command line when using the UCM or Base ClearCase and ClearQuest integration ...... 238 200. How do I – understand conjunction junction, what's your function: more ClearCase integration strategies ...... 239 201. How do I - have 2 VOBs on the same machine accessing different ClearQuest databases ...... 242 202. How do I - change the source control provider to ClearCase ...... 243 203. How do I – understand the unable to read registry value: Software\Atria\ClearCase\SCCServerName issue ...... 243 204. How do I – understand about SCC compliance and Rational ClearCase ...... 243 205. How do I - enable SCC trace operations with ClearCase ...... 244 CLEARCASE CONTEXT MENUS ...... 244 206. How do I – understand why Menu Choices cannot be added or modified in ClearCase 7.1 Context Menu Editor ...... 244 Page 8 of 341
ClearCase Environment – How do I 207. How do I – customize the ClearCase Windows Interface ...... 246 208. How do I - change ClearCase context menus without loading an export file 249 CLEARPROMPT ...... 250 209. How do I – understand the supplement to the Command Reference Guide about clearprompt ...... 250 DOCUMENTATION ...... 251 210. How do I – use the ClearCase Information Centre ...... 251 TEMPORARY FILES AND (.)DOT FILES ...... 252 211. How do I – understand the temporary files created by ClearCase ...... 252 212. How do I – understand about .dmp files in the ClearCase log directory ...... 253 213. How do I – understand the .PID file ...... 254 VIRTUALISATION ...... 255 214. How do I – understand that Clearlicense -hostid may return invalid results on Red Hat Linux if XEN kernel is running ...... 255 215. How do I – understand ClearCase Licensing and the MAC address on virtual machines ...... 255 216. How do I – understand why the Linux Virtual server clients report errors after VOB server crashes or is rebooted ...... 255 INTEROP ENVIRONMENT ...... 256 217. How do I - configure UNIX or Linux clients to access Windows VOBs ...... 256 218. How do I – understand the mnode settings and the username.map file with reference to SaMBa ...... 261 219. How do I – understand the ClearCase and Samba: A Supported Configuration 262 220. How do I – configure usernames and primary groups in a ClearCase Interop environment – they must be identical ...... 262 221. How do I – understand about the CLEARCASE_PRIMARY_GROUP variable .. 262 222. TROUBLESHOOTING: Here are some related technotes to problems where the CLEARCASE_PRIMARY_GROUP variable was set incorrectly: ...... 264 223. How do I – understand about the Primary Group requirements for element creation ...... 265 224. How do I – understand about the CLEARCASE_GROUPS variable ...... 267 225. How do I – understand about MVFS limitations on the number of ClearCase groups a user may belong ...... 268 226. How do I – understand the maximum groups on UNIX and Linux for use with ClearCase ...... 269 227. How do I – understand the access denied accessing files from Windows Explorer but not from Command Prompt (CLEARCASE_GROUPS) issue ...... 271 228. How do I – understand the CEARCASE_GROUPS EV when more than 32 groups and accessing 770 directories issue...... 272 229. How do I – Create ClearCase VOBs and Views in ClearCase Interoperation environment with UNIX® or Linux® with Microsoft® Windows® - you can’t ...... 272 230. How do I – Create a snapshot view from Windows stored on a ClearCase UNIX server ...... 272 231. How do I – resolve a checkout fails from Windows only in an interop environment issue ...... 272 232. How do I – understand the specific Samba 3.0.24 configuration required for ClearCase ...... 273 233. How do I – understand ClearCase configuration in a domain environment with a one-way trust ...... 273 234. How do I – understand usernames and primary groups in a ClearCase Interop environment ...... 273 235. How do I - understanding NOBODY in the credmap output ...... 274 236. How do I - recover ClearCase functionality after users and groups moved to a new domain ...... 275
Page 9 of 341
ClearCase Environment – How do I 237. How do I – understand about ClearCase permissions on Windows ...... 279 238. How do I – understand the “Cannot bind an admin_server handle on Windows” issue ...... 283 239. How do I - add multiple domain names to the CredmapAllowedDomainList 286 LICENSING ...... 288 240. How do I - reset the license usage statistics reported by clearlicense ...... 288 241. How do I - Denying users from pulling a ClearCase license ...... 288 242. How do I – know the ClearCase commands that DO NOT require a ClearCase license 289 243. How do I - switch between Atria and FLEXlm licensing ...... 289 244. How do I - configure ClearCase 7.1.x on UNIX to support multiple license servers ...... 290 245. How do I – understand why windows user is consuming two ClearCase licenses when license server is hosted on UNIX or Linux ...... 293 PERMISSIONS ...... 295 246. How do I – understand the this application has failed to start because the application configuration is incorrect issue ...... 295 247. How do I – understand the access denied errors executing an element in a proxy group configuration issue ...... 295 SUPPORT POLICIES ...... 297 248. How do I – understand about ClearCase support for Microsoft Windows 7 Operating system...... 297 249. How do I – understand the Support Policy for ClearCase on Solaris Branded Zones 297 250. How do I – understand the Support Policy for ClearCase on Linux ...... 298 251. How do I – understand about disk encryption software use with ClearCase 299 252. How do I – understand the support Policy for Microsoft Windows Vista ...... 299 253. How do I – understand the support policy for ClearCase use across multiple Active Directory forests ...... 300 254. How do I – understand the support Policy for ClearCase and Xen on Linux . 301 255. How do I – understand ClearCase Support for Red Hat Linux 5.0 ...... 301 256. How do I – understand the support Policy for High Availability clustering and ClearCase ...... 302 257. How do I – understand ClearCase Support for HP-UX 11.31 ...... 303 258. How do I – understand the support Policy for DFS (Distributed File System) and ClearCase ...... 303 259. How do I – understand the support Policy for Altiris Server Management Suite with ClearCase ...... 304 260. How do I – understand the support Policy for Microsoft Virtual PC on ClearCase and ClearQuest ...... 304 261. How do I – understand the support Policy for Anti-Virus and ClearCase ...... 305 262. How do I – understand the Rational Support Policy Addendum for VMware support ...... 306 263. How do I – understand support for IBM SWG products in a VMware® environment ...... 307 264. How do I – understand the support Policy for ClearCase with FLEXlm on HP- UX IA64 ...... 308 265. How do I – understand the support policy for ClearCase on Macintosh OS X 309 CACHING ...... 309 266. How do I – understand about the ClearCase cache directory ...... 309 CLEARCASE ENVIRONMENT ...... 310 267. How do I – deploy the ClearCase and ClearQuest Help systems on an intranet server 310 268. How do I – understand platform specific IPv6 restrictions for ClearCase ...... 315
Page 10 of 341
ClearCase Environment – How do I 269. How do I – understand about the limits for simultaneously mounting VOBs on a single host...... 315 270. How do I – Understand about Feature Levels and ClearCase ...... 317 271. How do I – modify the Vtree Browser font appearance in ClearCase 7.0.x .. 318 272. How do I – understand the Network Environments for ClearCase ...... 318 273. How do I – understand the issue that the use of Google Desktop with ClearCase causes conflicts ...... 319 274. How do I – understand why MVFS crashes if encryption software is installed on the system ...... 320 275. How do I – understand about the noatime filesystem mount option and ClearCase ...... 320 276. How do I – understand why you cannot access files or directories in ncaexported VOB/view from RHEL4 which is fixed in v7.0.1.1 ...... 321 277. How do I – set up the CCASE_NMASTER_TRIG environmental variable ...... 321 278. How do I – resolve non-ClearCase client hangs when attempting to mount an NCA exported view/VOB...... 321 279. How do I – understand about the maximum character length of a version extended path ...... 322 280. How do I – understand the requirements when IP address, hostname and NIS are changed ...... 322 281. How do I – understand about alternate_hostnames ...... 323 282. How do I – control the date format displayed by cleartool commands using the CCASE_ISO_DATE_FMT environment variable ...... 324 283. How do I – understand about the CCASE_ISO_DATE_FMT environment variable ...... 325 284. How do I – understand about naming conventions and characters used to create ClearCase objects ...... 326 285. How do I – understand about the special characters in file names on UNIX and Linux ...... 327 286. How do I – remove ClearCase objects whose name begins with a hyphen ... 328 287. How do I – understand about the interaction between ClearCase and file system snapshots ...... 329 288. How do I – understand about the TZ environment variable ...... 330 289. How do I - define TEMP user environment variables for the clearcase_albd account even if you cannot logon with this account ...... 331 290. How do I - stop client names from appearing in the ClearCase Administration Console ...... 332 291. How do I - activate ClearCase remote administration on UNIX and Linux .... 333 292. How do I – understand about files under source control and the write bit.... 334 293. How do I – understand the issue “Is there a Windows equivalent of the CLEARCASE_DBG_GRP EV” ...... 334 CLEARCASE SCHEDULER ...... 334 294. How do I – understand that the ClearCase Scheduler incorrectly computes next run time on day of transition to standard time ...... 334 295. How do I – understand why the Daily View Space scheduled jobs making several DNS calls ...... 336 296. How do I – use the ClearCase Scheduler without NIS on UNIX or Linux ...... 336 297. How do I – understand the unable to add a user to the Scheduler ACL list where NIS is not defined issue ...... 337 298. How do I – understand the ClearCase -nusers switch can only specify single users to allow access to an object issue ...... 337 299. How do I - move custom ClearCase Scheduler Jobs from one system to another ...... 337 300. How do I - recreate the ClearCase Scheduler database without losing customized default job information ...... 338
Page 11 of 341
ClearCase Environment – How do I 301. How do I – “Temporarily disabling jobs in the Scheduler” ...... 339 ANTI-VIRUS SOFTWARE ...... 340 302. How do I – understand the support Policy for Anti-Virus software and ClearCase ...... 340 Support Policy for Anti-Virus and ClearCase ...... 340 303. How do I – understand the RPC: Remote system error - [WINSOCK] No buffer space available issue ...... 340
Anti-virus software 1. How do I – understand the support Policy for Anti-Virus software and ClearCase What is the support policy for Anti-Virus Scanners installed on IBM® Rational® ClearCase® clients and servers and are there any transcripts of known configurations for Virus scanners that are compatible with VOB and View servers?
Overview ClearCase is not certified at this time to run with any specific Anti-Virus applications. We are currently testing with some major anti-virus vendors to ensure we do not find any major issues with the anti-virus product and ClearCase. The information in this technote is a compilation of support knowledge related to the configuration of Anti-Virus applications to successfully work along side Rational ClearCase. This is a consolidation of documents that have been written to detail the lessons-learned to assist you in avoiding known problems when Anti-Virus applications are configured on a ClearCase host. This means that ClearCase can coexist with an anti-virus program running, however, there are some considerations to plan for. Note: If problems caused by anti-virus configuration issues occur in your ClearCase environment, resolution of those issues is beyond the scope of Rational Client Support. Rational Client Support can assist in determining what the specific anti-virus ClearCase problem is, however, you should work with your anti-virus vendor to determine how to resolve the issues.
Topics Covered in this technote The general issues to consider when configuring Virus scanners on a ClearCase server are: When and How to Scan When and How NOT to Scan What to Scan What NOT to Scan
When and How to Scan: When possible scan manually or on a scheduled basis during down time (non-work time). This limits the performance impact virus scanning can impose during normal operations especially ClearCase use as this impact could be significant depending on client speed, network bandwidth, server performance, and the number of clients accessing VOBs and views on any given host. ClearCase should be shut down on the host being scanned. This avoids any possibility of the scanner affecting or being affected by ClearCase.
When and How NOT to Scan: "Realtime" or "on-access" scans should be avoided. Depending on how aggressive the virus scanner is, "on-access" scanning can disable ClearCase cleartext and source container creation. The final step in the on-access operation is typically to rename temporary containers and ClearCase creates many of these containers as part of its process. Also, on-access scans may lock a file to perform some operations resulting in the inability of ClearCase to rename the file. This may result in errors from vob_server regarding "operation 'rename_container' failed." Virus scanner should not be configured to attempt cleaning or deletion of infected files. These options can lead to corrupted or missing source containers and/or derived objects which in turn can lead to a dramatic increase in recovery time as the corrupted/missing containers have to be rebuilt.
What to Scan: Scan the VOB source pools. Be aware that binary files that have been added to source control may be compressed and inaccessible to the virus scanner unless the scanner can scan inside of zip files.
Page 12 of 341
ClearCase Environment – How do I Scan VOB cleartext pools. Be aware that the file names in this directory bear little relation to their real names, so a scan by extension (.txt, .exe etc...) will not properly scan. Scan VOB DO pools. This may protect against file infectors that may find a freshly built executable during a build and make a few minor changes. If that file is then winked in through another build, a virus-infected file would be publicly available. This would at least provide notification. Scan View storage directories. This would catch new files added to a directory by a virus and view private files modified by a virus.
What NOT to Scan: Do not scan the MVFS "view" drive ("M:" by default on Microsoft® Windows®). Scans on this drive will scan all views started on this system and all VOBs mounted on this system. The cleartext lookup/creation phase of a file open in MVFS can lead to serious performance degradation as the scan attempts to open all files in the view. Avoid scanning mapped drives to the MVFS on Windows. Scanning drives mapped to views is generally considered redundant as long as the view storage directories are being scanned. Similar performance problems related to scanning the MVFS drive itself can manifest itself during mapped drives scans as well. Avoid scanning /view mount point on UNIX® or Linux®, as this is a mirror of the root directory for the file system. Avoid scanning ClearCase Remote Client (CCRC) local view copy area storage directories and CCRC install directory. For optimal performance, consider disabling real-time scanning or avoid scanning the ClearCase Remote Client (CCRC) local view copy area storage directories and avoid scanning the directory into which CCRC is installed.
Related information TOC: ClearCase Matrices and Support Policies Cleaning a virus that was detected in ClearCase Japanese technote 1431194 2. How do I – understand the RPC: Remote system error - [WINSOCK] No buffer space available issue After installing McAfee® Enterprise 8.0 on a Microsoft® Windows® machine, IBM® Rational® ClearCase® omake builds fail with "RPC: Remote system error - [WINSOCK] No buffer space available" and system crashes.
Cause Omake builds are failing after installation of McAfee 8.0 with the following errors:
RPC: Remote system error - [WINSOCK] No buffer space available omake: Error: Error trying to contact view_server for view view:C:\viewstore\oa12.vws: No such file or directory omake: Error: Unable to contact View - oa12 RPC: Remote system error - [WINSOCK] No buffer space available cleartool: Error: Error trying to contact view_server for view view:C:\viewstore\a12.vws:
No such file or directory
Insufficient system resources exist to complete the requested service.
Fatal error C1083: Cannot open source file: '.\Font.cpp': Not enough space
Solution Upgrade to McAfee Virus Scanner 8.10. or
Apply McAfee Virus Scanner 8.0i patch 15 which resolves this issue by adding the ClearCase MVFS to the "do not scan" list of the McAfee filter driver. The patch is available for download on the McAfee website.
Note: This patch will fix a known memory leak issue and resolve other known ClearCase command problems. Page 13 of 341
ClearCase Environment – How do I
Create view fails after uninstalling McAfee Firewall ClearCase commands fail when McAfee 8.x is installed Error running fix_prot with McAfee 8.0 installed Failure removing VOBs & views with McAfee installed Veritas NetBackup and McAfee AntiVirus conflict About McAfee VirusScan Enterprise 8.0i Patch 11 Server Processes 3. How do I – understand about the albd_rt_params.conf file What is the purpose of the IBM Rational ClearCase albd_rt_params.conf file and how can it be used?
Answer Important note: The information in this technote provides details about the available options with the albd_rt_params.conf configuration file. These settings should only be changed by a ClearCase or system administrator who understands the impact as improper changes to this file could have negative performance consequences. If you are unsure about what settings to use, contact IBM Rational Client Support for further assistance before proceeding with any changes.
About the albd_rt_params.conf file:
The albd_rt_params.conf file provides a run time configuration control of albd_server. Some of these configuration settings were previously controlled by setting environment variables. This caused problems on Unix systems since: The easiest place to set those environment variables was the ClearCase startup script. The startup script could be replaced during a patch install, reverting the albd to the default settings.
This file is a user-created file and is stored in the following location: UNIX or Linux: /var/adm/rational/clearcase/config
Windows: C:\Program Files\Rational\ClearCase\var\config
ClearCase 7.0 or later: Options The following options are available in ClearCase 7.0.1.1 and later: ClearCase Registry: RGY_FLUSH_INTERVAL - Number of seconds between times albd flushes the registry files to disk. Refer to technote 1383863 Changing the flush interval time on the ClearCase registry server to improve performance for further details. ClearCase MultiSite: MSADM_SVR_PORT - Designates a single port to be used by MultiSite request for mastership (reqmaster) from a remote replica. Refer to technote 1366212 Using a static port for mastership requests with ClearCase MultiSite for further details MSSHP_MIN_PORT - Lowest port assigned to a MultiSite shipping server MSSHP_MAX_PORT - Highest port assigned to a MultiSite shipping server The following option is available in ClearCase versions 7.1.0.2, 7.0.1.5, 7.0.0.6, or later (with fix for APAR PK70970): ClearCase MultiSite: MSSHP_STRICT - If set to 1, enforces the specified range on both outgoing AND incoming ports just as the CLEARCASE_MIN_PORT and CLEARCASE_MAX_PORT environment variables and shipping server settings did. Page 14 of 341 ClearCase Environment – How do I Related information Improving VOB host performance MIN/MAX port limitations not honored 4. How do I – understand about Rational ClearCase server processes Network protocols The protocols used for network communications are TCP (Transmission Control Protocol) and UDP (User Datagram Protocol), which are layered over IP (Internet Protocol). Most processes use TCP, but for optimization some use UDP. The protocol that a ClearCase server process uses is hard coded and cannot be manually configured, changed or disabled. Rational ClearCase server processes The Rational ClearCase server processes are documented under Rational ClearCase network planning and administration in IBM Rational ClearCase Administrator's Guide: albd_server admin_server credmap_server view_server vob_server db_server vobrpc_server lockmgr rwp ALBD Configuration File The ALBD configuration file, albd.conf, is used by the albd_server to determine the RPC services that will be available through it. This conf file provides a list of the registered server processes, declares what kind they are and what protocol (udp and/or tcp) they use. It is located in %CLEARCASEHOME%\ClearCase\config\services, and it can be opened for viewing with a text editor. However, albd.conf must not be modified manually in attempt to make customizations in the environment. In addition to the above processes (with the exceptions of lockmgr and rwp), this file also list: promote_server mntrpc_server shipping_server ws_helper ctrack_server host_agent ccfs_server msadm_server Page 15 of 341 ClearCase Environment – How do I MultiSite Configuration File There is a separate configuration file for ClearCase MultiSite, ms_albd.conf, that contains server definitions that are specific to the MultiSite product. This conf file is also used by albd_server to determine the RPC services that will be available through it, and it is located in %CLEARCASEHOME%\ClearCase\config\services: Note: This conf file must not be modified manually in attempt to make customizations in the environment. syncmgr_server vob_synctool Synchronization Management is detailed in IBM Rational ClearCase MultiSite Administrator's Guide. Credentials Manager ClearCase does not have a built-in authentication mechanism, and makes use of the security and access controls provided by the Windows operating system. The credentials manager Service, cccredmgr, registers the clearcase group security identifier (SID) at system startup with MVFS. The credentials manager is not only a server process, but it runs on any ClearCase host that is configured to support local VOBs and views to regulate VOB and view access control. Active ClearCase Processes When ClearCase is installed on any host, you can run albd_list to show what processes are actually running, see technote 1148639 for more details. MultiVersion File System MVFS (MultiVersion File System) is not a server process, it loads a kernel driver that presents a file system to the user through a standard interface; see technote 1230196. 5. How do I – understand the Lock Manager process post and pre ClearCase v7 About the Lock Manager prior to 7.0 In addition to the content in the Administrator's Guide, the following highlights outline the purpose, features and limitations of the lock manager process. Windows, Linux, AIX®, SGI® and other platforms The lock manager is an individual process that co-ordinates concurrent access to VOB database files. The lock manager has a hard limit of 1024 users which corresponds to the number of VOBs and or users accessing those VOBs for a given host. On Solaris® and HPUX® The coordination of VOB locking is performed by the db_server and vobrpc_server processes themselves. A file, /var/adm/atria/almd is memory mapped by the lockmgr and all the db_server and vobrpc_server processes running on a VOB host - known as the shared memory lock manager (introduced in 4.1). Note: The shared memory lock manager has not been implemented for use on pSeries hardware. A single mutex mechanism is used to control concurrent updates to this file. Note: Mutex is short for mutual exclusion object. A mutex is a program object that allows multiple program threads to share the same resource, such as file access, but not simultaneously. When a program is started, a mutex is created with a unique name. After this stage, any thread that needs the resource must lock the mutex from other threads while it is using the resource. The mutex is set to unlock when the data is no longer needed or the routine is finished. The lock manager process is more of a lock janitor in this capacity as it just sets up and cleans up after the db_server and vobrpc_server processes. Page 16 of 341 ClearCase Environment – How do I Changes to the Lock Manager in 7.0 on UNIX and Linux Note: The 7.0 ClearCase Administrator's Guide does not include the details about the new lock manager. All of the information related to the new features are included below. As of ClearCase 7.0 the lock manager process has been removed for HP-UX, Itanium, Solaris, and Linux (x86). The lock manager functions have been absorbed by the db_server and vobrpc_server processes for VOBs and the syncmgr_server process for the MultiSite® syncmgrdb. This means that each VOB in essence now has its own lock manager. This change will allow many more VOBs and users on a single machine. Note: As of ClearCase 7.0 IFIX01, the lock manager enhancements in 7.0 now apply to AIX. Prior to the iFix, AIX uses a lock manager. There are no changes to the lock manager on Windows (x86 or x64), Linux (x64, iSeries pSeries, and zSeries), or Solais x86. There is still a lock manager process on these platforms. The instructions outlined in the ClearCase Administrator's Guide still applies to these platforms. New Configuration File on UNIX and Linux: The ability to have different parameters for each VOB on the system as well as a locally-specified override for server-wide settings is now possible through use of a configuration file called vob_almd_params. Note: Modifying this file does not require a reboot or even a restart of the ClearCase services; however, any changes made to the configuration file will be applied when the VOB is idle so as not to impact other operations in progress. A VOB is considered idle in this case when all of the db_server processes have completed work in that VOB. For example, if there are db_server processes still working (actively working or waiting to work) on a VOB, the changes made to the configuration file will not become active until all but one of those db_servers complete their work. When the last db_server is finished, ClearCase will consider the host idle and will then implement the changes for that VOB. IMPORTANT: For sites with very high and constant activity in their VOBs, it is recommended you stop and restart ClearCase to avoid any potential problems like the one identified in technote 1253547. The vob_almd_params server wide configuration file is located in the /opt/rational/clearcase/config/vob/db directory and controls the settings for all VOBs on the host. The vob_almd_params files in the individual VOB db directory ( The syntax employed within the vob_almd_params file: –u num –q num Upgrading UNIX and Linux: Since there is no longer a lock manager on UNIX and Linux in Rational ClearCase 7.0, existing lock manager parameters will not be reused upon upgrade. Instead, these parameters are overwritten with default values. To preserve existing values for these parameters, save a copy of the host's /var/adm/rational/clearcase/config/lockmgr.conf before you upgrade. After the upgrade, you can restore these parameter values to one of the vob_almd_params files above. Note: There is no longer a need to specify –f any longer when customizing the vob_almd_params file. The old –u and -q parameters were used for ALL VOBs on the system. You will need to recalculate if you plan to apply settings on a per-VOB basis. ClearCase Administrator's Guide addendum The 7.0 and 2003.06.00 ClearCase Administrator's Guide contain the same content. Addendums to the sections listed below are provided. 1. The ClearCase Administrator's Guide under the lockmgr reference information > Options and argument > -u section states: You can compute a very approximate worst case value for –u by using the formula: V*(N/4 + 5) where V is the number of VOBs on the host, and N is the number of users who access those Page 17 of 341 ClearCase Environment – How do I VOBs. Note: For UNIX and Linux using the new lock manager process in ClearCase 7.0, V will equal 1 since there is one "lock manager" per VOB. The formula will compute an approximate value; however, it is not worst case. Since one db_server process can consume up to 4 user table slots for each VOB the process is accessing, the worst case value for the user table (-u) should be: V*(N + 5) Note: The -q value in should be no more than 5*(-u value). 2. The ClearCase Administrator's Guide under the lockmgr reference information > Options and argument > -u section also states a better method to use to calculate the user table. For a more realistic value—one that does not cause the lock manager to consume unnecessary virtual memory on the VOB server host—monitor the total number of db_server and vobrpc_server processes running on the VOB server host for an extended period of typical use (perhaps a week or two). Then multiply the peak value by a factor that will accommodate growth (two, or perhaps a little more). Here is an example of what that section describes: If you count db_server and vobrpc_server processes and get 13 combined processes at 1:00 PM 18 processes at 1:30 PM 12 processes at 2:00 PM 13 processes at 2:30 PM and continue this pattern throughout the week, you will be able to find the maximum number for the user table. In this example the maximum was 18, so the -u value would be 36 which was derived by using twice the maximum number of processes at any one time ( 2 * 18). Note: The -q value in should be no more than 5*(-u value). 3. The ClearCase Administrator's Guide makes reference to a lockmgr_log file on UNIX and Linux. There is no lockmgr_log file. Any error related to the lock manager would appear in either the vobrpc_server log or the db_server log. Related information How to monitor the Lock Manager on Windows How to monitor the Lock Manager on UNIX Diagnosing Lock Manager registry settings on Windows About deadman lock timeouts About Rollforward recovery warnings Possible errors when the vob_almd_params is modified 6. How do I - monitor the Lock Manager status on Windows The following steps will assist you in capturing diagnostic output needed to troubleshoot the Lock Manager on Windows. 1. Log onto the VOB server with local administrative rights or as the clearcase_albd account. 2. Stop the lock manager process (lockmgr.exe) a. Open a command prompt (Start > Run > cmd) b. Execute the following command: net stop lockmgr Example from 2003.06.00 C:\>net stop lockmgr The Rational Lock Manager service is stopping. The Rational Lock Manager service was stopped successfully. 3. Set up the lock manager with the following parameters by typing: lockmgr -a almd -q 1024 -u 1016 -f 1016 -nosvc The -nosvc option is important. This option allows the lock manager to run in the command window and NOT AS A SERVICE in order to capture output. Page 18 of 341 ClearCase Environment – How do I Note: Make sure the command window has the ability to copy information from it (you will need it to capture the output). 4. In a separate command window, conduct ClearCase operations or allow the clients to work as usual. 5. Periodically, hit Note: Keep hitting Lockmgr Named: almd Lock manager installed, pid = 2136 @ Mon Jun 17 13:43:20 2002 Table size: 1868656 bytes ======1 tafs, 1 users, 7 open files Taf #0 Dev/inode: e88e4497/0ae02d99 Taf state: OKAY Tjf state: OKAY Seconds to journal checkpoint: 0 Number of locks: 0 Users: 0 ------User #0 Status: LIVE PID: 3036 TAF: 0 Pending lock request count: 0 Seconds until timeout: 0 Recovering user #: -1 User name: 4469fe9d3036@@@@ Open files: 0 1 2 3 4 5 6 ------File #0 Dev/inode: d4294e1c/2e12c564 Lock status: f Open users: 0 File #1 Dev/inode: 09784514/877aaadf Lock status: f Open users: 0 File #2 Dev/inode: 33544026/3c94d498 Lock status: f Open users: 0 File #3 Page 19 of 341 ClearCase Environment – How do I Dev/inode: bf554bca/399851f0 Lock status: f Open users: 0 File #4 Dev/inode: 736348aa/82fc6c5e Lock status: f Open users: 0 File #5 Dev/inode: 13bd480b/972e7df5 Lock status: f Open users: 0 File #6 Dev/inode: 92344182/07f5995f Lock status: f Open users: 0 ======7. How do I - Monitor the Lock Manager status on UNIX and Linux Note: The lockmgr process has been retired as of Rational ClearCase 7.0 and replaced with different technology. Review the Documentation supplement referenced below for more details. The following steps will assist you in capturing diagnostic output needed to troubleshoot the Lock Manager on UNIX or Linux. 1. SU to root 2. Run: ps -ef | grep lockmgr 3. Find the lockmgr pid. 4. Run: kill -3 0 users, 0 open files 1 users, 7 open files 1 users, 7 open files 2 users, 14 open files 8. How do I - diagnosing Lock Manager registry settings on Windows how to verify if the IBM® Rational® ClearCase® Lock Manager settings you added to the Microsoft® Windows® registry are in fact being used. Despite having set the LockMgrCmdLine key and its associated values within the Windows registry, the following errors are still seen in the ClearCase logs: 2/14/03 04:31:57 db_server(4648): Error: db_server.exe(4648): Error: Cannot open database in "d:\ClearCase_Storage\VOBs\this.vbs\db" 02/14/03 04:31:57 db_server(4648): Error: db_server.exe(4648): Error: Too many open databases on host (try increasing -f argument on lockmgr command line) 02/14/03 04:31:52 db_server(4648): Error: db_server.exe(4648): Error: Cannot open database in "d:\ClearCase_Storage\VOBs\mySW.vbs\db" 02/14/03 04:31:52 db_server(4648): Error: db_server.exe(4648): Error: Too many open databases on host (try increasing -f argument on lockmgr command line) 02/14/03 04:31:52 db_server(4648): Error: db_server.exe(4648): Error: Cannot open database in "d:\ClearCase_Storage\VOBs\theSW.vbs\db" 02/14/03 04:31:52 db_server(4648): Error: db_server.exe(4648): Error: Too many open databases on host (try increasing -f argument on lockmgr command line) 02/14/03 04:31:52 db_server(4648): Error: db_server.exe(4648): Error: Cannot open database in "d:\ClearCase_Storage\VOBs\newSYS.vbs\db" It appears the LockMgrCmdLine value is not being read from the registry and is using the default. Solution Page 20 of 341 ClearCase Environment – How do I In order to determine if this is the case, you need to do the following: 1. Download Regmon from http://www.sysinternals.com/utilities/regmon.html. 2. Stop the ClearCase services. 3. Run the regmon utility. 4. Start the ClearCase services. 5. In the regmon tracing, select Edit > Find > LockMgrCmdLine If the result is SUCCESS/FAILURE, this means that Windows is properly using the registry values assigned. Please review technote 1125258 to help determine the correct value for the -f parameter as it needs to be increased. If the result is NOT FOUND, double click the entry in Regmon. This will take the you directly to the value in the Registry. Check to make sure the entry is actually there, that there are no spelling errors or a preceding space in the key or value. 9. How do I – understand about the db.conf configuration file The db.conf file is an optional configuration file for the db_server process used for making changes to the way the db_server operates. Note: The db.conf file is not created during the Rational ClearCase installation. This file needs to be created manually and stored in the following locations: UNIX® and Linux®: /var/adm/atria/config or /var/adm/rational/clearcase/config Microsoft® Windows®: C:\Program Files\Rational\ClearCase\var\config The db.conf file can be used to control the size of the vista.tjf file by limiting the journal file size: Example. Add the following line to limit the vista.tjf files to grow to 1.2 Gigabytes. -journal_file_limit 1200000000 The db.conf file can be used to log lock times for debugging, the results of which are logged in the db_server log. Options -locks_held - print a warning to a log file if any transaction goes over X seconds -locks_wait - print a warning to a log file if any transaction is blocked for over X seconds Example: -locks_held 30 -locks_wait 30 Note: These two parameters will instruct the db_server to make a log entry for any lock held for 30 seconds or more. The db.conf file can be used to increase deadman lock time-out values If the logs indicate deadman lock time-outs, you can increase the time-out limit for the db_server processes. The default is 90 seconds. To increase the time-out add this line to the file: -deadman ClearCase does not have to be stopped or restarted after creating this file. 10. How do I – understand about deadman lock time-outs A deadman lock time-out occurs when a ClearCase server process detects a client process is holding a lock and is not responding within a set limit of time. In order to prevent deadlock situations whereby other client processes remain in a wait state for the lock to be released by the non-responsive client, the server process will terminate the connection of the non- responsive client and release the locks. Typical examples of deadman lock time-out scenarios include, but are not limited to: Client loses its network connection Client process hangs or loops endlessly Client process takes too long to complete an operation Page 21 of 341 ClearCase Environment – How do I Client host machine crashed or rebooted The default time-out values for the deadman time-out value is set to 90 seconds. Refer to technote 1122794 for information on how to increase the deadman lock time-out. 11. How do I – resolve a this client was launched with different lockmgr parameters than those now in the almd file issue Whydonthe db_server and vobrpc_server logs fill with errors when the vob_almd_params server wide configuration file is edited while IBM® Rational® ClearCase® is running on UNIX® and Linux®. Cause The db_server and vobrpc_server logs fill up with the following errors: 2007-01-11T10:01:09-05 vobrpc_server(23512): Error: Warning: this client was launched with different lockmgr parameters than those now in the almd file. Re-setting client parameters. 2007-01-11T10:40:02-05 db_server(8594): Error: Warning: this client was launched with different lockmgr parameters than those now in the almd file. Re-setting client parameters. This is caused by modifying the vob_almd_params server wide configuration located in /opt/rational/clearcase/config/vob/db while ClearCase is still running. Note: Review the Documentation Supplement about the Lock Manager for more information about the vob_almd_params and its use. Solution To avoid the error messages from appearing in the logs either 1. Stop ClearCase on the host and then edit the file or Edit the file when NO activity is taking place on the server. Note: A defect has been issued to (APAR IC50932) to suppress the warnings from the logs as in some cases, in high transaction environments, this issue can cause the logs to fill up with hundreds of entries per second causing the logs to grow exponentially. The solution to which requires you to stop and restart ClearCase to cease the logs from filling up the server. 12. How do I - start and stop ClearCase from the Windows command line The ClearCase server processes (Location Broker, Lock Manager, and Credentials Manager services) can be started and stopped from the command line; however, the MVFS is loaded directly into the kernel and cannot be shut down from the command line. To reload the MVFS, restart the PC. To see if the ClearCase ALBD, Lock Manager, and Credentials Manager services are running on the host, run the following command: NET START Note: A list programs will scroll on the screen. You want to look for a derivative of the following entries: Atria Location Broker IBM Rational Lock Manager Rational Cred Manager To stop the ALBD, Lock Manager, and Credentials Manager services, issue the following commands individually: NET STOP ALBD NET STOP LOCKMGR NET STOP CCCREDMGR To start the ALBD, Lock Manager, and Credentials Manager services, issue the following commands: Page 22 of 341 ClearCase Environment – How do I NET START ALBD NET START LOCKMGR NET START CCCREDMGR 13. How do I - starting and stopping ClearCase services remotely ClearCase services can be stopped or started from a remote host using the sc command that is packaged in the Microsoft Windows Resource Kit for NT, 2000 and 2003. The following services can be stopped remotely: "ATRIA LOCATION BROKER" or ALBD LOCKMGR CCCREDMGR Note: MVFS is loaded directly into the kernel and cannot be shutdown from the command line. The system must be restarted to stop and restart MVFS; refer to technote 1230196 for more details. Syntax: sc \\ Example: sc \\host1 stop albd 14. How do I – understand the unable to contact albd_server issue Attempts to start Rational ClearCase using atria_start returns the following error: unable to contact albd_server The albd_log file list the message, cannot read config file. The /var/adm/atria/config/albd.conf file is missing. Solution Copy: /opt/rational/clearcase/config/services/albd.conf.template to: /var/adm/atria/config/albd.conf to recreate the file. ClearCase will start successfully. 15. How do I – understand how ALBD RPC calls can cause significant performance degradation under very high load An inefficiency was discovered in an RPC library algorithm that affects albd_server transactions. This logic was designed to manage duplicate requests to the albd_server to prevent UDP retransmissions from causing false failures. Under certain conditions and under heavy load from a large number of ClearCase clients, the albd_server RPC throughput can drop significantly affecting all users of that albd_server. For ClearCase registry servers, this can cause widespread performance problems. Defect APAR PK45674 has been submitted to address this issue. 16. How do I – understand why Rational ClearCase operations hang with the error message of "timed out trying to communicate with ClearCase remote server. " This technote describes some symptoms that will occur when the workload on an IBM Rational ClearCase UNIX server exceeds the capacity of the server, and some measures that can be taken to relieve them. Symptom Intermittently, and particularly during peak usage periods of the day, users of both ClearCase Remote Client (CCRC) and full ClearCase client (ClearCase Explorer, for example) experience "hangs" which usually will eventually end with a pop-up message "timed out trying to communicate with ClearCase remote server". Page 23 of 341 ClearCase Environment – How do I Checking the ClearCase logs on the server shows messages like the following examples: >cleartool getlog -around now 10 albd db vobrpc ccfs ======Log Name: albd Hostname: vobhost Date: 2011-10-09T10:23:16+08:00 Selection: Lines between 2011-10-09T10:08:16+08:00 and 2011-10-09T10:38:16+08:00 displayed ------2011-10-09T10:18:04+08 albd_server(1319118): Error: Server vobrpc_server (pid=2809890) on "/vob_store/VOBs/aaa.vbs" died on startup; marking it as "down". ======Log Name: db Hostname: vobhost Date: 2011-10-09T10:23:16+08:00 Selection: Lines between 2011-10-09T10:08:16+08:00 and 2011-10-09T10:38:16+08:00 displayed ------2011-10-09T10:11:35+08 db_server(880886): Error: albd_rgy_findbyuuid_entry call failed: RPC: Timed out 2011-10-09T10:11:35+08 db_server(880886): Error: Trouble contacting registry on host "vobhost": timed out trying to communicate with ClearCase remote server. 2011-10-09T10:11:35+08 db_server(880886): Error: Error searching for replica e49551ac.d21b11dc.a041.00:02:c3:0d:60:4c in registry: error detected by ClearCase subsystem 2011-10-09T10:11:46+08 db_server(1642540): Error: albd_server_idle call failed: RPC: Timed out 2011-10-09T10:11:46+08 db_server(1642540): Error: Error sending idle message to albd server: timed out trying to communicate with ClearCase remote server ======Log Name: vobrpc Hostname: vobhost Date: 2011-10-09T10:23:16+08:00 Selection: Lines between 2011-10-09T10:08:16+08:00 and 2011-10-09T10:38:16+08:00 displayed ------2011-10-09T10:13:09+08 vobrpc_server(1868278): Error: albd_sched_info call failed: RPC: Timed out 2011-10-09T10:14:19+08 vobrpc_server(2650278): Error: albd_sched_info call failed: RPC: Timed out 2011-10-09T10:14:41+08 vobrpc_server(1167414): Error: albd_server_busy call failed: RPC: Timed out 2011-10-09T10:15:17+08 vobrpc_server(3293642): Error: albd_sched_info call failed: RPC: Timed out 2011-10-09T10:15:26+08 vobrpc_server(1167414): Error: Unable to contact albd_server on host 'vobhost' 2011-10-09T10:15:26+08 vobrpc_server(1167414): Error: Operation "rgy_findbyuuid_entry" failed: timed out trying to communicate with ClearCase remote server. 2011-10-09T10:15:26+08 vobrpc_server(1167414): Error: Unable to get VOB object registry information for replica uuid "9d2d6700.862011dd.a055.00:02:c3:0d:60:4c" (vobhost:/vob_store/VOBs/aaa.vbs): error detected by ClearCase subsystem ======Log Name: ccfs Hostname: vobhost Date: 2011-10-09T10:23:16+08:00 Selection: Lines between 2011-10-09T10:08:16+08:00 and 2011-10-09T10:38:16+08:00 displayed ------2011-10-09T10:21:16+08 albd_server(1319118): Error: ccfs_server(1236996): Error: Unable to contact albd_server on host 'vobhost' 2011-10-09T10:21:16+08 albd_server(1319118): Error: ccfs_server(1236996): Error: Operation "rgy_findbyuuid_entry" failed: timed out trying to communicate with ClearCase remote server. 2011-10-09T10:21:16+08 albd_server(1319118): Error: ccfs_server(1236996): Error: Unable to get VOB tag registry information for replica uuid "faab7d68.bae411df.8043.00:02:c3:0d:60:4c": timed out trying to communicate with ClearCase remote server Cause The problem can caused by UDP buffer overrun as a result of too many ClearCase Roles for one machine and or a large inundation of UDP packets simultaneously or in a small time interval wherein the machine cannot handle such a load. In general, ClearCase scales best horizontally across multiple machines instead of vertically on a machine with massive resources. UDP packet communication of the albd server (registry server), VOB server, VIEW server, and credmap server. If the machine itself is not tuned appropriately or does not have enough resources to accept the scale of UDP packets that are delivered to it in enough time for it to be processed in the machine's UDP receive buffer, the UDP packet will be dropped. Environment VOB server, View Server, Registry server, License Server are configured in a single server. Page 24 of 341 ClearCase Environment – How do I Resolving the problem To relieve the issue, you can execute any of the following options Option 1: Increase UDP buffer on the receiving problem server machine Solaris example: ndd -set /dev/udp udp_max_buf 8388608 ndd -set /dev/udp udp_xmit_hiwat 65535 ndd -set /dev/udp udp_recv_hiwat 65535 AIX example: no -p -o udp_recvspace=655360 no -p -o sb_max=1310720 Reference: http://publib.boulder.ibm.com/infocenter/pseries/v5r3/index.jsp?topic=/com.ibm.aix.prftungd/ doc/prftungd/udp_recvspace.htm Option 2: Split ClearCase roles across multiple machines Use a separate dedicated, licence and or registry server Use a separate dedicated, VOB and or View server 17. How do I – understand about RPC services and ClearCase on UNIX and Linux This is a list of UDP and TCP services used by the ClearCase albd on UNIX and Linux in /opt/rational/clearcase/config/services/albd.conf Example: # U G # RPC I I # No. Ver. Proto D D Kind Ctl Params Service-Program # ------# 390513 3 udp,tcp - - shared - view_server 390514 3 udp - - shared - vob_server 390515 3 tcp - - reusable - db_server 390516 2 tcp - - shared - promote_server 390518 2 tcp - - schedule 5,0,5000000 vobrpc_server 390519 1 tcp - - shared - mntrpc_server 390520 1 tcp - - unshared - shipping_server 390521 1 udp - - shared - credmap_server 390522 1 tcp - - unshared - ws_helper 390523 1 tcp - - shared - admin_server 390524 1 tcp - - schedule 5,0,5000000 ctrack_server #390525 (reserved) 390526 1 tcp - - shared - host_agent 390527 1 tcp - - schedule 5,100,0 ccfs_server 390528 1 tcp - - reusable - ccfs_server 390529 1 tcp - - shared - msadm_server ClearCase does not use rpcbind. If the user types rpcinfo -p Note: NFS functionality is typically required in a UNIX/Linux environment, so a system administrator will have to set up NFS to work in the absence of rpcbind if it is desired to turn off the registration of RPC services. The albd_server must run on any ClearCase host on port 371. The entries albd 371/udp albd 371/tcp must be in the services database (either networked or local) on any ClearCase host, client or server. When albd_server gets a request for VOB or view services, a vob_server or view_server process is started that will listen on a TCP port or remain open on a UDP port. The port numbers are chosen by the Page 25 of 341 ClearCase Environment – How do I operating system except when limited to a certain range by a ClearCase environment variables (review technote 1207525 for more information). Communication over these ports is usually by RPC, except for file system requests for view/VOB storage (which may also employ RPC if those requests are over NFS). SUMMARY: RPC is required for ClearCase. The UNIX commands rpcinfo -n 371 -u Note: Only albd_server has a default port (371). Other ClearCase client/server ports are negotiated by the operating system as needed. ClearCase Registry 18. How do I - manually restoring the primary registry server files from backup What are the steps necessary to manually restore the IBM® Rational® ClearCase® primary registry server using the files stored on the backup registry server in the event rgy_switchover fails? Answer The primary method used to recover a registry server entails using the rgy_switchover command. The rgy_switchover command upgrades a backup registry server host to primary registry server host and resets ClearCase clients to use the new primary registry server host. Review the ClearCase Command Reference Guide on the topic of rgy_backup (cleartool man rgy_backup) for more information. These steps assume there is a backup registry server. The ClearCase Administrator's Guide explains how to properly setup a backup registry server host as well as provides steps on how to restore the ClearCase registry server from backup in the event the primary server is unavailable (with and without a backup registry server configured). This technote explains how to manually copy the files from the backup registry server to the new primary registry server in the event that rgy_switchover fails. Locate the backup registry server and the related registry server files. Microsoft® Windows® default locations: 7.1.x C:\Program Files\IBM\RationalSDLC\ClearCase 7.0.1 and earlier C:\Program Files\Rational\ClearCase\var\rgy\backup UNIX®/Linux® default locations: 2003.06 and later /var/adm/rational/clearcase/rgy/backup 2002.05 /var/adm/atria/rgy/backup Identify the last time the registry files were backed up by viewing the date-time stamp appended to the registry server files: Example: 2003.06.15 and later on Windows: C:\Program Files\Rational\ClearCase\var\rgy\backup>dir Volume in drive C is Primary Volume Serial Number is FCD4-3F71 Directory of C:\Program Files\Rational\ClearCase\var\rgy\backup 03/14/2006 08:30 AM
ClearCase Environment – How do I 03/14/2006 08:26 AM 105 bbase_tag.14-Mar-06.08.26.21= 03/14/2006 08:26 AM 84 client_list.db 03/14/2006 08:26 AM 1,614 client_list.db.14-Mar-06.08.26.21 03/14/2006 08:26 AM 80 ct_servers 03/14/2006 08:26 AM 105 ct_servers.14-Mar-06.08.26.21 03/14/2006 08:26 AM 77 dct_dbs 03/14/2006 08:26 AM 105 dct_dbs.14-Mar-06.08.26.21 03/14/2006 08:26 AM 77 domains 03/14/2006 08:26 AM 105 domains.14-Mar-06.08.26.21 03/14/2006 08:26 AM 77 regions 03/14/2006 08:26 AM 226 regions.14-Mar-06.08.26.21 03/14/2006 08:26 AM 81 site_config 03/14/2006 08:26 AM 164 site_config.14-Mar-06.08.26.21 03/14/2006 08:26 AM 82 storage_path 03/14/2006 08:26 AM 531 storage_path.14-Mar-06.08.26.21 03/14/2006 08:26 AM 81 view_object 03/14/2006 08:26 AM 1,707 view_object.14-Mar-06.08.26.21 03/14/2006 08:26 AM 78 view_tag 03/14/2006 08:26 AM 1,893 view_tag.14-Mar-06.08.26.21 03/14/2006 08:26 AM 80 vob_object 03/14/2006 08:26 AM 1,848 vob_object.14-Mar-06.08.26.21 03/14/2006 08:26 AM 77 vob_tag 03/14/2006 08:26 AM 1,763 vob_tag.14-Mar-06.08.26.21 27 File(s) 11,463 bytes 2 Dir(s) 25,057,800,192 bytes free
Example: 2002.05.00 on Windows: C:\Program Files\Rational\ClearCase\var\rgy\backup>dir Volume in drive C is C Volume Serial Number is 1855-0079
Directory of D:\rational\var\rgy\backup
02/11/00 06:48p
Note the differences between 2002.05 and 2003.06; there are more files in the registry in 2003.06.00 and later.
Regardless of the ClearCase version, the next steps are the same. Copy all the files with the date-time stamp (ignoring the others) from the backup server to the new primary registry server.
UNIX Example: Page 27 of 341
ClearCase Environment – How do I
Backup Server: /var/adm/rational/clearcase/rgy/backup Primary Server: /var/adm/rational/clearcase/rgy
Copy the files from the backup directory on the backup server to the rgy directory on the primary server.
Rename the files removing the time-date extension.
Example:
Rename the file regions.14-Mar-06.08.26.21 to regions
Restart the ClearCase services on the registry server to take effect. 19. How do I – get a non-root UNIX account to run rgy_passwd Attempts to update or change the ClearCase registry password to create public VOBs as a non-root use on UNIX and Linux results in the error: rgy_passwd: Error: Unable to open file "/var/adm/rational/clearcase/rgy/vob_tag.sec": Permission denied. After the rgy_passwd command is run for the first time by root, the file vob_tag.sec stored in /var/adm/atria/rgy is created.
If the ownership of this file is changed to a different account, that account may run the rgy_passwd command. Review the IBM Rational ClearCase Command Reference on the topic of rgy_passwd (cleartool man rgy_passwd) for more information.
Example: pwd /var/adm/atria/rgy ls -l vob_tag.sec -rw------1 root other 12 Oct 30 17:00 vob_tag.sec id uid=0(root) gid=1(other) chown jdoe vob_tag.sec ls -l vob_tag.sec -rw------1 jdoe other 12 Oct 30 17: ROOT can modify registry password. id uid=0(root) gid=1(other)
/usr/atria/etc/rgy_passwd Password: Owner of file can modify registry password: id uid=22823(jdoe) gid=20(user)
/usr/atria/etc/rgy_passwd Password: 20. How do I – understand the ClearCase commands that require a ClearCase registry password
The following ClearCase commands require a ClearCase registry password: Note: This password is not associated with operating system, and is used for restricting creation and removal of public objects. cleartool mktag -public cleartool mkvob -public rgy_passwd cleartool rmregion Page 28 of 341
ClearCase Environment – How do I cleartool rmtag –vob setsite 21. How do I – deal with the ClearCase 7.0.1 registry files on UNIX and Linux hosts moving from 'rgy' directory to the 'config' directory information about a behavior change introduced in IBM® Rational® ClearCase® version 7.0.1 which may cause scripts to fail on UNIX® and Linux® platforms when referencing the ClearCase registry files that have been relocated to a different directory.
This change was made in order to allow for ClearCase to work properly in a High-Availability (HA) environment. The decision was made that all configuration files within the ClearCase server should be located in a central location, and the new location is now /var/adm/rational/clearcase/config. Before the upgrade to 7.0.1: % cleartool -ver ClearCase version 7.0.0 (Fri May 05 12:38:05 EDT 2006) 7.0.0.0-RATL-RCC-IFIX02 (Wed Oct 04 11:28:35 EDT 2006) 7.0.0.1-RATL-RCC (Fri Dec 08 12:13:03 EST 2006) 7.0.0.1-RATL-RCC-RWP-IFIX01 (Fri Mar 23 13:02:12 EDT 2007) 7.0.0.1-RATL-RCC-IFIX03 (Mon Jun 18 14:29:40 EDT 2007) @(#) MVFS version 7.0.0.1-IFIX03 (Fri Apr 13 06:36:57 2007) cleartool 7.0.0.1-IFIX03 (Fri Apr 27 00:18:56 EDT 2007) db_server 7.0.0.1-IFIX03 (Fri Apr 27 00:10:46 EDT 2007) VOB database schema version: 54
% pwd /var/adm/rational/clearcase/rgy
% ls -al |grep .conf -rw-r--r-- 1 root other 8 Jul 10 10:45 rgy_hosts.conf -rw-r--r-- 1 root other 5 May 31 12:04 rgy_region.conf -rw-r--r-- 1 root other 7 Sep 12 2006 rgy_svr.conf -rw-rw-r-- 1 root other 202 Sep 12 2006 site_config
% cd ../config
% ls -al total 80 drwxr-xr-x 2 root other 512 Jun 27 15:32 . drwxr-xr-x 15 root other 512 Jul 13 17:12 .. -r-xr-xr-x 1 root other 1019 Sep 12 2006 admin.conf -r-xr-xr-x 1 root other 3447 Feb 4 2004 albd.conf -r-xr-xr-x 1 root other 10666 Dec 29 2005 config.pl -rw-rw-r-- 1 root other 8 Jun 27 15:32 license_host -r-xr-xr-x 1 root other 2794 Oct 22 2004 ms_albd.conf -r--r--r-- 1 root other 996 Jun 27 15:32 msweb.conf -r--r--r-- 1 root other 659 Mar 6 2000 rfm_shipping.conf -r-xr-xr-x 1 root other 9530 Dec 31 2002 shipping.conf -rw-rw-r-- 1 root other 107 Jun 27 15:32 snapshot.conf -r-xr-xr-x 1 root other 5116 Oct 22 2005 vob_scrubber_params After the upgrade: % cleartool -ver ClearCase version 7.0.1 (Wed May 30 16:29:44 EDT 2007) @(#) MVFS version 7.0.1.0 (Wed Apr 11 21:42:52 2007) cleartool 7.0.1.0 (Tue May 15 10:10:24 EDT 2007) db_server 7.0.1.0 (Tue May 15 10:08:56 EDT 2007) VOB database schema version: 54
% pwd /var/adm/rational/clearcase/config
% ls -al |grep .conf -r--r--r-- 1 root root 1019 Jul 10 13:20 admin.conf -rw-r--r-- 1 root root 3447 Sep 1 2005 albd.conf -r--r--r-- 1 root root 2794 Sep 1 2005 ms_albd.conf -r--r--r-- 1 root root 996 Jul 10 17:40 msweb.conf Page 29 of 341
ClearCase Environment – How do I -r--r--r-- 1 root root 659 Mar 6 2000 rfm_shipping.conf -rw-r--r-- 1 root root 8 Jul 10 17:37 rgy_hosts.conf -rw-r--r-- 1 root root 5 Jul 10 17:37 rgy_region.conf -rw-r--r-- 1 root root 7 Jul 10 17:37 rgy_svr.conf -r--r--r-- 1 root root 9530 Dec 31 2002 shipping.conf -rw-rw-r-- 1 root root 107 Jul 10 17:37 snapshot.conf
% cd ../rgy
% ls -al total 34 drwxr-xr-x 3 root root 512 Jul 13 04:30 . drwxr-xr-x 15 root root 512 Jul 17 06:26 .. drwxr-xr-x 2 root root 512 Jul 13 04:30 backup -rw-rw-r-- 1 root root 102 Jul 10 16:02 bbase_object -rw-rw-r-- 1 root root 102 Jul 10 16:02 bbase_tag -rw-rw-r-- 1 root root 102 Jul 10 16:02 ct_servers -rw-rw-r-- 1 root root 102 Jul 10 16:02 dct_dbs -rw-rw-r-- 1 root root 102 Jul 10 16:02 domains -rw-rw-r-- 1 root root 203 Jul 10 16:02 regions -rw-rw-r-- 1 root root 102 Jul 10 16:02 site_config -rw-rw-r-- 1 root root 102 Jul 10 16:02 storage_path -rw-rw-r-- 1 root root 463 Jul 12 10:25 view_object -rw-rw-r-- 1 root root 498 Jul 12 10:25 view_tag -rw-r--r-- 1 root root 976 Jul 12 10:33 vob_object -rw-r--r-- 1 root root 1116 Jul 12 10:33 vob_tag -rw------1 root root 12 Jul 12 10:30 vob_tag.sec You will need to modify your scripts to reference the new path. 22. How do I - set or change the ClearCase registry password To set the registry password or if it needs to be changed, use the rgy_passwd utility to make the changes.
Review IBM Rational ClearCase Command Reference on the topic of rgy_passwd (cleartool man rgy_passwd) for more information.
Note: Changing the registry password will not affect any of the currently registered public VOBs. The change will only affect new VOBs that are publically registered. Special considerations:
Running rgy_passwd will create or edit the vob_tag.sec in the /var/adm/atria/rgy/ directory on UNIX and Linux. If the vob_tag.sec file does not exist, you must be root to run the rgy_passwd command. If the vob_tag.sec file exists, you must be the owner of that file. Review related technote below for more information. 23. How do I – understand how a non-root UNIX account can run rgy_passwd Attempts to update or change the ClearCase registry password to create public VOBs as a non-root use on UNIX and Linux results in the error: rgy_passwd: Error: Unable to open file "/var/adm/rational/clearcase/rgy/vob_tag.sec": Permission denied. After the rgy_passwd command is run for the first time by root, the file vob_tag.sec stored in /var/adm/atria/rgy is created.
If the ownership of this file is changed to a different account, that account may run the rgy_passwd command. Review the IBM Rational ClearCase Command Reference on the topic of rgy_passwd (cleartool man rgy_passwd) for more information.
Example: pwd /var/adm/atria/rgy ls -l vob_tag.sec Page 30 of 341
ClearCase Environment – How do I -rw------1 root other 12 Oct 30 17:00 vob_tag.sec id uid=0(root) gid=1(other) chown jdoe vob_tag.sec ls -l vob_tag.sec -rw------1 jdoe other 12 Oct 30 17: ROOT can modify registry password. id uid=0(root) gid=1(other)
/usr/atria/etc/rgy_passwd Password: Owner of file can modify registry password: id uid=22823(jdoe) gid=20(user)
/usr/atria/etc/rgy_passwd Password: 24. How do I – understand the computer is not a valid registry server problem The error may be caused by an incorrect registry hostname being set on the ClearCase client or the registry file on the registry server may be missing or corrupted.
Resolving the problem Note: When following the instructions below keep in mind that on Unix and Linux hosts running ClearCase version 7.0.1 and later the registry files are located in /var/adm/rational/clearcase/config Refer to technote 1265395 ClearCase 7.0.1 registry files on UNIX and Linux moved from 'rgy' to 'config' for further information about this change. UNIX/LINUX CLIENT Make sure that the correct registry server name is specified in the rgy_hosts.conf file on the client host from which the cleartool command has been executed:
cd /var/adm/atria/rgy cat rgy_hosts.conf
UNIX/LINUX SERVER Nonexistent or corrupted rgy_svr.conf file on the registry server host itself.
The rgy_svr.conf file on the registry host is what informs ClearCase that it is a registry host. The file should exist in the /var/adm/atria/rgy directory on the registry host, and it should contain the word master.
If this file does not exist, create it.
If the file exists but does not contain the word master, edit the file and add the keyword master. WINDOWS CLIENT Make sure that the correct registry server name is specified in the ClearCase Control Panel on the client from which the cleartool command has been executed. The "Use registry server on host" radio button ought to be selected with a valid host name in the box.
Page 31 of 341
ClearCase Environment – How do I
WINDOWS SERVER Make sure that the registry server points to itself in the ClearCase Control Panel by selecting the "Use local host as registry server" radio button.
25. How do I - Improve lsview -host and lsvob -host performance Using the new -quick option with the cleartool lsview -host and cleartool lsvob -host commands will provide faster look-up by listing views or VOBs as currently stored in the ClearCase registry.
Note: Physical storage is not examined, and aliases and IP addresses are not resolved. Therefore, changes that occurred since a view's creation may not be reflected in the listing.
Usage: lsview [-short | -long] [-host hostname [-quick]] [-properties [-full | -text_mode] | -age] [-region 'network-region-pattern'] [-cview | 'view-tag-pattern' ... | -storage view-storage-pname ... | -uuid view-uuid] Example: cleartool lsview –host
ClearCase Environment – How do I
Note: The look-up of entries is case-sensitive.
Example: Same command differing by case will result in different outputs. %>cleartool lsview -host host1 -quick test_view \\host1\ccstg_e\views\jdoe\test_view.vws
%>cleartool lsview -host HOST1 -quick
ENVIRONMENT VARIABLE Setting the CLEARCASE_RGY_QUICK environment variable causes the cleartool lsview -host or cleartool lsvob –host commands to use the -quick functionality by default.
For example, by setting this environment variable you can change the run-time behavior of -host in scripts without modifying the scripts.
The environment variable can be set to any value to turn on this behavior (example: CLEARCASE_RGY_QUICK=1) or unsetting the variable turns off the quick look-up option.
Note: The -host option used in conjunction with the CLEARCASE_RGY_QUICK environment variable will have no effect if the -region option is also used and the region is specified with a wildcard.
Example: cleartool lsview –host
For more information on CLEARCASE_RGY_QUICK or any of the ClearCase environment variables, refer to IBM Rational ClearCase Command Reference, or run cleartool man env_ccase. MVFS 26. How do I – understand why the ClearCase start script prevents MVFS from being unloaded from kernel under some conditions Under certain conditions, the ClearCase startup script may prevent MVFS from being removed from the kernel when stopping ClearCase, if the ClearCase startup script was run more than once on a Linux host while ClearCase was running. The following error is reported: ERROR: Module mvfs is in use Trouble unloading the mvfs module(8:1)
Cause Rational ClearCase start script prevents MVFS from being unloaded from Linux kernel. This issue has been identified as a product defect under APAR PK87459.
Diagnosing the problem Example of how to reproduce the issue: 1) Run the ClearCase start script:
/usr/atria/etc/clearcase start [root]# /usr/atria/etc/clearcase start ClearCase daemons: albd_server Mounting public VOBs...
2) Now, issue the startup script again:
[root]# /usr/atria/etc/clearcase start ClearCase daemons: albd_server mount_mvfs: File exists Trouble mounting the viewroot "/view"(16:29) Mounting public VOBs...
3) Now, try and stop ClearCase: Page 33 of 341
ClearCase Environment – How do I
[root]# /usr/atria/etc/clearcase stop Unmounting VOBs... ERROR: Module mvfs is in use Trouble unloading the mvfs module(8:1)
Resolving the problem A reboot of the server will clear the issue,
The defect has been resolved in ClearCase 7.0.0.8 and 7.0.1.7 WORKAROUND The only way to workaround this issue is to not use the /usr/atria/etc/clearcase start command more than once. 27. How do I – understand about the MVFS cache values in ClearCase Control Panel and cleartool getcache Why would there be a discrepancy between the IBM® Rational® ClearCase® MVFS Scaling Factor reported in the ClearCase Control Panel on Microsoft® Windows® as compared to that reported by cleartool getcache -mvfs?
Cause Attempts to view the MVFS cache on Windows from the command line reveals different results than that of the MVFS Performance tab in the ClearCase Control Panel. Example:
Issue the following command from a command prompt on Windows: cleartool getcache -mvfs
Note the values that are returned in the following rows: Mnode freelist
Cltxt freelist
DNC: Files
DNC: Directories
DNC: ENOENT
RPC handles
Readdir block cache size
MVFS scaling factor Example: C:\>cleartool getcache -mvfs Mnodes: (active/max) 3/12288 (0.024%) Mnode freelist: 0/1800 (0.000%) Cltxt freelist: 0/1800 (0.000%)
DNC: Files: 0/2400 (0.000%) Directories: 0/600 (0.000%) ENOENT: 0/2400 (0.000%)
RPC handles: 0/15 (0.000%)
Current MVFS cache enable settings: Attribute cache: enabled Close-to-open revalidation: enabled Name cache: enabled Readlink cache: enabled Root version cache: enabled VOB freelist low-water mark: 1620 Cleartext freelist low-water mark: 1672 Page 34 of 341
ClearCase Environment – How do I Readdir block cache size: 6 MVFS scaling factor: 2
Attribute cache miss summary (for tuning suggestions, see the documentation for administering ClearCase): Attribute cache total misses: 0 (100.00%)
Compare the output to that which is identified in the ClearCase Control Panel applet and note the differences.
Why is the output different?
Answer The MVFS Performance tab of the ClearCase Control Panel applet is an interface for changing the persistent-only MVFS cache settings. In other words, it represents the values which have been set to persist across MVFS restarts.
To see the values of the of the persistent cache as identified in the ClearCase Control Panel applet, issue the command cleartool getcache -mvfs -persistent Example: C:\>cleartool getcache -mvfs -persistent Persistent MVFS tunable values: MVFS scaling factor: 1 VOB freelist size: 1800 Cleartext freelist size: 1800
Note: The values returned by cleartool getcache -mvfs -persistent will only display the scaling factor and the values of the items that have the Override option checked in the Control Panel applet. The Control Panel Applet calculates and displays the (non-override) values that will be used based on the scaling factor.
The values returned from the command cleartool getcache -mvfs reflect the actual (live) cache.
Note: The value of "MVFS scaling factor" reported by cleartool getcache -mvfs is not really an actual value. It is the value at the time of the last reboot. Scaling factor is only ever used in the "persistent" context.
If an administrator has entered cleartool setcache -mvfs or cleartool setcache -mvfs -persistent_only or
Page 35 of 341
ClearCase Environment – How do I modified the Control Panel values since the last reboot, then the live cache values will not match the persistent cache values.
Review the IBM Rational ClearCase Command Reference Guide on the topic of getcache (cleartool man getcache) for more information. 28. How do I – why the iInstallation of ClearCase 7.1 fails during post- install phase and logs MVFS errors: Trouble mounting the viewroot "/view" This technote explains how to resolve an issue that can occur where installing IBM Rational ClearCase (CC) 7.1 fails during the post-install phase and reports MVFS errors: Trouble mounting the viewroot "/view" when installing on a host that had a previous ClearCase version installed .
Symptom Attempts to install ClearCase 7.1 on a server that was previously running with ClearCase version 7.0.1 is failing in the post-install phase. After the previous version of ClearCase was removed, InstallationManager keeps failing at the post install phase with the following errors in the logs:
Error occurred in phase: post-install configure SU: com.ibm.rational.clearcaseunix.last.sun5 1.0.0.00-7- 1-D081104 IU: last.sun5 null->999.999.999.-75020128 Message: Error executing "/opt/IBM/RationalSDLC/clearcase/etc/clearcase" operation (status=50). See agent output log for more information: /var/ibm/InstallationManager/logs/native/20090109_0940.log and then this:
Error during "post-install configure" phase: Error executing "/opt/IBM/RationalSDLC/clearcase/etc/clearcase" operation (status=32). See agent output log for more information: /var/ibm/InstallationManager/logs/native/20090109_0940a.log Error executing "/opt/IBM/RationalSDLC/clearcase/etc/clearcase" operation (status=50). See agent output log for more information: /var/ibm/InstallationManager/logs/native/20090109_0940.log
/var/ibm/InstallationManager/logs/native/20090109_0940.log contained:
ClearCase daemons: albd_server Loading MVFS ... mount: Operation not applicable to FSType mvfs Trouble mounting the viewroot "/view"(16:1) mvfslog: Error: The MVFS file system is not installed or not loaded, or the 'viewroot' is not mounted or is inaccessible: not a ClearCase object. Trouble setting MVFS kernel log file to /var/adm/rational/clearcase/log/mvfs_log(2:1) Mounting public VOBs... cleartool: Error: The MVFS file system is not installed or not loaded, or the 'viewroot' is not mounted or is inaccessible: not a ClearCase object. Trouble mounting public VOBs(32:1)
Cause Remnants of a previous installation of MVFS can interfere with the install process.
This problem may occur if MVFS is not completely cleaned out from a previous installation.
Resolving the problem
1. Check to see if the process is still running:
As root run: #modinfo | grep -i mvfs
If it returns something like the following: 114 780ca000 42353 18 1 mvfs (IBM/Rational MultiVersion Files)
then you need to unload the module: (the first number is the id of the module (in this case 114) ) # modunload -i 114 Check to see if the mvfs link or directory still exist from a previous ClearCase installation: ls -l /usr/lib/fs/mvfs/mount also check if the directory /usr/lib/fs/mvfs
Page 36 of 341
ClearCase Environment – How do I
If either of these exist, delete them. 29. How do I – understand why you are unable to load MVFS on UNIX or Linux after install MVFS not starting following installation on UNIX or Linux hosts and errors are reported in the install log. The following is an example of an entry reported in the ClearCase install log on a server named host1: mount: Error: Unable to get hostinfo for 'host1' Trouble mounting the viewroot "/view"(16:1) mvfslog: Error: The MVFS file system is not installed or not loaded, or the 'viewroot' is not mounted or is inaccessible: not a ClearCase object. Trouble setting MVFS kernel log file to /var/adm/rational/clearcase/log/mvfs_log(2:1) Mounting public VOBs... cleartool: Error: The MVFS file system is not installed or not loaded, or the 'viewroot' is not mounted or is inaccessible: not a ClearCase object. Trouble mounting public VOBs(32:1)
Cause ClearCase determines the server's name using the uname -n call. Other common processes (sendmail, for example) use the same approach and will often leave entries in /var/log/messages, /var/log/syslog or the equivalent file called by the dmesg command. The cause of this problem relates to the hostname of the computer not being set as the first entry after the IP address in the /etc/hosts file.
Resolving the problem Make the server name the first entry after the IP address in /etc/hosts. Note: Consult your operating system manual page for uname to get more details on server host name conventions. Example: Note: In this example, the server name is host1 (a Solaris machine): Original entry in the /etc/hosts file: 127.0.0.1 localhost 9.10.11.12 loghost
Note: Solaris uses a separate file /etc/hosts.
Change the second line to read as follows: 127.0.0.1 localhost 9.10.11.12 host1 loghost
Note: On Linux, a typical entry is only one line. In this example, the server is named host2 and the configuration is correct:
127.0.0.1 host2 host2.ibm.com localhost.localdomain localhost
Reboot the server. The error at this point will be resolved and the MVFS will load correctly.
You can also check /etc/nsswitch.conf and see what order the lookup is. If it is NIS files, ypcat the hosts file and grep for the system name. Once the system is entered into the NIS host map file, ClearCase will come right up 30. How do I – understand why a ClearCase installation on Linux x86 fails because MVFS cannot be loaded. The IBM Rational ClearCase installation on Linux x86 does not rollback when MVFS cannot be rebuilt using the kernel source.
Symptom The Rational ClearCase installation fails with the errors listed below. Rebuilding of mvfs module with your kernels symbol exports failed. You must rebuild the mvfs module by hand in directory {0} (see README.txt in that directory) and run make install. Error executing "/opt/ibm/RationalSDLC/clearcase/etc/clearcase" operation (status=8). See agent output log for more information
Cause The Rational ClearCase startup script returns a non-zero value while trying to load MVFS. Page 37 of 341
ClearCase Environment – How do I
Resolving the problem To work around this issue, take the following steps before installing Rational ClearCase on Linux x86: 1. Create an empty file at /var/adm/rational/clearcase/no_mvfs_tag.
2. Rebuild MVFS after the installation completes successfully. After MVFS has been rebuilt, delete /var/adm/rational/clearcase/no_mvfs_tag 31. How do I – understand about the MultiVersion File System (MVFS) The MultiVersion File System (MVFS) creates a virtual file system specifically designed for accessing data within a Rational ClearCase VOB.
The MVFS works similarly to UNIX® Network File System (NFS), in that it loads a kernel driver that presents a file system to the user through a standard interface within the Windows, UNIX or Linux kernel.
When you start a view and mount a VOB, remote procedure calls (RPC) are made to the view to determine which cleartext files should be presented to the user.
After the MVFS gets a file name and caches it, the operating system (OS) opens a call to the underlying file system where the view or the VOB storage directory resides.
The MVFS runs in the operating system kernel and cannot be stopped or started independently of the OS. Thus, to stop and restart the MVFS on UNIX, Linux or Windows, you must shut down and restart the computer.
The MVFS extends the host’s native operating system to provide file system support for dynamic views. A dynamic view is an MVFS directory that enables dynamic access to VOB elements. Dynamic views use the MVFS to present a selected combination of local and remote files as if they were stored in the native file system.
Notes: Rational ClearCase LT does not support MVFS. Both Snapshot and Web views do not use the MVFS. Here are some distinct and similar MVFS capabilities on Windows versus UNIX or Linux.
UNIX and Linux
On any UNIX or Linux host where the MVFS is installed: The /view directory functions as the mount point for the MVFS namespace. The code that implements the MVFS is (statically or dynamically) linked with a host’s operating system, and how the MVFS is linked depends on the type and version of the operating system. The MVFS on UNIX and Linux is always case-sensitive; it always uses case-sensitive file look-up and does no case conversion. File names that include these characters are recognized by the MVFS on UNIX and Linux: ? * / \ | < > A UNIX or Linux host can export a view-extended path name to some VOB mount point (for example, /view/exportvu/vobs/vegaproj) to allow non-ClearCase read-only access from a host that does not have Rational ClearCase installed. The supported file types are Files, Directories and Symbolic links. You cannot create other file types, such as UNIX special files, within a dynamic view. Microsoft Windows
On a Windows client with MVFS installed: Each dynamic view appears as a share under a special network name (\\view, by default) as well as a directory under the client’s MVFS drive (drive M, by default). The MVFS is a file system driver that is loaded by the Service Control Manager at system start up. The MVFS logs error and status messages to the file C:\mvfslogs. You can use the MVFS tab in the ClearCase program in Control Panel to change this path name. The MVFS can be configured to support various case-sensitivity and case-preservation options since the native Windows file system is case-insensitive and case-preserving, and performs case-insensitive file look-up. File names that include these characters are not recognized by the MVFS on Windows (and cannot be loaded into a Windows snapshot view): ? * / \ | < > The supported file types are Files and Directories. 32. How do I – run MVFS Debugging MVFS debugging may be necessary for a problem concerning data access, or execution of programs inside of the MVFS when execution of the same program outside of the MVFS works as expected. These types of situations are often related to unexpected data access calls that fail. It is often possible that such situations can be corrected once understood.
Page 38 of 341
ClearCase Environment – How do I Turning on MVFS debugging may provide information that will assist IBM Rational Customer Support in determining the problem. This information is very useful for troubleshooting, especially if the problem cannot be reproduced.
ABOUT MVFSLOG: The mvfslog utility is stored in the following directory:
Windows: C:\Program Files\Rational\ClearCase\bin UNIX/Linux: opt/rational/clearcase/etc
USAGE: Usage: mvfslog [debug | error | info | none | stale | warning] EXAMPLES: UNIX/Linux: bash-2.03# /opt/rational/clearcase/etc/mvfslog error Log priority: error vops mask: 0x00000000 vfsops mask: 0x00000000 xops mask: 0x00000000 traps mask: 0x00000000 Kernel logfile: "/var/adm/rational/clearcase/log/mvfs_log" Windows: %>mvfslog debug -irpops 0x7fff log priority: debug irpops mask: 0x7fffffff vops mask: 0x00000000 vfsops mask: 0x00000000 xops mask: 0x00000000 traps mask: 0x00000000 Kernel logfile: "C:\mvfslogs\19990201.log"
Note: The value irpops is only for the Windows MVFS. INSTRUCTIONS: To turn on MVFS debugging: 1. Log in as root or Administrator 2. Start and set into a view, mount the VOB and navigate to the location needed to reproduce the problem. 3. Turn on MVFS debugging in another command window: Note: On UNIX/Linux run the command: %> mvfslog debug Note: On Windows run the command: %> mvfslog debug -irpops 0x7fff 4. Reproduce the problem Note: Operations run with MVFS debug turned on will take significantly longer than usual. Do not turn off MVFS debug until the disk writes stop. 5. Turn MVFS debugging off:
Note: On UNIX/Linux run the command: %> mvfslog error
Note: On Windows run the command: %> mvfslog error -irpops 0x00000000 6. MVFS debug output is logged in: Windows: C:\mvfslogs (default) UNIX/Linux: /var/adm/rational/clearcase/log/mvfs_log (default)
The complete explanation of the problem with exact operations that were performed while tracing was enabled, and the MVFS debug output should be supplied when you contact IBM Rational Customer Support. Review the IBM Rational ClearCase Command Reference Guide on the topic of mvfslog (cleartool man mvfslog) for more information. 33. How do I – understand about cleartext lookup and flushing the mvfscache The following intermittent errors can printed in the MVFS logs after attempting to read certain files stored in a VOB using a dynamic view: Page 39 of 341
ClearCase Environment – How do I
Example: 45584c8a mvfs: Error: cleartext lookup view=view1 vob=/vobs/vob1 dbid=0x5c353 - No such file or directory 45584c8a mvfs: Error: cleartext pname= /net/host1/vobstore/vob1.vbs/c/cdft/11/18/6deaffe54eff11db9834000180c99fde 45584d25 mvfs: Error: cleartext lookup view=view1 vob=/vobs/vob1 dbid=0x2a029 - No such file or directory 45584d25 mvfs: Error: cleartext pname= /net/host1/vobstore/vob1.vbs/c/cdft/2b/26/1486ee8cd9a511d88cbd000180c9a19b jdoe@host2:/vobs/vob1/dir1> more foo.c foo.c: No such device or address 5584dab mvfs: Error: cleartext pname= /net/host1/vobstore/vob1.vbs/c/cdft/8/3e/12436513601111db981f000180c99fde 45584dba mvfs: Error: cleartext lookup view=view1 vob=/vobs/vob1 dbid=0x5fd9e - No such file or directory 45584dba mvfs: Error: cleartext pname= /net/host1/vobstore/vob1.vbs/c/cdft/8/3e/12436513601111db981f000180c99fde
The MVFS cache on the client has a record for cleartext that exists in the VOB storage and when the view attempts to use the cleartext in the location specified by the cache, it finds "no such file or directory" in the VOB storage. This means the MVFS cache may not have refreshed properly.
Solution Verify if cleartext actually exists for the element in the VOB storage area.
Example: Using the path from the error above: Navigate to the path in the VOB storage area: /net/host1/vobstore/vob1.vbs/c/cdft/8/3e See if the file 12436513601111db981f000180c99fde exists in the directory. If cleartext does not exist in the path specified in the error, you have two options: 1. Unmount and remount the VOB. Then attempt to access the file. Note: Unmounting a VOB can be a big deal if there are a lot of users. If this is the case or if unmounting/remounting the VOB is known to resolve the problem and the cleartext doesn't exist, try flushing the mvfscache on the client. It is a far simpler solution. 2. Flush the MVFS cache using the following syntax: %>mvfscache -f mnode,name Review the ClearCase Administrator's Guide on the topic of Improving client host performance under the section Reference information for more details about mvfscache. 34. How do I – understand the MVFS Scaling Factor on Windows Attempts to view the MVFS cache on Windows from the command line reveals different results than that of the MVFS Performance tab in the ClearCase Control Panel.
Example: Issue the following command from a command prompt on Windows: cleartool getcache -mvfs Note the values that are returned in the following rows: Mnode freelist Cltxt freelist DNC: Files DNC: Directories DNC: ENOENT RPC handles Readdir block cache size MVFS scaling factor Example: C:\>cleartool getcache -mvfs Mnodes: (active/max) 3/12288 (0.024%) Mnode freelist: 0/1800 (0.000%) Cltxt freelist: 0/1800 (0.000%)
DNC: Files: 0/2400 (0.000%) Directories: 0/600 (0.000%) Page 40 of 341
ClearCase Environment – How do I ENOENT: 0/2400 (0.000%)
RPC handles: 0/15 (0.000%)
Current MVFS cache enable settings: Attribute cache: enabled Close-to-open revalidation: enabled Name cache: enabled Readlink cache: enabled Root version cache: enabled VOB freelist low-water mark: 1620 Cleartext freelist low-water mark: 1672 Readdir block cache size: 6 MVFS scaling factor: 2
Attribute cache miss summary (for tuning suggestions, see the documentation for administering ClearCase): Attribute cache total misses: 0 (100.00%)
Compare the output to that which is identified in the ClearCase Control Panel applet and note the differences.
Q: Why is the output different?
A: The MVFS Performance tab of the ClearCase Control Panel applet is an interface for changing the persistent-only MVFS cache settings. In other words the values which have been set to persist across MVFS restarts.
The values returned from the command cleartool getcache -mvfs reflect the actual (live) cache.
Q: Why is the scaling factor from the command cleartool getcache -mvfs different?
A: Since the mvfs cache will change depending on usage, the values indicated in the actual cache will reflect what the scaling factor would be if set to that value.
For example, the above cleartool getcache -mvfs output reflects the following values:
DNC: Files: 0/2400 (0.000%) Directories: 0/600 (0.000%) ENOENT: 0/2400 (0.000%)
RPC handles: 0/15 (0.000%)
Readdir block cache size: 6
If the scaling factor in the control panel where changed to 2, the values in these rows would initialize at Page 41 of 341
ClearCase Environment – How do I the level indicated in the actual cache.
Example:
Solution To see the values of the of the persistent cache as identified in the ClearCase Control Panel applet, issue the command cleartool getcache -mvfs -persistent
Example:
C:\>cleartool getcache -mvfs -persistent Persistent MVFS tunable values: MVFS scaling factor: 1 VOB freelist size: 1800 Cleartext freelist size: 1800
Review the ClearCase Command Reference Guide on the topic of getcache (cleartool man getcache) for more information.
Note: The values returned by cleartool getcache -mvfs -persistent will only display the values of the items that have the Override option checked.
35. How do I – Understand the invalid MSDOS Function error on Windows copying a file from a UNIX or Linux VOB When copying files from a dynamic view in Windows Explorer to a location on the local filesystem (or outside of a ClearCase view), the following error occurs:
Invalid MSDOS function
In the ClearCase error logs, several errors similar to the following are seen:
Null VOB handle passed to libvob routine.
Internal Error detected in "./..\map_db.c" line 528
Note: This occurs intermittently, and for different files with different users.
This problem is in the Windows to UNIX or Linux interoperation environment. The mnode settings are set higher than 800 for the client machines in question.
Solution Adjust the mnode settings as follows: Page 42 of 341
ClearCase Environment – How do I Go to Start (> Settings) > Control Panel > double-click the ClearCase icon > click the MVFS Performance tab:
If the value in either of the following fields is set to a value higher than 800, change the existing value to 800 and reboot: Maximum number of mnodes to keep on the VOB free list Maximum number of mnodes to keep on the cleartext free list
36. How do I - install or uninstall the MVFS on Windows Installing ClearCase 7.0 or later results in an error "Install failed" at the end of the install.
Clicking OK to dismiss the error dialog displays the installation complete dialog and the system then restarts as expected.
Upon restart, the MVFS is not installed, however the rest of the ClearCase application appears to have been installed as expected In ClearCase 7.0 there now exists a new executable called installmvfs.exe in the
The intended use of this application is to combat problems that may result during installations where the Page 43 of 341
ClearCase Environment – How do I MVFS does not get installed at all or is not properly installed.
If the MVFS is not installed, this executable can be used without any impact to the rest of the ClearCase application.
This utility can also be used to uninstall the MVFS by using the /u parameter from the command line.
Example:
See technote 1230196 for more information About the MultiVersion File System (MVFS). 37. How do I – known the limitations for the MVFS on Microsoft Windows On Windows, the MVFS has the following known limitations: 1. File attributes on elements such as System and Hidden are not supported.
2. OS/2 Extended Attributes are not supported.
3. DOS sharing modes are not supported.
4. If your application queries an MVFS volume for the amount of disk space, the MVFS always returns the value 500 MB. Review technote 1130333 for more details. Alternate, or short (8.3-compliant), names are not supported in a VOB name space. Any alternate name may already exist in another version of the given directory, which could cause Rational ClearCase to return the wrong file data, so the MVFS does not return an alternate name to applications that request one. 38. How do I - rebuild the mvfs module for use with ClearCase 7.0.x This technote contains information about how to rebuild the mvfs module for use with ClearCase 7.0.x.
If you are running a Linux kernel that is compatible with one of the pre-built sets of modules, you should not need to rebuild the modules. Use the binary versions shipped in this release instead (this is the default option during the install). Refer to the README.txt file (/var/adm/rational/clearcase/mvfs/mvfs_src/README.txt) which covers the following: REBUILD INSTRUCTIONS for ClearCase 7.0 on 2.4 series Linux kernels (SLES8, RHEL3) REBUILD INSTRUCTIONS for ClearCase 7.0 on 2.6 series Linux kernels (SLES9, RHEL4) If you try to load an mvfs module that should match your kernel revision, but see errors like the following, you need to rebuild your mvfs module:
/lib/modules/fs/mvfs.o: unresolved symbol d_rehash_0680a5aa /lib/modules/fs/mvfs.o: unresolved symbol d_alloc_054621f7 /lib/modules/fs/mvfs.o: unresolved symbol __mntput_def2fc0a /lib/modules/fs/mvfs.o: unresolved symbol inode_setattr_e5f5e28a
Instructions for rebuilding the kernel module can be found in the "IBM Rational ClearCase and IBM Rational ClearCase Multisite: Installation Guide" manual /opt/rational/clearcase/doc/books/cpf_install.pdf). 39. How do I – understand why Rebuilding of MVFS modules with kernel symbol exports fails but installation of ClearCase is successful Using pre-built MVFS modules that are not compatible with the kernel results in the failure of MVFS to load after a successful installation of IBM Rational ClearCase.
Cause When the pre-built MVFS modules are not compatible, the installation process automatically tries to rebuild the kernel from the kernel sources on the machine. When the kernel sources are not available, the installation completes successfully but MVFS does not load. The installation log files contain an error similar to:
400 ERROR
ClearCase Environment – How do I valid: "/lib/modules/2.6.9-67.ELsmp/build" 402 ERROR
This issue can also occur when you install MVFS on a machine that has an unsupported kernel level.
Resolving the problem To work around this issue, check that your kernel version is supported. If it is not supported, switch to a supported version and manually rebuild the kernel. For Red Hat systems, you can obtain the necessary files by installing the kernel-devel RPM package that corresponds to the operating system.
For information on rebuilding the MVFS module, see /var/adm/rational/clearcase/mvfs/mvfs_src/README.txt.
40. How do I – configure the MVFS settings for use with eclipse based Rational products and dynamic views What MVFS settings are needed when using IBM® Rational® ClearCase® (CC) dynamic views with Eclipse based Rational products, such as IBM Rational Software Analyzer, IBM Rational Systems Developer, and IBM Rational Application Developer for WebSphere® Software?
Answer Eclipsed based clients are case sensitive and the Multiversion File System (MVFS) may not necessarily be configured, as such. When using dynamic views with IBM’s desktop product line (RSA, RSD, RAD) and the ClearCase SCM Adapter on Microsoft® Windows® systems, it is essential to have the correct letter-case parameters set for the MVFS. Otherwise, there will be detrimental side effects that will prevent certain features of the SCM Adapter and the Eclipse-based products from functioning properly.
Example: A new file is created from within a dynamic views without the case preserving option checked in the MVFS settings. The file will be reduced to all lower case. If the file is then checked out from an eclipse based client, eclipse will send a case sensitive path to ClearCase which will be unable to find the file.
To prevent this type of behavior you need to ensure that your MVFS settings are configured as shown in the example below. You can modify these setting in the ClearCase control panel.
Note: If you change any settings in the MVFS settings, you will need to reboot your Windows client for the change to take effect.
LDAP & Active Directory 41. How do I – understand the support Policy for LDAP and ClearCase About LDAP: LDAP is a free directory sharing protocol that runs over TCP/IP (Transmission Control Protocol/Internet Protocol). You can configure applications to authenticate users through an LDAP Directory Server. It's a protocol that helps manage network database information about authorized users on a network, such as user accounts, passwords, and what a user is and is not allowed to access. LDAP is vendor and platform neutral, which allows for authenticating users that are working across heterogeneous systems.
About ClearCase Support with LDAP: ClearCase version 2003.06.15 and later allows ClearCase users to authenticate using the LDAP (Lightweight Directory Access Protocol) industry standard.
When LDAP authentication is enabled, users enter names and passwords through standard ClearCase Page 45 of 341
ClearCase Environment – How do I dialogs (for example CCRC or CCWeb), and ClearCase will use the LDAP protocol to deliver the appropriate authentication.
This is not to say that ClearCase is integrated with LDAP, it merely runs on top of the operating system already configured to use the LDAP protocol. In other words, ClearCase authenticates with the operating system, and will support LDAP transparently if the OS is configured correctly to support LDAP.
To ensure ClearCase will authenticate against an LDAP directory, perform the following tasks: Arrange to work with your LDAP administrator to collect information about your LDAP environment. Ensure that the LDAP server is installed and configured. Ensure that the LDAP directory has been created and populated with user information. Ensure that LDAP access can be had to resources/shares intended to be used by ClearCase users outside of the ClearCase environment. Supported LDAP servers: ClearCase supports the following LDAP servers that support LDAP protocol Version 3: IBM Lotus® Domino® LDAP Server IBM Tivoli® Directory Server Microsoft® Active Directory Server Novell® eDirectory Server Sun® Java™ System Directory Server ClearCase support for PAM TOC: ClearCase Matrices and Support Policies Configuring Portfolio Manager to use LDAP LDAP support for secure sockets layer (SSL) in ClearQue LDAP support for Performance testing ClearCase fails to use LDAP authentication on 64-bit Li 42. How do I – use Active Directory Universal Groups and ClearCase A Universal Group within an Active Directory setup is defined as a group that can be used anywhere in the domain tree or entire forest.
A Universal Group can also include other Universal Groups, Global Groups, and Accounts from within any domain in the domain tree or forest. Note: Universal Groups can only be created while Active Directory is configured in Native mode and not Mixed mode. When a Rational ClearCase community operating in a Microsoft Active Directory environment includes users from multiple Active Directory domains that are part of the same forest, you can use an Active Directory universal group to provide users logged on to different domains with access to a common set of VOBs and views.
Universal Groups can be advantageous to Rational ClearCase configurations. If you have multiple domain environments in a single forest you will not need to setup proxy groups, as you did in Windows NT 4.0 domains. Universal groups can include any user or group from any domain in a forest and can be granted rights to any resource in any domain in a forest. Because these Universal groups can contain other groups, they provide an alternative to the Proxy Groups. Review IBM Rational ClearCase Administrator's Guide on the topic of Rational ClearCase and Windows Domains for more details. Documentation References: ClearCase 7.1: Using active directory universal groups
ClearCase 7.0.1: Using active directory universal groups
ClearCase 7.0: Rational ClearCase Windows domains 43. How do I – understand about Windows Active Directory Distribution and Security groups What is a Distribution group and can it be used for a ClearCase group? Distribution groups have only one function—to create e-mail distribution lists. You use distribution groups with e-mail applications to send e-mail to the members of the group. Distribution groups play no role in security (you do not assign permissions to distribution groups), and you cannot use them to filter Group Policy settings.
When setting up the ClearCase administrator group or the ClearCase users group, a global domain security group must be used.
Page 46 of 341
ClearCase Environment – How do I Note: ClearCase itself does not have any security features. ClearCase relies on the Operating Systems security. For this reason any groups used for ClearCase must be global domain security groups.
Security groups are listed in discretionary access control lists (DACLs) that define permissions on resources and objects. They are used to manage user and computer access to shared resources as well as to filter Group Policy settings.
Once a global domain group has been created, its type cannot be changed. If the group is a distribution group it must be removed and recreated if it was intended to be a security group. SYMPTOMS OF DISTRIBUTION GROUP USE:
If the ClearCase users group were a distribution group, ClearCase would not recognize this group as the CLEARCASE_PRIMARY_GROUP. Looking at the creds output all security groups that the user is a member of, are displayed. Distribution groups do not show up in the creds output. Distribution groups also do not show up when using "net user
The following errors may be seen: When running any ClearCase command on the server:
unable to get user id for current user
From a client system when attempting creating a view:
The given credentials are not recognized by the remote host.
Credmap from a client:
Identity on host "clearcaseserver": User SID: NOBODY Primary group SID: NOBODY
Cause ClearCase requires 32-bit LDAP libraries. If only the 64-bit LDAP libraries are installed ClearCase is unable to use them correctly. Note: A system trace of the clearcase process will show ClearCase does not successfully contact LDAP, and that it is reading user information from the local /etc/passwd and /etc/groups files.
Diagnosing the problem System traces run against clearcase processes will confirm ClearCase in not contacting PAM successfully.
Note: Any operating system command used to check user ids or group membership on the server (such as "id") will work correctly.
Example:
As an example, to capture a system trace of oserv, you would execute the following, while the oserv was running: strace -f -F -o ~/oserv-strace.txt oserv
The -f -F options tell strace to also trace fork(2) and vfork(2) processes respectively, in case there are any. The -o option saves all strace output to the oserv-strace.txt file, and oserv is the program strace will run and trace.
Resolving the problem
Page 47 of 341
ClearCase Environment – How do I Install the appropriate 32-bit LDAP clients and libraries.
Note: If you are authenticating with an OpenLDAP server, you will be required to install the ldap clients and libraries. If you are authenticating against an old version of OpenLDAP server, then only you need to install the compat libraries. This means you need only install the openldap and openldap-clients and nss_ldap package. These libraries will be available in the 32-bit version of the Linux distribution being used. Shell access & Emulations 45. How do I – understand why SSH connection hangs when attempting to exit after starting ClearCase Linux SSH connection hangs when attempting to exit after starting ClearCase.
This can affect the use of scripts to start/stop ClearCase remotely using SSH.
Cause This is a due to a OpenSSH server design, which will not close the console until all process/jobs executed by the user are completed.
Refer to this SSH FAQ for further details, http://www.snailbook.com/faq/background-jobs.auto.html
Resolving the problem Redirect the ClearCase start script to either /dev/null or to a log file. Example: /usr/atria/etc/clearcase start < /dev/null >& /dev/null /usr/atria/etc/clearcase start < /tmp/ccstart >& /tmp/ccstart 46. How do I – understand the support Policy for Shell Access and ClearCase ABOUT SHELLS Sometimes called command shell or command prompt, a shell is the command processor interface. The command processor is the program that executes operating system commands. The shell, therefore, is the part of the command processor that accepts commands. After verifying that the commands are valid, the shell sends them to another part of the command processor to be executed. SUPPORTED SHELLS FOR CLEARCASE USE ON UNIX & LINUX All shells on UNIX and Linux that are included with the operating system are supported. below is a list of the more commonly used shells: Bourne shell (sh) Cshell (csh) Korn Shell (ksh) Bourne Again Shell (bash) Z Shell (zsh) TC Shell (tcsh)
Note: There may be particular features of a given shell that do not work with ClearCase and those will be identified on a case by case basis. See related solutions below for known issues.
SUPPORTED SHELL FOR CLEARCASE USE ON WINDOWS The only officially supported command interpreter/prompt/shell on a Windows is cmd.exe.
There are multiple issues with selecting the right additional 3rd-party shells and testing. All of the UNIX shell ports (for example Cygwin) are not tested nor supported on Windows.
Also, there is no real tty device (Teletype device) on Windows, supporting CLI (command line interface) under the various shells is troublesome. (The shell could be written as GUI, without Win32 Console.)
Note: Teletype device used to be one of the major manufacturers of terminal devices in the early days of Unix. The term is used now for any character-based data terminal.
47. How do I – understand the support Policy for Xwindows xterm emulators and ClearCase What is the support policy for IBM® Rational® ClearCase® use through Xwindows xterm emulators, such as Hummingbird® eXceed, WRQ Reflections X and like products, to perform UNIX® or Linux® ClearCase operations from a Microsoft® Windows® client. Page 48 of 341
ClearCase Environment – How do I
Cause ClearCase Project Explorer crashes on an AIX® server when accessed from Windows using Hummingbird Exceed: user@host:~> clearprojexp& [4] 483514 user@host:~> X Error of failed request: BadGC (invalid GC parameter) Major opcode of failed request: 70 (X_PolyFillRectangle) Resource id in failed request: 0xd0 Serial number of failed request: 93127 Current serial number in output stream: 93139
Solution ClearCase is currently not supported through Hummingbird eXceed, WRQ Reflections X or like protocols to allow Windows clients to perform ClearCase tasks on UNIX or Linux servers. Xclearcase and its child GUI applications, such as xcleardiff and clearprojexp, are only supported for explicit use on UNIX and Linux platforms. Note: These GUI utilities are also supported for use directly on the Xwindows host server machine when ClearCase is installed. Though it is unsupported, you may find that a remote xhost configuration works successfully for your production requirements. However, if the need should arise for you to contact IBM Rational Customer Support, Xwindows xterm emulators introduce many variables that can potentially affect and/or inhibit our troubleshooting ability in detecting and resolving root problems with the application. We recommend that ClearCase be utilized via supported portals such as ClearCase Web, ClearCase Remote Client, or native client; refer to technote 1233090 for more details. Otherwise, utilize the cleartool functionality via a supported command line interface, such as telnet or ssh. Change Requests: 1. (RFE) RATLC00687454 has been filed requesting support of Hummingbird eXceed to allow Windows clients to perform xclearcase tasks on UNIX or Linux servers. 2. (RFE) RATLC00736859 is open to allow UNIX or Linux GUI access from a Windows client through WRQ Reflections X or similar products.
The decision was made by Product Management to exclude the resolution of these change requests from future upgrades and releases due to the significant architectural changes required to implement the solution Network Attached Storage (NAS) devices
48. How do I – understand about Root permissions on Network Attached Storage and ClearCase When creating a view with the storage residing on a Network Attached Storage (NAS) device, a warning followed by a pair of errors appear: cleartool: Warning: Storage pathname "/net/filer/filer/views" may not reside on host "server". cleartool: Error: Failed to record hostname "server" in storage directory "/net/filer/filer/views/my_view.vws". cleartool: Error: Unable to create view "/net/filer/filer/views/my_view.vws". The warning message is expected when NAS (or remote) storage is used, and can be safely ignored. It simply means that ClearCase noticed that the storage resides on an NFS mounted disk instead of a locally attached disk. The errors are also expected, and are returned because the UNIX (or Linux) root account does not have the proper permissions on the NAS share to create the views. Note: A similar error is displayed when attempting to create a VOB as well. Here is a breakdown on why this is happening 1. After the view/VOB storage is created using cleartool mkview | mkvob command, an RPC call is sent to the admin_server for additional clean up work. 2. The admin_server records, in the .hostname file under the view/VOB storage directory, the hostname where the view_server or vob_server process is going to run. 3. The admin_server is started by the albd_server, which runs as root on UNIX and Linux. Hence, the admin_server is also started by and runs as root. 4. The admin_server fails when it tries to open the .hostname file in the view or VOB storage location because it is coming over NFS as nobody, since root access has not been granted to the NAS share. 5. After the admin_server fails, control goes back to the cleartool command which proceeds to remove the files it created and prints the errors shown above. Page 49 of 341
ClearCase Environment – How do I 6. The view_server/vob_server host needs root access on the NAS device because the admin_server uses it to access the private files of the view/VOB, which are owned by the user who is creating the view/VOB. 7. Since root comes across NFS as nobody, the admin_server fails to access some files of the view because of the restricted permissions. Defect APAR IC40472 has been submitted to change this behavior so that root does not need to be granted access to the view/VOB storage on a NAS.
Solution The defect has been resolved so that root no longer requires permission on the NAS share to create VOBs or Views. That means the cleartool mkview and cleartool mkvob commands will execute successfully without root access on the NAS device. This feature can be obtained in the following ClearCase UNIX and Linux patches (or later):
ClearCase 2003.06 clearcase_p2003.06.00-8
ClearCase 2002.05 clearcase_p2002.05.00-36
VOB Admin operations require root access The cleartool mkvob command does not require root access after installing the aforementioned patches, however, there are VOB administration operations that still require root to run successfully, such as protectvob, space and dospace. Notes: This is not true for administration commands that can be run as the VOB owner, such as checkvob, reformatvob and rmvob. This does not apply to view administration, as there are no ClearCase admin commands or utilities for views on UNIX and Linux; instead, OS level commands are used.
Add root access on NAS The VOB admin operations that are supported on the remote storage require the clients to have root access to the NAS share. Give root permission to the NAS by adding the following line to the /etc/exports file on the NAS device:
/vol/ccvol/viewstg -root=unix_host Where unix_host is the hostname of the UNIX (or Linux) server.
Protectvob failing on remote storage Defect, APAR PK20192, is open to investigate why cleartool protectvob may fail in a supported configuration for using a NAS device. As detailed above, VOB administration commands, such as protectvob, must have root access on the remote storage to complete successfully. However, this defect is investigating cases where it is not working as expected. There is currently no fix available for this defect.
WORKAROUND: 1. Copy chown_pool and chown_container scripts from /opt/rational/clearcase/etc to the remote device.
IMPORTANT: These scripts currently do not run on Linux. Review technote 1258689 for details the associated workaround. 2. Login as root on the VOB server Change directory (cd) to the directory on the filer where the scripts were placed and run the script chown_pool
49. How do I – understand the chown_pool and chown_container support on Linux Attempts to run the chown_pool and or chown_container utilities on Linux results in the following error:
Don't know system of type Linux Currently these utilities only run on UNIX®. Change request (RFE) RATLC01020018 has been submitted to add support for the chown_pool and chown_container utilities to run on Linux.
WORKAROUND:
Edit /opt/rational/clearcase/etc/chown_pool, and add the following lines into the cases statement: Page 50 of 341
ClearCase Environment – How do I
Linux*) CD=cd FIND=find ECHO=echo SILENT_GREP="egrepp -q" ;;
Edit /opt/rational/clearcase/etc/chown_container, and add the following lines into the cases statement:
Linux*) CHOWN=chown CHMOD=chmod ECHO=echo SILENT_GREP="egrep -q" AWK=awk ;;
50. How do I - run cleartool protectvob for VOBs stored on NAS Hosting VOB storage on a NAS device is common practice when using Rational ClearCase, but there are some specific considerations with regards to changing protections on the VOB object.
You will need to reprotect the pools on the NAS device prior to running cleartool protectvob against the VOB.
Note: Defect APAR PK20192 has been submitted to resolve the differences in running protectvob on a NAS filer so the additional steps below are no longer required.
INSTRUCTIONS: 1. Before running cleartool protectvob, you must first copy scripts from the VOB server to a directory on the NAS device.
IMPORTANT: These scripts currently do not run on Linux. Review technote 1258689 for details the associated workaround.
The scripts that you need to copy are:
/opt/rational/clearcase/etc/chown_pool /opt/rational/clearcase/etc/chown_container
Note: You can copy the scripts to any directory on the NAS device that you choose; the location of the scripts is insignificant, as long as they are locally on the NAS device. 2. Login as root on the VOB server, change directory (cd) to the directory on the NAS device where the scripts were placed, and run the script chown_pool.
The syntax to reprotect a pool to a vobadm user and staff group is
chown_pool vobadm.staff /path/to/pool
Example:
#/usr/dir1/tools/chown_pool vobadm.staff sdft
Note: The protections on the pool will be changed accordingly. You must repeat this against each pool, respectively. Now running cleartool protectvob will work the same for a VOB stored on a NAS device the same as it would for a VOB stored on a local disk.
Example: cleartool protectvob –chown vobadm -chgrp staff /usr/lib/vob.vbs
Note: You will need to be logged in with account that has root access.
Page 51 of 341
ClearCase Environment – How do I Storage 51. How do I – understand the storage device support for ClearCase The three generic types of storage available today are as follows: Direct Attached Storage (DAS) Storage (usually disk or tape) is directly attached by cable to the computer processor. The hard disk drive inside a PC or as tape drive attached to a single server are simple types of DAS. Input/Output (I/O) requests access the device directly. Storage Area Network (SAN) SAN is a high-speed sub-network of shared storage devices. A storage device is a host that contains nothing but a disk or array of disks for storing data.
A SAN's architecture works in a way that makes all storage devices available to all servers on a local area network (LAN) or wide area network (WAN). As more storage devices are added to a SAN, they too will be accessible from any server in the larger network. In this environment, the server merely acts as a pathway between the end user and the SAN.
Because stored data does not reside directly on a server other than the SAN, the server's power is utilized for business applications, and network capacity is released to the end user. Network Attached Storage (NAS) A NAS device (also known as appliance or filer), which is usually an integrated processor plus disk storage, is attached to a TCP/IP based local area network (LAN) or wide area network (WAN) and accessed using specialized file access and file sharing protocols. File requests received by a NAS are translated by the internal processor to device requests.
What does ClearCase Support? ClearCase supports DAS as long as the host operating system is supported. Review the Related Information section below for more details. ClearCase supports SANs as long as the host operating system is supported. Review the Related Information section below for more details. Most SAN solutions rely on switching technology for protocol implementation, in conjunction with fiber channel. This is similar to a DAS configuration. CIFS oplocks need to be disabled for any file systems containing ClearCase storage. ClearCase supports certified NAS appliances only. For up to date information on the supported NAS devices, refer to the Related Information below for more details. CIFS oplocks need to be disabled for any file systems containing ClearCase storage. 52. How do I – understand the ClearCase default storage locations for views on Windows When creating a view, the storage location must be specified, either by selecting a server storage location or by specifying an explicit path, refer to Specifying the view storage location (Windows) for directions on how to do this using the graphical user interface. The server storage location is defined in the ClearCase registry, see technote 1147041 for more details About ClearCase Server Storage locations. The explicit path allows you to select any (local or remote) shared location, with the correct access requirements, to use as the view storage location; see technote 1143292 for information About ClearCase permissions on Windows.
Set the Explicit Path Automatically
Note: This solution contains information about modifying the system registry. Before making any modifications to the Microsoft Registry Editor, it is strongly recommended that you make a backup of the existing registry. For more information describing how to back up the registry, refer to the Microsoft Knowledge Base article 256986.
The explicit path field can be automatically populated on a per-user basis by making a change to the Windows registry:
HKEY_CURRENT_USER\Software\Atria\ClearCase\CurrentVersion\clearviewtool
Page 52 of 341
ClearCase Environment – How do I
The value of Last View Dir holds the default explicit pathname for a Dynamic View. The value of Last WS View Dir holds the default explicit pathname for a Snapshot View.
Placing the UNC path of the location you wish to use for the view's storage in these values will cause the path to be populated in the text box for explicit path when creating new views. 53. How do I – understand about ClearCase Server Storage locations
A ClearCase server storage location (cleartool mkstgloc) is a physical data storage that is shared and its global path is registered in ClearCase. This facilitates the creation of VOB and view storages in a central location, namely, a VOB and/or view server. The inference of server is only indicating that the host has the ability to store VOBs or views, but this can be true for a client install also. For example, many client installs will act as their own view server. Note: A share or exported location, that is not registered in ClearCase, can serve as a storage location for VOBs and views, but it is not advertised in the ClearCase network for general use.
Storage for view creation with cleartool mkview: Dynamic views Default storage location for dynamic views is none; a server storage location must be specified explicitly using -stgloc or indirectly using -auto. For dynamic views, automatic server storage selection proceeds as follows:
1. Server storage locations that have no global path (-ngpath) are disqualified. 2. Server storage locations on heterogeneous hosts are disqualified. 3. Local server storage locations are preferred over remote ones. 4. A server storage location is selected at random from the remaining candidates. Snapshot views Default storage location for snapshot views: An automatically selected server storage location, if any can be found; else -colocated_server. For snapshot views, automatic server storage selection proceeds as follows:
1. Server storage locations with global paths (-gpath) that reside on heterogeneous hosts are disqualified. 2. Local server storage locations are preferred over remote ones. 3. A server storage location is selected at random from the remaining candidates. Note: The same logic applies when creating a view using the graphical user interface (GUI); the view creation wizard. Also, for assistance, use the Help button available from the storage selection dialogue of the view creation wizard.
Storage for VOB creation with cleartool mkvob: The VOB database (located in subdirectory db of the VOB storage directory) must physically reside on a Rational ClearCase host, where it is accessed by ClearCase server programs (and processes) running locally. -stgloc {vob-stgloc-name | -auto } Specifies a server storage location in which the VOB storage directory is to be created. The server storage location must have been created previously with mkstgloc. Page 53 of 341
ClearCase Environment – How do I The name of the VOB server storage location can be specified explicitly as vob-stgloc-name, or specify - auto to direct mkvob to select one. If -auto is specified , a server storage location for the VOB is selected as follows: a. Server storage locations that have no global path (mkstgloc -ngpath) and that reside on remote hosts are disqualified. b. Server storage locations on heterogeneous hosts are disqualified. c. Local server storage locations are preferred over remote ones. d. Globally accessible server storage locations (mkstgloc -gpath) are preferred over those that are not (mkstgloc -ngpath). e. The server storage location with the most free space is selected. Note: The same logic applies when creating a VOB using the graphical user interface (GUI); the VOB creation wizard. Also, for assistance, use the Help button available from the storage selection dialogue of the VOB creation wizard.
Storage Locations with ClearCase Interop In an interop environment it is not possible for a server storage location to be created across operating systems when using Rational ClearCase. The opposing platforms are not able to convert the command syntax from black-slash '\' to forward-slash '/' and vice versus. For example, when trying to run cleartool mkstgloc from a Microsoft® Windows® host with the storage on a UNIX® or Linux® server it fails with syntax errors:
M:\>cleartool mkstgloc -vob -region region_name -host UNIX_server -hpath \\UNIX_server\share -gpath \\UNIX_server\share New_storage_location \\UNIX_server\share. cleartool: Error: Required command argument is missing. Usage: ...
The server storage location must be created from a host on the same platform. Note: Views and .NET issues 54. How do I – understand the Visual Studio.NET metadata files and the function they serve when integrated with ClearCase The following is a living list of information about the various metadata files associated with Visual Studio.NET and IBM Rational ClearCase.
Folder Hierarchy The Visual Studio.NET (VS.NET) and ClearCase metadata exist in a simple hierarchy of folders. The first folder is the Solution folder and is named after the VS.NET Solution. The Solution folder contains one *.SLN file (see below), at least one *.SUO file (see below), and zero or more VS.NET Project folders. Project folders are named after their VS.NET Projects. The contents of the Project folders vary, but they always contain one *.CSPROJ file (see below) per Project folder, and a *.WEBINFO file (see below) if the Project is a web (ASP.NET) project.
SLN (Solution File) The VS.NET Solution metadata is stored in the *.sln file. The Solution and all the Projects associated with it can be opened within VS.NET by opening the *.sln file. It is a text file and can be edited. It is version controlled.
CSPROJ (Project File) The metadata file associated with individual projects is *.csproj. Within VS.NET, opening the *.csproj file will open that individual project. It is a text file and can be edited. It is version controlled.
SUO (Solution User Option File) When ASP.NET Projects (generally termed as web projects) are created and version controlled, using VS.NET and ClearCase, VS.NET stores absolute paths of key artifacts (like Solution, Project, Web) and source code control information in the Solution User Options (.suo) file in addition to other files. A Solution user option file, is a binary file, which is specific to a given user, and is not version controlled.
WEBINFO (WEBINFO File) When a web project (ASP.NET) is created, a *.webinfo file is also created in the same location as the *.CSPROJ. This WEBINFO file is also not version controlled by default. It must be manually added to source control if multiple view must used with the web project. It is a text file and stores the URL pointing to the web projects *.CSPROJ file.
Page 54 of 341
ClearCase Environment – How do I 55. How do I – set up and use the Rational Modelling Extension for Microsoft.NET - Rational ClearCase Integration Setting up and using the integration of IBM Rational Modeling Extension for Microsoft .NET (RME) and IBM Rational ClearCase.
Supported versions of ClearCase for the Integration The Visual Studio .NET 2005 - ClearCase integration is supported with the following versions of ClearCase: 2003.06.15 or later setting up Visual Studio.NET 2005 for the ClearCase Integration 1. Start Visual Studio.NET 2005 2. Click Tools -> Options... 3. Select Source Control 4. Select ClearCase in the drop-down list 5. Click OK
Adding Visual Studio.NET 2005 Solution to Source Control 1. Start Visual Studio.NET 2005 2. Click Create -> Project 3. Select a template 4. Click Browse... 5. Navigate to
If the above dialog is displayed, do the following: 1. Switch to Visual Studio .NET 2005 2. Select the solution in the Solution Explorer 3. Right-click Click Check Out for Edit...
4. Click Check Out Page 55 of 341
ClearCase Environment – How do I C# to UML Transformation with Modeling projects under Source Control Since IBM Rational Software Architect (RSA) can modify the model (*.emx) file, the Check Out Element(s) dialog will display as long as the ClearCase SCM Adapter preference is set to prompt for check out. This functionality is the same as the base functionality of the RSA - ClearCase integration.
56. How do I – understand about Microsoft Visual Studio.NET bindings and ClearCase Bindings tell Visual Studio what Source Control Provider to use when opening Solutions and Projects. This information is stored in the .sln and .proj files.
Visual Studio .NET uses very specific xml tags that the IDE inserts in the solution (.sln) and project (.XXproj) files. These tags need to modified whenever the integration of Source Control Provider changes. The following is an example of what the xml tags look like in a Solution file. Note: This specific example is taken from the ClearCase 7.0 integration with VS.NET 2003 involving a single Visual Basic project.
Microsoft Visual Studio Solution File, Format Version 8.00 Project("{F184B08F-C81C-45F6-A57F-5ABD9991F28F}") = "bindingsbasic", "bindingsbasic\bindingsbasic.vbproj", "{89DFE835-F77B-4411-99F4-DEDFAFF81D88}" ProjectSection(ProjectDependencies) = postProject EndProjectSection EndProject Global GlobalSection(SourceCodeControl) = preSolution SccNumberOfProjects = 2 SccProjectName0 = SAK SccLocalPath0 = . SccProvider0 = MSSCCI:ClearCase CanCheckoutShared = true SolutionUniqueID = {FB34BB4B-40F0-4B65-BD8F-B61DA7A380A6} SccProjectUniqueName1 = bindingsbasic\\bindingsbasic.vbproj SccLocalPath1 = bindingsbasic CanCheckoutShared = true EndGlobalSection ...... The following is an example of what the xml tags look like in a VB project file.
ClearCase Environment – How do I
.NET 2003 screenshot
Note: The following pop-up may appear:
Source Code Control (SCC) identifies that a Solution/Project is under source control only if that Solution/Project is added to source control from within Microsoft Visual Studio.NET. What this means is that if a Solution/Project was created through Microsoft Visual Studio.NET but added to source control from outside of Microsoft Visual Studio.NET (for instance, using cleartool mkelem or Add to Source Control using ClearCase GUIs) then Microsoft Visual Studio.NET does not recognize this Solution/Project as a source controlled object, hence you will not see SCC context menus for files. Below are the steps to follow, should you have to correct the bindings after editing projects with the incorrect version of the CC VS.Net Integration. 1. Install ClearCase 2003.06.15 (Service Release 5) and cccq_dotnet 2. Remove the old view containing the solution and create a new one. 3. Open VisualStudio and set the source control plug-in to ClearCase 4. Open the solution. You will receive the following error message:
"The source control provider associated with the solution could not be found. ... Do you want to permanently remove the source control bindings ...." 5. Click YES 6. In the solution explorer checkout the solution and project files a. Make sure that the old source control binding section is removed from the solution file (if it has not already been removed).
The old source control binding section looks like this:
Page 57 of 341
ClearCase Environment – How do I GlobalSection(SourceCodeControl) = preSolution ..... EndGlobalSection b. Add the new source control binding section into the solution file
The new source control binding section looks like this:
GlobalSection(RationalClearCase) = preSolution SourceControlProvider = RationalClearCase EndGlobalSection c. In each project file, add or replace the source control information under
In VS2005, *.vdproj files represent Setup Projects.
In order to create the correct Rational ClearCase source control bindings for this project, add the following strings as shown below :
"SccProjectName" = "8:Rational ClearCase" "SccLocalPath" = "8:Rational ClearCase" "SccAuxPath" = "8:Rational ClearCase" "SccProvider" = "8:Rational ClearCase"
Example :
"DeployProject" { "VSVersion" = "3:800" "ProjectType" = "8:{978C614F-708E-4E1A-B201-565925725DBA}" "IsWebType" = "8:FALSE" "ProjectName" = "8:Setup1" "LanguageId" = "3:1033" "CodePage" = "3:1252" "UILanguageId" = "3:1033" "SccProjectName" = "8:Rational ClearCase" "SccLocalPath" = "8:Rational ClearCase" "SccAuxPath" = "8:Rational ClearCase" "SccProvider" = "8:Rational ClearCase" 7. Check in everything. 8. Close VisualStudio and remove in ClearCase Explorer all files ending with the following extensions: ~sak*.sln ~sak*.csproj ~sak*.webproj ~sak*.tmp *.vssscc *.vspscc *.ccscc Restart VisualStudio 57. How do I - add existing ASP.NET 2005 Framework 2.x Web Applications to source control with Rational ClearCase How to add an existing Microsoft® Visual Studio.NET® 2005 web project (ASP.NET Web Application) using Framework 2.x to source control using IBM® Rational® ClearCase® version 7.0 or later.
Cause These instructions differ from the 2002/2003/2005 (Framework 1.x) ASP.NET integration with ClearCase because the .csproj file is not longer used in .NET Framework 2.0. The reason for this change is related to the VS.NET bindings and the differences in how an MSSCCI integration (.NET 2002 & 2003) writes to a VS.NET project file versus the way VSIP integration (.NET 2005) writes to a project file. Review technote 1252437 for more details. Page 58 of 341
ClearCase Environment – How do I
If you have not yet attempted to add your existing ASP.NET 2005 (Framework 2.x) Web Application to ClearCase source control, follow the procedure below. Note: The procedure below assumes an ASP.NET (Framework 2.x) project already exists as a Visual Studio.NET project inside a Visual Studio.NET solution and that you are using Internet Information Server 5.0 or later.
IMPORTANT: If you have already attempted to manually add your existing ASP.NET 2005 (Framework 2.x) solution or project to ClearCase source control and you are having problems, review the DISCLAIMER at the end of the technote for instructions. Add an existing ASP.NET 2002/2003/2005 (Framework 1.x) Project to ClearCase: If you need to add your existing ASP.NET (Framework 1.x) 2002/2003/2005 project to source control, refer to technote 1129589. Add a New ASP.NET (Framework 1.x) Project to ClearCase: If you need to add a new ASP.NET (Framework 1.x) solution or project to source control with ClearCase, refer to technote 1129588. Add an existing VS.NET Project (Non-ASP.NET) to ClearCase: If you need to add a VS.NET (non-ASP.NET) project to source control with ClearCase, refer to technote 1129529. Add a New VS.NET Project to ClearCase. Follow the instructions in the Online Help.included with ClearCase (Start > Programs > IBM Rational > IBM Rational ClearCase > Online Help > Rational ClearCase integrations with vendor products > Microsoft VS.NET)
Solution Instructions - Step by Step: Virtual Directory Setup Set up Internet Information Server
1. Create a VOB and snapshot view to use with your ASP.NET 2005 (Framework 2.x) project. Note: Rational does not support serving ASP applications or webs in a dynamic view. Production deployment needs to be done through a snapshot view. Review Microsoft Knowledge Base Article 320268 for more details on the errors related to using a dynamic view to host ASP pages. Developing an ASP.NET project however, can be performed from a dynamic view.
2. Copy the ASP.NET 2005 Project(s) into the snapshot view. Example: C:\snapshot_view\vob\ASP_Project\
3. Open Internet Information Services (IIS) and create a Virtual Directory. The Example: Start > Settings > Control Panel > Administrative Tools > Internet Information Services
4. Create a name for the Virtual Directory (App2 will be used for this example).
5. Provide a path for the virtual directory using the ASP.NET 2005 Project in the snapshot view. Example: C:\snapshot_view\vob\ASP_Project\App2\
6. Set the Access Permissions as required. Page 59 of 341
ClearCase Environment – How do I Note: There are no ClearCase specific permissions required.
7. Close all windows to finish. You will see the included sub folders now appear in the IIS containing all files.
8. Repeat for each Project as needed.
Add the ASP.NET Project to ClearCase Source Control 1. Create a New Blank Solution. From the .NET 2005 File > New > Project > Other Project Types > Visual Studio Solutions > Blank Solution
Example:
Note: DO NOT add to source control at this time. Provide a name for the Solution (Solution1 will be used for this example). Click the Browse button and navigate to the location of the ASP.NET 2005 project located in the snaphot view (C:\snapshot_view\vob\ASP_Project) Ensure Add to Rational ClearCase is unchecked and click OK. This is an example of the directory structure of the ASP.NET project from Windows Explorer:
Note: The others directory contains the incs project which is specific to the App2 ASP.NET 2005 project used in this example. This is relevant to step #4 below.
2. Open the existing Web site to the Virtual Directory in .NET 2005. Example: Click File > Open> Local IIS> Default Web Site> App2 and click Open Note: This step will ADD the Project to the Solution.
Note: The Set Project Location window may appear after opening the application. If it does, proceed to Step 3 If it does not, proceed to Step 4.
Page 60 of 341
ClearCase Environment – How do I
IMPORTANT - You need understand your project directory structure to complete this next section (if applicable). 3. If there are any include statements in the Web Project, verify that the references are correct or manually correct the Project Location. Note: For this example the App2 references the following include statements and needs correction:
Example: Within the App2 application the following include statement appears in the Default.aspx file. Note: Footer.html actually resides at http://localhost/other/incs This path needs to be manually mapped in the Set Project Location Window as follows: a. Highlight the Project Location b. Type (do not browse) the http path in the Change... window (Example http://localhost/other/incs) and click OK.
4. Add the Solution to source control. Example: From the Solution Explorer window, right click on Solution1 and select Add Solution to Rational ClearCase.
Note: The ClearCase Add to Source Control window will appear.
Page 61 of 341
ClearCase Environment – How do I
Note: If you do not see the ClearCase menu options at this time, close and reopen the Solution. Verify Integration is setup correctly: 1. Open the Solution file (Solution1.sln) in a text editor.
Example using Solution1.sln:
2. Verify the following sections for each Project in the Solution are as follows:
Scc* sections state Rational ClearCase (in yellow):
Example: SccProjectName = "Rational ClearCase" SccAuxPath = "Rational ClearCase" SccLocalPath = "Rational ClearCase" SccProvider = "Rational ClearCase"
Project path is set to http://localhost and NOT a local path to the snapshot view (in green):
Good Example: Microsoft Visual Studio Solution File, Format Version 9.00 # Visual Studio 2005 Project("{E24C65DC-7377-472B-9ABA-BC803B73C61A}") = "http://localhost/App2/", "http://localhost/App2", "{922A731F-38E5-43B6-AB55-1B511D302122}"
Bad Example: Microsoft Visual Studio Solution File, Format Version 9.00 # Visual Studio 2005 Project("{E24C65DC-7377-472B-9ABA-BC803B73C61A}") = "C://snapshot_view/vob/ASP_Project/App2/", "App2", "{922A731F-38E5-43B6-AB55-1B511D302122}" 3. Perform this verification for all projects that are listed in the Solution file.
DISCLAIMER:
Page 62 of 341
ClearCase Environment – How do I If you have already attempted to manually add your ASP.NET2005 Solution or Project to ClearCase source control in any way that does not follow the above procedure, then you must remove (cleartool rmelem) everything from ClearCase and start over using the above procedure. Every project and solution has a different combination of files and directories that must be left outside source control as view private. Given the large, and growing, number of ASP.NET project types, Rational Technical Support cannot account for every file and directory that must be left out of source control. Therefore, any attempt to manually add an existing ASP.NET project to ClearCase source control that does not follow the above procedure will not be supported. Related information Add existing ASP.NET 2002/2003 project to ClearCase About Microsoft Source Control Bindings messages Difference between MSSCCI and VSIP integration Convert a VS.NET 2002/2003 Project to VS.NET 2005 About Security settings with Microsoft 2.0 Framework 58. How do I – understand the procedure to integrate ClearCase and VS.NET 2005 and 2003 This technote explains how to integrate ClearCase version 2003.06.16 or 7.0 and VS.NET 2005/2003 if ClearCase is installed before VS .NET 2005/2003 on a client system.
Note: If ClearCase is installed before VS.NET, the ClearCase installation ignores the integration portion as VS.NET has not been installed yet.
IMPORTANT: Visual Studio .NET 2005 is only supported with 2003.06.15 (Service Release 5 patch 2006C) when used with the IBM Rational ClearCase Client for Visual Studio .NET (CCCQ.NET) add-on for .NET. For details on the ClearCase Client plug-in, refer to Release Notes GI11-6728-00.
INSTRUCTIONS:
1. Go to Start > Control Panel > Add/Remove Programs
2. Locate the IBM Rational ClearCase program and click the Change option.
3. When the ClearCase installation Wizard window appears select Next.
Page 63 of 341
ClearCase Environment – How do I
4. You will be prompted to either Modify, Repair, or Remove the application. Select Modify and click Next.
5. When the Custom Setup window appears, select IBM Rational ClearCase Client for VS .NET. Expand the option and ensure that you select, This feature will be installed on the local hard drive. Click Next.
Page 64 of 341
ClearCase Environment – How do I
6. The Ready to Modify Program window will appear, click Install.
7. After the installation is completed, select Finish.
Note: You will need to restart the system in order to complete the integration.
After restart, when you open VS .NET 2005/2003, you will now see the ClearCase option on the Menu Bar at the top of the GUI. 59. How do I – understand about Security settings with Microsoft .NET 2.0 Framework projects under ClearCase control Problem This technote explains how the new security settings in the Microsoft® .NET 2.0 Framework bundle can cause builds under Visual Studio.NET 2005 to fail when stored in an IBM® Rational® ClearCase® VOB.
Cause Microsoft .NET 2.0 Framework has security trust rights that need to be modified as they are too restrictive for builds and to work with .NET projects in Microsoft Visual Studio .NET 2005.
Solution Follow these instructions to increase the trust level in order to successfully build your .NET projects: 1. Click Start > (Settings) > Control Panel > Administrative Tools > Microsoft .NET Framework 2.0 Configuration
Page 65 of 341
ClearCase Environment – How do I
2. In the right Panel, click on the Configure Code Access Security Policy task.
3. Click on the Adjust Zone Security
Page 66 of 341
ClearCase Environment – How do I
4. The Security Adjustment Wizard will pop up. Click Next
Make sure you have Full Trust for My Computer
and Local Intranet
Page 67 of 341
ClearCase Environment – How do I
Note: You can select the other zones security opens to your preference unless you know they will affect your application in some way. 5. Click Next and confirm the settings are correct
6. Click Finish Now you should be able to build and work in your .NET project.
60. How do I - create new ASP.NET Framework 1.x Web Applications while under source control with Rational ClearCase Problem This technote explains the procedure for creating a new Microsoft® Visual Studio.NET version 2002, 2003 and 2005 web project (ASP.NET Web Application) using Framework 1.x while under IBM® Rational® ClearCase® source control.
Cause If you have already added an ASP.NET (Framework 1.x) solution or project to ClearCase source control, and wish to create a new project, follow the procedure below. Note: If you have already added your ASP.NET (Framework 1.x) solution or project to ClearCase source control and you are having problems, review the Troubleshooting Tips at the end of the technote for assistance. Add an existing ASP.NET Project to ClearCase: If you need to add your existing ASP.NET project to source control, refer to the following technotes: .NET 2002 & 2003 & 2005 (Framework 1.x): Technote 1129589 .NET 2005 (Framework 2.x): Technote 1256082
Add an existing VS.NET Project (Non-ASP.NET) to ClearCase: If you need to add a VS.NET (non-ASP.NET) project to source control with ClearCase, refer to technote 1129529. Add a New VS.NET Project to ClearCase. Page 68 of 341
ClearCase Environment – How do I Follow the instructions in the Online Help.included with ClearCase (Start > Programs > IBM Rational > IBM Rational ClearCase > Online Help > Rational ClearCase integrations with vendor products > Microsoft VS.NET)
Solution Creating a New ASP.NET project in ClearCase: 1. Create a VOB and view that you plan using with your ASP.NET (Framework 1.x) project.
Note: Rational does not support serving ASP applications or webs in a dynamic view. Production deployment needs to be done through a snapshot view. Review Microsoft Knowledge Base Article 320268 for more details on the errors related to using a dynamic view to host ASP pages. Developing an ASP.NET project however, can be performed from a dynamic view.
IMPORTANT: Open VS.NET and click Tools > Options and select Projects and Solutions from the Environment category. In the box labeled Visual Studio Projects Location, browse or type the view/VOB path. This should be done before continuing to step #2. 2. Create a blank solution and store in the VOB.
Note: This will create a solution folder in the VOB. 3. In ClearCase Explorer or Windows Explorer create a folder inside the solution folder that will represent the name of your ASP.NET project or application. 4. Start the Internet Information Services (IIS) Manager.
Example: Click Start > Settings > Control Panel > Administration Tools > Internet Service Manager. 5. Right-click Default Web Site and select Properties. 6. Under the Home Directory tab, select A directory located on this computer and then browse to solution folder located in the VOB. 7. Click Apply, and then OK. Close the Default Web Site properties.
Note: You can also accomplish the mapping in IIS above using virtual directories.
a. Right Click on the default web site node and select create new virtual directory.
b. The alias for the virtual directory should be the same name as the project folder you created in step #3 above.
c. Browse or type in the path where the project folder lives when prompted. i.e. M:\view- tag\vob-tag\folder
Note: The path to the content must go through the drive letter that is set in the ClearCase Control Panel under the MVFS tab. The default is "M". This must be set to the same value on all systems that will be accessing common projects and applications
d. Enable all access rights when prompted. Read, run scripts, execute, write, and browse.
e. Select finish. 8. Open VS.NET
Create a new ASP.NET Web Application project. During creation, select to add the project to the solution you created in step #2. Right click on the solution you created in step #2 and select Add New Project. Then select the type of VB Project you would like.
Note: Make sure the URL path is pointing to http://localhost/project-name.
IMPORTANT: If you create the project without creating the solution first, .NET will place the solution file in C:\Documents and Settings\{username}\MY Visual Studio Projects. When you try to add the project to source control .NET will look for the solution file in the VOB and when .NET can not find the solution file, .NET will abort the add to source control operation. The solution file must be placed in the VOB. The project folder must be placed inside the solution folder. 9. In the VS.NET Solution Explorer, right-click on the Solution and select Add to Source Control... 10. You may see a pop-up dialog box that says the following:
You are attempting to add some File Share Web access projects to source control. If you continue, you will no longer be able to open these projects using Front Page Web Access." Page 69 of 341
ClearCase Environment – How do I
Click Continue. 11. You may then see another pop-up dialog box that says the following:
The project
Click Continue. 12. Once the project has been added to source control you are now ready to perform ClearCase Operations within the .NET IDE.
Note: In order to Debug or Start without Debugging within the .NET IDE you will need to perform the following steps: Set a breakpoint Set your Start Page for the default.aspx file you are going to use as the start page. Rebuild the solution. Checkout the following files o Global.asax o Web.config o Default.aspx (start page) Rebuild the solution. Debug or Start Without Debugging.
This completes the steps required for the first view.
Troubleshooting Tips:
If you are experiencing permission issues or other unexpected results please consider the information below. ASP.NET maintains its own cache information. To clean up the cache go to C:\winnt\Microsoft.NET\Framework\
Then cd into C:\winnt\Microsoft.NET\Framework\
If you receive an error Access is denied while trying to clean up the cache information do the following first. a. Stop IIS Services b. Go to Task Manager and End Process aspnet_up.exe c. End Process any other web service that is running ASP applications such as xpweb_debug or xpweb_application name.
DEBUGGING ASP.NET In order to debug ASP.NET webs and applications, the user must be local administrator on the machine running IIS, as well as, a member of the local VS Developers group. This group is created during the installation of Visual Studio.NET. Security Exception Error
Note: If you encounter the following error using virtual directories:
Security Exception Description: The application attempted to perform an operation not allowed by the security policy. To grant this application the required permission please contact your system administrator or change the application's trust level in the configuration file.
Exception Details: System.Security.SecurityException: Security error.
Source Error:
Line 30: private static bool __intialized = false; Line 31: Line 32: public Global_asax() { Line 33: if ((ASP.Global_asax.__intialized == false)) { Line 34: ASP.Global_asax.__intialized = true;
Page 70 of 341
ClearCase Environment – How do I 61. How do I - add existing Microsoft ASP.NET Framework 1.x Web Applications to source control with Rational ClearCase How to add an existing Microsoft® Visual Studio.NET® 2002 or 2003 or 2005 web project (ASP.NET Web Application) using Framework 1.x to source control using IBM® Rational® ClearCase®. Cause If you have not yet attempted to add your existing ASP.NET 2002/2003/2005 (Framework 1.x) Web Application to ClearCase source control, follow the procedure below. Note: The procedure below assumes an ASP.NET (Framework 1.x) project already exists as a Visual Studio.NET project inside a Visual Studio.NET solution and that you are using Internet Information Server 5.0 or later. If you have already added your ASP.NET (Framework 1.x) solution or project to ClearCase source control and you are having problems, review the Troubleshooting Tips at the end of the technote for assistance. IMPORTANT: If you have already attempted to manually add your existing ASP.NET (Framework 1.x) solution or project to ClearCase source control and you are having problems, review the DISCLAIMER at the end of the technote for instructions. Add an existing ASP.NET 2005 (Framework 2.x) Project to ClearCase: If you need to add your existing ASP.NET 2005 (Framework 2.x) project to source control, refer to technote 1256082. Add a New ASP.NET (Framework 1.x) Project to ClearCase: If you need to add a new ASP.NET (Framework 1.x) solution or project to source control with ClearCase, refer to technote 1129588. Add an existing VS.NET Project (Non-ASP.NET) to ClearCase: If you need to add a VS.NET (non-ASP.NET) project to source control with ClearCase, refer to technote 1129529. Add a New VS.NET Project to ClearCase. Follow the instructions in the Online Help.included with ClearCase (Start > Programs > IBM Rational > IBM Rational ClearCase > Online Help > Rational ClearCase integrations with vendor products > Microsoft VS.NET)
Solution Instructions - Step by Step: Virtual Directory Setup Set up Internet Information Server
1. Create a VOB and snapshot view to use with your ASP.NET (Framework 1.x) project.
Note: Rational does not support serving ASP applications or webs in a dynamic view. Production deployment needs to be done through a snapshot view. Review Microsoft Knowledge Base Article 320268 for more details on the errors related to using a dynamic view to host ASP pages. Developing an ASP.NET project however, can be performed from a dynamic view. 2. Copy the ASP.NET (Framework 1.x) Project(s) into the snapshot view.
Example:
C:\snapshot_view\vob\ASP_Project\
3. Open Internet Information Services (IIS) and create a Virtual Directory.
The Example: Start > Settings > Control Panel > Administrative Tools > Internet Information Services
Page 71 of 341
ClearCase Environment – How do I
4. Create a name for the Virtual Directory (App2 will be used for this example). 5. Provide a path for the virtual directory using the ASP.NET (Framework 1.x) Project in the snapshot view. Example:
C:\snapshot_view\vob\ASP_Project\App2\ 6. Set the Access Permissions as required. Note: There are no ClearCase specific permissions required. 7. Close all windows to finish. You will see the included sub folders now appear in the IIS containing all files. 8. Repeat for each Project as needed. Back to top Add the ASP.NET Project to ClearCase Source Control
1. Copy the existing Solution folder into the ClearCase view within the VOB.
Note: Be sure to leave the copied Solution folder with the same name.
2. Within the copied Solution folder, open the solution (*.sln) file and remove the entire section labeled:
"GlobalSection(SourceCodeControl) = preSolution" through "EndGlobalSection" inclusive.
Note: If using virtual directories, change project URL to point to the Virtual Directory created above, should be 2nd line in file.
3. Delete *.vssscc from every folder and sub-folder of the Solution.
4. Delete *.scc from every folder and sub-folder of the Solution.
5. Delete *.vspscc from every folder and sub-folder of the Solution.
6. From Visual Studio.NET open the copied .sln file.
Note: Click OK to all pop-up windows.
7. In the Solution Explorer, right click on the Solution and Remove any web projects which could not be located.
8. In each web project sub-folder, create a .webinfo file if one does not exist.
Note: The .webinfo file should be named
The following is an example of what the .webinfo file must contain:
ClearCase Environment – How do I
Note: This step will fail if the webinfo file from step 8 is not created. 11. In the Solution Explorer, right-click the Solution and click Add Solution to Source Control... 12. In the Solution Explorer, right-click each web project click Add Existing Item... 13. Select the .webinfo file which is inside the project's folder and Checkout when prompted to do so.
You have now completed the steps for adding an existing ASP.NET (Framework 1.x) project to ClearCase for one view. If you wish to work on the ASP.NET (Framework 1.x) project through other views, you must follow the following procedure for those views. DISCLAIMER If you have already attempted to manually add your ASP.NET (Framework 1.x) Solution or Project to ClearCase source control in any way that does not follow the above procedure, then you must remove (cleartool rmelem) everything from ClearCase and start over using the above procedure. Every project and solution has a different combination of files and directories that must be left outside source control as view private. Given the large, and growing, number of ASP.NET project types, Rational Technical Support cannot account for every file and directory that must be left out of source control. Therefore, any attempt to manually add an existing ASP.NET project to ClearCase source control that does not follow the above procedure will not be supported. Troubleshooting Tips:
If you are experiencing permission issues or other unexpected results please consider the information below. ASP.NET maintains its own cache information. To clean up the cache go to C:\winnt\Microsoft.NET\Framework\
Then cd into C:\winnt\Microsoft.NET\Framework\
If you receive an error Access is denied while trying to clean up the cache information do the following first. a. Stop IIS Services b. Go to Task Manager and End Process aspnet_up.exe c. End Process any other web service that is running ASP applications such as xpweb_debug or xpweb_application name. DEBUGGING ASP.NET In order to debug ASP.NET webs and applications, the user must be local administrator on the machine running IIS, as well as, a member of the local VS Developers group. This group is created during the installation of Visual Studio.NET. Security Exception Error
Note: If you encounter the following error using virtual directories:
Security Exception Description: The application attempted to perform an operation not allowed by the security policy. To grant this application the required permission please contact your system administrator or change the application's trust level in the configuration file.
Exception Details: System.Security.SecurityException: Security error.
Source Error:
Line 30: private static bool __intialized = false; Line 31: Line 32: public Global_asax() { Line 33: if ((ASP.Global_asax.__intialized == false)) { Line 34: ASP.Global_asax.__intialized = true;
Review Microsoft Knowledge Base Article 320268 for more details. 62. How do I – understand the ClearCase checkin default options and VS.NET integration This technote identifies a difference in the default checkin behavior as seen through IBM® Rational® ClearCase® Explorer or Windows® Explorer GUI versus that of the Microsoft® Visual Studio .NET integration with ClearCase. Page 73 of 341
ClearCase Environment – How do I
When using ClearCase Explorer or the Windows Explorer integration with ClearCase the default behavior during checkin is to NOT checkin if identical to previous version.
This option must be selected, by default, in order to checkin identical versions. Example:
This is not consistent with the default behavior when running the Visual Studio .NET 2002, 2003 and 2005 integration with ClearCase.
The default behavior is to checkin identical.
To change this behavior to be consistent with the ClearCase default option for all checkins, within VS.NET 2002 & 2003 click Tools > Options > Source Control > SCC Provider > Advanced > Operations and uncheck the Checkin even if identical option.
Note: In .NET 2005, the default behavior is the same; however, there is no longer an option to disable the checkin identical feature for all checkins. The difference in .NET 2005 is that you are now prompted during each checkin to choose if you want to checkin identical (whereas in .NET 2002 and 2003 you did not have this option).
You can now uncheck the option for each checkin. Page 74 of 341
ClearCase Environment – How do I
Note: You will need to ensure that ClearCase is configured to Prompt for comment in order to see the window that has the checkin option; otherwise, you will not be prompted to change the option and the checkin will be identical by default. Check the following setting from .NET 2005 as follows:
Tools > Options > ClearCase Rational ClearCase > General > ClearCase User Options > Operations
63. How do I – improved handling of the Open from Source Control function within Microsoft Visual Studio .NET IBM® Rational® ClearCase® 2003.06.01 and later has improved handling of the Open from Source Control function within Microsoft® Visual Studio® .NET by using a new file with the extension ".ccscc".
The *.ccscc file is a ClearCase Source Control Info file that contains information about the projects in a solution.
This file was introduced in ClearCase 2003.06.01 in order to improve ClearCase's handling of the Open from Source Control function specifically when Virtual Projects are involved. This file is required by ClearCase and needs to be added to source control. The file is created when the project is added to source control. This functionality cannot be disabled and the file cannot be removed.
Note: The *.ccscc file needs to be under source control to support multi-user "Open from Source Control" operations. If this file were left as a view-private, a second user opening the Solution that contains projects would encounter error messages. For solutions that contain mixed projects, the projects will fail to open and remain unavailable. 64. How do I – understand the procedure to integrate ClearCase and VS.NET 2005 How do I integrate Microsoft® Visual Studio .NET 2005 using IBM® Rational® ClearCase® version 2003.06.16 (Service Release 6), version 7.0 or later if ClearCase is installed before VS .NET 2005 on a client system.
Procedure to integrate ClearCase version 2003.06.16 or 7.0 and VS .NET 2005
This technote explains how to integrate ClearCase version 2003.06.16 or 7.0 and VS.NET 2005 if ClearCase is installed before VS .NET 2005 on a client system. Page 75 of 341
ClearCase Environment – How do I
Note: Visual Studio .NET 2005 is only supported with 2003.06.15 (Service Release 5 patch 2006C) when used with the IBM Rational ClearCase Client for Visual Studio .NET (CCCQ.NET) add-on for .NET. For details on the ClearCase Client plug-in, refer to Release Notes GI11-6728-00.
INSTRUCTIONS:
1. Go to Start > Control Panel > Add/Remove Programs
2. Locate the IBM Rational ClearCase program and click the Change option.
3. When the ClearCase installation Wizard window appears select Next.
Page 76 of 341
ClearCase Environment – How do I
4. You will be prompted to either Modify, Repair, or Remove the application. Select Modify and click Next.
5. When the Custom Setup window appears, select IBM Rational ClearCase Client for VS .NET. Expand the option and ensure that you select, This feature will be installed on the local hard drive. Click Next.
Page 77 of 341
ClearCase Environment – How do I
6. The Ready to Modify Program window will appear, click Install.
7. After the installation is completed, select Finish.
Note: You will need to restart the system in order to complete the integration.
Page 78 of 341
ClearCase Environment – How do I After restart, when you open VS .NET 2005, you will now see the ClearCase option on the Menu Bar at the top of the GUI. 65. How do I – understand the possible corruption caused editing files from Visual Studio.NET using remote dynamic views There is a known problem reported and confirmed by Microsoft as a defect in the Windows redirector that causes potential file corruption when files are edited are served up from a remote file share. In ClearCase, this has been determined to affect editing from the Visual Studio.NET IDE in dynamic views when the view server is remote. In this configuration, the Visual Studio.NET IDE can truncate files resulting in data loss. The problem is traceable to a memory mapped file issue and the specific way that the IDE editor maps files for editing. The operating systems where this defect exists include Windows 2000, Windows XP and Windows 2003. Note: This problem is also more prevalent in Windows 2000 with Service Pack 4 than earlier Windows 2000 service packs.
Solution Microsoft has hot-fixes for this defect.
You need to contact Microsoft Support Services the fix by specifying the appropriate Knowledge Base Article.
The links to the Microsoft hot-fixes are below, under the Related information section.
66. How do I - FIX: The IBM Rational ClearCase remote view may cause file corruption in Visual Studio .NET 2003 View products that this article applies to. Article ID : 875516 Last Review : May 15, 2006 Revision : 4.0 For a Microsoft Microsoft Visual Studio .NET (2002) version of this article, see 883518http://support.microsoft.com/kb/883518/.
SYMPTOMS The third-party products that this article discusses are manufactured by companies that are independent of Microsoft. Microsoft makes no warranty, implied or otherwise, regarding the performance or reliability of these products.
When you use IBM Rational ClearCase remote view to make a change to a file, you may experience a file corruption problem and you may receive the one of the following error messages in Microsoft Visual Studio .NET 2003: Access Denied The volume for a file has been externally altered so that the opened file is no longer valid. (Win32:ERROR_FILE_INVALID 1006, NTSTATUS:STATUS_FILE_INVALID 0xC0000098). Back to the top RESOLUTION A supported hotfix is now available from Microsoft, but it is only intended to correct the problem that this article describes. Apply it only to systems that are experiencing this specific problem.
To resolve this problem, contact Microsoft Product Support Services to obtain the hotfix. For a complete list of Microsoft Product Support Services telephone numbers and information about support costs, visit the following Microsoft Web site: http://support.microsoft.com/contactus/?ws=support Note In special cases, charges that are ordinarily incurred for support calls may be canceled if a Microsoft Support Professional determines that a specific update will resolve your problem. The usual support costs will apply to additional support questions and issues that do not qualify for the specific update in question.
The English version of this hotfix has the file attributes (or later file attributes) that are listed in the following table. The dates and times for these files are listed in Coordinated Universal Time (UTC). When you view the file information, it is converted to local time. To find the difference between UTC and local time, use the Time Zone tab in the Date and Time tool in Control Panel. Date Time Version Size File name ------24- July-2004 04:16:10 7.10.4206.0 3,788,800 Msenv.dll 24-July-2004 04:27:27 7.10.4206.0 602,624 VCProject.dll 24-July-2004 04:28:35 7.10.4206.0 1,836,032 VCProjectEngine.dll Back to the top Page 79 of 341
ClearCase Environment – How do I MORE INFORMATION For more information, click the following article number to view the article in the Microsoft Knowledge Base: 824684 Description of the standard terminology that is used to describe Microsoft software updates When you experience this problem, you can edit and save the file successfully. But when you reopen the file, you will find that the file is no longer valid. You may see additions to the file, deleted data that is still present, or data missing from the end of file. You will not experience this problem if you make a change to the files locally.
For additional information about ClearCase, visit the following Web site: http://www-306.ibm.com/software/awdtools/clearcase/index.html Microsoft provides third-party contact information to help you find technical support. This contact information may change without notice. Microsoft does not guarantee the accuracy of this third-party contact information. 67. How do I - add existing Microsoft ASP.NET Framework 1.x Web Applications to source control with Rational ClearCase If you have not yet attempted to add your existing ASP.NET 2002/2003/2005 (Framework 1.x) Web Application to ClearCase source control, follow the procedure below. Note: The procedure below assumes an ASP.NET (Framework 1.x) project already exists as a Visual Studio.NET project inside a Visual Studio.NET solution and that you are using Internet Information Server 5.0 or later. If you have already added your ASP.NET (Framework 1.x) solution or project to ClearCase source control and you are having problems, review the Troubleshooting Tips at the end of the technote for assistance.
IMPORTANT: If you have already attempted to manually add your existing ASP.NET (Framework 1.x) solution or project to ClearCase source control and you are having problems, review the DISCLAIMER at the end of the technote for instructions. Add an existing ASP.NET 2005 (Framework 2.x) Project to ClearCase: If you need to add your existing ASP.NET 2005 (Framework 2.x) project to source control, refer to technote 1256082. Add a New ASP.NET (Framework 1.x) Project to ClearCase: If you need to add a new ASP.NET (Framework 1.x) solution or project to source control with ClearCase, refer to technote 1129588. Add an existing VS.NET Project (Non-ASP.NET) to ClearCase: If you need to add a VS.NET (non-ASP.NET) project to source control with ClearCase, refer to technote 1129529. Add a New VS.NET Project to ClearCase. Follow the instructions in the Online Help.included with ClearCase (Start > Programs > IBM Rational > IBM Rational ClearCase > Online Help > Rational ClearCase
Solution Instructions - Step by Step: Virtual Directory Setup Set up Internet Information Server
1. Create a VOB and snapshot view to use with your ASP.NET (Framework 1.x) project.
Note: Rational does not support serving ASP applications or webs in a dynamic view. Change request (RFE) RATLC00608173 has been submited to add support for this functionality.
Production deployment needs to be done through a snapshot view. Review Microsoft Knowledge Base Article 320268 for more details on the errors related to using a dynamic view to host ASP pages. Developing an ASP.NET project however, can be performed from a dynamic view. If the KB article has been applied successfully, attempts to use a Dynamic view with .NET IIS the following must be done: Do NOT used the Mapped Drive: M:\viewname\......
Use a UNC path to the MVFS drive: \\view\
Where \\view is the literal name and
Page 80 of 341
ClearCase Environment – How do I 2. Copy the ASP.NET (Framework 1.x) Project(s) into the snapshot view.
Example: C:\snapshot_view\vob\ASP_Project\
3. Open Internet Information Services (IIS) and create a Virtual Directory.
The Example: Start > Settings > Control Panel > Administrative Tools > Internet Information Services
4. Create a name for the Virtual Directory (App2 will be used for this example). 5. Provide a path for the virtual directory using the ASP.NET (Framework 1.x) Project in the snapshot view. Example:
C:\snapshot_view\vob\ASP_Project\App2\ 6. Set the Access Permissions as required. Note: There are no ClearCase specific permissions required. 7. Close all windows to finish. You will see the included sub folders now appear in the IIS containing all files. 8. Repeat for each Project as needed.
Add the ASP.NET Project to ClearCase Source Control
1. Copy the existing Solution folder into the ClearCase view within the VOB.
Note: Be sure to leave the copied Solution folder with the same name.
2. Within the copied Solution folder, open the solution (*.sln) file and remove the entire section labeled:
"GlobalSection(SourceCodeControl) = preSolution" through "EndGlobalSection" inclusive.
Note: If using virtual directories, change project URL to point to the Virtual Directory created above, Page 81 of 341
ClearCase Environment – How do I should be 2nd line in file.
3. Delete *.scc from every folder and sub-folder of the Solution.
4. Delete *.vspscc from every folder and sub-folder of the Solution.
5. From Visual Studio.NET open the copied .sln file.
Note: Click OK to all pop-up windows.
6. In the Solution Explorer, right click on the Solution and Remove any web projects which could not be located.
7. In each web project sub-folder, create a .webinfo file if one does not exist.
Note: The .webinfo file should be named
The following is an example of what the .webinfo file must contain:
8. In the Solution Explorer, right-click the Solution and click Add > Add Existing Project From Web.
9. Give the URL to the
Note: This step will fail if the webinfo file from step 8 is not created.
10. In the Solution Explorer, right-click the Solution and click Add Solution to Source Control...
11. In the Solution Explorer, right-click each web project click Add Existing Item...
12. Select the .webinfo file which is inside the project's folder and Checkout when prompted to do so.
You have now completed the steps for adding an existing ASP.NET (Framework 1.x) project to ClearCase for one view. If you wish to work on the ASP.NET (Framework 1.x) project through other views, you must follow the following procedure for those views.
DISCLAIMER If you have already attempted to manually add your ASP.NET (Framework 1.x) Solution or Project to ClearCase source control in any way that does not follow the above procedure, then you must remove (cleartool rmelem) everything from ClearCase and start over using the above procedure. Every project and solution has a different combination of files and directories that must be left outside source control as view private. Given the large, and growing, number of ASP.NET project types, Rational Technical Support cannot account for every file and directory that must be left out of source control. Therefore, any attempt to manually add an existing ASP.NET project to ClearCase source control that does not follow the above procedure will not be supported.
Troubleshooting Tips:
If you are experiencing permission issues or other unexpected results please consider the information below. ASP.NET maintains its own cache information. To clean up the cache go to C:\winnt\Microsoft.NET\Framework\
Then cd into C:\winnt\Microsoft.NET\Framework\
If you receive an error Access is denied while trying to clean up the cache information do the following first. Page 82 of 341
ClearCase Environment – How do I a. Stop IIS Services b. Go to Task Manager and End Process aspnet_up.exe c. End Process any other web service that is running ASP applications such as xpweb_debug or xpweb_application name.
DEBUGGING ASP.NET In order to debug ASP.NET webs and applications, the user must be local administrator on the machine running IIS, as well as, a member of the local VS Developers group. This group is created during the installation of Visual Studio.NET. Security Exception Error
Note: If you encounter the following error using virtual directories:
Security Exception Description: The application attempted to perform an operation not allowed by the security policy. To grant this application the required permission please contact your system administrator or change the application's trust level in the configuration file.
Exception Details: System.Security.SecurityException: Security error.
Source Error:
Line 30: private static bool __intialized = false; Line 31: Line 32: public Global_asax() { Line 33: if ((ASP.Global_asax.__intialized == fals e)) { Line 34: ASP.Global_asax.__intialized = true;
68. How do I - create new ASP.NET Framework 1.x Web Applications while under source control with Rational ClearCase the procedure for creating a new Microsoft® Visual Studio.NET version 2002, 2003 and 2005 web project (ASP.NET Web Application) using Framework 1.x while under IBM® Rational® ClearCase® source control.
Cause If you have already added an ASP.NET (Framework 1.x) solution or project to ClearCase source control, and wish to create a new project, follow the procedure below.
Note: If you have already added your ASP.NET (Framework 1.x) solution or project to ClearCase source control and you are having problems, review the Troubleshooting Tips at the end of the technote for assistance. Add an existing ASP.NET Project to ClearCase: If you need to add your existing ASP.NET project to source control, refer to the following technotes: .NET 2002 & 2003 & 2005 (Framework 1.x): Technote 1129589 .NET 2005 (Framework 2.x): Technote 1256082
Add an existing VS.NET Project (Non-ASP.NET) to ClearCase: If you need to add a VS.NET (non-ASP.NET) project to source control with ClearCase, refer to technote 1129529. Add a New VS.NET Project to ClearCase. Follow the instructions in the Online Help.included with ClearCase (Start > Programs > IBM Rational > IBM Rational ClearCase > Online Help > Rational ClearCase integrations with vendor products > Microsoft VS.NET)
Solution Creating a New ASP.NET project in ClearCase: 1. Create a VOB and view that you plan using with your ASP.NET (Framework 1.x) project.
Note: Rational does not support serving ASP applications or webs in a dynamic view. Change request (RFE) RATLC00608173 has been submited to add support for this functionality.
Production deployment needs to be done through a snapshot view. Review Microsoft Knowledge Base Article 320268 for more details on the errors related to using a dynamic view to host ASP pages. Developing an ASP.NET project however, can be performed from a dynamic view.
If the KB article has been applied successfully, attempts to use a Dynamic view with .NET IIS the following must be done:
Do NOT used the Mapped Drive: Page 83 of 341
ClearCase Environment – How do I M:\viewname\......
Use a UNC path to the MVFS drive: \\view\
Where \\view is the literal name and
The option A share located on another computer on the IIS admin console "Virtual Directory" tab, enter the user's account credentials (when you press the "connect as" button) and set the anonymous access account (on the "Directory Security" tab) to the same account.
IMPORTANT: Open VS.NET and click Tools > Options and select Projects and Solutions from the Environment category. In the box labeled Visual Studio Projects Location, browse or type the view/VOB path. This should be done before continuing to step #2. 2. Create a blank solution and store in the VOB.
Note: This will create a solution folder in the VOB. 3. In ClearCase Explorer or Windows Explorer create a folder inside the solution folder that will represent the name of your ASP.NET project or application. 4. Start the Internet Information Services (IIS) Manager.
Example: Click Start > Settings > Control Panel > Administration Tools > Internet Service Manager. 5. Right-click Default Web Site and select Properties. 6. Under the Home Directory tab, select A directory located on this computer and then browse to solution folder located in the VOB. 7. Click Apply, and then OK. Close the Default Web Site properties.
Note: You can also accomplish the mapping in IIS above using virtual directories.
a. Right Click on the default web site node and select create new virtual directory.
b. The alias for the virtual directory should be the same name as the project folder you created in step #3 above.
c. Browse or type in the path where the project folder lives when prompted. i.e. M:\view- tag\vob-tag\folder
Note: The path to the content must go through the drive letter that is set in the ClearCase Control Panel under the MVFS tab. The default is "M". This must be set to the same value on all systems that will be accessing common projects and applications
d. Enable all access rights when prompted. Read, run scripts, execute, write, and browse.
e. Select finish. 8. Open VS.NET
Create a new ASP.NET Web Application project. During creation, select to add the project to the solution you created in step #2. Right click on the solution you created in step #2 and select Add New Project. Then select the type of VB Project you would like.
Note: Make sure the URL path is pointing to http://localhost/project-name.
IMPORTANT: If you create the project without creating the solution first, .NET will place the solution file in C:\Documents and Settings\{username}\MY Visual Studio Projects. When you try to add the project to source control .NET will look for the solution file in the VOB and when .NET can not find the solution file, .NET will abort the add to source control operation. The solution file must be placed in the VOB. The project folder must be placed inside the solution folder. 9. In the VS.NET Solution Explorer, right-click on the Solution and select Add to Source Control... 10. You may see a pop-up dialog box that says the following:
You are attempting to add some File Share Web access projects to source control. If you continue, you will no longer be able to open these projects using Front Page Web Access."
Page 84 of 341
ClearCase Environment – How do I
Click Continue. 11. You may then see another pop-up dialog box that says the following:
The project
Click Continue. 12. Once the project has been added to source control you are now ready to perform ClearCase Operations within the .NET IDE.
Note: In order to Debug or Start without Debugging within the .NET IDE you will need to perform the following steps: Set a breakpoint Set your Start Page for the default.aspx file you are going to use as the start page. Rebuild the solution. Checkout the following files o Global.asax o Web.config o Default.aspx (start page) Rebuild the solution. Debug or Start Without Debugging.
This completes the steps required for the first view. Troubleshooting Tips:
If you are experiencing permission issues or other unexpected results please consider the information below. ASP.NET maintains its own cache information. To clean up the cache go to C:\winnt\Microsoft.NET\Framework\
Then cd into C:\winnt\Microsoft.NET\Framework\
If you receive an error Access is denied while trying to clean up the cache information do the following first. a. Stop IIS Services b. Go to Task Manager and End Process aspnet_up.exe c. End Process any other web service that is running ASP applications such as xpweb_debug or xpweb_application name.
DEBUGGING ASP.NET In order to debug ASP.NET webs and applications, the user must be local administrator on the machine running IIS, as well as, a member of the local VS Developers group. This group is created during the installation of Visual Studio.NET. Security Exception Error
Note: If you encounter the following error using virtual directories:
Security Exception Description: The application attempted to perform an operation not allowed by the security policy. To grant this application the required permission please contact your system administrator or change the application's trust level in the configuration file.
Exception Details: System.Security.SecurityException: Security error.
Source Error:
Line 30: private static bool __intialized = false; Line 31: Line 32: public Global_asax() { Line 33: if ((ASP.Global_asax.__intialized == false)) { Line 34: ASP.Global_asax.__intialized = true;
Page 85 of 341
ClearCase Environment – How do I 69. How do I - move a Visual Studio.NET project under SourceSafe to ClearCase while retaining history Here is the procedure to complete the migration of a Visual Studio.NET (7.x and 8.x) project (that's currently under source control in Visual SourceSafe 6.0) to ClearCase. This procedure will retain the project history after moving the project to ClearCase source control. The below instructions contain two phases that must be completed for a successful migration. INSTRUCTIONS:
PHASE 1 of 2
1. Ensure that SourceSafe is the current source code control provider.
8.x (VS.NET 2005)
In VS.NET, click Tools > Options > Source Control > Plug-in Selection Ensure that Microsoft Visual SourceSafe is the selected source code control plug-in.
7.x (VS.NET 2003)
Check to ensure that the ProviderRegKey data value within the Windows Registry is set to Microsoft Visual SourceSafe as the active source code control (SCC) provider. a. Click Start > Run and type: regedit b. Navigate to HKEY_LOCAL_MACHINE\SOFTWARE\SourceCodeControlProvider c. Ensure the ProviderRegKey=Software\Microsoft\SourceSafe
Page 86 of 341
ClearCase Environment – How do I
2. Recursively checkout the project(s) to be migrated and the solution.
Note: At a minimum you should checkout the solution.sln and any project.*proj files.
3. Open VS.NET and open the solution.
4. Click File > Source Control > Change Source Control.
5. Individually select and then Unbind the solution and the project(s).
Page 87 of 341
ClearCase Environment – How do I
6. Recursively checkin the project(s) in Visual SourceSafe.
Page 88 of 341
ClearCase Environment – How do I
7. Close VS.NET
PHASE 2 of 2
1. Ensure that Rational ClearCase is the current source code control provider.
8.x (VS.NET 2005)
In VS.NET, click Tools > Options > Source Control > Plug-in Selection Ensure that Rational ClearCase is the selected source code control plug-in.
7.x (VS.NET 2003)
Change the ProviderRegKey data value within the Windows Registry to point to IBM Rational ClearCase as the active source code control (SCC) provider. a. Click Start > Run and type: regedit b. Navigate to HKEY_LOCAL_MACHINE\SOFTWARE\SourceCodeControlProvider c. Change the ProviderRegKey=Software\Atria\ClearCase
2. Export\import the solution and project(s) using the ClearCase utilities clearexport_ssafe and Page 89 of 341
ClearCase Environment – How do I clearimport
3. Open VS.NET and open the solution (File > Open Solution and browse to the solution.sln within your view/VOB context).
4. Click File > Source Control > Change Source Control.
5. Connect\Rebind the solution and the project(s).
8.x (VS.NET 2005)
For [email protected] 2005, you may not need to manually rebind. Simply open the project in VS.NET 2005, close VS.NET 2005, and then opened it again. Source code control with ClearCase should be functional.
7.x (VS.NET 2003)
6. You will be prompted to checkout the .sln and .*proj files to complete the server binding change.
Page 90 of 341
ClearCase Environment – How do I
Once the binding is complete, the projects will be under ClearCase source code control with all of its previous history retained. 70. How do I – understand about an error occurred during the parsing of a resource required to service this request Why attempts to run the Start without Debugging operation in a Microsoft® ASP.NET project stored in an IBM® Rational® ClearCase® VOB results in the error could not load type global and provides steps to resolve the issue.
Cause The Runtime Security Policy settings in the Microsoft Framework Configuration are too restrictive.
The resulting error message will look similar to the following:
Server Error in '/netvb_proj' Application. ------Parser Error
Description: An error occurred during the parsing of a resource required to service this request. Please review the following specific parse error details and modify your file appropriately.
Parser Error Message: Could not load type 'net_proj.Global'.
Page 91 of 341
ClearCase Environment – How do I
Solution 1. Close VS.NET application 2. On the Web server, change the Microsoft .NET Framework Configuration settings as follows: i. Click Start > (Settings) > Control Panel > Administrative Tools > Microsoft .NET Framework Configuration (1.1 or 2.0) ii. Expand Runtime Security Policy > Machine > Code Groups iii. Right-click All_Code, and then click New
iv. Select Create a new code group. Give your code group a relevant name, such as the name of the applications share. Click Next
Page 92 of 341
ClearCase Environment – How do I
v. In the Choose the condition type for this code group list, select All Code and Click Next
vi. Click on Use existing permission set, and select FullTrust and Click Next
Page 93 of 341
ClearCase Environment – How do I
vii. Click Finish
3. Open up the Services applet (Start > Run, type services.msc) 4. Stop and Restart the IIS Admin Service Launch VS.NET and run the Start without Debugging operation. 71. How do I – understand why a project must be in a view error when adding VS.NET solution to source control When trying to add a Microsoft® Visual Studio® .NET solution or project to IBM® Rational® ClearCase® source control, the error, project must be in a view, appears.
Symptom The following error is reported when attempting to add a Visual Studio .NET solution or project to ClearCase source control: project must be in a view
Cause When a project is created in Visual Studio .NET, the associated solution file (*.sln) is by default created in the folder My Documents\My Projects\
Resolving the problem Page 94 of 341
ClearCase Environment – How do I The project and solution must be kept in separate folders within the same view for the add to source control to be successful. Close Visual Studio .NET, and ensure the project files and the .sln files are maintained in separate folders within a single view.
Open the solution from its new location, and then add the solution or project to source control. Regions 72. How do I – understand the VOB tags are still displayed in the GUI after changing regions issue After changing the region on a local host , the VOB-tags (and view-tags) from the former region are still displayed in IBM® Rational® ClearCase® Explorer and Microsoft® Windows® Explorer.
Cause After switching regions on the local host, the mounted VOBs (and the running views) from the former region are still appearing in ClearCase Explorer and Windows Explorer. Note: Below illustration only shows ClearCase Explorer.
Region 1 With the region set to region1, two mounted VOBs appear in ClearCase Explorer:
List the VOBs in region1:
C:\>cleartool lsvob \childvob \\HOST1\clearcase_storage\vobs\childvob.vbs private \AdminVOB \\HOST1\clearcase_storage\vobs\AdminVOB.vbs private * \1vob \\HOST1\clearcase_storage\vobs\1vob.vbs private * \2vob \\HOST1\clearcase_storage\vobs\2vob.vbs private List the available regions:
C:\>cleartool lsregion region1 unix region2 test List the host information:
C:\>cleartool hostinfo -long Client: HOST1 Product: ClearCase 7.0.0.0 Operating system: Windows NT 5.1 (build 2600) Service Pack 2 Hardware type: Pentium Registry host: HOST1 Registry region: region1 License host: HOST1
Region 2
Page 95 of 341
ClearCase Environment – How do I Change regions on the local host:
C:\>cleartool hostinfo -l Client: HOST1 Product: ClearCase 7.0.0.0 Operating system: Windows NT 5.1 (build 2600) Service Pack 2 Hardware type: Pentium Registry host: HOST1 Registry region: region2 License host: HOST1 From ClearCase Explorer, the VOB-tags are still listed:
The VOB-tags cannot actually be accessed, and their contents are not available. Closing and reopening ClearCase Explorer does not clear the VOB-tags, neither does stopping and restarting ClearCase. Even though the VOB-tags appear, they do not interfere with working in other VOBs that are actually tagged (and mounted) in that region. Note:The VOB-tags do not appear in the cleartool lsvob output of the new region.
Views still appearing after changing regions ClearCase Explorer The view shortcuts continue to be listed in ClearCase Explorer, even after using Refresh View Shortcuts, but they are not accessible, and trying to use them fails with: Cannot start dynamic view admin_vu No tag in region for view "
Windows Explorer The views are listed under the M drive in Windows Explorer, and possibly still show as mapped to a network drive if that option is in use. When accessing them, there is no error, but accessing a VOB does not show any ClearCase context menu options, such as Add to Source Control... or Check Out. Note:The view-tags do not appear in the cleartool lsview output of the new region.
Solution VOBs The VOBs must be unmounted before changing regions on the local host, whether that be a ClearCase server or client. By changing back to the old region, you can unmount the VOBs, then change back to the new region and the VOB-tags will no longer appear in ClearCase Explorer or Windows Explorer.
Page 96 of 341
ClearCase Environment – How do I If you happen to have deleted the old region (while VOBs were still mounted), then rebooting the Windows host will stop the VOB-tags from the old/former region from appearing. View The views must be stopped before changing regions on the local host, whether that be a ClearCase server or client: cleartool endview
Scenario You have multiple ClearCase regions. The VOB server is configured in regionA. A client host is configured in regionB. Attempts to run cleartool protectvob from the client in regionB fails with the error cannot find VOB. The VOB is not tagged in the region that the VOB server resides in.
Solution A VOB or view must have a tag in the region to which its server host is assigned. The term server host represents the host to which the VOB or view processes run. In most cases, each VOB or view must have a tag in the region on the host on which the VOB and view storage directory resides. The exception is where VOB or views storage pools are managed on remote servers (such as on NAS servers).
Example: A VOB server is named host1 and the region set on that host is named region1. There are 2 other regions created on the registry server (region2 and region3). When a VOB is created whose storage resides on host1, there MUST BE a tag created in region1 at a minimum. A tag can be created in other regions as required. If this configuration standard is not met, problems with access to the VOB or view can and will develop over time. Email 74. How do I - configure fully qualified domain names in e-mail notifications using SMTP explains how to configure the inclusion of a domain name extension in the sender field of email notifications using SMTP on Microsoft® Windows® hosts running IBM® Rational® ClearCase® Service Release 5 (2003.06.15) or later.
Solution Note: This solution contains information about modifying the system registry. Before making any modifications to the Microsoft Registry Editor, it is strongly recommended that you make a backup of the existing registry. For more information describing how to back up the registry, refer to the Microsoft Knowledge Base article 256986.
A registry key was introduced in version 2003.06.15 (Service Release 5) that enables Windows clients to include a domain name extension in the sender field of messages issued by the email notify command.
Note: This only affects "Mail From" of the SMTP setting.
The registry key can be set to a value that will be appended to a user name when the Notify program sends email over SMTP.
How to setup the registry key:
Page 97 of 341
ClearCase Environment – How do I Set the following registry value to an e-mail domain that is valid within your organization. For example us.mycompany.com.
Registry Settings System Key: [HKEY_LOCAL_MACHINE\Software\Atria\ClearCase\CurrentVersion\MailDomainName]
Verify that this is working correctly: You can test to see if this is working correctly by running the notify utility with -t (trace) option to send an mail to yourself:
Note: The Notify program referenced above is a utility used by the job scheduler and other servers to send e-mail notifications. It is not intended to be used outside of this facility and any such use is unsupported. notify -t [email protected]
The output from the trace should indicate the correct fully qualified domain name for the user in the "MAIL FROM" line (in the example below: [email protected]).
Example:
>>> 19:44:29.218 (notify): SMTP Send: MAIL FROM:[email protected]
Note: Be aware of the expected behavior experienced when the Notify program is used: If the MailDomainName registry value does not exist, the hostname is appended to the user name after the '@' (default behavior). If the MailDomainName registry value exists and is not empty, it's content are appended to the user name after '@'. - If the MailDomainName registry value exists and is empty, nothing is appended to the user name (not even '@'). Problems and issues 75. How do I – understand why cleartool checkvob –evil_twin
Cause Evil twins are created when the same name is created in different branches of the same VOB directory. It is important to exercise caution in deciding whether to remove a twin, to avoid potentially losing data.
If the VOB is at Feature Level 7 (schema 80), you can use the cleartool subcommand, checkvob - evil_twin
Resolving the problem You can use the cleartool subcommand, describe -aliases, to find the directory version that catalogs the element that is a twin of the other element. Look under the output section labeled Significant pathnames:
> cleartool describe –aliases –all /var/tmp/myvob/file.c … Significant pathnames: /var/tmp/myvob/file.c@@ /var/tmp/myvob/subd@@/main/mine/1/hello.c@@
In this example, the twin displayed by checkvob as /var/tmp/myvob/file.c is also cataloged as hello.c in version /main/mine/1 of the directory element /var/tmp/myvob/subd. Because this element is cataloged Page 98 of 341
ClearCase Environment – How do I in another directory element in the VOB, take extreme caution when cleaning up evil twins; the element may be legitimately used by the name /var/tmp/myvob/file.c.
For comprehensive information on evil twins, search the Rational ClearCase 8.0 Information Center for "evil twin." 76. How do I – understand the “Error: albd_rgy_get_entry call failed: RPC: Timed out - Trouble contacting registry on host "hostname"” issue When issuing a cleartool command from the command line of a ClearCase client system that attempts to communicate with a remote registry server, the following error is generated:
C:>cleartool lsview albd_rgy_get_entry call failed: RPC: Timed out cleartool: Error: Trouble contacting registry on host "host1": timed out trying to communicate with ClearCase remote server. The same error may also be seen when attempting to run a cleartool lsview or cleartool lsvob on Linux.
Cause There are various possible causes for this error which include these two:
Cause 1 On Windows this failure may be due to personal firewall software packages, such as CyberArmor, XP SP2 firewall, or Zonelabs, installed on the client.
Cause 2 On Linux, where all other network diagnostics appear to be in order but a hang still occurs, this could be caused by the Maximum Transmission Unit (MTU) setting which is usually at least 1500 on systems coming out of the box. If the setting is below 1500 for any reason, ClearCase packets fail.
Diagnosing the problem Here is an example of the MTU setting discussed in Cause 2 above: eth0 Link encap:Ethernet HWaddr 00:16:3E:3E:21:DB inet addr:145.36.66.5 Bcast:145.36.66.255 Mask:255.255.255.0 inet6 addr: fe80::216:3eff:fe3e:21db/64 Scope:Link UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1 RX packets:4685434 errors:0 dropped:0 overruns:0 frame:0 TX packets:1465722 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:1000 RX bytes:6744026824 (6.2 GiB) TX bytes:227891731 (217.3 MiB)
Resolving the problem Solution 1 Check for any personal firewall software packages installed or enabled on the client. If so, disable, remove, or configure the software so that ALL ClearCase processes can communicate to and from the client (essentially allow communication to and from all the executables in the ClearCase installation directory). Review technote 1117638 for more details why firewalls and ClearCase do not operate together. Note: IBM Rational does not test against, nor support, the use of personal firewall software packages in conjunction with ClearCase. Solution 2 The MTU setting needs to be set to at least 1500 by the network administrator. 77. How do I – understand the MustGather: Required information for UNIX or Linux Core issues REQUIRED TROUBLESHOOTING INFORMATION: 1. What executable cored? (On some architectures, you can see this by using the command 'file
Note: If the program coring is not a ClearCase program, this could either be an MVFS problem or a bug with the program that is coring itself. Try the same execution outside of the MVFS (outside of a dynamic view context). If it works, the problem is most likely MVFS related. If it fails, then the user should contact the vendor of the program that is coring.
2. If a ClearCase program is coring, then collect a copy of the core. Page 99 of 341
ClearCase Environment – How do I 3. Get the ClearCase log files.
4. Get a transcript of the failure that includes the command executed and the stdout and errors produced by the execution.
5. Is the core dump reproducible? If yes, provide steps to reproduce.
6. Does the program dump core on all clients (or at least more than one)? If 'no', what is the difference between the systems that are effected and those that are not?
7. What method was used to install ClearCase (such as, standard, link, mount, and so forth)?
Note: If ClearCase is link installed, is it possible that the release host became unavailable while the executable was in the process of running? This could cause the executable to core.
Contact IBM Rational Client Support for further assistance prepared to provide the above information. 78. How do I – understand the ALERT: albd service unexpectedly installed during a ClearCase 7.1 Client Only Installation on Windows This alert is meant to inform you of an issue that can occur when installing IBM Rational ClearCase (CC) 7.1 on Windows where the albd service is unexpectedly installed even though the option for Local vobs and views was not selected.
ISSUE When performing a Client Only install on a Windows host and not selecting "Local vobs and views", the albd service is unexpectedly installed.
This issue has been identified as a product defect under APAR PK78380. IMPACT The installation of the albd_server process creates an unnecessary process on what is expected to be a client only install. The ClearCase albd server process account also needs to be granted rights to "Log on as a service" (which may not be desired). If the proper rights are not granted, the service will fail to start and ClearCase will not function properly on that client. Note: You will receive the correct behavior where you can not create local vobs or views and you can still create remote VOBs and views without an issue. However, the albd_server is running on the system where it should not have been installed. Refer to the IBM Rational ClearCase Administrators Guide under the topic of Defining required domain accounts manually for further details about the albd server process account requirements. WORKAROUND The workaround for this issue is to do the following: 1. From a command prompt, run net stop albd. This will stop the albd_server. Note: You can also stop the service in the ClearCase Control panel and the Microsoft Services Management Console. 2. Then run sc delete albd. This command will remove the albd service from Windows. KNOWN ISSUES ClearCase Doctor reports "ClearCase does not appear to be running on this computer.".
The removal of the service also adds a new error to ClearCase doctor, which says that ClearCase is not running on the machine.
Page 100 of 341
ClearCase Environment – How do I
Uninstalling ClearCase:
After implementing this fix, if you try to uninstall ClearCase, you will receive an error that the installer was unable to stop the albd service. Also, some ClearCase files in the C:\Program Files\IBM\RationalSDLC are not removed. You can remove the ClearCase directory manually by doing a right-click==>Delete. If you receive an access denied message regarding CCshmemV3, reboot the system and then delete the files. Using the above workaround does not resolve the problem of ClearCase Doctor incorrectly reporting that the client can have local vobs and views. Refer to technote 1366273 for further information about a separate defect related to this issue.
79. How do I – understand why clearmake core dumps on RHEL 4 64-bit Linux platform When clearmake is run on a RHEL 4 64-bit platform, clearmake core dumps. Running the same clearmake on a 32-bit system has no issues.
Cause The main cause for this may be due to a very large makefile macro of over 390K characters.
Resolving the problem Break the macro down to smaller macro definitions. Once the macro is broken down into smaller macro definitions, then the core events will stop. The reason that this did not core on a 32-bit system was in how memory was managed for compiling programs. Basically, a 32-bit system could use unlimited amounts of memory. On a 64-bit system with a 32-bit application being compiled, there is a 2GB limit and that is what caused the core event 80. How do I – understand the “Running Eclipse or compilers or any application that sets file locks in a view causes Linux Kernel Panic” issue While running on Red Hat Enterprise Linux 4 (RHEL4) on kernel 2.6.9-22 and -34 applications that sets file locks in a VOB/View context worked as expected. After upgrading to 2.6.9-42 these same applications caused a kernel panic. The following are examples of the output from a resulting crash:
Call Trace: nfs_lock+0x0/0xc7 [nfs] locks_remove_posix+0x8f/0x137 __fput+0x41/0x100 filp_close+0x59/0x5f Page 101 of 341
ClearCase Environment – How do I mvop_linux_close_kernel+0x18/0x1f [vnode] mvop_linux_close+0x81/0xc9 [vnode] mvfs_closev_ctx+0x15d/0x230 [mvfs] vnode_fop_release+0x62/0x7d [vnode] __fput+0x55/0x100 filp_close+0x59/0x5f put_files_struct+0x57/0xc0 do_exit+0x245/0x404 sys_exit_group+0x0/0xd get_signal_to_deliver+0x31e/0x346 do_signal+0x55/0xd9 autoremove_wake_function+0x0/0x2d pipe_readv+0x225/0x29e pipe_read+0x1c/0x20 vfs_read+0xb6/0xe2 sys_read+0x3c/0x62 do_notify_resume+0x28/0x38
OR
[ffffffff8018ca5a] locks_remove_flock+125 [ffffffffa01cfb79] lockd:nlmclnt_locks_release_private+33 [ffffffff8018c9d3] locks_remove_posix+374 [ffffffffa02b06cb] nfs:nfs_commit_inode+79 [ffffffff8017878d] __fput+73 [ffffffff801773e8] filp_close+103 [ffffffff80177471] sys_close+130 [ffffffff801101c6] system_call+126
Cause The cause is a combination of two issues: 1. Kernel Related Problem from Red Hat (kernel bug):
http://rhn.redhat.com/errata/RHBA-2007-0791.html
RIT117294-NFS randomly returns EINTR on lock removal and causes a panic condition within the Kernel.
This issue has been confirmed by Red Hat to be a kernel bug caused by issues with the file system not handling file locking correctly.
There is a current bug against this issue with Red Hat, #1361130.
ClearCase Related Problem with MVFS: Defect APAR PK25224 has been submitted to address the issue. Review technote 1240506 for more details.
Resolving the problem 1. Contact Red Hat to obtain a fix for the NFS kernel bug.
This issue has been confirmed by RedHat to be a kernel bug caused by issues with the file system not handling file locking correctly. Refer to following errata kernel notes for more information concerning the bug:
http://rhn.redhat.com/errata/RHBA-2007-0791.html
***IMPORTANT NOTE*** Before you apply the above errata (or later erratas for RedHat Enterprise 4 U6, or later kernels beyond U6) to a ClearCase system with MVFS installed, you will be required to apply a fix to resolve the issue reported in APAR PK61579. Refer to technote 1296516 for further information. 2. Apply the patches which resolve defect APAR PK25224. Review technote 1240506 for more details.
Page 102 of 341
ClearCase Environment – How do I IMPORTANT: Both of the above fixes (Red Hat kernel and ClearCase MVFS) will be necessary to fully resolve this issue.
81. How do I – understand the MVFS related issue where NFS file locks on Red Hat Linux become stranded causing system panic System panic occurs after applying RedHat kernel patch for Bugzilla Bug 41942 - RIT161907 as a result of stranded NFS file locks on Red Hat Linux. Any attempts to access remotely hosted VOBs or Views from the MVFS using NFS, especially if the VOB and View storage is on a network attached storage (NAS) filer, has the chance to cause an indefinite file lock within the Red Hat 2.6.x kernel virtual filesystem (VFS) when the above referenced patch or later is applied.
Cause Defensive MVFS code causes NFS file locks on Red Hat Linux to be stranded causing a system panic, after applying RedHat kernel patch for Bugzilla Bug 41942 - RIT161907
Bugzilla Bug 41942 - RIT161907 addressed several issues within the RedHat kernel that caused file locks to be held in excess of 30 seconds with the following configuration: ClearCase 7.x VOB server
RedHat Linux versions RHES 4 with U4, U5, U6 and RHES 5 with no updates and U1 [This includes all errata kernels for those particular updates]
NAS storage for the hosted VOBs RedHat has identified problems within those kernels within Bugzilla Bug 41942 - RIT161907: http://rhn.redhat.com/errata/RHBA-2007-0791.html Once the RedHat kernel patch has been applied to the host operating system OR when any newer versions of the RedHat kernel contain the patch, the following ClearCase configurations require the resolution for APAR PK61579 to be applied immediately to that system. Defect APAR PK61579 has been opened to investigate this issue.
To be added to the list of clients reporting this issue, contact IBM Rational Client Support.
Environment Configuration involved in problem scenario: 1. Any remote VOB/View access from a client using the MVFS
2. VOB/View storage is on a NAS device, and MVFS is installed on either the VOB/View server and/or a client is accessing the hosted VOBs/Views
3. File access through MVFS that accesses remote storage on NFS The MVFS versions of ClearCase affected are as follows: clearcase_p2003.06.00-37 and later
7.0.0.1-IFIX04 and later
7.0.1-IFIX01 and later.
Resolving the problem There is currently no resolution available for this defect. WORKAROUND Contact IBM Rational Client Support to request a testfix. 82. How do I - understand about Evil Twins
About Evil Twins This technote explains what is meant by the term "Evil Twins" and provides guidance on how to identify and recover from evil twins in your IBM Rational ClearCase environment. A video demonstration of the material contained in this technote is available on the IBM Rational Support channel on You Tube under the topic of ClearCase Evil Twin Elements. Page 103 of 341
ClearCase Environment – How do I Note: ClearCase 8.0 introduced new functionality to help you better manage Evil Twin elements. Refer to the ClearCase 8.0 Information Center under the topics of Managing "evil twins", protectvob and checkvob for further details.
ABOUT EVIL TWINS What is meant by the term "Evil Twins"?
"Evil Twins" is a commonly used phrase to describe a situation in which two elements, of the same name, are created in two different versions of the same directory element. Example:
DIR1@@/main/1 ==> foo.c added DIR1@@/main/2 ==> foo.c rmnamed DIR1@@/main/3 ==> foo.c added Evil Twins are often created when two people add the same file to source control at the same time. ClearCase allows this to happen because the element is actually referenced internally by its OID (Object ID) and not it's name. ******* Another kind of Evil Twins can occur on Microsoft® Windows®. The Windows operating system is case IN-sensitive (as opposed to UNIX® and Linux® which is case sensitive). This means that only one name regardless of case can exist in a single directory on Windows. To illustrate, open Windows Explorer and attempt to create the following files in a temp directory:
FOO.c foo.c You will be unable to do so due to how Windows manages file names. The ClearCase MVFS can be configured to be case sensitive.
By setting the MVFS to be case sensitive, you can then create files in a VOB in the same directory that have the same name differing only by case.
For example, you can create the following files in the same directory: FOO.c foo.c Page 104 of 341
ClearCase Environment – How do I
This is not a problem, so long as it is intentional and you are aware of the situation. If you are not aware of the situation, it could be problematic. For example, if you use a combination of Snapshot views and dynamic views on Windows and have a case sensitive MVFS setting, you could run into a problematic scenario: For example: dir1@@\main\1\FOO.c dir1@@\main\1\foo.c As Windows will only allow one of these files to exist in a directory space on Windows, ClearCase cannot load both into a snapshot view hosted on Windows. Note: An eclipsed file is not the same as an evil twin, refer to technote 1132484 for more information about eclipsed files and ClearCase.
LOCATE EVIL TWINS Now that you know what the identifying mark of an evil twin is, you can now takes steps to locate them in your VOB.
Use the cleartool find command to locate either FILE or DIRECTORY elements that "may be" evil twins.
CONFIRM EVIL TWINS The following steps need to be taken to confirm the existence of evil twins.
1. When two files are found with the same name in two different versions of the directory, you can run the cleartool dump command to see if the files are in fact different elements.
Example: foo.c ==> DIR1@@/main/1 foo.c ==> DIR1@@/main/3
If you suspect foo.c may have an evil twin, run the cleartool dump
Example:
M:\dynamic_view\test_vob>cleartool dump foo.c@@ foo.c@@ (e7e4cd6a.e3f74b8f.b3ce.df:06:35:fe:a8:6c) M:\dynamic_view\test_vob\foo.c@@ oid=e7e4cd6a.e3f74b8f.b3ce.df:06:35:fe:a8:6c dbid=177 (0xeb82ef) mtype=file element type=12 stored fstat: ino: 0; type: 2; mode: 0444 usid: NT:S-1-5-21-4179696171-2760821386-689065543-500 gsid: NT:S-1-5-21-4179696171-2760821386-689065543-1011 nlink: 1; size: 0 atime: Wed Dec 31 19:00:00 1969 mtime: Thu Oct 12 07:36:44 2006 ctime: Thu Oct 12 07:36:44 2006 returned fstat: ino: 177; type: 2; mode: 0444 usid: NT:S-1-5-21-4179696171-2760821386-689065543-500 gsid: NT:S-1-5-21-4179696171-2760821386-689065543-1011 nlink: 1; size: 0 atime: Thu Oct 12 07:36:44 2006 mtime: Thu Oct 12 07:36:44 2006 ctime: Thu Oct 12 07:36:44 2006 master replica dbid=3 source pool=33 cleartext pool=35
Note: You can use the Windows findstr command or the UNIX or Linux grep command to sort the results more effectively.
M:\dynamic_view\test_vob>cleartool dump foo.c@@ | findstr oid oid=e7e4cd6a.e3f74b8f.b3ce.df:06:35:fe:a8:6c dbid=177 (0xeb82ef)
/view/test_vob%>cleartool dump foo.c@@ | grep oid Page 105 of 341
ClearCase Environment – How do I oid=e7e4cd6a.e3f74b8f.b3ce.df:06:35:fe:a8:6c dbid=177 (0xeb82ef)
Alternative to dump Instead of dumping the element, you could also run the following command from two views to compare the output: cleartool describe -fmt \"%On, %n\n\"
2. Once you run the cleartool dump command for both files, compare the OIDs.
Note: Be sure you run the dump command using the @@ extension after the file name. This denotes you are dumping the element. If you leave off the @@, you will dump the version (as opposed to the element), thus affecting your output.
If the element OIDs are different but the names are the same, you have evil twins.
RECOVER FROM EVIL TWINS
If you discover evil twins in your configuration, it is important to address them as soon as possible.
You have two choices to resolve the problem.
1. Rename one of the elements using the cleartool mv command. 2. Remove one of the elements using the cleartool rmelem command.
Note: If in a UCM environment, you will need to first rename the element (using cleartool mv) and then remove the name using cleartool rmname. The reason is that removing elements in UCM using cleartool rmelem is not recommended as it can negatively affect your configuration. Review technote 1119222 for more information about removing elements in UCM.
PREVENTION TRIGGERS
The best solution used to control the creation of evil twins is to implement a pre-operational trigger during the mkelem/ add to source control operation.
The objective of the trigger would be to search the directory version tree for an element of the same name prior to creation of the new element.
In other words, the script used by the trigger will be required to look for two different files, with the same name, in two or more different versions of the same directory.
Note: Depending on the number of versions and branches on the directory, this could take some time, thus leading to potential performance degradation around the mkelem operation.
A request for enhancement (RFE) has been submitted requesting that ClearCase provide a built in prevention of evil twins. Refer to ID 1327 RATLC01033987) on the Rational Software RFE Community for further information or to post comments and add yourself to the watchlist for this RFE.
Rational RFE Community homepage Refer to the Rational RFE Community homepage for details and status of Requests for Enhancements for Rational products.
Update: Evil twin detection and prevention added to ClearCase 8.0 "Evil twins" are two elements of the same name that have been created in different versions of the same directory element. When the directory versions are merged, it is not clear which twin has been lost, nor even that the twins may have different versions that need to be merged. The evil twin detection and prevention feature enables you to detect evil twins and suppress their creation. It also enables you to detect and locate existing evil twins.
Related information Google results on Evil Twins IBM developerWorks Warning: Element "element" is not visible in view "view About the MultiVersion File System (MVFS) About eclipsed files and ClearCase
Page 106 of 341
ClearCase Environment – How do I 83. How do I – understand eclipsed files in ClearCase The definition of a ClearCase eclipse A VOB object that is not visible because another object with the same name is currently selected by the view.
Eclipsed elements The most frequent object that become eclipses are elements. An eclipsed element is created when it is obscured by a view-private file.
This event occurs when the dynamic view is not able to delete the local copy of the file after you have checked it in.
Example: The following example illustrates how an eclipsed file are created: 1. In a dynamic view create a view private file (test.txt) 2. In another dynamic view with the same config spec create a view private file with the same name as the first view (test.txt). 3. In one of the views, add the view private file to source control. 4. The other view will now display the file (test.txt) as eclipsed. Certain applications will create a temporary file within the view, thus creating the eclipsed file situation. In the case described above, a third-party tool is locking the local file and preventing ClearCase from deleting it during check-in. Note: Shutting down the application prior to performing the initial copy operation will avoid the eclipse problem.
Solution The solution for resolving eclipsed objects is to rename or remove the local / view-private copy of the object that is obscuring the VOB copy. In the scenario where a third party application is holding a lock on the local copy, you will need to shut down the application in question to release the lock and then refresh the view. The local copy should be removed at that point; however, if for some reason the element is still eclipsed, you should then be able to rename the local copy to resolve the problem. HINT: The following command can assist in finding ecipsed files:
Microsoft® Windows®: cleartool ls -r | find "eclipse" UNIX® and Linux®: cleartool ls -r | grep eclipse
84. How do I – resolve error: unable to set set-id on file Attempts to create a VOB or view on UNIX or Linux (even if the storage is hosted on a NAS filer), can result in the following errors: Error 1: UID Error - example cleartool: Error: unable to set set-id on file /net/host/export/views/test_view.vws/.identity/uid: No such file or directory cleartool: Error: Failed to set identity on view: No such file or directory cleartool: Error: Unable to create view "/net/host/export/views/test_view.vws". Reason: The entry in the dfstab has a value of nosuid applied.
Error 2: GID Error - example cleartool: Error: unable to set set-id on file /vob_store/test.vbs/.identity/group.1501: No such file or directory cleartool: Error: Operation "server_save_ids_flag" failed: No such file or directory. cleartool: Error: Unable to create versioned object base Reason: The user creating the VOB is a member of more than 16 groups.
Page 107 of 341
ClearCase Environment – How do I Error 3: Creating a VOB on NAS cleartool: Warning: Storage pathname "/fas270/vob_test" may not reside on host "ux-host". Registry password: cleartool: Error: unable to set set-id on file /fas270/vob_test/test.vbs/.identity/uid: 0 cleartool: Error: unable to set set-id on file /fas270/vob_test/test.vbs/.identity/gid: 0 cleartool: Error: unable to set set-id on file /fas270/vob_test/test.vbs/.identity/group.10: No such file or directory cleartool: Error: Operation "server_save_ids_flag" failed: No such file or directory. cleartool: Error: Unable to create versioned object base "/fas270/vob_test/test.vbs".
The nosuid option was added for the VOB storage export on the NAS device in the exports configuration file.
Example: The VOB storage export is /vol/ccvol %>/net/fas270/vol % more vol0/etc/exports
#Auto-generated by registry Tue Jan 23 15:09:36 GMT 2007 /vol/vol0 -ro,rw=128.126.65.1,root=128.126.65.1,nosuid /vol/nfstest -rw,root=128.126.65.1,nosuid /vol/cifstest -rw,root=128.126.65.1,nosuid /vol/CM_vol -rw,root=128.126.65.1,nosuid /vol/ccvol -rw,root=128.126.65.1,nosuid
Solutions Error1: Check the entry in /etc/dfs/dfstab for an entry of nosuid. If this entry exists, remove it.
Bad Example: share -F nfs -o rw,anon=0,nosuid -d "project dirs" /export1
Good Example: share -F nfs -o rw,anon=0 -d "project dirs" /export1
Error2: If using ClearCase 7.0, use the CLEARCASE_GROUPS variable to help manage the 16 group limitation. Review technote 1124574 for more details. If using a version of ClearCase prior to ClearCase 7.0, remove the extra groups from the group list and recreate the VOB.
Error3: Remove the nosuid option from the export configuration file for the VOB storage and reboot the NAS filer to take effect.
Example: The VOB storage export is /vol/ccvol
%>/net/fas270/vol % more vol0/etc/exports
#Auto-generated by registry Tue Jan 23 15:09:36 GMT 2007 /vol/vol0 -ro,rw=128.126.65.1,root=128.126.65.1,nosuid /vol/nfstest -rw,root=128.126.65.1,nosuid /vol/cifstest -rw,root=128.126.65.1,nosuid /vol/CM_vol -rw,root=128.126.65.1,nosuid /vol/ccvol -rw,root=128.126.65.1
VOB creation will now succeed as expected.
85. How do I – understand the cleartool: Warning: OBSOLETE command or flag: "-gpa[th]" issue Attempts to register and tag an IBM® Rational® ClearCase® VOB or View that is hosted on a NAS filer results in an error or warning such as cleartool: Warning: OBSOLETE command or flag: "-gpa[th]" while attempting to use the syntax that is stated in the Administrator's Guide.
Cause The ClearCase 7.0 Administrator's Guide on the topic of Administering VOBs on the section titled Replacing a VOB server host for a NAS device displays the following example to register and tag a Page 108 of 341
ClearCase Environment – How do I VOB on a NAS filer: cleartool register -vob -host vobsvr1 -hpath /net/nasdevice/vobstg/libpub.vbs \ -gpath /net/nasdevice/vobstg/libpub.vbs /net/nasdevice/vobstg/libpub.vbs cleartool mktag -vob -replace -host vobsvr1 -tag /vobs/libpub \ -hpath /net/nasdevice/vobstg/libpub.vbs -gpath \ /net/nasdevice/vobstg/libpub.vbs /net/nasdevice/vobstg/libpub.vbs
Attempts to register a VOB or View on a NAS filer using these options results in the following warning: cleartool: Warning: OBSOLETE command or flag: "-gpa[th]"
Note: As stated in the ClearCase 7.0 Release Notes, the following commands have been made obsolete: register -gpath This option is now obsolete. Behavior of obsolete options and aliases can be controlled through use of the CLEARCASE_OBSO_SYN environment variable. For more information, see the env_ccase reference page. mktag -hpath This option is now obsolete. Behavior of obsolete options and aliases can be controlled through use of the CLEARCASE_OBSO_SYN environment variable. For more information, see the env_ccase reference page. The ClearCase 7.0 Command Reference Guide on the topic of env_ccase states the following about the CLEARCASE_OBSO_SYN environment variable:
CLEARCASE_OBSO_SYN Detects instances of the obsolete option-argument style of specifying an object (see the cleartool reference page). If you set this environment variable to the value WARN, it issues warnings when it detects obsolete syntax. When set to SILENT, it silently accepts obsolete syntax. When set to FAIL, it issues errors when it detects obsolete syntax. Default: FAIL.
Solution You need to set the CLEARCASE_OBSO_SYN environment variable to SILENT in order to use the obsolete syntax needed to register and tag a VOB or View on a NAS filer.
Note: When you use a certified NAS device to provide VOB storage, create one or more VOB storage locations on your NAS device (as described in Creating server storage locations on a NAS device) and then use mkvob -stgloc to create VOBs in this storage location to avoid having to use the obsolete commands with register and mktag.
Documentation defect APAR PK37622 has been submitted to update the 86. How do I – resolve a ClearCase Explorer crashes after switching registry servers on host issue Why doees IBM® Rational® ClearCase® Explorer crashes if an instance is open with a view started when a different registry server is set on that host. A warning message will be added to notify the end-user of this issue before changing the registry server.
Cause When working in ClearCase Explorer, it pulls the view (and VOB) information from the registry server that is set on the local host in the ClearCase Properties:
Page 109 of 341
ClearCase Environment – How do I
If a different registry server is set in the Clearcase Properties while ClearCase Explorer is open with a view in use, then ClearCase Explorer will crash, and MVFS errors may appear and/or get reported in the logs. Any active instance of ClearCase Explorer is not able to update with the new registry server information.
This issue has been reported as defect APAR PK16513.
Solution ClearCase Explorer should not remain active when the registry server is changed on the local host. This defect has been resolved in the following updates: ClearCase 7.0 7.0.0.0-RATL-RCC-IFIX02 ClearCase 2003.06.00 Service Release 6
After applying this update, a warning message will be added that appears when you attempt to change registry server without shutting down ClearCase Explorer first: There is at least one instance of ClearCase Explorer running. Changing the registry server while ClearCase Explorer is running can cause undesirable behavior in ClearCase Explorer. It is recommended to close all instances of ClearCase Explorer before proceeding.
Note: This warning does not prevent the change, but does give you a chance to avoid any related problems, as you can cancel out of the operation to shutdown ClearCase Explorer first.
After the registry change is made, when you start ClearCase Explorer, messages similar to the following may get reported when attempting to access a view:
You should click OK on the message, then use View > Refresh View Shortcuts to make any views that you have tagged and registered in the current region available in ClearCase Explorer. 87. How do I – understand the cleartool space output versus du output differences Why is there often a significant difference between IBM Rational ClearCase cleartool space
The cleartool space command is reporting on the space used by actual data within the VOB storage directory and subdirectories. This does not include allocated disk space the database may still have for deleted or scrubbed objects. The operating system command of du reports on allocated disk usage, whether data is present in the database or not. The output from du command will invariably be a larger value than that of cleartool Page 110 of 341
ClearCase Environment – How do I space.
The cleartool reformatvob command will help align the output between cleartool space and du output. Note: The reformatvob command will regain the space occupied in the VOB database thereby making the VOB space (reported by cleartool space)closer to the actual amount of space on the disk (as reported by du). There are some discrepancies which will further keep the two outputs from being similar.
Say for example, you relocate half of VOB A to VOB B. The original source files will remain in the VOB A but will be linked to VOB B. Those source files don't go away from the .vbs/s directory even though they are no longer linked in the db to the OID's in the old VOB.
So when cleartool space is run in the example below, the du is larger as it looks at the actual disk space and not in the database.
So the s directory using space will be smaller using cleartool space on the database than du on the actual ,vbs/s directory.
> cleartool space -dir s Use(Mb) %Use Directory 88.3 1% s ------88.3 1% Subtotal 11444.5 93% Filesystem :/data/p02/vobs/f01 (capacity 12288.0 Mb)
> du -sm s 310.00 s 88. How do I – understand about the Microsoft Word Tracked Changes feature and ClearCase This technote explains why attempts to diff or merge an IBM® Rational® ClearCase® element that is a Microsoft® Word document fails with errors about pending tracked changes and provides instructions to resolve the issue.
Attempts to compare (diff) or merge a previous version of a Microsoft Word document results in the following error:
------Diff Merge ------ClearCase is not able to carry out this operation. One or both versions of the document contain pending tracked changes. Resolve all revisions made to both documents and re-try the operation. ------or ------Diff Merge ------Word cannot compare the file
"Command failed"
Make sure the specified files exist and that the pathnames are correct. Also ensure that there are no pending "tracked changes" in either version of the document. ------The Word document has been checked-in with pending "tracked changes" applied.
Solution ClearCase uses the Merge and Diff capability of Word through the ms_word type manager. Microsoft Word cannot merge copies of files with pending tracked changes applied. Review Microsoft KB article 189241 and KB article 191030 for more details. Before the document is compared or merged, all the pending tracked changes must be completed and track changes turned off.
Page 111 of 341
ClearCase Environment – How do I Determine which branch or version of the element has the pending "tracked changes" enabled and create a new version in which the changes are accepted and change tracking is turned off. 89. How do I – understand the adjusting the MVFS cache size when ClearCase is running may cause a kernel panic issue A known defect that can cause a kernel panic if the Directory Name Cache in the MultiVersion File System (MVFS) on UNIX® or Linux® is adjusted while IBM® Rational® ClearCase® is running.
Cause The backtraces may show the following: > ::cpuinfo ID ADDR FLG NRUN BSPL PRI RNRN KRNRN SWITCH THREAD PROC 3 1041bc00 1d 1 0 -1 no no t-0 000002a10001fd20 (idle) 0 04baea98 1d 0 0 11 yes no t-6 000003001063bca0 perl 1 04d39520 1d 0 0 0 no no t-0 0000030023db5760 perl 2 04d38020 1b 1 0 0 yes no t-0 000003001ee47c40 perl
> 000003001063bca0::findstack stack pointer for thread 3001063bca0: 2a105816a31 [ 000002a105816a31 panic_idle+0x1c() ] 000002a105816ae1 prom_rtt() 000002a105816c31 mvfs_dnclist_init+0xd8() 000002a105816ce1 mvfs_dnc_setcaches+0x2ec() 000002a105816db1 mvfs_set_cache_sizes+0x64() 000002a105816ec1 mvfs_mioctl+0xa48() 000002a105817001 mvfs_ioctlv_subr+0x174() 000002a1058170e1 mfs_ioctlv+0x20() 000002a1058171a1 ioctl+0x1e4() 000002a1058172f1 syscall_trap32+0xa8() > 000003001ee47c40::findstack stack pointer for thread 3001ee47c40: 2a10162a371 000002a10162a421 die+0xa4() 000002a10162a501 trap+0x900() 000002a10162a641 sfmmu_tsb_miss+0x66c() 000002a10162a761 prom_rtt() 000002a10162a8b1 mvfs_get_urdir+4() 000002a10162a961 mvfs_rvclookup+0x1bc() 000002a10162aa41 mfs_bindroot+0x44() 000002a10162ab21 mvfs_lookup_ctx+0x80c() 000002a10162ac11 mfs_lookup+0x24() 000002a10162acd1 lookuppnvp+0x2e8() 000002a10162aed1 lookuppn+0x108() 000002a10162af91 lookupname+0xe8() 000002a10162b0b1 vn_open+0x100() 000002a10162b221 copen+0x94() 000002a10162b2f1 syscall_trap32+0xa8() This has been recorded as defect, APAR PK41017.
WORKAROUND
Change the scaling factor when the system is quiet, and then reboot.
Review the ClearCase Command Reference Guide on the topic of setcache (cleartool man setcache) for more information.
Note: Attempts to only stop ClearCase to adjust the cache will fail. You need to adjust the cache while ClearCase is idle and started and then reboot the server to take affect.
Example Error:
# /opt/rational/clearcase/etc/clearcase stop
# cleartool setcache -mvfs -persistent -scalefactor 4 cleartool: Error: Operation "view_mfs_set_cache_sizes (current sizes)" failed: not a ClearCase object. cleartool: Error: Operation "view_mfs_set_cache_states (current sizes)" failed: not a ClearCase object. cleartool: Warning: Some or all of the parameters you are setting will not take effect until you restart ClearCase. Page 112 of 341
ClearCase Environment – How do I
# /opt/rational/clearcase/etc/clearcase start ClearCase daemons: albd_server lockmgr -q 1024 -u 256 -f 256 Loading MVFS ... Mounting public VOBs...
# cleartool setcache -mvfs -persistent -scalefactor 4 cleartool: Warning: Some or all of the parameters you are setting will not take effect until you restart ClearCase. 90. How do I – understand the unsupported Features of Solaris 10 with Rational ClearCase and ClearCase LT issue There are limitations to Solaris® 10 support with IBM® Rational® ClearCase® and ClearCase LT®; Open Solaris (Solaris Express) and some new Solaris 10 features are not supported for use.
ClearCase 7.0 (SPARC & x86) Support for Solaris 10 for both SPARC and x86 have been added since the initial release of ClearCase 7.0. ClearCase 2003.06.00 (SPARC & x86) SPARC: Support for Solaris 10 was added for the SPARC platform as of patches clearcase_p2003.06.00- 26 and clearcase_p2003.06.00-27 as well as clearcase_lt_p2003.06.00-16. x86: Support for Solaris 10 was added for the x86 platform after 2003.06.00 was released and has its own installation package which contain all of the updates as of patch 35 & patch 36. Review technote 1240885 for more details.
** Open Solaris (Solaris Express), along with some other new features in Solaris 10 are not supported with Rational ClearCase and ClearCase LT.
These Solaris 10 features are not supported: Process Management Rights, Least Privilege, and Process Rights Sets Authorizations Predictive Self Healing ZFS Note: NFS v4 is only supported with AUTH_SYS authentication (which is the default). Refer to the readme file available with the patches for more details. 91. How do I – understand why the limit of file descriptors (ulimit -n) is changed after setview Why the ulimit is changed after executing cleartool setview when using IBM® Rational® ClearCase® on UNIX® or Linux®.
Cause After running cleartool setview
# csh
# ulimit -a time(seconds) unlimited file(blocks) unlimited data(kbytes) unlimited stack(kbytes) 8192 coredump(blocks) unlimited nofiles(descriptors) 256 vmemory(kbytes) unlimited
# ct setview jcslinux0
root@jstaquet4 # ulimit -a time(seconds) unlimited file(blocks) unlimited data(kbytes) unlimited stack(kbytes) 8192 coredump(blocks) unlimited nofiles(descriptors) 1024 <===== ??? Page 113 of 341
ClearCase Environment – How do I memory(kbytes) unlimited
# ls ~/.cshrc ~/.cshrc: No such file or directory
# ls ~/.login ~/.login: No such file or directory This has created a problem when the ulimit is set higher than 2048, but gets decreased to a lower value after running cleartool setview. Defect APAR PK23013 has been opened to investigate why cleartool setview is adjusting file descriptor limit.
Solution
The new limit is calculated by cleartool setview.
This limit is internally hard coded; cleartool setview must adapt this limit per operating system to ensure proper functionality of views (which require opening many files).
WORKAROUNDS: 1. Set the limit again, once the view has been set. Besides resetting the descriptor limit after the cleartool setview, you can set the default soft limit the same as hard limit.
For example, both soft and hard limit are set to 4096 or 8192. In this case, the setview command will not reset descriptor limit to 2048. 92. How do I – resolve the can't check out, or merge elements through xclearcase issue Why does the IBM® Rational® ClearCase® GUI on UNIX® and Linux® fails with the message, Warning: Missing charsets in String to FontSet conversion, during checkout or merging or elements from xclearcase along with instructions to resolve the problem.
Attempts to checkout or merge from within the xclearcase GUI on UNIX or Linux results in the error:
Warning: Missing charsets in String to FontSet conversion X Error of failed request: BadFont (invalid Font parameter) Major opcode of failed request: 55 (X_CreateGC) Resource id in failed request: 181 Current serial number in output stream: 185 The LANG variable was set incorrectly to en_us.utf8. Solution Open the /etc/sysconfig/i18n file and set the LANG variable to en_US, or C. Note: Setting the variable in any other location, such as the rc file for example, will not produce the expected results. The variable must be set in the i18n file. 93. How do I – understand about XML and the Windows 1252 encoding scheme issue Currently Rational ClearCase does not support files encoded with the Windows 1252 scheme. An example of a file encoded in the Windows 1252 encoding scheme is a Visual Studio .NET C# project file (*.csproj). This file looks like XML to an end-user, but not to ClearCase, for these files often contain BOM (Byte Order Mark) characters in file. Note: A byte order mark (BOM) consists of the character code U+FEFF at the beginning of a data stream, where it can be used as a signature defining the byte order and encoding form, primarily of unmarked plaintext files. A BOM is useful at the beginning of files that are typed as text, which can serve as a hint indicating that the file is in Unicode. Review the related information section for more information about Unicode and BOMs.
If the element type of a Visual Studio .NET file is specified as type XML, then attempts to run DiffMerge on this file will likely produce the following error:
Unknown encoding (error 18) at line 1, column 32. Defect APAR IC43090 was opened for version 2002.05.00 and has been closed as a permanent restriction for that release. Page 114 of 341
ClearCase Environment – How do I Defect APAR IC38873 has been submitted to address this behavior for versions 2003.06.00 and 7.0.
Solution This defect has been resolved in the following updates:
ClearCase 7.0 7.0.0.1-RATL-RCC-IFIX01
ClearCase 2003.06.00 Service Release 6 IMPORTANT: The fix is built into the xmldiffmrg code. The xmlparser was upgraded to support the following encodings: windows-1251, windows-1252, and ISO-8859-15.
Note: By default Visual Studio *.csproj files are recognized as text files and as such are added to source code control using a text file type manager. In order for the fix to work, the following steps need to be taken: 1. Existing project files need to have their type manager changed from Text to XML. Review the ClearCase Command Reference Guide on the topic of chtype (cleartool man chtype) for more information. 2. When these new project files are added to source code control, you will need to override the text file type manager to ensure the XML type manager is used. This requires managing the Magic File in order to allow ClearCase to handle *.csproj files as xml. Review the Match by name only section of technote 1118099 for instructions on how to modify the magic file to recognize *.csproj file extensions so ClearCase can manage these files using XML type manager. WORKAROUNDS:
These can be used to help manage files with Windows 1252 encodings in ClearCase (diffs and merges) more effectively. 1. When prompted during the XML diff merge to merge as XML or plain text, choose plain text and then merge the documents manually. 2. Comment out or remove the XML declaration in the file header: .
Note: These project files probably do not use any characters beyond the ASCII range (> 127), in which case 1252 is equivalent to ASCII, and the file(s) will parse and merge with no problems. If you still get a parse error after removing the declaration, the file probably contains a non- ASCII character. 3. If the file uses one or more characters outside the ASCII range (e.g., > 127 and < 256), you could try specifying the iso-8859-1 encoding instead of 1252. This is ISO-Latin-1. The difference between 1252 and 8859 is that 1252 defines a few extra glyphs. Any Latin-1 character will display fine. If a character is 1252-only (for example 0x95), you may not see the right glyph in the display, but the file will parse with no errors and the correct value will be written out to disk. 94. How do I – understand the ClearCase magic file changes needed to handle .csproj files with the XML type manager This technote identifies an issue that can occur in IBM® Rational® ClearCase® (CC) where Visual Studio files are UTF-8 encoded and the Windows diff-merge application does not support UTF-8 encoding.
All Visual Studio files are UTF-8 encoded and the Windows diff-merge application does not support UTF-8 encoding
The .csproj extension is currently not part of the Magic files, so it is added to Source Control as text_file type instead of xml which causes issues with the merge and may possibly cause file corruption.
This issue has been identified as a product defect under APAR PK37029
Resolving the problem There is currently no resolution for the above referenced defect. WORKAROUND Add the .csproj extension to a Magic File so that ClearCase will set files with that extension to an element type of xml and change any existing .csproj elements to xml.
This can be done by adding the following magic file entry: xml binary_delta_file : -name "*.csproj"; 1. Existing project files need to have their type manager changed from Text to XML. Review the IBM Rational ClearCase Command Reference Guide on the topic of chtype (cleartool man chtype) for more information. Page 115 of 341
ClearCase Environment – How do I 2. When these new project files are added to source code control, you will need to override the text file type manager to ensure the XML type manager is used. This requires managing the Magic File in order to allow ClearCase to handle *.csproj files as xml. Review the Match by name only section of technote 1118099 How file types are determined when creating a new element for instructions on how to modify the magic file to recognize *.csproj file extensions so ClearCase can manage these files using XML type manager. Refer to the following technotes for further information: Technote 1122471 About the ClearCase Magic file for information about creating a personal magic file where you can add this additional file extension.
Technote 1256807 Changing the XML Diff/Merge Type Manager for details about Changing the XML Diff/Merge Type Manager to use a 3rd party tool that can handle XML files with UTF-8 character encoding refer to
95. How do I – understand the reports are not visible in Report Builder issue After clicking on the various reports, located in the left-hand pane, Report Builder displays a blank interface. Example of working Report Builder interface:
Example of non-working Report Builder interface:
Page 116 of 341
ClearCase Environment – How do I
The exact cause of the problem is currently unknown; however, it was determined in one case that another instance of Perl (such as ActivePerl) may be installed on the host and is conflicting with the Rational shipped version of Perl (CCPerl or RatlPerl) which is used by Report Builder.
WORKAROUND: Uninstall the third party version of Perl to avoid the application conflict.
96. How do I – understand the empty derived objects not showing up in the config record issue derived objects with a zero byte count will be included in the configuration record when using IBM® Rational® ClearCase® build tools as long as the compiler will open such files for read.
Cause The audit utility in Rational ClearCase will catalogue any file that is open for read during the build regardless of the file's size. However, the files that get opened during a build are dependent on the compiler as some will not open files for read when they are 0 bytes (or empty). For example, if an empty .h file is not showing up in the config record, it is because the tool that is being used is not opening it for read. When a file is not opened for read, the ClearCase audit tool does not record it in the config record because it is not considered a significant event. If it is not in the config record, clearmake's up-to-date checking does not consider the status of the file to be relevant.
Solution
The ClearCase audit utility only catalogues significant events during a build, which includes a file being open for read or a the look-up of an explicit dependency. Insignificant events are not included in config records as this would require picking up every file stat (among other things) that the build script's tool is using.
WORKAROUND:
Specify the .h file as an explicit dependency in the makefile, which automatically makes any look-up a significant event.
For more information on the ClearCase Build Concepts, refer to IBM Rational ClearCase Building Software. 97. How do I – understand the PK27439: SORTING CLEARCASE EXLORER issue
Error description On ClearCase 6 'clicking ? dragging' was allowed for view shortcuts on the left panel of the ClearCase explorer window. The arrangement was also 'remembered'. After the window was closed and reopened, the previous arrangement of views remained. Page 117 of 341
ClearCase Environment – How do I
In ClearCase 7.0, 'Clicking and dragging' is disabled. The only way to sort the views is to arrange by removing the shortcut and adding it in the position where it was desired. The problem comes when CC explorer is restarted, the arrangement of views is not the same as when it was re-arranged before closing. Local fix Problem summary ClearCase Explorer doesn't allow "click and drag"of view shortc uts and doesn't remember customized order of view shortcuts. Problem conclusion ClearCase Explorer was changed significantly to be more scalable for large numbers of views. This change in behavior was a side effect of that change. Now, all newly added view shortcuts are in sorted order and not in the order in which they were added. So even if you exit the tool and reopen it again, you will find all the view shortcuts in sorted order. So it is consistent with the order in which view shortcuts were added. Example: If there are 2 view shortcuts in clearexplorer, "view1" and "view3", try adding a view shortcut "view2". Shortcut "view2" will be inserted between "view1" and "view3" and not at the end. If you re-open the CC Explorer you will find the alignment of shortcuts in the same order in which they were inserted, e.g. "view1" followed by "view2" followed by "view3", which is consistent behavior. Due to the age and limitations of the current ClearCase GUI applications, we are in the process of replacing them with newer versions. In order to most effectively allocate our resources, we are limiting the work we do on the legacy GUIs. Since this is a relatively minor usability issue, we do not plan to expend resources to fix it in the current GUI. 98. How do I – understand the nable to rename
Cause Attempts to checkout an element version to a view reports warnings and fails with the following error:
% cleartool co -nc makefile cleartool: Warning: Unable to rename "makefile" to "makefile.keep": Read-only file system. cleartool: Error: Checked out version, but could not copy data to "makefile" in view: File exists. Correct the condition, then uncheckout and re-checkout the element. cleartool: Warning: Copied checked-out version data to "makefile.checkedout". cleartool: Warning: Checked-out version is not selected by view. Checked out "makefile" from version "/main/branch/0".
The config spec for the view is missing the CHECKEDOUT rule.
Page 118 of 341
ClearCase Environment – How do I Solution
The CHECKEDOUT rule must be the first rule in the config spec, which is the default when a new view is created.
Edit the views config spec to add CHECKEDOUT as the first rule, like:
> cleartool edcs -tag admin_vu element * CHECKEDOUT #element * /main/dev/LATEST element * /main/LATEST #-mkbranch dev 99. How do I – understand the checked out version, but could not copy data to view: Read-only file system issue
While performing a checkout, the following error is received:
********************************************** UNIX® and Linux® ********************************************** cleartool: Error: Checked out version, but could not copy data to "
********************************************** Microsoft® Windows® ********************************************** cleartool: Error: Checked out version, but could not copy data to "
Correct the condition, then uncheckout and re-checkout the element. cleartool: Error: Unable to check out "
%>cleartool lsview -properties -full test_view * test_view /net/host/viewstore/test_view.vws Created 02-May-01.17:36:29 by user1.group1@host1 Last modified 16-May-01.12:16:10 by user1.group1@host1 Last accessed 16-May-01.12:16:10 by user1.group1@host1 Last config spec update 16-May-01.12:16:10 by user1.group1@host1 Last view private object update 15-May-01.17:42:08 by user1.group1@host1 Text mode: msdos Properties: dynamic ucmview readonly nshareable_dos Owner: user1 : rwx (all) Group: group1 : r-x (read) Other: : r-x (read)
Solution If the view is in a read-only state, there are two options to resolve the problem: 1. Create a new view Modify the existing view to resolve the problem
Note: To modify the existing view you can run the cleartool chview command to change the view properties from read-only to read-write.
EXAMPLE:
%> cleartool chview -readwrite
Page 119 of 341
ClearCase Environment – How do I
100. How do I – understand the ClearCase 7.0 installation fails on Solaris 8 issue Attempts to install ClearCase 7.0 on a Solaris 8 host results in the following error:
# ./install_release ld.so.1: ../../common/bin/ratlperl: fatal: libCstd.so.1: open failed: No such file or directory ERROR: It appears that ../../common/bin/ratlperl may not be working properly. Note that this error may occur if you are installing on an unsupported platform. Check documentation for supported platforms to ensure you are running on a supported platform. One of the prerequisite Solaris patches as outlined in the IBM Rational ClearCase Installation and Upgrade Guide for Linux® and UNIX® (GI11-6366-00) is missing on the Solaris host.
Solution Install the required operating system patches as instructed in the ClearCase 7.0 Installation Guide. Once the required patches are applied, proceed with the installation of
101. How do I – understand View and VOB creation errors in ClearCase Interop Attempts to create a VOB from the GUI results in the following error:
VOB Creation Graphical Interface Using the VOB Creation Wizard fails with the following error: Error creating VOB : VOB Creation Wizard: Error: Problem starting vob_server for vob HOST3:\\HOST3\vobs\test_vob.vbs VOB Creation Wizard: Error: See albd or VOB error logs on host HOST3 VOB Creation Wizard: Error: Warning: Error initializing vob_server. VOB Creation Wizard: Error: INTERNAL ERROR detected and logged with the NT Event Service. See the Event Viewer for the error message. Internal Error detected in ".\../map.c" line 2106 VOB Creation Wizard/vob/map: Error: Null VOB handle passed to libvob routine. VOB Creation Wizard: Error: Unable to create versioned object base "\\HOST3\vobs\test_vob.vbs".
OR
The following error occurs: Error accessing storage path location Status=8274016
Command Line Attempts to create a VOB from the CLI results in the following error: cleartool: Error: Problem starting vob_server for VOB HOST3:\\HOST3\syntax\tas_vob.vbs cleartool: Error: See albd or VOB error logs on host HOST3 cleartool: Warning: Error initializing vob_server. cleartool: Error: INTERNAL ERROR detected and logged with the NT Event Service. See the Event Viewer for the error message. cleartool: Error: Unable to create versioned object base "\\HOST3\syntax\tas_vob.vbs". View Creation
Attempts to create a dynamic view from either the Clear View Tool or the command line results in the following error: Error creating view -- 'test_view'. clearviewtool: Warning: Config spec OK, but unable to tell view server to load. clearviewtool: Warning: View server should be restarted. clearviewtool: Error: Set configuration spec of C:\Program Files\Rational\ClearCase\default_config_spec failed: view storage directory or control files unavailable -- additional information may be present in the view server host's view log clearviewtool: Error: Unable to create view "\\HOST3\viewstore\test_view.vws" These errors occur when creating a VOB or dynamic view from Windows and attempting to store it on a UNIX or Linux host.
Solution UNIX and Linux VOB and view storage created on a UNIX system must be created from the UNIX Operating System. Page 120 of 341
ClearCase Environment – How do I Windows VOB and view storage created on a Windows system must be created from the Windows Operating System. Region Synchronizer In order to use or see a VOB or view that is stored on UNIX from Windows, the Region Synchronizer in the ClearCase HomeBase can be used. The Region Synchronizer (RegSync) helps a ClearCase administrator maintain the ClearCase VOB and view registries in network installations where Windows systems require access to UNIX VOBs and views. RegSync coordinates, or synchronizes, VOB and view names (VOB-tags and view-tags) between UNIX and Windows network regions. Note: RegSync exists only on Windows. Importing Tags from UNIX to Windows The typical usage pattern for RegSync has two phases: 1. The administrator uses RegSync to "import" a set of UNIX VOBs and views, making them accessible to a network. 2. Thereafter, the administrator uses RegSync intermittently to add Windows region support for one, or several new UNIX VOBs, or views.
Overview of Using the Synchronize ClearCase Regions dialog box: From the Region Synchronizer's main dialog box, use the following general procedure: 1. Specify either VOB-tags or view-tags. 2. Verify that the Windows and UNIX network region names are correct. 3. Select a UNIX VOB or view. 4. Click on Import..., and then complete the resultant "make tag" dialog box to create a tag in the Windows region for the selected VOB or view.
Click the HELP button in the Region Synchronizer for more detailed assistance.
Importing VOB Tags from UNIX to Windows The RegSync utility detailed above is only available for importing tags from Windows to UNIX or Linux. Note: Views cannot be shared from Windows to UNIX or Linux. 102. How do I – understand the MVFS or RWP fails to load after reboot on Secure Linux issue Attempts to install ClearCase on Linux results in the following error:
ClearCase daemons: /opt/rational/clearcase/etc/albd_server: error while loading shared libraries: /opt/rational/clearcase/shlib/libatriaxdr.so: cannot restore segment prot after reloc: Permission denied albd_server /opt/rational/clearcase/etc/mount_mvfs: error while loading shared libraries: /opt/rational/clearcase/shlib/libatriaxdr.so: cannot restore segment prot after reloc: Permission denied Trouble mounting the viewroot "/view"(16:127) /opt/rational/clearcase/etc/mvfslog: error while loading shared libraries: /opt/rational/clearcase/shlib/libatriaxdr.so: cannot restore segment prot after reloc: Permission denied Trouble setting MVFS kernel log file to /var/adm/rational/clearcase/log/mvfs_log(2:127) Mounting public VOBs... /opt/rational/clearcase/bin/cleartool: error while loading shared libraries: /opt/rational/clearcase/shlib/libatriaxdr.so: cannot restore segment prot after reloc: Permission denied Trouble mounting public VOBs(32:127)
Note: The following errors are reported in dmesg output during system startup after reboot when ClearCase is installed on SELinux: Server1 kernel: SELinux: initialized (dev mvfs, type mvfs), not configured for labeling Nov 29 11:12:39 Server1 kernel: audit(1133280759.779:2): avc: denied { mount } for pid=3149 comm="mount_mvfs" name="/" dev=mvfs ino=1 scontext=user_u:system_r:initrc_t tcontext=system_u:object_r:unlabeled_t tclass=filesystem Nov 29 11:12:39 Server1 clearcase: mount_mvfs: Permission denied Nov 29 11:12:39 Server1 clearcase: Trouble mounting the viewroot "/view"(16:22)
Cause Security-enhanced Linux (SELinux) is an implementation of a mandatory access control mechanism.
This mechanism is in the Linux kernel, checking for allowed operations after standard Linux discretionary access controls are checked. Page 121 of 341
ClearCase Environment – How do I
The SELinux configuration is preventing the shared library "libatriaxdr.so" from loading.
ClearCase does not currently support Secure Linux (SELinux).
Diagnosing the problem Verify if SELinux is enabled:
Example from Redhat 4:
/usr/bin/sestatus
SELinux status: enabled SELinuxfs mount: /SELinux Current mode: enforcing Mode from config file: enforcing Policy version: 18 Policy from config file:targeted
Policy booleans: allow_ypbind active dhcpd_disable_trans active httpd_disable_trans inactive httpd_enable_cgi active
Resolving the problem Change request (RFE) RATLC00762574 has been submitted requesting support for ClearCase on SELinux.
Change request (RFE) RATLC01035180 has also been opened to investigate adding better error handling of ClearCase installations on SELinux.
Note: Refer to technote 1268209 for information about a similar error reported when installing Rational ClearQuest® on Linux.
WORKAROUND: SELinux is enabled with the enforcing option in the /etc/selinux/config file.
Modify the /etc/selinux/config file to reflect the following option and reboot:
SELINUX=permissive
Note: An alternate method to turn off (or verify) the security component of Linux is disabled is to run the System > Config > SecurityLevel GUI and click the tab with text label of "SELinux". Ensure the option ENABLE is deselected. Reboot is required if the option is changed.
The MVFS or RWP will now load without error; however, since this is not a supported configuration, IBM Technical support is not able to assist in further troubleshooting any issue related to configuration or settings on SELinux.
If the system can not be reboot, or if you would like to save time, you can reset the SELinux setting between "enforcing" ( 1 ) and "permissive" ( 0 ) with the setenforce command.
Example: setenforce 1 - Sets SELinux to "enforcing". setenforce 0 - Sets SELinux to "permissive"
Related information About SELinux SELinux Symposium Support Policy for ClearCase on Linux
Page 122 of 341
ClearCase Environment – How do I 103. How do I – understand the copy and Paste from html help pages into a command shell delivers incorrect output Why does performing a copy and paste from the IBM® Rational® ClearCase® html help pages into a command prompt results in errors or incorrect output.
Steps to reproduce: 1. Open a command prompt. 2. Open the Command Reference Guide on any topic (cleartool man
Note: In this example the lsprivate command is used. From the command prompt type cleartool man lsprivate to open the Command Reference page to lsprivate. 3. After reviewing the help, you decide you want to copy and paste the command example you are interested in (see example below).
Excerpt from cleartool lsprivate manual page:
4. Attempts to copy the text from the manual page and pasting it into the command shell results in one of the following errors:
Error 1: Note the û character in the output.
%>cleartool lsprivate –size –age cleartool: Error: "ûsize" is not a directory element. cleartool: Error: "ûage" is not a directory element.
%>cleartool lsprivate -size -age cleartool: Error: Extra arguments: "ûsize" Usage: lsprivate [-tag view-tag] [-invob vob-selector] [-long | -short] [-size] [-age] [-co] [-do] [-other]
%>cleartool ls -directory -vob_only cleartool: Error: Unable to access "ûdirectory": No such file or directory. cleartool: Error: Unable to access "ûvob_only": No such file or directory.
Error 2: %>cleartool lsprivate –size –age cleartool: Error: Missing change options. Usage: lsprivate [-tag view-tag] [-invob vob-selector] [-long | -short] [-size] [-age] [-co] [-do] [-other]
Control characters are being carried from the buffer when copied into a standard command shell.
104. How do I – understand the issues about RHEL4 Linux servers with NFS V4 enabled RedHat's NFS server configuration is complex and can be problem-prone, especially when trying to use an automounter (/net/hostname) to get to RHEL4-hosted files.
Enabling V4 effectively disables V2/V3 automounts for those systems supporting NFS version 4 clients.
Even though the Linux NFS server-side configuration for NFS V4 is done in the same configuration file as Page 123 of 341
ClearCase Environment – How do I the V2/V3 exports (/etc/exports), making the exported name space for V4 identical to that for V2/V3 is not possible.
Note: Clients with only NFS V3 or V2 will still work OK.
Symptoms that are seen from the client end, which are evidence of this problem include: 1. Looking up '..' can result in an I/O error (to the screen and/or in the system logs) /net/hostname/
There are no known solutions at this time. WORKAROUNDS: 1. Turn off NFS V4 servers on RHEL4.
To do this, add the following line in /etc/sysconfig/nfs:
RPCNFSDARGS="-N 4"
This option tells Linux to not use NFS V4 which means that any access looking for NFS V4 will revert to NFS V3.
Note: The /etc/sysconfig/nfs file may not exist by default. If the file needs to be created, it should be done as root and allocated 755 permissions. Explicitly mount (rather than use the automounter) the ClearCase storage directories using NFS V4 on the server. This will mitigate the problem of conflicting namespaces between NFS V4. V3. and V2.
105. How do I – understand the data collection for memory reference errors and blue screens on Windows STEP 1: Identify the problem 1. WHICH processes are failing? (Example: clearexplorer.exe, db_server.exe ....) 2. WHEN are they failing? (Example: shutting down GUI, performing X operation ....) 3. HOW often do the errors appear? (Example: every night at X time, every day around X time ....) 4. HOW many machines does this happen on? (Example: ALL, one or X number)
STEP 2: Collect relevant logs Collect the logs from a good machine and a bad machine and compare the two for differences.
For example review technote 1131335 for more information on collecting ClearCase logs from Windows. STEP 3: Collect Memory Dump There are 2 different tools that can be used to help collect data about Memory Reference errors. The instructions for each are provided below: Dr. Watson
Stop Event DR. WATSON ABOUT DR. WATSON: The Dr. Watson for Windows program (DRWTSN32.EXE) is preinstalled in your Windows system32 directory. The default options are set the first time Dr. Watson runs, which can be either when an application error occurs or when you run it from the command prompt.
When an application error occurs in Windows, the system searches for an application-software exception (error) handler. If it does not find an exception handler, the system verifies that the application is not currently being debugged and considers the exception to be unhandled. The system then processes unhandled exceptions by looking in the Registry for an application-error debugger.
REGISTRY VALUES: The system looks in the following registry entry for the values named Debugger and Auto. 32-bit HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\AeDebug
64-bit HKEY_LOCAL_MACHINE\Software\Wow6432Node\Microsoft\Windows NT\CurrentVersion\AeDebug The Debugger value shows the name of the debugger specified to analyze application errors. If the Debugger value is found, the system checks to see if the Auto value is set to zero or one.
Page 124 of 341
ClearCase Environment – How do I AUTO - ZERO: If Auto is set to zero, the system generates a message box that advises you that an error has occurred in the application. If the Debugger value contains the name of a valid debugger (such as WinDbg or NTSD), the message box will have two buttons: OK and Cancel. a. If you choose the OK button, the application is terminated. b. If you choose the Cancel button, the debugger specified in the Debugger value is started. Note: If the Debugger value is empty, the message box will have only an OK button and no debugger will start.
Back to top
AUTO - ONE: If Auto is set to one and a debugger is specified in the Debugger value, the system does not generate a message box before automatically starting the debugger. When Windows is set up on your system, the Auto value is set by default to one and the Debugger value is set to DRWTSN32. This means that when an application error occurs, Dr. Watson will automatically diagnose the error and log the appropriate diagnostic information. DR. WATSON SETUP: 1. Click Start > Run and type: DRWTSN32 Note the location of the crash dump file (user.dmp) and the log file (drwtsn32.log). 2. Uncheck Dump All Thread Contents. - This restricts the dump to the specific process that caused the error. 3. Ensure the following options are checked:
Crash Dump Type = Full Visual Notification Create Crash Dump File
4. Close Dr. Watson 5. Run the application that creates the Dr. Watson error.
Page 125 of 341
ClearCase Environment – How do I Note: There should be a user.dmp file and a drwtsn32.log with data in the file at the specified location (from step 1).
CHANGING DEBUGGER APPLICATION TO DR. WATSON: What if Dr. Watson is NOT my default debugger? How do I switch to Dr. Watson as my default debugger instead of VC++ (for example)? 32-bit If you have been using a different application as your default debugger, and you want to use Dr. Watson instead click Start > Run and type: drwtsn32 -i Note: The -i switch causes the necessary changes to be made to the Registry. 64-bit If you are using a 64 bit machine, you need to change the registry manually to ensure dr watson picks up the error: Under HKEY_LOCAL_MACHINE\Software\Wow6432Node\Microsoft\Windows NT\CurrentVersion\AeDebug Set Debugger = drwtsn32 -p %ld -e %ld -g STOP EVENT ABOUT STOP EVENTS: If you want to force the Dr. Watson debugger to generate a log or dump file, configure the host for a Stop Event. STOP Events literally means Windows has stopped! These appear only in the NT-based operating systems: NT, 2000, and XP. Read the following article for more information on Setting up Windows to capture Stop Events. CONFIGURE WINDOWS FOR A MEMORY DUMP: Review MSKB article 254649 for an overview of memory dump file options for Windows Server 2003, Windows XP, and Windows 2000. Instructions: 1. Click Start > Settings > Control Panel and double-click System 2. On the Advanced tab, click Settings in the Startup and Recovery section. 3. Ensure the Write Debugging Information drop down box has Complete memory dump selected and note the Dump File: location window as this is where the dump file(s) will be saved. 4. Ensure Overwrite any existing file is checked. 5. Ensure the Automatically restart box is checked.
Example screenshot (from XP)
CONFIGURE STOP EVENT: To configure the Stop Event, you will need to make a registry change on the host. To add an entry to the registry 1. Click Start > Run and type: regedit 2. Navigate to the subkey HKLM\System\CurrentControlSet\Services\i8024prt\Parameters Page 126 of 341
ClearCase Environment – How do I 3. Select the Parameters subkey, and then click Add Value from the Edit menu. 4. In the Add Value dialog box, in the Value Name box type CrashOnCtrlScroll, in the Data Type box select REG_DWORD, and then click OK. 5. Double-click the CrashOnCtrlScroll entry. In the DWORD Editor dialog box, type 1 in the Data box and then click OK. 6. Close Regedit, and restart your computer. After the computer has restarted, you can generate a stop event.
GENERATE STOP EVENT: Press and hold the right Ctrl key (the left Ctrl key will not allow you to generate a stop event), and then press the Scroll Lock (ScrLk) key twice. A stop event will occur, and a stop error will be displayed with the following message:
*** STOP: 0x000000E2 (0x00000000, 0x00000000, 0x00000000, 0x00000000) The end-user manually generated the crashdump.
After generating a stop event, the computer will be inoperable until it has been restarted. After the restart, complete functionality will be restored. TROUBLESHOOTING STOP MESSAGES: Read the following article for more information on Troubleshooting Specific Stop messages.
106. How do I – understand the persistent VOBs do not remount automatically issue VOBs that are flagged to mount automatically do so during system start-up on Windows. Sometimes applications step on one another attempting to start which can impact other applications. There is nothing that can be done to solve this as Windows can not be configured to control application start-up. Another cause can result from an inefficient Network Access Order on the client.
Solution Make sure the system Network Provider Order is optimized by placing ClearCase Dynamic Views & Microsoft Windows Network at the top of the order and restart the client.
Example:
ClearCase Dynamic Views Microsoft Windows Network NFS (if applicable) Terminal Services Web Client Network Netware (if applicable)
Instructions to access the Network Provider Order:
Windows XP: Start > Control Panel > Network Connections > Advanced > Advanced Settings > Provider Order
Windows 2000: Start > Settings > Network and Dial-up Connections > Advanced > Advanced Settings > Provider Order
Windows NT 4.0: Start > Settings > Control Panel > Network > Services > Access Order
Using Sleep.exe The sleep.exe command can be found in a Windows Resource Kit Tools and an example batch file is as follows: sleep.exe 6 cleartool mount \123 cleartool mount \456 cleartool mount \789 cleartool mount \etc.. sleep.exe 15 Page 127 of 341
ClearCase Environment – How do I Note: If the Access Order is already optimized or if the VOBs do not automatically mount after making the change, contact IBM Rational Client Support for more assistance. 107. How do I – understand the segmentation fault (coredump) when running ClearCase operations ClearCase example: Attempts to run the cleartool rmbl command results in a Segmentation fault (coredump) on UNIX and Linux failing with the following error:
%>cleartool rmbl baseline:BL1_07_25_2007@/vobs/VOB1> Remove baseline "baseline:BL1_07_25_2007@/vobs/PVOB"? Ýno¨ y cleartool: Warning: Searching PVOBs for baselines that depend upon baseline "BL1_07_25_2007". This may take a few minutes... cleartool: Warning: The composite baseline "Mainline_05_09_2007" depends upon a baseline that is unavailable or has been removed. Segmentation fault(coredump) MultiSite example: Attempts to run the mkreplica -import command results in a Segmentation fault (coredump) on UNIX and Linux failing with the following error: Processing packet ./repl_myreplica.test_14-Apr-05.20.03.33_6972_187... multitool: Error: No more memory available. multitool: Error: No more memory available. ksh: 57346 Segmentation fault(coredump) The maximum size of the operating system's kernel resource data area was reached.
Solution Increase the kernel's resource data area and rerun the command. Running ulimit -a will show the "data" as it is currently configured. Example: >/etc> ulimit -a time(seconds) unlimited file(blocks) unlimited data(kbytes) 131072 stack(kbytes) 32768 memory(kbytes) 32768 coredump(blocks) 2097151 nofiles(descriptors) 2000
To change the data variable in a csh shell, log in as root and run the following command:
>/etc> limit data
Example: hostname:/etc> limit data 262144 hostname:/etc> ulimit -a time(seconds) unlimited file(blocks) unlimited data(kbytes) 262144 stack(kbytes) 32768 memory(kbytes) 32768 coredump(blocks) 2097151 nofiles(descriptors) 2000
Run the command once more.
Note: Depending on the shell you are using, the syntax to change the variable may be different. Refer to the ulimit man page to get the syntax commands for each shell.
# man ulimit 108. How do I – Use Performance Monitor Alerts to warn of Desktop Heap problems Given that the heap size is statically allocated, there is no way to completely avoid the issue. However, you can configure Windows to warn you when you are about to start running out of desktop heap. Page 128 of 341
ClearCase Environment – How do I
First, you need to know roughly how many service processes your host can support. In Microsoft Knowledge Base Article 142676 they note that 512KB of desktop heap space is roughly enough for 90 service processes to run. The "90" processes is derived from the 48 MB limit minus 3 MB increments divided by 512 KB. (49152 KB - 3072 KB) / 512 KB = 90
Note: 49152 KB = 48 MB & 3072 KB = 3 MB
In other words you can have approximately 90 non-interactive desktops (Services).
Note: If you were to raise the 3rd number to 3072, the result would be.
(49152 KB - 3072 KB) / 3072 KB = 15
Hence you would then be able to run approximately 15 non-interactive desktops (Services).
Based on this knowledge, you can set up a Performance Monitor alert to warn you when this threshold is close.
To determine the approximate number of service processes your Windows server can run:
1. Determine the third number of the "SharedSection=" portion of the HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Session Manager\Subsystems\Windows string value.
2. Take 48 MB - 3 MB -- (49152 KB - 3072 KB) and divide that by the 3rd value. Example: If you set "SharedSection=1024,3072,1024", the result would be:
(49152 KB - 3072 KB) / 1024 KB = 45 You could have approximately 45 non-interactive desktop services running.
Performance Monitor on Windows 2000® and Windows XP®: 1. Open the Performance Monitor application. (Start/Settings/Control Panel/Administrative tools/Performance)
2. Open "Performance Logs and Alerts"
3. Right Click "Alerts" and select "New Alert Settings."
4. Type in any name, and Hit OK.
5. In the Alert settings dialog box that appears, enter a descriptive comment and then click the "Add" button in the "counters" section.
6. Select the "System" Performance Object.
7. Select the "Processes" counter from the list below it.
Page 129 of 341
ClearCase Environment – How do I 8. Click "Add" and then "Close"
9. With the "Processes" counter selected, Change the dropdown in the "Alert when the value is:" to "Over" and the "Limit" to the number we calculated from the desktop heap settings we set.
10. Go to the "Action" tab and make sure that "Log an entry in the application event log" is set. You may want to also set "Send a network message to:" to send a message to an administrator's workstation. There is the option for running a specific program as well; configuring that to send you e-mail or a page is "left as an exercise for the reader."
11. "OK" out of this dialog to start the alert monitor running.
12. Exit the application and the alerts will be collected in the background by the "Performance Logs and Alerts" service. Performance Monitor on Windows NT®: The most important thing to be aware of on Windows NT is that performance monitor alerts will only occur if the Performance Monitor application is currently running. Also, once the application is exited, the alert settings are lost if not specifically saved. So, once configured, the settings need to be saved and reloaded after each server reboot. To Configure the Performance monitor: 1. Start the Performance Monitor application. (Start/Programs/Administrative Tools/Performance Monitor)
2. Select "View/Alert"
3. Select "Edit/Add To Alert"
4. Select the "Objects" Object
5. Select the "Processes" Counter.
6. In "Alert if:" select "Over" and then enter the number calculated above.
7. Click "Add" and then "Done"
8. Select "Options/Alert" and make sure that "Log to Application Event Log" is selected. You may want to also set "Send a network message to:" to send a message to an administrator's workstation.
9. Select File/Save Workspace. Save the workspace out with a descriptive filename. (Example: ProcessAlert.pmw)
10. Create a new shortcut in the Windows start menu's "Startup" group as follows.
a. Right Click on the Start menu
b. Select "Explore all Users"
c. Drill down to the "Programs/Startup" folder.
d. Right click in the right hand pane, select "New/Shortcut".
e. For the program name, type "%systemroot%\system32\perfmon.exe" followed by the path to the workspace file you saved.
f. "Next" through and finish creation of the shortcut Now, when ANY user logs into this server machine, the performance monitor statistics collection and alert monitoring will occur.
Monitoring ClearCase Desktop heap usage with Desktop heap Monitor: *** Set up Desktop heap monitor Download and install Desktop Heap monitor following the URL below. http://www.microsoft.com/downloads/details.aspx?familyid=5CFC9B74-97AA-4510-B4B9- B2DC98C8ED8B&displaylang=en
Page 130 of 341
ClearCase Environment – How do I To start monitoring, run dheapmon -l to have the driver loaded as follows;
C:\kktools\dheapmon8.1\x86>dheapmon -l
Desktop Heap Information Monitor Tool (Version 8.1.2925.0) Copyright (c) Microsoft Corporation. All rights reserved. Dheapmon - Driver loaded successfully *** Monitor how much non-interactive desktop heap size ClearCase consumes. 1. Stop ClearCase and run dheapmon to confirm active desktop heaps.
C:\kktools\dheapmon8.1\x86>dheapmon
Desktop Heap Information Monitor Tool (Version 8.1.2925.0) Copyright (c) Microsoft Corporation. All rights reserved. ------Session ID: 0 Total Desktop: ( 11456 KB - 7 desktops)
WinStation\Desktop Heap Size(KB) Used Rate(%) ------WinSta0\Default 3072 77.7 WinSta0\Disconnect 64 4.5 WinSta0\Winlogon 128 13.1 Service-0x0-3e7$\Default 2048 11.9 Service-0x0-3e4$\Default 2048 1.7 Service-0x0-3e5$\Default 2048 1.1 SAWinSta\SADesktop 2048 0.1 ------
2. Start ClearCase and run dheapmon again to recognize the desktop heap assigned for ClearCase (ClearCase albd user).
C:\kktools\dheapmon8.1\x86>dheapmon
Desktop Heap Information Monitor Tool (Version 8.1.2925.0) Copyright (c) Microsoft Corporation. All rights reserved. ------Session ID: 0 Total Desktop: ( 13504 KB - 8 desktops)
WinStation\Desktop Heap Size(KB) Used Rate(%) ------WinSta0\Default 3072 77.7 WinSta0\Disconnect 64 4.5 WinSta0\Winlogon 128 13.1 Service-0x0-3e7$\Default 2048 12.2 Service-0x0-3e4$\Default 2048 1.7 Service-0x0-3e5$\Default 2048 1.1 SAWinSta\SADesktop 2048 0.1 Service-0x0-1b6a3a7$\Default 2048 0.4 ------
In this example the last listed Service-0x0-1b6a3a7$\Default is the desktop heap assigned for all processes with clearcase_albd user account. The heap size should be the same as the 3rd value of "SharedSection"in Windows Registry.
Note: You may not be able to easily identify which service desktop belongs to which service other than by knowing it's behavior. So, of the four service desktops on his machine, the one we selected is not necessarily the one that is the albd desktop.
Then, run dheapmon -v -w
In this example, WinStation is Service-0x0-1b6a3a7$.
Page 131 of 341
ClearCase Environment – How do I C:\kktools\dheapmon8.1\x86>dheapmon -v -w Service-0x0-1b6a3a7$
Desktop Heap Information Monitor Tool (Version 8.1.2925.0) Copyright (c) Microsoft Corporation. All rights reserved. ------
Windowstation: (Service-0x0-1b6a3a7$) SessionID: 0 Desktop: (Default) Addr: be690000
Desktop Heap 2097152 (0x 200000) Bytes Committed 12288 (0x 3000) Bytes Uncommitted 2084864 (0x 1fd000) Bytes Allocated 9152 (0x 23c0) Bytes Total Freed 3136 (0x c40) Bytes Unused 2088000 (0x 1fdc40) Bytes Used Rate ( 0.4) % ------
"Allocated" is the size actually used by ClearCase server processes with clearcase_albd account.
As albd_server.exe and syncmgr_server.exe are such processes, the above result means that these 2 processes consume 9152 byte in the desktop heap.
Accessing views/VOBs and run dheapmon -v -w
C:\kktools\dheapmon8.1\x86>dheapmon -v -w Service-0x0-1b6a3a7$
Desktop Heap Information Monitor Tool (Version 8.1.2925.0) Copyright (c) Microsoft Corporation. All rights reserved. ------Page 132 of 341
ClearCase Environment – How do I
Windowstation: (Service-0x0-1b6a3a7$) SessionID: 0 Desktop: (Default) Addr: be690000
Desktop Heap 2097152 (0x 200000) Bytes Committed 24576 (0x 6000) Bytes Uncommitted 2072576 (0x 1fa000) Bytes Allocated 22048 (0x 5620) Bytes Total Freed 2528 (0x 9e0) Bytes Unused 2075104 (0x 1fa9e0) Bytes Used Rate ( 1.1) % ------
In this example, "Allocated" size has been increased to 22048 from 9152 at step 2 above. In addition, 4 ClearCase servers (view_server, db_server, vob_server and vobrpc_server) get activated as follows;
This means, these 4 processes consume 12896 (22048-9152) byte. 109. How do I – understand the History Browser display is grey and blank issue Symptom The History Browser graphical user interface (GUI) appears grey and blank on some machines and not others, while the command line invocation (cleartool lshistory) is working correctly.
Cause The font settings in the History Browser GUI are either set improperly or not set optimally for the host display settings.
Resolving the problem These steps will resolve the font settings problem in the History Browser GUI. Note: There are two solutions documented below, however, the first one applies to all versions and the second one only applies to ClearCase 2002.05.00 and earlier versions. Solution 1: 1. Click Start > Programs > Rational Software > Rational ClearCase > History Browser
Note: This can also be achieved by navigating to a view in either Microsoft® Windows® Explorer or ClearCase Explorer, right click an element and select 'History' from the choices provided.
2. Click Views > Options and select the Display tab
Page 133 of 341
ClearCase Environment – How do I
3. The Font radio button defaults to Captions and you will need to perform the following actions independently on 'Text'. a. Click Change
b. Ensure there is a Font, Font Style and Size displayed in the window. Then select a specific font style and size.
Note: If the font size is set to size 8 and you are still having problems seeing the GUI, select another font style and size. For example, select Arial from the Font list and select 10 from the Size list.
c. Click OK
4. Perform the actions in Step 3 again, only you will be selecting Text.
5. Exit and reopen the History Browser.
Solution 2: (2002.05.00 and 2003.06.10 (no patches) version and earlier ONLY) If the steps in solution 1 do not help, try the following solution. Note: The following directions require you to edit the registry using the Windows Registry Editor. However, editing the Windows Registry incorrectly can cause serious problems that may require you to reinstall your operating system. Use Registry Editor at your own risk. Before proceeding review the Microsoft KB article, KB256986 - Description of the Microsoft Windows Registry.
Page 134 of 341
ClearCase Environment – How do I 1. Open registry editor (Start > Run and type regedt32).
2. Navigate to the registry key HKEY_CURRENT_USER\Software\Atria\ClearCase\CurrentVersion
3. Delete the key Rational ClearCase History Browser
4. Close Registry editor.
5. Open History Browser and check the display.
Note: When the above registry key is deleted clearhistory.exe rebuilds the registry key with its original defaults. Installation & Patching 110. How do I – understand why MVFS does not loading after kernel upgrade or is missing after installation on Linux This technote explains how to resolve an issue that can occur when using IBM Rational ClearCase where the Multi-version File System (MVFS) is missing after an installation or it fails to load after a kernel upgrade.
Symptom Possible Symptoms: 1. MVFS is not installed after the installation. 2. After a Kernel upgrade the MVFS will not load.
Cause For Symptom 1
The path /lib/modules/
For Symptom 2
Since the previous MVFS module was compiled for the old Kernel, there is no MVFS for the new Kernel.
Environment Linux machines with ClearCase 7.1.2.x
Diagnosing the problem The commands below will not return successful: lsmod | grep mvfs modprobe -l mvfs ls /lib/modules/`uname -r`/kernel/fs/mvfs/mvfs.ko
Resolving the problem Manually compile the MVFS module. 1. Be sure the required packages to compiling software are installed:
kernel-devel-
Note: If your machine is a 64-bit you must install 32-bit compat libraries as well. 2. After all dependencies are resolved follow the steps below: a. cd /var/adm/rational/clearcase/mvfs/mvfs_src b. Change the file mvfs_param.mk.config to fit your case
RATL_EXTRAFLAGS := -DRATL_REDHAT -DRATL_VENDOR_VER=500 -DRATL_EXTRA_VER=0 -DRATL_COMPAT32 Page 135 of 341
ClearCase Environment – How do I LINUX_KERNEL_DIR=/lib/modules/
Note: Change
Reference: /var/adm/rational/clearcase/mvfs/mvfs_src/README.txt 111. How do I – understand the ClearCase support for Red Hat Enterprise Linux 5.0 Update 4 Support for Red Hat Enterprise Linux 5.0 Update 4 has been added for ClearCase versions 7.0.1.7 and 7.0.0.8.
Refer to Technote 1239315 System Requirements for ClearCase 7.0.x.x for further details regarding supported version requirements. 112. How do I – understand that the package IBM Rational ClearCase is already installed. This package can only be installed in one location error reported when recording a response file using -skipinstall
This technote explains how to resolve an error, Package IBM Rational ClearCase is already installed. This package can only be installed in one location that can occur when selecting a package to install during the recording of a response file when using the -skipinstall option for a IBM Rational ClearCase (CC) 7.1 installation.
Symptom This error appears when you select a package to install during the recording of a response file with the - skipinstall option; even if ClearCase is not installed on the machine. Package IBM Rational ClearCase is already installed. This package can only be installed in one location.
This error appears when you select a package to install during the recording of a response file with the - skipinstall option; even if ClearCase is not installed on the machine. Package IBM Rational ClearCase is already installed. This package can only be installed in one location.
Cause The agent data location specified after the -skipinstall has already been used for the creation of a response file for this product. Using -skipInstall option allows you to specify a directory known as the
Resolving the problem Remove the contents of the agent data location or create a new directory to be used as the agent data location for the creation of this response file.
Related information Recording a response file without installing Page 136 of 341
ClearCase Environment – How do I 113. How do I – understand being unable to complete ClearCase 7.1 installation if registry or license server host names contain an underscore During a ClearCase 7.1 installation after entering the registry or license server hostname, the Next button is not active and the installation can not continue
Cause When running through a ClearCase 7.1 installation, the user has to fill in the registry server and license server fields with machine names. If a machine name contains an underscore ( _ ) is entered into one of these fields, the Next button at the bottom of the IBM Installation Manager Window will not become selectable. The issue only occurs when using the graphical user interface (GUI) to perform an install.
Resolving the problem During the install, enter a fictitious name for the host name without the underscore. After the install has completed, edit the rgy_hosts.conf (for registry server hostname) or license_host (for license server hostname) file located in the /var/adm/rational/clearcase/config directory by default, to put in the correct host name. Then restart ClearCase. The other option that can be used is to do a silent install using a response file. When recording the response file, you will be required to put in a fictitious name for either the registry or license server. Once the response file is completed, you will need to edit the following lines: For the registry server:
For Atria licensing server: If we install using a response file, there is no need to edit the rgy_hosts.conf file. 114. How do I – understand why the Daily Scheduled Jobs do not run by default in ClearCase 7.1.x This technote explains a change in IBM Rational ClearCase 7.1.x where Daily Scheduled Jobs such as Daily VOB Pool Scrubbing, Daily VOB Snapshots and Daily Registry Backup are not run by default and must be explicitly enabled on ClearCase VOB and registry server hosts as needed.
Symptom The default behavior for the ClearCase 7.1.x Daily Scheduled Jobs has changed whereby, they are not run by default. For ClearCase VOB and registry hosts, of most importance are the first three jobs, Daily VOB Pool Scrubbing, Daily VOB Snapshots and Daily Registry Backup. Although the running of these jobs is not necessary on client hosts, it is important to consider enabling these jobs on VOB and registry server hosts to avoid issues such as the following which could occur if administrators are not aware that the Daily Jobs are not running by default: Job 1: Daily VOB Pool Scrubbing Purpose: Scrub cleartext and derived object storage pools of all local VOBs, using scrubber.
If a system administrator is dependent on this job to scrub the pools mentioned above on ClearCase VOB server hosts and this job is not enabled on those hosts, there is a potential to run out of disk space on the disk where these pools reside.
Job 2: Daily VOB Snapshots Purpose: Copy the VOB database for all local VOBs that are configured for snapshots, using vob_snapshot.
If a system administrator is dependent on this job to create vob snapshot backups on ClearCase VOB server hosts and this job is not enabled on those hosts, the backups will not be performed.
Job 3: Daily Registry Backup Purpose: Copy the ClearCase registry from the primary registry server host (when run on a backup registry server host), using rgy_backup.
If a system administrator is dependent on this job to backup the registry data on ClearCase registry server hosts and this job is not enabled on those hosts, there will be no backup made. Page 137 of 341
ClearCase Environment – How do I
Refer to the IBM Rational ClearCase Command Reference Manual under the topic of schedule for further details about the default behavior which states the following:
Default schedule
When no job database exists, the albd_server uses the initial set of job definitions in the file initial_schedule to create a default schedule. This schedule consists of some jobs that are run weekly and other jobs that are run daily. Weekly jobs are run by default. Daily jobs are not run by default: you must explicitly enable them. Daily jobs: * Scrub cleartext and derived object storage pools of all local VOBs, using scrubber. * Copy the VOB database for all local VOBs that are configured for snapshots, using vob_snapshot. * Copy the ClearCase registry from the primary registry server host (when run on a backup registry server host), using rgy_backup. * Run user-defined daily operations in ccase_local_day. * Generate and cache data on disk space used by all local views, using space. * Generate and cache data on disk space used by all local VOBs, using space.
Cause The change was made based on an enhancement request (RATLC01031142) that was implemented in ClearCase 7.1 indicating that the default run behavior was inappropriate for enterprise ClearCase deployments. Thus, user intervention and configuration is required to enable the Daily Scheduled jobs by default in ClearCase version 7.1 and later.
Diagnosing the problem Schedule job defaults By default, the initial scheduled job settings appear as listed in the examples below.
Note the "
Job.NextRunTime:
ClearCase/ClearQuest Integration: Page 138 of 341
ClearCase Environment – How do I Job.Begin # Job.Id: 7 Job.Name: "Daily Base CC/CQ Integration Central Cache Manager " Job.Description.Begin: Clean up Base CC/CQ integration central cache area when used Job.Description.End: Job.Schedule.Daily.Frequency: 1 Job.Schedule.StartDate: 1994-07-03 Job.Schedule.LastDate: 1994-07-03 Job.Schedule.FirstStartTime: 01:00:00 Job.DeleteWhenCompleted: FALSE # Job.Task: 20 Job.Task: "Base CC/CQ Integration Central Cache Manager" Job.Args: -help Job.NotifyInfo.OnEvents: JobEndOKWithMsgs,JobEndFail Job.NotifyInfo.Using: email Job.NotifyInfo.Recipients: root Job.Created: 2009-08-03T00:53:53-04:00 by myco.com/root@myhost Job.LastModified: 2009-08-03T00:53:53-04:00 by myco.com/root@myhost Job.NextRunTime:
MultiSite: Job.Begin # Job.Id: 12 Job.Name: "Daily MultiSite Export" Job.Description.Begin: For each replicated VOB on this host, create an update packet for that replica's siblings Job.Description.End: Job.Schedule.Daily.Frequency: 1 Job.Schedule.StartDate: 1994-07-03 Job.Schedule.LastDate: 1994-07-03 Job.Schedule.FirstStartTime: 20:00:00 Job.DeleteWhenCompleted: FALSE # Job.Task: 13 Job.Task: "MultiSite Sync Export" Job.Args: -quiet 1 -all Job.NotifyInfo.OnEvents: JobEndOKWithMsgs,JobEndFail Job.NotifyInfo.Using: email Job.NotifyInfo.Recipients: root Job.Created: 2009-08-03T00:53:53-04:00 by myco.com/root@myhost Job.LastModified: 2009-08-03T00:53:53-04:00 by myco.com/root@myhost Job.NextRunTime:
Job 1 has historically controlled the starting of the daily jobs, and thus directly impacts the following Job dependencies:
# Job.Id: 2 Job.Name: "Daily VOB Snapshots" # Job.Schedule.Sequential.FollowsJob: 1
# Job.Id: 3 Job.Name: "Daily Registry Backup" # Job.Schedule.Sequential.FollowsJob: 2
# Job.Id: 4 Page 139 of 341
ClearCase Environment – How do I Job.Name: "Daily Local Tasks" # Job.Schedule.Sequential.FollowsJob: 3
# Job.Id: 5 Job.Name: "Daily View Space" # Job.Schedule.Sequential.FollowsJob: 4
# Job.Id: 6 Job.Name: "Daily VOB Space" # Job.Schedule.Sequential.FollowsJob: 5
Resolving the problem Enable the schedule jobs as needed on VOB and Registry server hosts.
Example: To enable Job Id 1, and thus, also enabling Job Ids 2, 3, 4, 5 and 6, make the following modifications to the scheduled Job Id 1: 1. Edit the schedule (cleartool schedule -edit)
Note: In ClearCase, root (UNIX and Linux) or a member of the ClearCase administrators group (Windows) always has Full access to the scheduler on the local host (the computer where that user is logged on).
Example: UNIX or Linux /usr/atria/bin/cleartool schedule -edit
Windows: cleartool schedule -edit
2. Modify the following entry for Job Id 1:
Job.Begin # Job.Id: 1 Job.Name: "Daily VOB Pool Scrubbing" Job.Description.Begin: Scrub the cleartext and derived object storage pools of all local VOBs. Job.Description.End: Job.Schedule.Daily.Frequency: 1 Job.Schedule.StartDate: 1994-07-03 Job.Schedule.LastDate: 1994-07-03 <---REMOVE THIS LINE Job.Schedule.FirstStartTime: 04:30:00 Job.DeleteWhenCompleted: FALSE # Job.Task: 3 Job.Task: "VOB Pool Scrubber" Job.Args: Job.NotifyInfo.OnEvents: JobEndOKWithMsgs,JobEndFail Job.NotifyInfo.Using: email Job.NotifyInfo.Recipients: root Job.Created: 2009-08-03T00:53:53-04:00 by myco.com/root@myhost Job.LastModified: 2009-08-03T00:53:53-04:00 by myco.com/root@myhost Job.Predefined: TRUE Job.NextRunTime:
3. Save the schedule by responding yes to the following prompt:
Replace the entire schedule? [yes]
Page 140 of 341
ClearCase Environment – How do I 4. Check the schedule to be sure the changes have taken effect:
/usr/atria/bin/cleartool schedule -get -job 1
Job.Begin # Job.Id: 1 Job.Name: "Daily VOB Pool Scrubbing" Job.Description.Begin: Scrub the cleartext and derived object storage pools of all local VOBs. Job.Description.End: Job.Schedule.Daily.Frequency: 1 Job.Schedule.StartDate: 1994-07-03 Job.Schedule.FirstStartTime: 04:30:00 Job.DeleteWhenCompleted: FALSE # Job.Task: 3 Job.Task: "VOB Pool Scrubber" Job.Args: Job.NotifyInfo.OnEvents: JobEndOKWithMsgs,JobEndFail Job.NotifyInfo.Using: email Job.NotifyInfo.Recipients: root Job.Created: 2009-08-03T00:53:53-04:00 by myco.com/root@myhost Job.LastModified: 2009-08-03T01:23:41-04:00 by myco.com/root@myhost Job.Predefined: TRUE Job.NextRunTime: 2009-08-03T04:30:00-04:00<-- ENABLED Job.End Over the next several days, check the ClearCase schedule comments for the job completion and notes to verify that all of the anticipated Daily jobs have run successfully. 115. How do I – understand comparing pre-7.1 install technologies to new technologies in 7.1 for achieving enterprise deployment on Windows systems How do I map previous Windows install technologies to the new install technologies used in IBM Rational ClearCase and IBM Rational ClearQuest version 7.1 and later?
Answer The method for installation and deployment of IBM Rational ClearCase and IBM Rational ClearQuest has changed with the release of 7.1. The new installation technologies use repositories and response files, whereas the prior technologies used release areas and specific customized data files.
The following table summarizes the differences between the prior concepts and the new concepts employed by the new installation technology.
Prior to 7.1 release 7.1 release and later
Network area Administrators of Rational The pre-7.1 release area is ClearCase or Rational ClearQuest referred to as a repository in 7.1. use a release area, a network area The repository might be a shared in which they deploy customized directory on a machine acting as a installations. file server or a directory on a Web server. Repositories are read only. Customized files The customized configurations of The configuration file sitedefs.dat Rational ClearCase or Rational is replaced by response files. ClearQuest reside in a customized Administrators can create these data file, sitedefs.dat, by default. XML based response files either by using the -record option or by copying and editing generic response files provided in technotes or within the media. Note: For Rational ClearQuest, it is not possible to provide a path for a default ClearQuest profile Deployment Administrators can either push the To deploy Rational ClearCase and installation to the end user or have Rational ClearQuest using Page 141 of 341
ClearCase Environment – How do I the end user perform the Installation Manager installation from the release area. administrators push out the response files to end users. The end users can load the response files within the Installation Manager GUI or end users can perform a silent install using the response for configuring Rational ClearCase or Rational ClearQuest. Loading the response file in Installation Manager is similar to how you see the default answers when invoking setup.exe and having the choice to accept or change. Achieving deployment using the new technology Administrators who perform deployment of Rational ClearCase and Rational ClearQuest can either push installations to end users or have the end user pull down the installation files and perform the installation. Essentially, Administrators will do the following:
1. Establish a directory on the network where the repository will reside. If you need to access the repository using HTTP, you must use the IBM Packaging Utility to copy the repository to a directory that is served by your HTTP server *. The IBM Packaging Utility is contained in the Rational Enterprise Deployment media. A repository is created by unzipping the file you pulled down from IBM Passport Advantage.
* Refer to technote 1393769 Installation Scenario: Install of ClearCase or ClearQuest with Installation Manager from HTTP server for information about installing from an HTTP server.
2. Create a response file. There are two ways you can create a response file for your deployment. Install the IBM Installation Manager onto a machine and use the –record option to record a response file. The other way is to obtain a sample response file from the media or technotes and customize the response file for your deployment.
The following technotes contain sample response files:
Technote 1351501 Sample response files for IBM Rational ClearCase Technote 1348204 Sample response files for IBM Rational ClearQuest
Response files can reside on any machine, but they must be specific to the platform that they are used to install on. For example, you create a response file for a Windows install and the response file resides on a Network Appliance (NetApp) that is served by a UNIX system. This response file is used when installing on Windows.
As in the past, Administrators do not need to install the IBM Rational product on the machine creating the response files. They must make sure that the network locations and objects specified during the configuration process are accessible as the IBM Installation Manager checks their availability.
3. Deploy the product. You can push the installs to the end users, or end users can access the repository and perform the installation using the recorded response file.
The following technotes provide sample installation scenarios with step by step instructions to aid Administrators in preparing for deployment: Technote 1390818 Installation Scenario: Install ClearCase or ClearQuest with Installation Manager from a network shared drive
Technote 1393304 Installation Scenario: Install of ClearCase or ClearQuest with Installation Manager from HTTP server
Technote 1393735 Installation Scenario: Silent Install of ClearCase or ClearQuest from network shared drive
Technote 1393769 Installation Scenario: Silent Install of ClearCase or ClearQuest with Installation Manager from remote file server 116. How do I – understand about the pathname limitation on Windows and its affect on ClearCase On Windows, a path can only be approximately 256 single-byte characters long.
The following example illustrates this limitation: Attempts to create directory tree in Windows Explorer will truncate after so many characters. Note: The path is C:\temp
Page 142 of 341
ClearCase Environment – How do I
Attempts to create a file or directory in the last directory results in the following error:
Refer to the following Microsoft references for further information:
KB148754 KB121059 Naming a File
Note: The above KB articles apply for Windows 95 but the problem still exists with NT/2000/XP/2003.
ClearCase will be affected by this limitation.
Example:
Directory path in dynamic view:
M:\dynamic_view\test_vob\path_limit\abcdefghijklmnopqrstuvwxyz\ abcdefghijklmnopqrstuvwxyz\abcdefghijklmnopqrstuvwxyz\abcdefghi jklmnopqrstuvwxyz\abcdefghijklmnopqrstuvwxyz\abcdefghijklmnopqr stuvwxyz\abcdefghijklmnopqrstuvwxyz\abcdefghijklmnopqrstuvwxyz >cd a* The filename or extension is too long.
Note: Attempts to create an element in this directory will succeed; however, you will not be able to traverse the path to access the element due to the Windows limitation.
Example:
M:\dynamic_view\test_vob\path_limit\abcdefghijklmnopqrstuvwxyz\ abcdefghijklmnopqrstuvwxyz\abcdefghijklmnopqrstuvwxyz\abcdefghi jklmnopqrstuvwxyz\abcdefghijklmnopqrstuvwxyz\abcdefghijklmnopqr stuvwxyz\abcdefghijklmnopqrstuvwxyz\abcdefghijklmnopqrstuvwxyz >cleartool mkelem -nc test.txt Created element "test.txt" (type "text_file"). Checked out "test.txt" from version "\main\0".
M:\dynamic_view\test_vob\path_limit\abcdefghijklmnopqrstuvwxyz\ abcdefghijklmnopqrstuvwxyz\abcdefghijklmnopqrstuvwxyz\abcdefghi jklmnopqrstuvwxyz\abcdefghijklmnopqrstuvwxyz\abcdefghijklmnopqr stuvwxyz\abcdefghijklmnopqrstuvwxyz\abcdefghijklmnopqrstuvwxyz >notepad test.txt
Page 143 of 341
ClearCase Environment – How do I
To illustrate the distinction, attempts to create a view-private file from Windows Explorer in the same directory where the element was created results in the following error:
ClearCase Version Extended Paths The term path in a ClearCase context also means the full path of the element you pass to the command. For example, if you are using version extended pathname such as filename@@\main\branch\branch\label\branch it is very easy to reach this operating system limit, especially in a UCM environment.
Review the ClearCase Command Reference Guide on the topic of pathnames_ccase (cleartool man pathnames_ccase) for more information about path name resolution, dynamic view context, and extended namespace.
Common ClearCase operations that are affected by long version extended pathnames are:
Merge and Findmerge
Deliver
Rebase
Export & Import
Example:
During a ClearCase merge operation on Windows, the following error appears:
Unable to get the absolute pathname of "M:\devuser1_servicing_processflow_integration\processflow\Source\Shared\ com\finances\core\processflow\ToplinkModel\Class\ com.finances.core.processflow.domain.BorrowerGroupInformationDO.xml@@\main \servicing_processflow_integration\integration_servicing_processflow\3": No such file or directory. Skipping
The reason for the error is related to the length of the path. The version extended path name is too long for Windows to manage. Note: This length includes the drive letter (M:\) as well as the version extended pathname (@@\main\...\3). In order to work around this limitation, you will need to shorten the pathname so Windows can process the command. In this example, you can accomplish this task by renaming the file, the view, the branch structure (what ever you can to shorten the path). Page 144 of 341
ClearCase Environment – How do I For example, you can map a network drive to substitute the MVFS drive and view path. By mapping M:\devuser1_servicing_processflow_integration to Z:\ will cut the path by 42 characters in this example.
Context Menu does not display ClearCase options
ClearCase Context Menu appears until limitation is reached:
Further down: No ClearCase Context Menu:
Further down: No other context menus (for example Winzip® is missing).
Page 145 of 341
ClearCase Environment – How do I
Enhancements to combat the limitation: Starting with ClearCase 2003.06.00, there was a change to the cleartool interface which now supports object names of up to 1024 bytes in length. Although this enhancement is not specific to UCM, it is of particular interest to UCM users, who must contend with long, generated object names.
Note: GUIs do not support 1024 bytes object names in 2003.06.00. Starting with ClearCase 2003.06.14 (Service Release 4) enhancements to the ClearCase GUIs were made to better handle the limitation, however, the Windows pathname limitation still exists and will need to be managed.
Note: The maximum length for an object name is still 255 characters. Review technote 1256146 for more details regarding ClearCase metadata. How to Avoid this issue
The only way to successfully avoid any path name issues is to keep control over the length of your paths.
You can also avoid any path problems (especially in UCM), by using shorter object names (branches, labels, streams, baselines).
WORKAROUNDS:
1. Map a network drive to your dynamic views to reduce the number of characters in the path.
2. Use the subst command to map long paths to a drive:
Example:
C:\>subst K: M:\Joe_Smith_dynamic_view\development_VOB\directory1\directory2 117. How do I - deploy the ClearCase and ClearQuest Help systems on an intranet server Learn how to modify the Help systems for the native (non-Eclipse) ClearCase and ClearQuest products to run on a single intranet server, allowing access to the documentation from remote clients.
Understanding the IBM Eclipse Help System (IEHS) startup modes
The Help system that is installed with ClearCase and ClearQuest 7.1 can run in two modes: standalone mode and information center mode. By default, the Help system is configured to run in standalone mode, which means that when you start the Help system directly from ClearCase and ClearQuest (by clicking the Help button in a dialog, or by selecting the Help option in a menu) it runs on your local client Page 146 of 341
ClearCase Environment – How do I machine, and other machines/clients cannot access it. You have the option to reconfigure the Help system to run in information center mode on a server, which will provide you with a Web-based information center that all of your client machines can access (a central Help system for all users of the product).
Understanding the structure of the Help system
The ClearCase and ClearQuest Help systems include: Version 3.1.1 of IEHS (An IBM-branded version of the Eclipse Help System) Startup and shutdown scripts ClearCase documentation plug-ins and features ClearQuest documentation plug-ins and features
The startup and shutdown scripts installed with ClearCase and ClearQuest are configured to start the Help system in standalone mode. You can add new startup scripts that use information center mode instead, and have users point to this new instance of the Help system on the server for their documentation. Users will access the server-based Help system with a browser, not from their ClearCase and ClearQuest clients (Help calls from the clients will continue to open up the local instance of IEHS).
Overview of the setup/customization process
To customize the Help system, you will follow these basic steps:
1. Create the new IC_start and IC_end scripts. 2. Move the startup.jar and config.ini files. 3. Run the IC_start script to start the server. 4. Access the IC from a browser on a remote machine. 5. Run the IC_end script to shut down the server.
If you have both ClearCase and ClearQuest installed, you can choose to create a single Help system for both products, or separate the documentation into two Help systems. For more information, see the Using the customized IEHS with multiple Rational products section of this document.
The following sections explain the customization process in more detail.
1. Creating the new startup and shutdown scripts
To configure IEHS to start in information center mode, you need to create a new set of startup (IC_start) and shutdown (IC_end) scripts. You will store your new scripts in the same location as the original scripts. The scripts are located in the following locations (using default installation paths): ClearQuest Windows: C:\Program Files\IBM\RationalSDLC\ClearQuest\doc ClearCase Windows: C:\Program Files\IBM\RationalSDLC\ClearCase\doc ClearCase UNIX and Linux: /opt/rational/clearcase/doc 1a. Creating IC_start.bat and IC_end.bat scripts on Windows
On a Windows system, create two new files, IC_start.bat and IC_end.bat with the following contents: IC_start.bat
"C:\Program Files\IBM\RationalSDLC\common\JAVA5.0\jre\bin\java" -classpath "C:\ProgramFiles\IBM\IMShared\plugins\org.eclipse.help.base_3.1.0\helpbase.jar" org.eclipse.help.standalone.Infocenter -eclipsehome "C:\Program Files\IBM\IMShared" -port 8889 -command start -clean -noexec
IC_end.bat
"C:\Program Files\IBM\RationalSDLC\common\JAVA5.0\jre\bin\java" -classpath "C:\ProgramFiles\IBM\IMShared\plugins\org.eclipse.help.base_3.1.0\helpbase.jar" org.eclipse.help.standalone.Infocenter -eclipsehome "C:\Program Files\IBM\IMShared" -port 8889 -command shutdown -noexec 1b. Creating IC_start.sh and IC_end.sh scripts on UNIX
On a UNIX system, create two new files, IC_start.sh and IC_end.sh with the following contents:
IC_start.sh #!/bin/sh /opt/IBM/RationalSDLC/common/java/jre/bin/java –classpath /opt/IBM/IMShared/plugins/org.eclipse.help.base_3.1.0/helpbase.jar Page 147 of 341
ClearCase Environment – How do I org.eclipse.help.standalone.Infocenter -eclipsehome /opt/IBM/IMShared -command start -port
1b. Creating IC_start.sh and IC_end.sh scripts on Linux
On a Linux system, create two new files, IC_start.sh and IC_end.sh with the following contents:
IC_start.sh #!/bin/sh /opt/ibm/RationalSDLC/common/java/jre/bin/java –classpath /opt/ibm/IMShared/plugins/org.eclipse.help.base_3.1.0/helpbase.jar org.eclipse.help.standalone.Infocenter -eclipsehome /opt/ibm/IMShared -command start -port
Several files need to be moved to the “-eclipsehome” location that we use in the new scripts. You should make copies of the files and paste them in their new locations, rather than actually moving them.
2a. Moving the startup.jar and config.ini files on Windows
Copy startup.jar from C:\Program Files\IBM\RationalSDLC\ClearQuest\doc\eclipse\ and paste it in C:\Program Files\IBM\IMShared\.
Copy config.ini from C:\Program Files\IBM\RationalSDLC\ClearQuest\doc\eclipse\configuration and paste it in C:\Program Files\IBM\IMShared\configuration\. 2b. Moving the startup.jar and config.ini files on UNIX
Copy startup.jar from /opt/rational/clearcase/doc/eclipse/ and paste it in /opt/IBM/IMShared/. Copy config.ini from /opt/rational/clearcase/doc/eclipse/configuration/ and paste it in /opt/IBM/IMShared/configuration/. 2c. Moving the startup.jar and config.ini files on Linux
Copy startup.jar from /opt/rational/clearcase/doc/eclipse/ and paste it in /opt/ibm/IMShared/. Copy config.ini from /opt/rational/clearcase/doc/eclipse/configuration/ and paste it in /opt/ibm/IMShared/configuration/.
3. Starting up the Help system
Run the new IC_start script. The Help system starts up and runs in the background. On Windows, a command window opens and remains open as long as the Help system is running. You should now be able to access the InfoCenter from a remote machine
4. Opening the Help system from a remote machine
To view the information center from a remote machine, open a browser and type the URL http://
5. Shutting down the Help system
When you are done using the InfoCenter, shut it down by running the IC_end script
Using the customized IEHS with multiple Rational products Page 148 of 341
ClearCase Environment – How do I
If you have both ClearCase and ClearQuest installed, you can choose to create a single Help system for both products, or separate the documentation into two Help systems. The following sections explain the different options. Running a single Help system for ClearCase and ClearQuest
If you have both ClearCase and ClearQuest installed, and you want to combine the Help systems into one information center, you only need to create the IC_start and IC_end scripts in one of the product directories. For example, create and run the scripts in C:\Program Files\IBM\RationalSDLC\ClearQuest\doc\, C:\Program Files\IBM\RationalSDLC\ClearCase\doc\, or /opt/rational/clearcase/doc/. Documentation plug-ins for both products are stored in the same location: C:\Program Files\IBM\IMShared\plugins\, /opt/IBM/IMShared/plugins/, or /opt/ibm/IMShared/plugins/.
When you run the startup script and open the IC in a browser, you will see both the ClearCase and ClearQuest plug-ins in the table of contents.
Separate Help systems for ClearCase and ClearQuest
If you want to keep the documentation for ClearCase and ClearQuest separate, and run two different information centers, there are a few additional steps that you need to follow:
1. Create two sets of the IC_start and IC_end scripts, one set in each of the product directories C:\Program Files\IBM\RationalSDLC\ClearQuest\doc\ C:\Program Files\IBM\RationalSDLC\ClearCase\doc\ or /opt/rational/ClearCase/doc/ 2. Copy the ClearQuest-specific documentation plug-ins and features to the ClearQuest directory in the installation location.
3. Copy the ClearCase-specific documentation plug-ins and features to the ClearCase directory in the installation location.
4. Copy the Eclipse-specific Help plug-ins and features to the eclipse folder in the installation location.
5. Modify the IC_start and IC_end scripts to point to the new plug-in locations. In all of the IC_start and IC_end scripts, change the “-eclipsehome” option to “-eclipsehome eclipse” Also, make sure that you specify different port numbers for each IC. See the following sections for lists of the Eclipse, ClearCase, and ClearQuest Help plug-ins and features that you need to copy. Eclipse-specific Help plug-ins
Copy the following folders and jar files from C:\Program Files\IBM\IMShared\plugins\ (Windows) /opt/IBM/IMShared/plugins/ (UNIX) /opt/ibm/IMShared/plugins/ (Linux) to C:\Program Files\IBM\RationalSDLC\ClearCase\doc\eclipse\plugins\ (Windows) /opt/rational/clearcase/doc/eclipse/plugins/ (UNIX and Linux) and C:\Program Files\IBM\RationalSDLC\ClearQuest\doc\eclipse\plugins\ (Windows)
Folders: com.ibm.help.hs.doc_3.1.1 com.ibm.help.ic.doc_3.1.1 org.apache.lucene_1.4.3 org.eclipse.help.base_3.1.0 org.eclipse.help.debug_1.0.0 org.eclipse.help.webapp_3.1.0 org.eclipse.help_3.1.0 org.eclipse.tomcat_4.1.30.1
Jar files: com.ibm.watson_0.1.2.jar org.eclipse.core.commands_3.1.0.jar org.eclipse.core.expressions_3.1.0.jar Page 149 of 341
ClearCase Environment – How do I org.eclipse.core.runtime.compatibility_3.1.0.jar org.eclipse.core.runtime_3.1.1.jar org.eclipse.core.variables_3.1.0.jar org.eclipse.help.appserver_3.1.0.jar org.eclipse.help.ui_3.1.1.jar org.eclipse.jface_3.1.1.jar org.eclipse.osgi_3.1.1.jar org.eclipse.swt.win32.win32.x86_3.1.1.jar org.eclipse.swt_3.1.0.jar org.eclipse.ui.forms_3.1.0.jar org.eclipse.ui.win32_3.1.0.jar org.eclipse.ui.workbench_3.1.1.jar org.eclipse.ui_3.1.1.jar org.eclipse.update.configurator_3.1.0.jar org.eclipse.update.core_3.1.1.jar Eclipse-specific Help features
Copy the following folders from C:\Program Files\IBM\IMShared\features\ (Windows) /opt/IBM/IMShared/features/ (UNIX) /opt/ibm/IMShared/features/ (Linux) to C:\Program Files\IBM\RationalSDLC\ClearCase\doc\eclipse\features\ (Windows) /opt/rational/clearcase/doc/eclipse/features/ (UNIX or Linux) and C:\Program Files\IBM\RationalSDLC\ClearQuest\doc\eclipse\features\ (Windows) /opt/rational/clearquest/doc/eclipse/features/ (UNIX or Linux)
Folders: com.ibm.help.hs.doc.feature_3.1.1 com.ibm.help.ic.doc.feature_3.1.1 ClearCase Help plug-ins
Copy the following Help plug-ins from C:\Program Files\IBM\IMShared\plugins\ (Windows) /opt/IBM/IMShared/plugins/ (UNIX) /opt/ibm/IMShared/plugins/ (Linux) to C:\Program Files\IBM\RationalSDLC\ClearCase\doc\eclipse\plugins\ (Windows) /opt/rational/clearcase/doc/eclipse/plugins/ (UNIX or Linux)
Jar files: All jar files named com.ibm.rational.clearcase.*.doc.*.jar com.ibm.ccl.feedreader_1.0.0.v20070912.jar com.ibm.ccl.welcome.bits_7.0.3.v20071001.jar com.ibm.help.common.accessibility.doc_7.5.0.jar com.ibm.help.common.doc_7.5.0.v20080701.jar com.ibm.help.common.nav.doc_7.5.1.v20080722.jar com.ibm.help.common.rational.doc_7.5.0.v20080701.jar com.ibm.help.common.resources.doc_7.5.0.jar com.ibm.help.gallery.cat_7.5.2.v20080701.jar com.ibm.welcome.common.rational.doc_7.5.0.jar com.ibm.rational.team_api.doc_7.1.0.v200810131214.jar com.ibm.rational.team_api_cc_tut.doc_7.1.0.jar com.ibm.rational.crm_migration.doc_7.1.0.jar com.ibm.rational.licensing.doc_7.1.0.v200810131214.jar Note: The date-time stamps on the files in your installation directory may be different than the ones listed here. ClearCase Help features
Copy the following Help features from C:\Program Files\IBM\IMShared\features\ (Windows) Page 150 of 341
ClearCase Environment – How do I /opt/IBM/IMShared/features/ (UNIX) /opt/ibm/IMShared/features/ (Linux) to C:\Program Files\IBM\RationalSDLC\ClearCase\doc\eclipse\features\ (Windows) /opt/rational/clearcase/doc/eclipse/features/ (UNIX or Linux) All folders named com.ibm.rational.clearcase.*.doc.* com.ibm.rational.crm.doc.feature_7.1.0.v200810131214 com.ibm.rational.crm.tours.doc.feature_7.1.0.v200810131214 com.ibm.rational.crm.tuts.doc.feature_7.1.0.v200810131214 com.ibm.ccl.welcome.bits.feature com.ibm.help.common.feature com.ibm.help.common.rational.feature Note: The date-time stamps on the files in your installation directory may be different than the ones listed here.
ClearQuest Help plugins
Copy the following Help plug-ins from C:\Program Files\IBM\IMShared\plugins\ (Windows) to C:\Program Files\IBM\RationalSDLC\ClearQuest\doc\eclipse\plugins\ (Windows) Jar files: All jar files named com.ibm.rational.clearquest.*.doc.*.jar com.ibm.ccl.feedreader_1.0.0.v20070912.jar com.ibm.ccl.welcome.bits_7.0.3.v20071001.jar com.ibm.help.common.accessibility.doc_7.5.0.jar com.ibm.help.common.doc_7.5.0.v20080701.jar com.ibm.help.common.nav.doc_7.5.1.v20080722.jar com.ibm.help.common.rational.doc_7.5.0.v20080701.jar com.ibm.help.common.resources.doc_7.5.0.jar com.ibm.help.gallery.cat_7.5.2.v20080701.jar com.ibm.welcome.common.rational.doc_7.5.0.jar com.ibm.rational.team_api.doc_7.1.0.v200810131214.jar com.ibm.rational.team_api_cq_tut.doc_7.1.0..jar com.ibm.rational.crm_migration.doc_7.1.0.jar com.ibm.rational.licensing.doc_7.1.0.v200810131214.jar Note: The date-time stamps on the files in your installation directory may be different than the ones listed here.
ClearQuest Help features
Copy the following Help features from C:\Program Files\IBM\IMShared\features\ (Windows) to C:\Program Files\IBM\RationalSDLC\ClearQuest\doc\eclipse\features\ (Windows) All folders named com.ibm.rational.clearquest.*.doc.* com.ibm.rational.crm.doc.feature_7.1.0.v200810131214 com.ibm.rational.crm.tours.doc.feature_7.1.0.v200810131214 com.ibm.rational.crm.tuts.doc.feature_7.1.0.v200810131214 com.ibm.ccl.welcome.bits.feature com.ibm.help.common.feature com.ibm.help.common.rational.feature Note: The date-time stamps on the files in your installation directory may be different than the ones listed here.
Troubleshooting
If the information center does not start up, you can try the following things: Run the IC_end script and then restart the IC. Delete the folders, but not the config.ini file, from the configuration directory and restart the IC.
Page 151 of 341
ClearCase Environment – How do I 118. How do I - enable debugging for ClearCase and ClearQuest installs using Installation Manager Certain situations can sometimes cause the installation of ClearCase or ClearQuest to fail. If the information provided in the log files is not enough to solve the problem, turning on debugging can help further narrow down the problem.
Answer Debugging can be turned on either after Installation Manager is installed or before if you are having problems installing Installation Manager itself. Enable Debugging Turning on debugging once Installation Manager is installed: 1. cd to the logs directory
UNIX/Linux: cd /var/ibm/InstallationManager/logs
Windows: cd c:\Documents and Settings\All Users\Application Data\IBM\Installation Manager\logs 2. Create a file named log.properties and add the following 3 lines:
Director=DEBUG Engine=DEBUG InstallOrderManager=DEBUG InstallOperation=DEBUG 3. Save the file 4. Now invoke Installation Manager and repeat the install that is having problems.
The debug information will be written to the log file in: Windows: c:\Documents and Settings\All Users\Application Data\IBM\Installation Manager\logs\
If the debug information doesn't help you solve the issue, send the following data to IBM Rational Client Support for further analysis. Windows: zip up the contents of c:\Documents and Settings\All Users\Application Data\IBM\Installation Manager\ UNIX/Linux: tar up the contents of /var/ibm/InstallationManager Note: If you are having problems with the installation of the Installation Manager itself, you can still create the log.properties file as noted above, however, you will need to carefully create the directories to put the file in (as they do not exist within a pre-install state). You can issue a mkdir -p /var/ibm/InstallationManager/logs command to generate the directories necessary to create the log.properties file, and thus debug the install of the Installation Manager, if necessary. 119. How do I – understand the knowledge Collection: Available White Papers for the ClearCase Family of Products This knowledge collection is intended to provide a single listing of available White Papers for the ClearCase Family of products.
DOCUMENTATION Document # Title
7014695 ClearCase 7.1 Release Report
7009863 ClearCase 7.0.1 Release Report
7015035 Deploying the ClearCase and ClearQuest Help systems on an intranet server
Page 152 of 341
ClearCase Environment – How do I
GENERAL
7009697 About the Rational ClearCase Type Manager
IBM Rational ClearCase support for AIX PowerHA 7015883
INSTALLATION AND UPGRADE
7010633 Simplifying an Enterprise Installation of the IBM Rational ClearCase Remote Client
7005767 Preparing Linux for ClearCase Installation
Upgrading a Rational ClearCase and ClearQuest Community to Version 7.0.0, 7.0, Windows, GI11-6759-00 UNIX, Linux
7010114 Deploying Rational ClearCase using Microsoft SMS
INTEGRATIONS
7010674 Utilizing the ClearCase Integration with WebSphere Business Modeler
3915 IBM Rational ClearCase integration with IBM WebSphere Studio Application Developer
7015886 ClearCase 7.x and Rhapsody: Supported Integrations
4562 ASP. NET development using IBM Rational ClearCase
INTEROP
7011199 ClearCase and Samba: A Supported Configuration
MULTISITE
7015218 ClearCase Multisite Replica Recovery in secure one-way synchronization environments
7016869 ClearCase MultiSite divergence - preventing and recovering from divergence
UCM
7012941 Understanding ClearCase UCM Deliver Dependencies
7014131 Understanding ClearCase Client, Administrative VOB Interactions and Metadata in UCM
7015347 Understanding Nested UCM Project VOB Environments
7012930 ClearQuest and ClearCase, ClearCase Remote Client (CCRC) UCM Environment Operations Guide
2057 Unified Change Management from Rational Software: An Activity-Based Process for Managing Change
PERFORMANCE
7016576 ClearCase Registry server Performance Enhancements for version 7.1
VOB
7010498 Remote VOB Storage Pools on Windows
Page 153 of 341
ClearCase Environment – How do I 120. How do I – understand the White paper: ClearCase Registry server Performance Enhancements for version 7.1 The following white paper has been published to provide details about the enhancements made in ClearCase 7.1 to improve registry server performance.
ClearCase Registry server Performance Enhancements for version 7.1 121. How do I – understand why the installation of ClearCase 7.1 fails during post-install phase and logs MVFS errors: Trouble mounting the viewroot "/view" This technote explains how to resolve an issue that can occur where installing IBM Rational ClearCase (CC) 7.1 fails during the post-install phase and reports MVFS errors: Trouble mounting the viewroot "/view" when installing on a host that had a previous ClearCase version installed .
Symptom Attempts to install ClearCase 7.1 on a server that was previously running with ClearCase version 7.0.1 is failing in the post-install phase. After the previous version of ClearCase was removed, InstallationManager keeps failing at the post install phase with the following errors in the logs:
Error occurred in phase: post-install configure SU: com.ibm.rational.clearcaseunix.last.sun5 1.0.0.00-7- 1-D081104 IU: last.sun5 null->999.999.999.-75020128 Message: Error executing "/opt/IBM/RationalSDLC/clearcase/etc/clearcase" operation (status=50). See agent output log for more information: /var/ibm/InstallationManager/logs/native/20090109_0940.log and then this:
Error during "post-install configure" phase: Error executing "/opt/IBM/RationalSDLC/clearcase/etc/clearcase" operation (status=32). See agent output log for more information: /var/ibm/InstallationManager/logs/native/20090109_0940a.log Error executing "/opt/IBM/RationalSDLC/clearcase/etc/clearcase" operation (status=50). See agent output log for more information: /var/ibm/InstallationManager/logs/native/20090109_0940.log
/var/ibm/InstallationManager/logs/native/20090109_0940.log contained:
ClearCase daemons: albd_server Loading MVFS ... mount: Operation not applicable to FSType mvfs Trouble mounting the viewroot "/view"(16:1) mvfslog: Error: The MVFS file system is not installed or not loaded, or the 'viewroot' is not mounted or is inaccessible: not a ClearCase object. Trouble setting MVFS kernel log file to /var/adm/rational/clearcase/log/mvfs_log(2:1) Mounting public VOBs... cleartool: Error: The MVFS file system is not installed or not loaded, or the 'viewroot' is not mounted or is inaccessible: not a ClearCase object. Trouble mounting public VOBs(32:1)
Cause Remnants of a previous installation of MVFS can interfere with the install process. This problem may occur if MVFS is not completely cleaned out from a previous installation.
Resolving the problem Refer to technote 1376016 Uninstall ClearCase 7.1 on Linux or Unix for information about how to cleanup when a previous uninstall of ClearCase was not completed. 122. How do I – understand why applying the latest Fix Pack may yield error: zip com.ibm.rational.team.write.runonce.key 1.0.0.v200810242053 not found This technote explains how to resolve an error, zip com.ibm.rational.team.write.runonce.key 1.0.0.v200810242053 not found, that can occur when attempting to install an IBM Rational product Fix Pack using the Installation Manager.
Either of the following scenarios will produce this error: 1. When updating ClearCase or ClearQuest from 7.1.0.0 to fix pack 7.1.0.1, the installation aborts and reports an error:
Page 154 of 341
ClearCase Environment – How do I "Failed to find all installation files zip com.ibm.rational.team.write.runonce.key 1.0.0.v200810242053 not found" Symptom When you are attempting to apply the current fix pack for any Rational Product through Installation Manager where there is one or more than one product installed on the same system you may receive an error: zip com.ibm.rational.team.write.runonce.key 1.0.0.v200810242053 not found
Cause The cause of this error is a result of an attempt to apply a fix pack without referencing the original installation repository. This cause holds true to any Rational Product that is installed on the same system.
For example:
In symptom 1 above Fix pack 7.1.0.1 is a "delta" update which requires version 7.1.
This issue is caused by not having the version 7.1 repository available as a selected repository. The 7.1 repository and the 7.1.0.1 repositories need to be accessible for the Installation Manager to apply the updates.
In the case where you are applying the fix pack to both ClearCase and ClearQuest four repositories are needed: ClearCase version 7.1
ClearQuest version 7.1
ClearCase fix pack 7.1.0.1
ClearQuest fix pack 7.1.0.1 Resolving the problem To resolve the issue you must ensure that all repositories are present and active at the point you want to apply a fix pack. Add the required repositories to the Installation Manager in "File" -> "Preferences" and rerun the installation. For instance, if you have ClearCase, ClearQuest and RequisitePro installed on the same system and want to apply the fix packs, you must apply all the fix packs at the same time. You cannot apply only one fix pack to one product. Here are the basic steps to correct the issue: 1. Launch IBM Installation Manager
2. Go to File, then Preferences
3. Under the Repositories section ensure that you have a check mark active for the original installation repository as well as the Fix Pack repository.
Once all areas have been made active you can proceed with the update and apply the fix pack. Refer to technote 1380386 How to update an IBM Rational 7.1.x install through IBM Installation Manager for further details. 123. How do I – understand the ClearCase 7.1 equivalent to installing by siteprep in pre 7.1 versions ClearCase 7.1 uses Installation Manager, and siteprep is no longer available.
Silent install using response file is a similar method to using siteprep.
The steps below point to the appropriate sections of the ClearCase 7.1 installation documentation and will help you to install ClearCase 7.1 (siteprep style).
1. Verifying and extracting electronic images
Page 155 of 341
ClearCase Environment – How do I 2. Installing Packaging Utility
3. Copying product packages using Packaging Utility
4. Recording a response file using Installation Manager without installing
5. Install Installation Manager from all clients:
IBM Installation Manager tasks 6. Setting repository preferences in Installation Manager 7. Installing and running Installation Manager in silent mode 124. How do I - configure ClearCase on a mobile computer that is disconnected from and then reconnected to the network When using ClearCase on a laptop that is routinely disconnected from the network, the optimal configuration parameters are as follows:
REASONS:
During logon, the clearcase_albd account attempts to contact the domain for which it is a member for authentication. Since the computer is not connected to the network, login can be delayed unnecessarily.
Errors will appear in the logs that the "albd_server must run in the clearcase group". This is due to the fact that domain group membership cannot be checked. INSTRUCTIONS: 1. Open the Computer Management Console (Right-click My Computer and select Manage)
Page 156 of 341
ClearCase Environment – How do I 2. Expand Services and Applications and select Services
3. Double-click Atria Location Broker
4. Change the Startup type to Manual
5. Click OK
6. Repeat steps for Rational (Atria) Cred Manager & Rational (Atria) Lock Manager
Note: When connected to the network, you will need to start the services manually.
Page 157 of 341
ClearCase Environment – How do I Disable ClearCase network operations
REASON: Disabling ClearCase network operations informs ClearCase that the tool is not connected to the network. When the checkbox is cleared, integrations that require access to the ClearCase network are disabled. Review technote 1118151 for more details on Working disconnected from the network in snapshot views.
INSTRUCTIONS: Open to the ClearCase Control Panel (Start > (Settings) > Control Panel) Double click the ClearCase icon Click Options tab Clear the checkbox Connected to the ClearCase Network Click OK
Note: When connected to the network, this checkbox needs to be enabled.
Enable a Hardware Profile & Disable ClearCase Services Microsoft® recommends hardware profiles for machines that need to boot in environments both with and without network connectivity. Review the related information below for more details. Create a new Hardware Profile: 1. Open the Control Panel (Start > (Settings) > Control Panel) 2. Double click the System icon 3. Click the Hardware Profiles tab 4. Create a new Hardware Profile (Copy existing one)
Page 158 of 341
ClearCase Environment – How do I 5. Click OK
Disable ClearCase services 1. Open to the Control Panel (Start > (Settings) > Control Panel) 2. Double click the Services icon 3. Double click Atria Location Broker from the list 4. Click the Log On tab 5. Select the newly created profile in the Hardware Profiles section 6. Click Disable. 7. Repeat steps for Rational (Atria) Cred Manager & Rational (Atria) Lock Manager
Page 159 of 341
ClearCase Environment – How do I
Note: When booting ON the network, use the normal profile. When booting OFF the network, use the "Off Network" profile.
Related information How to create a Hardware Profile Hardware Profiles Overview Stop and Start ClearCase Services from command line 125. How do I - install ClearCase v7.1.x on a platform that does not use the GUI You must use the silent installation process to install IBM Rational ClearCase on platforms that do not use the graphical user interface (GUI).
These platforms are:
* HP Itanium * HP PA-Risc * zLinux * Linux ppc * Solaris x86
Note: For platforms that do use the GUI, follow the installation instructions provided in the IBM Rational ClearCase Information Center: http://publib.boulder.ibm.com/infocenter/cchelp/v7r1m0/index.jsp.
To silently install Rational ClearCase:
1. If the ESD image is not available through a UNC or NFS path: a. Copy the ESD Image onto the local machine. b. Unzip the ESD image. The path to the ESD image is denoted as esd_image_root Note: A DVD image is an ESD image that is unzipped.
2. If the ESD image is available through a UNC or NFS path, copy the file esd_image_root/product_response_platform.xml onto a writeable disk. Page 160 of 341
ClearCase Environment – How do I
3. Open and read the license agreement files located in esd_image_root/license_agreements. xx indicates the language of the file. The files are: * LA_xx * LI_xx * non_ibm_license * notices
4. Open the response file, product_response_platform.xml.
5. If you agree to the license agreement, change the value for the acceptLicense key to true.
6. Change the value for the repository location key to 'esd_image_root/diskTag.inf'.
7. Follow the comments within the response file to configure your product's installation.
8. Open the file esd_image_root/InstallerImage_$platform/install.xml. Find the version key and copy the value. You use this value in the next step. For example:
9. Open the response file. In the
10. If IBM Installation Manager is not installed, you must install it. If an older version of Installation Manager is installed, it must be upgraded. To install Installation Manager that is bundled along with the product or to upgrade the current installed version of Installation Manager, follow the instructions below. a. Add the repository location for Installation Manager into the downloaded response file:
c. Copy the install instruction below into your response file:
d. An example of part of a response file after adding the repository location for Installation Manager:
11. Run the command: esd_image_root/InstallerImage*/install --launcher.ini esd_image_root/InstallerImage*/silent- install.ini -silent -input product_response_platform.xml -log logfile To display progress text to the console add -showVerboseProgress to the command. Page 161 of 341
ClearCase Environment – How do I 126. How do I - update the Windows ClearCase ALBD Password In any IBM® Rational® ClearCase® environment that uses Microsoft® Windows®, ClearCase requires a Windows user account to start the ClearCase Atria Location Broker Daemon (ALBD) service. This article explains one way of changing the ALBD password, which you typically must do frequently for security. One of the tasks of IBM® Rational® ClearCase® administrators when working in Microsoft® Windows® environments is managing the account required to start the IBM Rational ClearCase Atria Location Broker Daemon (ALBD) service. Most companies' security policies require that all account passwords must change periodically, typically about every 90 days, and the ClearCase password is usually no exception, of course. Changing the password every 90 days is relatively easy, but the fact that this change must now be propagated to tens, hundreds, or even thousands of Windows clients can make it a difficult and time-consuming task. There are numerous ways to automate this task, though, and each has its own pros and cons. This article explains one method (see Resources for an article about alternatives). IMPORTANT NOTICE: Please read the license.txt file that is part of the zip package for this utility. This utility is provided "as-is" and there is no support provided for this by IBM Rational. This utility may modify the Microsoft Windows registry settings as well as potentially change a Microsoft Service process definition. Changing these registry and service settings through the use of this utility involves some element of risk and may result in problems and errors occuring during the execution of Windows. Anyone running this utility needs to be aware of the potential risks. The ClearCase context Rational ClearCase has three services, or processes, that must run in the background on a Microsoft Windows platform: The lock manager (lockmgr)
The credentials manager (cccredmgr)
The ALBD service The last one, the ALBD service, requires a Windows user account with ClearCase privileges to function properly. In the definition of this service, during ClearCase installation, the ClearCase administrator must specify the name of this privileged account, the password, the Windows domain, and the Windows group for this account. In some cases, only the password will ever change for this account. In other installations, there may be a requirement to change another or all of these values. Note: To change these values, you need administrator's rights on the Windows client machine. A utility to automate password changes To make changing multiple ClearCase passwords easier, you can use a utility (ccalbdpw.exe) that resides on the client software. The utility reads a sitedefs.dat file on a network release area and simply updates the Windows registry information for the ALBD service. The utility must be executed using an account that has permission to change the registry values. To use this utility, you follow this three-step process: 1. Change the Windows ALBD service account password.
2. Update the ClearCase network release area with the new password by copying the sitedefs.dat file to the SETUP directory in the network release area.
3. Run the password update utility (ccalbdpw.exe) on each client.
The ccalbdpw.exe utility reads the new password value from the SETUP\sitedefs.dat file and updates the Windows registry value. The new password value takes effect when you reboot the machine or when you stop and restart the ClearCase services. Advantages of the using this utility The advantages of this utility are that the password is secure and that the utility works with the existing ClearCase installation information on your workstation. If you prefer, you can modify the script for this utility to run on every reboot of a workstation and automatically pick up any changes. To make maintenance tasks of the ALBD service account easier, this script also enables you to change this data in the Windows registry: Password
ALBD service account name
ALBD group name
Path to the network release area
Page 162 of 341
ClearCase Environment – How do I This script was designed to be used with Microsoft Systems Management Server (SMS) and other installation or upgrade tools. It also provides a detailed error message if a problem occurs. Contents of the compressed utility file This password change utility currently supports Rational ClearCase Windows version 2003.06 and version 7. The .zip file included as a download with this article contains these elements: A Windows executable file for the utility
A readme.txt file with a detailed instructions and a complete listing of all error codes
A license.txt file that indicates that this is an as-is utility; therefore, does not include IBM Rational technical support
Download Description Name Size Download method
readme, license and executable files ccalbdpw_v404.zip 57KB HTTP
127. How do I – understand why package IBM Rational ClearCase is already installed. This package can only be installed in one location error reported when recording a response file using -skipinstall This technote explains how to resolve an error, Package IBM Rational ClearCase is already installed. This package can only be installed in one location that can occur when selecting a package to install during the recording of a response file when using the -skipinstall option for a IBM Rational ClearCase (CC) 7.1 installation
Symptom This error appears when you select a package to install during the recording of a response file with the - skipinstall option; even if ClearCase is not installed on the machine. Package IBM Rational ClearCase is already installed. This package can only be installed in one location.
Cause The agent data location specified after the -skipinstall has already been used for the creation of a response file for this product
Resolving the problem Remove the contents of the agent data location or create a new directory to be used as the agent data location for the creation of this response file 128. How do I – understand why after restarting the ClearCase host the CM server does not automatically restart This technote identifies an issue that can occur after shutting down and restarting the IBM Rational ClearCase (CC) host the CM server does not start automatically.
Symptom After shutting down and restarting the ClearCase host the CM server does not start automatically
Cause This issue is caused by the missing execute flags for the IBM Embedded WebSphere Application Server (eWAS) startup and shutdown scripts in the directory: /etc/init.d. After the installation, the CM Server will not be started after reboot:
-rwxr-xr-x 1 root root 4905 Jan 8 14:38 clearcase -rw-r--r-- 1 root root 2461 Jan 8 14:40 ewas_shutdown -rw-r--r-- 1 root root 2478 Jan 8 14:40 ewas_startup -rw-r--r-- 1 root root 1490 Jan 8 14:42 ihs_shutdown -rw-r--r-- 1 root root 1511 Jan 8 14:42 ihs_startup This issue has been identified as a product defect, APAR PK79083.
Resolving the problem Run chmod 755 on these scripts: startup - ewas_startup and ihs_startup shutdown - ewas_shutdown and ihs_startup , which is located in /etc/init.d
Page 163 of 341
ClearCase Environment – How do I
129. How do I – understand why the Next button is disabled when installing ClearCase and ClearQuest at the same time When installing both IBM Rational ClearCase and IBM Rational ClearQuest at the same time using IBM Installation Manager, the Next button is disabled.
Symptom The following error is found in the Installation Manager log file: java.lang.UnsatisfiedLinkError: com/ibm/common/install/win32/Win32Helper.GetDomainsN()[Ljava/lang/String; com.ibm.common.install.win32.Win32Helper.GetDomains(Win32Helper.java:596) com.ibm.rational.cc.serviceacount.panel.ServiceAccountPanel.createControl(S erviceAccountPanel.java:141) This issue occurs when multiple versions of the same product are listed during installation. You can view the multiple product versions by checking the Show all versions check box. Multiple products versions are available when they are found in the list of repository locations that IBM Installation Manager points to in its preferences. Multiple product versions can be available by pressing the button Check for Other Versions and Extensions.
Resolving the problem To work around this issue, select one product at a time when installing using Installation Manager. For example, install Rational ClearCase first, then install Rational ClearQuest 130. How do I – understand the compatible ClearCase server and client iFix and Fix Pack levels Do the iFix or Fix Pack levels need to match (or be the same) for both an IBM® Rational® ClearCase® server and client running the same ClearCase base or major version?
Answer Note (UCM environments): Rational Client Support has become aware of some compatibility issues with UCM GUIs that will be published. All the compatibility issues can be resolved by upgrading the server to the same or newer version than the client.
The iFix or Fix Pack levels do not need to be the same as long as the ClearCase server version is at the same or at a higher version than the client. IBM Rational iFixes and Fix Packs for clients and servers running at the same version level (such as 7.0 or 7.0.1) do not introduce any incompatibility issues. Although upgrading the server before the clients is recommended, for example, the following combinations are supported: "Server at ClearCase v7.0.1 with Client at v7.0.1 iFix01" "Server at ClearCase v7.0.0.0 with Client at v7.0.0.1" "Server at ClearCase v7.0.0.0 with Client at v7.0.0.2" Product Documentation Refer to the following sections of the ClearCase Installation and Upgrade Guides for further details: UNIX/Linux: Section titled Before you Install under the topic of Compatibility across releases
Windows: Section titled Configuring your Installation under the topic of Operational compatibility across versions of Rational ClearCase
ClearCase Compatibility Across Releases (for ClearCase 7.1) Related information How to apply a Rational iFix or Fix Pack on Windows 131. How do I – understand the Knowledge Collection: Manually uninstall ClearCase This knowledge collection is intended to help remove Rational ClearCase from any of the supported platforms: 1302974 - System Requirements for ClearCase 7.1 1239315 - System Requirements for ClearCase 7.x 1136950 - System Requirements for ClearCase 2003.06.xx Page 164 of 341
ClearCase Environment – How do I
The following information identifies the platforms for which uninstall documents have been created for, as well as a document that provides information for removing ClearCase updates.
Note: ClearCase 7.1 introduced the use of the IBM Installation Manager that enables you to install, update, roll back, and remove product installations. Be sure to check the versions identified in each of the documents referenced below to be sure it applies to your installed ClearCase version. Uninstall Linux Manually uninstall Rational ClearCase from a Red Hat® Linux or SUSE® Linux server by removing the installed binaries and start-up scripts, see technote 1257486.
Uninstall Solaris Manually uninstall Rational ClearCase from a Sun® Solaris server by removing the installed binaries and start-up scripts, see technote 1134883.
Uninstall Microsoft Windows Manually uninstall Rational ClearCase from a Microsoft® Windows® host, including directory trees and registry entries, see technote 1179647. Manually uninstall ClearCase 7.1 on Windows, see technote 1358566 .
Uninstall AIX Manually uninstall IBM® Rational® ClearCase® from an IBM AIX® server by removing the installed binaries and start-up scripts, see technote 1134199.
Uninstall HP-UX Manually uninstall Rational ClearCase from an HP-UX server by removing the installed binaries and start- up scripts, see technote 1127418. Uninstall ClearCase Updates Removing Rational ClearCase updates, such as patches, service releases, iFixes, and fixpacks, from a network wide release area or a host installation, see technote 1131826. 132. How do I – understand about the IBM Rational ClearCase Windows release area Extracting files from a Web Download archive (*.zip) to disk is synonymous with a "CD Image" and is not considered a release area.
Both an actual CD Image and Web Download bits are considered staging areas.
The staging area is used to create a release area.
Attempts to apply service releases, ifixes or fixpacks to a staging area will result in the above error during upgrade.
The following instructions detail how to create a release area using the bits from a Web Download. 1. Extract all downloaded files to a temporary location (example C:\temp). 2. Change directories into the temp location and execute Setup.exe.
Note: This process performs some simple checks (such as, whether ClearCase is already installed) and then launches siteprep.exe which is used to create a release area. 3. Select "Enterprise deployment" for the deployment method.
Note: A "Release Area" is synonymous with "Enterprise deployment". The actual text for the option to select when choosing a deployment method states:
Enterprise deployment [Create a network wide release area and customize it using Siteprep] 4. Answer the siteprep configuration questions including where the release area will be stored to complete the procedure.
Note: The location chosen for the release area will then be populated with the bits from the Web Download archive as needed (depending on the selections chosen from siteprep.) Failure to create a proper release area can result in the following error during upgrade:
Error 1334. The file '
ClearCase Environment – How do I
Note: Error 1334 is usually generated due to mixed-media forms when installing or upgrading Rational Products. 133. How do I – understand about the ALERT: albd service unexpectedly installed during a ClearCase 7.1 Client Only Installation on Windows This alert is meant to inform you of an issue that can occur when installing IBM Rational ClearCase (CC) 7.1 on Windows where the albd service is unexpectedly installed even though the option for Local vobs and views was not selected
ISSUE When performing a Client Only install on a Windows host and not selecting "Local vobs and views", the albd service is unexpectedly installed.
This issue has been identified as a product defect under APAR PK78380. IMPACT The installation of the albd_server process creates an unnecessary process on what is expected to be a client only install. The ClearCase albd server process account also needs to be granted rights to "Log on as a service" (which may not be desired). If the proper rights are not granted, the service will fail to start and ClearCase will not function properly on that client. Note: You will receive the correct behavior where you can not create local vobs or views and you can still create remote VOBs and views without an issue. However, the albd_server is running on the system where it should not have been installed. Refer to the IBM Rational ClearCase Administrators Guide under the topic of Defining required domain accounts manually for further details about the albd server process account requirements. WORKAROUND The workaround for this issue is to do the following: 1. From a command prompt, run net stop albd. This will stop the albd_server. Note: You can also stop the service in the ClearCase Control panel and the Microsoft Services Management Console. 2. Then run sc delete albd. This command will remove the albd service from Windows.
KNOWN ISSUES ClearCase Doctor reports "ClearCase does not appear to be running on this computer.".
The removal of the service also adds a new error to ClearCase doctor, which says that ClearCase is not running on the machine.
Page 166 of 341
ClearCase Environment – How do I
Uninstalling ClearCase:
After implementing this fix, if you try to uninstall ClearCase, you will receive an error that the installer was unable to stop the albd service. Also, some ClearCase files in the C:\Program Files\IBM\RationalSDLC are not removed. You can remove the ClearCase directory manually by doing a right-click==>Delete. If you receive an access denied message regarding CCshmemV3, reboot the system and then delete the files.
Using the above workaround does not resolve the problem of ClearCase Doctor incorrectly reporting that the client can have local vobs and views. Refer to technote 1366273 for further information about a separate defect related to this issue.
134. How do I – understand the clarification on the alert issued for RHEL 4 Update 5/6 and RHEL 5 and support for ClearCase VOB hosts with Network Attached VOB storage Due to the defects below, IBM Rational cannot certify the following ClearCase configuration combinations: ClearCase 7.0 / 7.0.1 VOB server Network Attached Storage for VOBs AND EITHER RedHat Enterprise 4 Update 5/6 OR RedHat Enterprise 5
Bugzilla Bug 41942 - RIT161907- 30 second flock() calls against files stored on a NetApp while using NFS https://bugzilla.redhat.com/show_bug.cgi?id=432855
-Bugzilla Bug 41974 - RIT163042-Pages of a memory mapped NFS file get corrupted. https://bugzilla.redhat.com/show_bug.cgi?id=432974
Answer Symptoms of the 30 Second flock() defect include poor VOB performance as well as ClearCase command timeouts.
Symptoms of the mmap defect include affected VOBs being completely non-responsive to ClearCase commands as well as 100% CPU utilization for db_server and vobrpc_server processes.
Given all of the above, IBM Rational cannot certify the specified configurations above. Once RedHat has addressed both defects, IBM Rational will begin the recertification process.
Page 167 of 341
ClearCase Environment – How do I Note: ClearCase client configurations utilizing RedHat Enterprise 4 Update 5/6 or RedHat Enterprise 5 still may experience problems outside of ClearCase if Network Attached Storage is utilized for Views or other Client Side applications that rely on NFS. As mentioned above, performance or mmap file corruption could occur if used on the above specified versions of RedHat Enterprise Linux.
Please contact RedHat Engineering Support for further clarification and greater detail on the above Bugzilla cases. 135. How do I – understand the issue of db_server or vobrpc_server processes on a RedHat Enterprise Linux VOB server consume 100% CPU when using NAS storage for VOBs db_server or vobrpc_server processes consume 100% of a CPU on a RedHat Linux VOB server when using NAS storage for the VOBs.
Cause A defect with the Linux implementation of NFS was discovered.
Note: This only applies to clients with Red Hat Linux VOBs hosting VOB storage on a NAS device. Refer to technote 1315605 Clarification on the alert issued for RHEL 4 Update 5/6 and RHEL 5 and support for ClearCase VOB hosts with Network Attached VOB storage for the latest up to date information concerning this defect:
Diagnosing the problem The following behavior will be seen when running into this issue:: 1. A db_server or vobrpc_server process is consuming 100% of a CPU in a tight (user space) loop By a tight user space loop, we mean: a. the db_server or vobrpc_server process is consuming 100% CPU and b. the CPU it is using is in user mode not system mode. (See #2 below) 2. You can check to see if you have the problem by running "top" and checking to see if a db_server or vobrpc_server process is consuming 100% of a CPU. You can also run the "sar" command - and check the heading %user in typical sar output such as: # sar -u 1 10 Linux 2.6.9-55.EL (miami) 12/21/2007 11:33:44 AM CPU %user %nice %system %iowait %idle 11:33:45 AM all 99.90 0.00 0.00 0.00 0.10 11:33:46 AM all 100.00 0.00 0.00 0.00 0.00 11:33:47 AM all 100.00 0.00 0.00 0.00 0.00 11:33:48 AM all 99.99 0.00 0.00 0.00 0.01 11:33:49 AM all 99.00 0.00 0.99 0.99 0.01 11:33:50 AM all 100.00 0.00 0.00 0.00 0.00 11:33:51 AM all 99.00 0.00 0.00 0.00 1.00 11:33:52 AM all 100.00 0.00 0.00 0.00 0.00 11:33:53 AM all 100.00 0.00 0.00 0.00 0.00 11:33:54 AM all 99.99 0.00 0.00 0.00 0.01 Resolving the problem There is currently no fix available for this defect. WORKAROUNDS: a. Avoid installing RHEL 4 Update 5 or Update 6 or Update 7 on VOB servers as well as RHEL 5 or RHEL 5 with Update 1 or Update 2 b. Revert to RHEL 4 Update 4 where the problem has not been seen c. To temporarily workaround the issue, kill the db_server or vobrpc_server that is consuming CPU and continue to monitor the CPU utilization.
Notes: It may take a couple of days for the problem to re-appear. If another db_server or vobrpc_server process starts consuming 100% of a CPU after this is done, you will need to do the following: 1. Determine all the VOBs the affected host services (cleartool lsvob -host `hostname`) 2. Stop ClearCase (log in as root, run "/opt/rational/clearcase/etc/clearcase stop") 3. For each VOB listed in step 1, delete the "almd" file located in the "db" directory inside the directory listed in step 1. 4. Restart ClearCase (log in as root, run "/opt/rational/clearcase/etc/clearcase start") Page 168 of 341
ClearCase Environment – How do I 136. How do I – understand the NFS locking problems impact performance on a RedHat Enterprise Linux VOB server when using NAS storage for VOBs A defect with the Linux implementation of NFS was discovered.
Note: This only applies to clients with Red Hat Linux VOBs hosting VOB storage on a NAS device. Refer to technote 1315605 Clarification on the alert issued for RHEL 4 Update 5/6 and RHEL 5 and support for ClearCase VOB hosts with Network Attached VOB storage for the latest up to date information concerning this defect.
Diagnosing the problem If long lock monitoring is enabled on a VOB host (by setting -locks_held 20 in the db.conf file), then warning messages are printed in the db_server_log file and the vobrpc_log file stating that VOB locks were held for 30 seconds or an exact multiple of 30 seconds. Resolving the problem There is currently no solution available for this defect. WORKAROUND: If you have not already installed the affected Red Hat Linux updates, then take the following advisement into consideration: Avoid installing RHEL 4 Update 5 or Update 6 or Update 7 Avoid installing RHEL 5 or RHEL 5 with Update 1 or Update 2 137. How do I – understand the system Requirements for ClearCase 7.x Check the ClearCase System Requirements link for the latest system requirements. 138. How do I – understand about the available iFixes and FixPacks for ClearCase Family 7.x Check the Available iFixes and FixPacks for ClearCase Family 7.x link for the list of available iFIXES and FixPacks for ClearCase Family 7.x 139. How do I – understand the ClearCase 2003.06.00 and 7.0 release and patch mappings Check the ClearCase 2003.06.00 and 7.0 release and patch mappings link for the list of patch mappings. 140. How do I – understand the changes made to the behavior of the install_release Reset Selections option in ClearCase 7.0 The behavior change was made to provide a cleaner method of installing or de-installing a component in ClearCase on Unix or Linux. One of the benefits of this change is that you no longer have to look at the previous install log to see what components are currently installed since resetting your selections will provide that information. WHAT WAS CHANGED Selecting the "r" Reset selections option when running and install_release now resets the selections back to the list of currently installed components instead of clearing all the selections. ClearCase 2003.06 (Previous Functionality) In ClearCase version 2003.06.00 and earlier selecting the "r" Reset selections option results in the clearing of all the selections (those identified by the "*" character displayed by the selection number) resulting in no components being selected. ClearCase 7.0 or later (New Functionality) In ClearCase version 7.0 or later selecting the "r" Reset selections option reverts the selections (those identified by the "*" character displayed by the selection number) to the current installation list of components resulting in a list of selections that identifies which components are currently installed. Review IBM Rational ClearCase Installation and Upgrade Guide on the topic of Installing Rational ClearCase on individual hosts for more installation information.
EXAMPLES Example 1: ClearCase 2003.06 (Previous Functionality) In the following example the list of currently installed components includes: full clearcase and multisite, ccweb, and the ClearDDTS Integration with ClearCase and the user is attempting to de-install some components. One misleading assumption that a user may have when running through this example may have been that removing ClearDDTS from the list of selected components would have resulted in the removal of that component which is incorrect.
Please select for installation from the following components: Page 169 of 341
ClearCase Environment – How do I
Components preceded with a '*' are selected for installation.
1 : ClearCase Minimal Developer Installation 2 : ClearCase Server-only Installation 3 : ClearCase MultiSite Full Function Installation 4 : ClearCase Web Interface Server 5 : ClearQuest Integration with ClearCase 6 : ClearDDTS Integration with ClearCase 7 : ClearCase Mainframe Connectors 8 : ClearCase MultiSite Shipping Server-only Installation 9 : ClearCase Full Function Installation a : Select all f : Finish selection x : Toggle expanded descriptions r : Reset selections q : Quit
Selection number(s)>>
Next selection, '*' denotes a selected component
1 : ClearCase Minimal Developer Installation 2 : ClearCase Server-only Installation * 3 : ClearCase MultiSite Full Function Installation * 4 : ClearCase Web Interface Server 5 : ClearQuest Integration with ClearCase 6 : ClearDDTS Integration with ClearCase 7 : ClearCase Mainframe Connectors 8 : ClearCase MultiSite Shipping Server-only Installation * 9 : ClearCase Full Function Installation a : Select all f : Finish selection x : Toggle expanded descriptions r : Reset selections q : Quit
Selection number(s)>>
Selection number(s)>> r
(Note: This clears all of the previous selections so no components are selected. The user may not recall what is currently installed and available for de-install.)
1 : ClearCase Minimal Developer Installation 2 : ClearCase Server-only Installation 3 : ClearCase MultiSite Full Function Installation 4 : ClearCase Web Interface Server 5 : ClearQuest Integration with ClearCase 6 : ClearDDTS Integration with ClearCase 7 : ClearCase Mainframe Connectors 8 : ClearCase MultiSite Shipping Server-only Installation 9 : ClearCase Full Function Installation a : Select all f : Finish selection x : Toggle expanded descriptions r : Reset selections q : Quit
Selection number(s)>>
Next selection, '*' denotes a selected component
1 : ClearCase Minimal Developer Installation 2 : ClearCase Server-only Installation * 3 : ClearCase MultiSite Full Function Installation * 4 : ClearCase Web Interface Server Page 170 of 341
ClearCase Environment – How do I 5 : ClearQuest Integration with ClearCase 6 : ClearDDTS Integration with ClearCase 7 : ClearCase Mainframe Connectors 8 : ClearCase MultiSite Shipping Server-only Installation * 9 : ClearCase Full Function Installation a : Select all f : Finish selection x : Toggle expanded descriptions r : Reset selections q : Quit
Selection number(s)>> f
The following installation methods are available:
1. Local Install: Install occurs on the local host. 2. Remote Install: Install occurs on a single remote host. 3. Multiple Remote Installs: Install occurs on a set of remote hosts. 4. Local Deinstall: Deinstall occurs on the local host.
Type "Help" or "h" for expanded descriptions
Type "Quit" or "q" to exit the installation
Please select the installation method by number.
Method of installation>> 4
Method of installation>> 4 User specified:Install method:deinstall
User specified:Install model:deinstall
Next selection, '*' denotes a selected component
1 : ClearCase MultiSite Full Function Installation 2 : ClearCase Web Interface Server * 3 : ClearDDTS Integration with ClearCase 4 : ClearCase Full Function Installation a : Select all f : Finish selection x : Toggle expanded descriptions r : Reset selections q : Quit
Selection number(s)>> f *************************************************************************** >> Shutdown running ClearCase Product Family software *************************************************************************** Shutting down running ClearCase Product Family software. This will interfere with current users of the installed software.
Running:/opt/rational/clearcase/etc/clearcase stop Reading component installation scripts. *************************************************************************** >> Begin component customization removal *************************************************************************** *************************************************************************** >> Begin deinstalling files from /opt/rational *************************************************************************** ***************************************************************** >> Beginning deinstallation of component files for DDTs_CC_int from /opt/rational/clearcase Deleting file: /opt/rational/clearcase/ddts/bin/cleartrack Deleting file: /opt/rational/clearcase/ddts/bt_inform Deleting file: /opt/rational/clearcase/ddts/list_bugs Page 171 of 341
ClearCase Environment – How do I Deleting file: /opt/rational/clearcase/ddts/local_policy.pl Deleting file: /opt/rational/clearcase/ddts/policy_vars.sh Deleting file: /opt/rational/clearcase/ddts/summarize_request Deleting link: /opt/rational/clearcase/ddts/triggers Deleting file: /opt/rational/clearcase/ddts/validate_request Deleting file: /opt/rational/clearcase/sun5/lib/perl5/integ/ddts.pl ***************************************************************** >> Beginning deinstallation of component files for CC_crm_int from /opt/rational/clearcase Deleting file: /opt/rational/clearcase/bugtrack/bin/bug_task Deleting file: /opt/rational/clearcase/bugtrack/bin/bug_task.bat Deleting file: /opt/rational/clearcase/bugtrack/bin/find_fixes Deleting file: /opt/rational/clearcase/bugtrack/bin/find_fixes.bat Deleting file: /opt/rational/clearcase/bugtrack/bin/find_wip Deleting file: /opt/rational/clearcase/bugtrack/bin/find_wip.bat Deleting file: /opt/rational/clearcase/bugtrack/getpolicy Deleting file: /opt/rational/clearcase/bugtrack/install/vob_prep Deleting file: /opt/rational/clearcase/bugtrack/install/vob_prep.bat Deleting file: /opt/rational/clearcase/bugtrack/nt_install/_inst32i.ex_ Deleting file: /opt/rational/clearcase/bugtrack/nt_install/_isdel.exe Deleting file: /opt/rational/clearcase/bugtrack/nt_install/_setup.dll Deleting file: /opt/rational/clearcase/bugtrack/nt_install/_sys1.cab Deleting file: /opt/rational/clearcase/bugtrack/nt_install/_user1.cab Deleting file: /opt/rational/clearcase/bugtrack/nt_install/data.tag Deleting file: /opt/rational/clearcase/bugtrack/nt_install/data1.cab Deleting file: /opt/rational/clearcase/bugtrack/nt_install/lang.dat Deleting file: /opt/rational/clearcase/bugtrack/nt_install/language.dat Deleting file: /opt/rational/clearcase/bugtrack/nt_install/layout.bin Deleting file: /opt/rational/clearcase/bugtrack/nt_install/os.dat Deleting file: /opt/rational/clearcase/bugtrack/nt_install/setup.exe Deleting file: /opt/rational/clearcase/bugtrack/nt_install/setup.ini Deleting file: /opt/rational/clearcase/bugtrack/nt_install/setup.ins Deleting file: /opt/rational/clearcase/bugtrack/nt_install/setup.lid Deleting file: /opt/rational/clearcase/bugtrack/post_ci_trig Deleting file: /opt/rational/clearcase/bugtrack/post_ci_trig.bat Deleting file: /opt/rational/clearcase/bugtrack/post_co_trig Deleting file: /opt/rational/clearcase/bugtrack/post_co_trig.bat Deleting file: /opt/rational/clearcase/bugtrack/post_unco_trig Deleting file: /opt/rational/clearcase/bugtrack/post_unco_trig.bat Deleting file: /opt/rational/clearcase/bugtrack/pre_ci_trig Deleting file: /opt/rational/clearcase/bugtrack/pre_ci_trig.bat Deleting file: /opt/rational/clearcase/bugtrack/pre_co_trig Deleting file: /opt/rational/clearcase/bugtrack/pre_co_trig.bat Deleting file: /opt/rational/clearcase/bugtrack/pre_unco_trig Deleting file: /opt/rational/clearcase/bugtrack/pre_unco_trig.bat Deleting file: /opt/rational/clearcase/sun5/lib/perl5/integ/clrcase.pl Deleting file: /opt/rational/clearcase/sun5/lib/perl5/integ/clrtrack.pl Deleting file: /opt/rational/clearcase/sun5/lib/perl5/integ/ctime.pl Deleting file: /opt/rational/clearcase/sun5/lib/perl5/integ/open3.pl ***************************************************************** >> Beginning deinstallation of component files for INT_CC from /opt/rational/clearcase *************************************************************************** >> Recording clean deinstall of components *************************************************************************** Component DDTs_CC_int removed Component CC_crm_int removed Component INT_CC removed *************************************************************************** >> Starting ClearCase Product Family software *************************************************************************** #
FINAL: zorro Errors:0 Warnings:0
# ./install_release
[/opt/rational]: Page 172 of 341
ClearCase Environment – How do I
User specified:Deinstall from: /opt/rational
User specified:Release area pathname:/usr/ccase_rls/2003.06.00/sun5
1 : ClearCase Full Function Installation 2 : ClearCase MultiSite Full Function Installation 3 : ClearCase Web Interface Server a : Select all f : Finish selection x : Toggle expanded descriptions r : Reset selections q : Quit
Selection number(s)>> Example: ClearCase 7.x (New Functionality) Reverts back to the current installation list of components. This is how it looks and works in ClearCase version 7.x, which actually makes more sense and is less confusing. (The reset defaults back to the list of previously installed components and only de-selects any component selections the user may have changed).
Please select for installation from the following components:
Components preceded with a '*' are selected for installation.
* 1 : ClearCase Web Interface Server 2 : ClearCase Server-only Installation * 3 : ClearCase Full Function Installation * 4 : ClearCase MultiSite Admin Web * 5 : ClearQuest Integration with ClearCase 6 : ClearCase z/OS Extensions 7 : ClearDDTS Integration with ClearCase 8 : ClearCase MultiSite Shipping Server-only Installation * 9 : ClearCase MultiSite Full Function Installation 10 : ClearCase Minimal Developer Installation a : Select all f : Finish selection x : Toggle expanded descriptions r : Reset selections q : Quit
Selection number(s)>> 6
Next selection, '*' denotes a selected component
* 1 : ClearCase Web Interface Server 2 : ClearCase Server-only Installation * 3 : ClearCase Full Function Installation * 4 : ClearCase MultiSite Admin Web * 5 : ClearQuest Integration with ClearCase * 6 : ClearCase z/OS Extensions 7 : ClearDDTS Integration with ClearCase 8 : ClearCase MultiSite Shipping Server-only Installation * 9 : ClearCase MultiSite Full Function Installation 10 : ClearCase Minimal Developer Installation a : Select all f : Finish selection x : Toggle expanded descriptions r : Reset selections q : Quit
Selection number(s)>>
Selection number(s)>> r * 1 : ClearCase Web Interface Server 2 : ClearCase Server-only Installation * 3 : ClearCase Full Function Installation Page 173 of 341
ClearCase Environment – How do I * 4 : ClearCase MultiSite Admin Web * 5 : ClearQuest Integration with ClearCase 6 : ClearCase z/OS Extensions 7 : ClearDDTS Integration with ClearCase 8 : ClearCase MultiSite Shipping Server-only Installation * 9 : ClearCase MultiSite Full Function Installation 10 : ClearCase Minimal Developer Installation a : Select all f : Finish selection x : Toggle expanded descriptions r : Reset selections q : Quit
Selection number(s)>>
- To remove a component it is now clear in clearcase version 7 that one needs to chose the Local Deinstall to do so.
The following installation methods are available:
1. Local Install: Install occurs on the local host. 2. Remote Install: Install occurs on a single remote host. 3. Multiple Remote Installs: Install occurs on a set of remote hosts. 4. Local Deinstall: Deinstall occurs on the local host.
Type "Help" or "h" for expanded descriptions
Type "Quit" or "q" to exit the installation
Please select the installation method by number.
- Notice now the deinstall knows only or shows only the components that were previously installed and not the whole list like the install shows.
Next selection, '*' denotes a selected component
1 : ClearCase Web Interface Server 2 : ClearCase Full Function Installation * 3 : ClearCase MultiSite Admin Web 4 : ClearQuest Integration with ClearCase 5 : ClearCase MultiSite Full Function Installation a : Select all f : Finish selection x : Toggle expanded descriptions r : Reset selections q : Quit
Selection number(s)>> r 1 : ClearCase Web Interface Server 2 : ClearCase Full Function Installation 3 : ClearCase MultiSite Admin Web 4 : ClearQuest Integration with ClearCase 5 : ClearCase MultiSite Full Function Installation a : Select all f : Finish selection x : Toggle expanded descriptions r : Reset selections q : Quit
Selection number(s)>>
Method of installation>>
Page 174 of 341
ClearCase Environment – How do I 141. How do I – understand the issue when only root can run cleartool commands issue Why do all users, except for root user on UNIX® or Linux®, receive the error, Permission denied, when running IBM® Rational® ClearCase® cleartool commands.
Cause The permissions on the files in the ClearCase bin directory are too restrictive: 2002.05 (and previous): /usr/atria/bin 2003.06 (and later): /opt/rational/clearcase/bin In one case, the execution of the ls -l command in the bin directory showed the permissions as 550. Note: This can happen if root's umask was set too strictly (for example 027) when installing ClearCase for the first time. Cause 2 The permissions on the files in the release area are incorrect (too restrictive).
Example: # pwd /opt/software/2003.06.00/sun5/clearcase/sun5/bin
# ls -al total 84818 dr-xr-x--- 2 root other 1536 May 3 2006 . dr-xr-x--- 8 root other 512 Apr 25 2003 .. -r-xr-x--- 1 root other 562624 Mar 24 2003 CCDeveloper -r-xr-x--- 1 root other 186368 Oct 16 1996 Gmake -r-xr-x--- 1 root other 10972 Apr 24 2003 Perl -r-xr-x--- 1 root other 760748 Oct 21 2002 Perl5.002 -r-xr-x--- 1 root other 535484 Mar 24 2003 ccf4j -r-xr-x--- 1 root other 26036 Mar 24 2003 ccfdevinstall -r-xr-x--- 1 root other 152319 Dec 13 2005 ccintf4j.jar ...
This release area seems to have been created with umask 027, and thus the permissions are incorrect (they should be 555, not 550).
Solution 1 Set umask to 02 or 022 and re-install ClearCase with ./install_release -force option to repair the permissions for all ClearCase directories. Note: The file mode creation mask (umask) sets the file mode creation mask of the invoking process to the given mode. Review your operating system manuals for information on how to set umask on your host (man umask).
Solution 2 If ./install_release -force does not seem to resolve the issue with an acceptable umask (you will see many Unchanged entries in the install log), or if the proper umask was used for the initial installation but you see the same symptoms, check the release area itself for proper permissions.
The release area will instead need to be recreated with an acceptable umask, such as 002 or 022. 142. How do I – understand about ClearCase and allow_non_root_installation Are there any differences with an IBM® Rational® ClearCase® client installation on UNIX® or Linux® if the install is performed by a normal user with the allow_non_root_installation flag enabled. There is no difference in ClearCase behavior if installed by root or by non root. The installation using non root will complete as expected if root was used. 143. How do I – do a silent Install and Uninstall of ClearCase on UNIX To install or uninstall ClearCase on UNIX or Linux with no user intervention, follow these steps: 1. Log in as root
2. cd into the release area to the install subdirectory
Page 175 of 341
ClearCase Environment – How do I 3. Run the following command:
./install_release -echo_cmd_only -force This will run through all the questions needed to complete an installation, but will stop before any action is taken. The -force option is added because if you are trying this on a system that already has ClearCase installed, it's likely that a regular installation will detect that everything is already up to date, and thus fail to ask you anything.
Note: Defect APAR PK32306 was submitted to address a known issue where running the command in step #3 actually performs the uninstall as opposed to simply providing the output to the questions answered as expected. Also, the deinstall fails on Solaris® and Linux but completes on other platforms. This defect has been resolved in the following update clearcase_p2003.06.00-45.
When the script stops, it will display the complete installation command with full switches that reflects the options that the user selected.
For example: ./install_release -to
Note: The output from the ./install_release -echo_cmd_only -force command cannot simply be "cut and paste" from the screen as the output is broken up into lines so that it is displayed on the screen properly. You will need to paste the output into a file and join those lines. One way to do this is to use the vi editor. Starting at the first character in the first line, use the "$" to find each end of line and the execute a "J" to join the current line with a next line. Continue this process until the entire file is one line. Then cut the command line from inside vi and paste it to the command line on the screen. Depending on your shell and or editor, you may have to paste line by line until you have one continuous string to execute.
You can then run this command to install the product, but first, you need to add the -no_query switch to the beginning of the command line.
Example: ./install_release -no_query ..... If you do not add this switch, you will be asked at least 2 questions to confirm the list of selected products and to confirm installation of the product.
Note: The script will first attempt to shutdown ClearCase just like any other installation. If the shutdown fails, it may not be able to complete the installation, thus user intervention will be required.
Aside from that, running this command with the addition of the -no_query option will run through a complete installation of ClearCase on UNIX and Linux with no user intervention. 144. How do I - remove the ClearCase patch subdirectories Is it okay to remove individual patch subdirectories from the release area after they are applied to save disk space?
For example, the following patches have been applied to a ClearCase release area on Solaris:
%>ls /usr/ccase_rls/2003.06.00/sun5/clearcase/patches clearcase_p2003.06.00-19 clearcase_p2003.06.00-38 multisite_p2003.06.00-14 clearcase_p2003.06.00-37 clearcase_p2003.06.00-43 multisite_p2003.06.00-16
Is it acceptable to remove the clearcase_p2003.06.00-# and multisite_p2003.06.00-# directories that contain the patches? Yes. After the patches are successfully applied, it is okay to remove these subdirectories. 145. How do I – remove ClearCase patches from a release area There is currently no method to remove a single patch (or patches) from a ClearCase release area. The only option is to remove and recreate the release area without the patch.
Page 176 of 341
ClearCase Environment – How do I 146. How do I – resolve the multitool -ver and cleartool –ver not accurately reflection the patched state of a system The output of IBM® Rational® ClearCase® cleartool -ver and ClearCase MultiSite® multitool -ver may not be an accurate reflection of the patches applied on a target system for Microsoft® Windows®, UNIX® or Linux®.
There are 2 places that ClearCase keeps version information. 1. Local Host: Windows: C:\Program Files\Rational\ClearCase\install UNIX/Linux: /opt/rational/clearcase/install/version 2. Release Area: Windows:
Since each file is consulted separately, the results can differ if the files are edited or if for some reason they did not update properly in the patching process.
Solution Assuming that the machine has been reinstalled and still does not show the correct version, it is safe to copy the version files (version and ms_version) from the release area directory to the local install directory. 147. How do I - manually uninstall ClearCase on Linux For ALL ClearCase versions: ======1. Log in as root 2. Stop ClearCase services (/opt/rational/clearcase/etc/clearcase stop) -- VERY IMPORTANT! 3. Backup the /var/adm/rational/clearcase directory 4. Make sure that any customizations (such as trigger scripts or a modified atria_start) made in the /opt/rational/clearcase path are backed up 5. Remove the /view directory (ClearCase services MUST be stopped before this in done!!)
ClearCase 2003.06.00 and later ======6. Rename (or remove) the ClearCase files in the start-up directories Red Hat mv /etc/init.d/clearcase /etc/init.d/old.clearcase rm /etc/rc.d/rc0.d/K08clearcase rm /etc/rc.d/rc1.d/K08clearcase rm /etc/rc.d/rc2.d/K08clearcase rm /etc/rc.d/rc3.d/S77clearcase rm /etc/rc.d/rc4.d/K08clearcase rm /etc/rc.d/rc5.d/S77clearcase rm /etc/rc.d/rc6.d/K08clearcase SUSE mv /etc/init.d/clearcase /etc/init.d/old.clearcase rm /etc/rc3.d/K10clearcase rm /etc/rc3.d/S12clearcase rm /etc/rc5.d/K10clearcase rm /etc/rc5.d/S12clearcase 7. Remove the install directory (by default stored in /opt/rational/clearcase)
cd /opt/rational/ rm -rf clearcase 8. Remove the adm directory (by default stored in /var/adm/rational/clearcase)
cd /var/adm/rational/ rm -rf clearcase 9. Reboot the server. Page 177 of 341
ClearCase Environment – How do I ClearCase is now completely de-installed from the system. 148. How do I - manually uninstall ClearCase on Solaris For ALL ClearCase versions: ======1. Log in as root 2. Stop ClearCase services (/opt/rational/clearcase/etc/clearcase stop) -- VERY IMPORTANT! 3. Backup the /var/adm/rational/clearcase directory 4. Make sure that any customizations (such as trigger scripts or a modified atria_start) made in the /opt/rational/clearcase path are backed up 5. Remove the /view directory (ClearCase services MUST be stopped before this in done!!) ClearCase 2003.06.00 and later ======6. Rename (or remove) the ClearCase files in the start-up directories mv /etc/init.d/clearcase /etc/init.d/old.clearcase mv /etc/rc2.d/S77clearcase /etc/rc2.d/old.S77clearcase mv /etc/rc0.d/K35clearcase /etc/rc0.d/old.K35clearcase 7. Remove the install directory (by default stored in /opt/rational/clearcase) cd /opt/rational/ rm -rf clearcase
8. Remove the adm directory (by default stored in /var/adm/rational/clearcase) cd /var/adm/rational/ rm -rf clearcase
9. Reboot the server.
ClearCase 4.2 through 2002.05.00: ======
6. Rename (or remove) the ClearCase files in the start-up directories mv /etc/init.d/atria /etc/init.d/old.atria mv /etc/rc2.d/S77atria /etc/rc2.d/old.S77atria mv /etc/rc0.d/K35atria /etc/rc0.d/old.K35atria 7. Remove the install directory (by default stored in /usr/atria) cd /usr rm -rf atria
8. Remove the adm directory (by default stored in /var/adm/atria) cd /var/adm rm -rf atria
9. Reboot the server.
ClearCase is now completely de-installed from the system. 149. How do I - Manually uninstall ClearCase on HP-UX For ALL ClearCase versions: ======1. Log in as root 2. Stop ClearCase services (/opt/rational/clearcase/etc/clearcase stop) -- VERY IMPORTANT! 3. Remove the MVFS (if applicable): swremove -x auto_kernel_build=true CCASE-MVFS 4. Backup the /var/adm/rational/clearcase directory 5. Make sure that any customizations (such as trigger scripts or a modified atria_start) made in the /opt/rational/clearcase path are backed up 6. Remove the /view directory (ClearCase services MUST be stopped before this in done!!) ClearCase 2003.06.00 and later ======7. Rename (or remove) the ClearCase files in the start-up directories mv /sbin/init.d/clearcase /sbin/init.d/old.clearcase mv /sbin/rc0.d/K08clearcase /sbin/rc0.d/old.K08clearcase mv /sbin/rc1.d/K08clearcase /sbin/rc1.d/old.K08clearcase Page 178 of 341
ClearCase Environment – How do I mv /sbin/rc2.d/K08clearcase /sbin/rc2.d/old.K08clearcase mv /sbin/rc3.d/S77clearcase /sbin/rc3.d/old.S77clearcase mv /sbin/rc4.d/K08clearcase /sbin/rc4.d/old.K08clearcase mv /sbin/rc5.d/S77clearcase /sbin/rc5.d/old.S77clearcase mv /sbin/rc6.d/K08clearcase /sbin/rc6.d/old.K08clearcase 8. Remove the install directory (by default stored in /opt/rational/clearcase) cd /opt/rational/ rm -rf clearcase
9. Remove the adm directory (by default stored in /var/adm/rational/clearcase) cd /var/adm/rational/ rm -rf clearcase
10. Reboot the server.
ClearCase 4.2 through 2002.05.00: ======
7. Rename (or remove) the ClearCase files in the start-up directories mv /sbin/init.d/atria /sbin/init.d/old.atria mv /sbin/rc1.d/S77atria /sbin/rc2.d/old.K007atria mv /sbin/rc3.d/K35atria /sbin/rc0.d/old.s750atria 8. Remove the install directory (by default stored in /usr/atria) cd /usr rm -rf atria
9. Remove the adm directory (by default stored in /var/adm/atria) cd /var/adm rm -rf atria
10. Reboot the server.
ClearCase is now completely de-installed from the system. 150. How do I - manually uninstall ClearCase on Windows This procedure outlines the necessary steps to completely remove ClearCase from the Windows operating system: 1. Deinstall ClearCase using the Add or Remove Programs. Click Start > (Settings) > Control Panel Double-click Add or Remove Programs Select Rational ClearCase from the list of programs and click OK. Choose Remove the Existing Installation option, click OK, and follow the instructions in the subsequent dialogues. Note: It is not necessary to have the IBM Rational ClearCase Installation CD to uninstall the software from your network, if you have installed from a release area. You will need the CD if you have installed from a CD.
Note: If running 2002.05.00, you may need to use the uninstal.exe application. Review technote 1146783 for more information.
Note: If running Windows 2003 and attempting to uninstall 2002.05 (which is not supported), the uninstall will fail. Skip to step 2. The services normally removed by the usual uninstall will be removed in step 3. 2. Remove the ClearCase Release Area and the installation directory tree (by default C:\Program Files\Rational\ClearCase).
Note: If other Rational products are installed, be sure you only remove the ClearCase directory. 3. After completing steps #1 and #2, ensure that the following registry keys have been removed (if you wish to be thorough).
Note: This solution contains information about modifying the system registry. Before making any modifications to the Microsoft Windows Registry Editor, it is strongly recommended that you make a Page 179 of 341
ClearCase Environment – How do I backup of the existing registry. For more information describing how to back up the registry, refer to the Microsoft Knowledge Base article 256986. m. Registry Settings System Keys:
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Albd]
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\cccredmgr]
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog\ Application\ClearCase]
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog\ System\Mvfs]
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\LockMgr]
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Mvfs]
Note: The above keys may also be found in the following locations as well. [HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001] [HKEY_LOCAL_MACHINE\SYSTEM\ControlSet002] [HKEY_LOCAL_MACHINE\SYSTEM\ControlSet003]
Note: The following items under [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services should not be removed if other Rational Products are installed. IBMHTTPServer6.0 - (ClearCase 7.0 only) Rational_Web_Platform - (ClearCase 2003.06.00 only) Rational_Web_Platform_Tomcat - (ClearCase 2003.06.00 only) Rational_Web_Platform_Tomcat_ReqWeb - (ClearCase 2003.06.00 only)
Software Keys: [HKEY_LOCAL_MACHINE\SOFTWARE\Atria\ClearCase]
[HKEY_LOCAL_MACHINE\SOFTWARE\Rational Software\ClearCase]
User Keys: HKEY_CURRENT_USER\Software\Atria]
Note: If the ClearCase program is not removed from the Add or Remove Programs list in the Control Panel, the following registry keys will clear this item:
Verify that these keys have been removed by the deinstallation and if not remove the Additional Registry Keys [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\ Uninstall\{681411BD-5AD8-4DA5-BBEE-EF20E3628D33}]
[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Installer\Products\ DB1141868DA55AD4BBEEFE023E26D833]
4. Restart the host to complete the procedure. 151. How do I – conduct a silent install of a Rational Software Development Platform desktop products Prior to following the steps below, make sure the silent install of the IBM® Installation Manager has completed.
Once the Installation Manager is installed you need to point to the RSA directory where the disk directories are located. 1. Launch the Installation Manager (Start -> Programs -> IBM Installation Manager -> IBM Installation Manager) 2. Go to File -> Menu and select Preferences 3. Select the Repositories 4. Select Add Repository Page 180 of 341
ClearCase Environment – How do I 5. Browse to the directory where the repository.config file is located
Create a response file and make sure c:\rel_area directory exists 1. Go to a command prompt (Start -> Run, then type cmd) 2. CD to C:\Program Files\IBM\Installation Manager\Eclipse 3. Type launcher.bat -record C:\rel_area\response.xml Note: If you want a log file you will need to add a -log C:\rel_area\record_log.xml 4. Follow the install screens 5. Select Install 6. Click Cancel 7. Click Finish 8. Close Installation Manager Note: response.xml will not be created until Installation Manager is closed.
Running the response file 1. Go to a command prompt (Start -> Run, then type cmd) 2. CD to C:\Program Files\IBM\Installation Manager\Eclipse. Type launcher.bat -silent -input C:\rel_area\response.xml 152. How do I - use Microsoft SMS to deploy ClearCase 7.x installations A Whitepaper titled Deploying Rational ClearCase using Microsoft SMS has been released by IBM Rational to provide specific instructions on how to deploy Rational ClearCase 7.x using Microsoft Systems Management Service (SMS). 153. How do I – deploy a customized Enterprise Installation of IBM Rational ClearCase using CCRC A Whitepaper titled Customized Enterprise Installation of IBM Rational ClearCase using CCRC has been released to provide specific instructions on how to deploy the ClearCase Remote Client in an enterprise environment. 154. How do I – understand the feature differences between ClearCase and ClearCase LT
Page 181 of 341
ClearCase Environment – How do I
GLOSSARY: Definition of features not included in ClearCase LT. Dynamic Views: The MVFS is not included with ClearCase LT; hence all related features associated with the MVFS are not included. Detailed build auditing: No configuration records are created in ClearCase LT. Binary Sharing: Only snapshot views are used, thus view sharing is not possible with ClearCase LT. Build dependency automation: All related libraries that integrate with the MVFS to create derived objects are removed along with all associated cleartool subcommands and GUIs. Distributed Builds (UNIX, z/OS): Clearmake build tool not included in ClearCase LT. Distributed servers: Only one ClearCase LT server is used to host VOBs and Views for its clients. All processes run on the server - no distributed load. Unable to use Pool Mappings (host VOB storage pools on different servers). Repository/database replication and synchronization: MultiSite add-on can not be integrated with ClearCase LT.
Additional differences: Limited platform choices for ClearCase LT. Only CCFS can be used as the interop solution between Windows® and UNIX®. Only a single ClearCase region may be implemented for Windows and UNIX.
Guidelines for CCLT and ClearCase interoperation: ClearCase and ClearCase LT cannot be installed on the same host.
Page 182 of 341
ClearCase Environment – How do I ClearCase cannot be installed over ClearCase LT. You must uninstall ClearCase LT completely and then install ClearCase; however, ClearCase LT can be upgraded to ClearCase following the upgrade instructions in the Installation Guide. A ClearCase LT client cannot access a ClearCase server
Note: A ClearCase LT client can access an upgraded ClearCase LT server (to ClearCase) as long as it can acquire a ClearCase license from that server. If the ClearCase server was not upgraded from CCLT, the CCLT client cannot access the server. Please note that the CCLT client cannot take advantage of full ClearCase features until the client has been upgraded. A ClearCase client cannot access a ClearCase LT server 155. How do I – understand the Supplement to the ClearCase 7.0.0 Administrator's Guide about configuring ClearCase on a ClearQuest server Can the IBM® Rational® ClearCase® MVFS be installed as a client on a Rational ClearQuest® server in order to view change sets?
In the IBM Rational ClearCase Administrator's Guide (GI11-6362-00) regarding step 1 for Installing and configuring Rational ClearCase and Rational ClearQuest on the Rational ClearQuest server on page 305, the guide states the following:
Install Rational ClearCase on the Rational ClearQuest server with the Client and Server option. During installation of Rational ClearCase, select the MVFS feature. The MVFS feature enables the Rational ClearQuest server to display change sets.
Can installing only client MVFS feature be enabled?
Answer The only requirement is that MVFS be enabled so that a dynamic view can be created and accessed on the server machine; therefore, it is possible to install an MVFS enabled client.
Note: It is recommended to have a "server" install from a troubleshooting perspective, so local VOBs could be created for troubleshooting any problems that may arise. 156. How do I – understand why the installation of ClearCase 7.0.0.1_IFIX04 and 7.0.1.0_IFIX01 on RHEL 5 do not update the updated.config file properly RHEL 5 is supported on ClearCase as of version 7.0.1 (7.0.1.0-RATL-RCC-IFIX01) and 7.0.0.1 (7.0.0.1- RATL-RCC-IFIX04).
There are no errors or warnings during the installation.
After installing ClearCase and creating views on the system, the updatedb command will recursively run through your hard drive using your view paths (/view/
Cause Previous releases of Red Hat use slocate as a file locator and database catalog tool. In RHEL 5 this was changed to mlocate. The config file, previously located /etc/cron.daily/slocate.cron, is not found during installation, thus the appropriate sections in the file are not updated to avoid cataloging filesystems (such as the MVFS).
Defect RATLC01037787 has been opened to investigate this issue. WORKAROUND:
After the installation you need to manually update the /etc/updatedb.conf file as follows: Add mvfs and nfs to the PRUNEFS variable Add /view and /vobs to the PRUNEPATHS variable Example: PRUNEFS = "auto afs iso9660 sfs udf nfs mvfs"
PRUNEPATHS = "/afs /media /net /sfs /tmp /udev /var/spool/cups /var/spool/squid /var/tmp /view /vobs"
Page 183 of 341
ClearCase Environment – How do I Note: If you experience this problem and your disk space fills up (or close to it), you will also need to remove the previously built mlocate databases to reclaim space. These databases area located in /var/lib/mlocate. 157. How do I – understand the “Address already in use” error There may be another application that is using port 371 (TCP/371 and UDP/371) which is reserved for ClearCase thus causing a conflict.
On Windows the ALBD service is terminating immediately following startup and the following errors are reported in the Windows® Application log:
--- Albd(9640): Error: Unable to setup "udp" RPC service. Albd(9640): Error: bind: [WINSOCK] Address already in use --- as well as --- albd_server.exe: Error: bind: WINSOCK address already in use. --- 1. Shut down ClearCase 2. Open a command prompt (Click Start > Run type cmd) and run
netstat -a | find "371"
Note: Any application listening on port 371 will cause problems for ClearCase. One application that has been found listening on this port is BackWeb (http://www.backweb.com). 3. Shut down any program(s) found using port 371 from the Windows Task Manager and ClearCase will be able to operate again. On UNIX and Linux port 371 in the /etc/services or NIS services map may have another application using port 371. You may see errors in the albd_log as such: albd_server Error: bind: Address already in use albd_server Error: Unable to setup "udp" RPC service 1. Check /etc/services to ensure no other application is using port 371.
Note: If the /etc/services file is managed by NIS, run the following command:
ypcat services | grep 371
Correct output should look similar to the following:
albd 371/udp # Atria albd_server albd 371/tcp # Atria albd_server
Kill any program(s) found using port 371 and ClearCase will be able to operate again. 158. How do I – understand about the Stand Alone configuration for Rational ClearCase How can I configure IBM® Rational® ClearCase® in a stand alone environment on Microsoft® Windows® 2000, XP and Server™ 2003? LAN Configuration A stand alone configuration has a single host that functions as both the server and client. However, Rational ClearCase needs local area network (LAN) functionality to work correctly. The network communications that ClearCase requires entails remote procedure calls (RPC) between the client and server. In a stand alone environment there is no direct server connectivity from the client to achieve LAN operations. Use of the loopback adapter or a local host lookup configuration on the host machine is required. The TCP and UDP packets for ClearCase LAN activity are sent out to a specific host that typically use a host name. If the packets are unable to resolve the host name or reach the host's IP address, then the communications attempt will fail, and subsequently the application will fail. For reference information on how to successfully set the loopback adapter correctly, follow technote 1188184. For details on configuring the local host lookup, refer to the information available on the Microsoft Web Site on TCP/IP Fundamentals for Microsoft Windows
Page 184 of 341
ClearCase Environment – How do I
Note: Either method will ensure that outward bound packets resolve to a local address, which will enable the local ClearCase services to function properly.
ClearCase group, server process account and server process Note: If you have not done so already, then you should first read and understand the details covered in IBM Rational ClearCase Administrator's Guide. If you do not have a hard copy, the document is available in soft copy, cc_admin.pdf, on any host with Rational ClearCase installed, and is located by default in C:\Program Files\Rational\ClearCase\doc\books. In Microsoft Windows, the default base requirement for a ClearCase server to function in a stand alone environment is the local ClearCase Administrators group ("clearcase" by default) along with the albd server process user account ("clearcase_albd" by default). The addition of this group along with the corresponding clearcase_albd user will allow the system to function as a stand-alone ClearCase server. The ClearCase server installation requires the following: A ClearCase group, by default clearcase A ClearCase server process account, by default clearcase_albd A ClearCase server process, Atria Location Broker Daemon (ALBD)
ClearCase Group and ClearCase Server Process Account The ClearCase group and server process account can be created during the Rational ClearCase installation since the account used to complete the install must have local administrator rights. However, you can create these manually, just be sure to make the server process account a member of the ClearCase group. The ClearCase group is a special group recognized by the application for privileged operations. It is set in the Windows registry by the ClearCaseGroupName registry key. The server process account is used to run the ClearCase server process, and must be a member of the ClearCase group for it to be a privileged user, refer to technote 1146253 for more details. For more information on creating the group and account manually refer to IBM Rational ClearCase Administrator's Guide > ClearCase and Windows Domains > Domain User and Group Accounts > Defining Required Domain Accounts Manually ClearCase Server Process The server process, ALBD, runs as the ClearCase server process account and is denoted as albd_server.exe in the Windows process list from Task manager. This process handles a variety of tasks on hosts configured to support local VOBs and views: Starting and stopping other ClearCase services as needed Setting up network communications between ClearCase clients and servers Responding to requests for registry information on a ClearCase registry server host Responding to requests for licenses on a ClearCase license server host
For more information, refer to IBM Rational ClearCase Administrator's Guide > ClearCase Server Processes > albd_server.
Restrictions Rational ClearCase is a team product, but the stand alone configuration limits its capabilities to a single host. This configuration is geared toward isolated testing, isolated builds, new ClearCase version testing, or other like uses that do not require the sharing of ClearCase resources. The stand alone system will be unable to contact other ClearCase servers, and correspondingly, will be unable to act as a ClearCase server to outside clients. For more information, refer to IBM Rational ClearCase Administrator's Guide > ClearCase and Windows Domains > Domain Configurations Compatible with ClearCase > ClearCase on Nondomain Hosts Note: If it is necessary for this host to be used in a ClearCase network or domain environment, then it is advised to uninstall Rational ClearCase first, and remove the local ClearCase group and server process account. Then proceed with logging into the domain from this host and install Rational ClearCase accordingly, referring to the domain's ClearCase group and server process account. Related information Network Environments for ClearCase About the CLEARCASE_PRIMARY_GROUP variable About ClearCase permissions on Windows Rational ClearCase 7.0 installation on Windows Troubleshooting ALBD startup failures on Windows
159. How do I – understand about ClearCase File Server (CCFS)
ClearCase File Server (CCFS) is a proprietary file server from IBM Rational Software. Page 185 of 341
ClearCase Environment – How do I The ClearCase File Server is a TCP/IP-based mechanism for file transfers between UNIX® and Linux® VOB servers and clients running UNIX, Linux and or Microsoft® Windows®. CCFS works with snapshot views only. Snapshot Views use CCFS A ClearCase client running on Windows with CCFS enabled will not require a third-party NFS client-based or SMB server-based product in order to access UNIX/Linux VOBs; see technote 1128707 for more details.
Note: If you require dynamic view access from Windows to UNIX/Linux, you will require an NFS or SMB interop solution; see technote 1136951 (2003.06.00) or technote 1239315 (7.x) for the list of supported Network Access and Storage Platforms.
A UNIX/Linux client using snapshot views accessing a Windows VOB will only use CCFS.
Note: Dynamic view access from UNIX/Linux clients to Windows hosted VOBs is not supported at this time.
A UNIX/Linux client accessing a UNIX/Linux VOB can use CCFS if the ClearCase server and client environment are ClearCase LT (CCLT) only. CCLT is designed to work in this configuration, since NFS is not supported with CCLT.
Note: However, full ClearCase (non-CCLT) was designed to use NFS. Thus, full ClearCase cannot be configured to use only CCFS in an all UNIX/Linux environment, as NFS is a requirement.
Windows 95-98 ClearCase clients running Windows 95 or Windows 98 use CCFS as their sole transfer mechanism when accessing UNIX/Linux VOBs. Because Windows 95 and Windows 98 computers cannot use dynamic views, or run view servers, you must have at least one Windows NT/2000/XP/2003 computer that will run the view server process. This computer will also contain the view storage directory for snapshot views created on Windows 95 and Windows 98 computers.
TCP/IP Connection When CCFS is enabled, file transfers between Windows clients and UNIX/Linux VOB servers in ClearCase client applications and snapshot view operations (such as check out, check in, snapshot view creation, and update) take place over a standard TCP/IP connection.
File transfers between Windows view servers and UNIX/Linux VOB servers also use this TCP/IP connection. 160. How do I – understand how the ClearCase File Service (CCFS) can be disabled on an IBM® Rational® ClearCase® VOB server?
To disable the CCFS server ccfs_server:
Edit the file /var/adm/atria/config/ccfs.conf the following line (all lowercase): ccfsserver=no
The default setting is unspecified, which means the ccfs_server is enabled, or you may have the following line (all lowercase): ccfsserver=yes
NOTE: While the ccfs_server is technically “disabled” by specifying [ccfsserver=no], the server process WILL be running on the VOB server to answer client requests to use the service, if for instance the Windows client has the “Use CCFS to access UNIX VOBs” checked. This is because the client has CCFS enabled, and there needs to be a response from the server side. The denial will be sent by the ccfs_server, and then the client will try alternate paths.
Thus, there will always be a ccfs_server IF a Windows client is attempting access. The point is that there will be no transfers across CCFS if the configuration is correct within the ccfs.conf file. Page 186 of 341
ClearCase Environment – How do I
You can verify the setting on a TEST VOB by running a debugged ccfs_server for the test VOB in question as follows:
/usr/atria/etc/ccfs_server -d 4
Then, check the ccfs_server logs, after trying to access and create elements from a Windows client with CCFS enabled, where it should show the contact but NO transfers. Problem(Abstract)
Firewalls 161. How do I – understand about Firewalls and ClearCase Currently, Rational ClearCase processes are not supported to operate through a firewall. ClearCase, in the absence of MultiSite, does not relay any traffic across firewalls unless you: Attempt to use ClearCase across a WAN OR Have a desktop firewall in use OR Internal LAN firewall
Note: IBM Rational ClearCase is known to operate correctly through firewalls in internal networks if the following conditions are met: Port 371 (UDP and TCP) is passed through to any/all ClearCase server hosts from the allowed hosts. All ports over 1024 are open from the allowed ClearCase client hosts to needed ClearCase server hosts. If problems caused by firewall configuration issues occur in your ClearCase environment, resolution of those issues is beyond the scope of ClearCase support. Rational support can assist in figuring out what the specific firewall problem is (connections being aggressively closed by the firewall, packets being dropped, etc....), however it is your responsibility to work with your firewall vendor to determine how to resolve the issues.
ClearCase Port Assignment Rational ClearCase communicates using different server processes through indiscriminate ports. ClearCase specifically uses port 371 for the albd_server process; however, the ports to which the child processes spawned from the albd service are assigned dynamically. It is the nature of the port assignment that makes firewall access with ClearCase impossible. Note: Port-based firewalls within a development environment will cause problems for the ClearCase or ClearCase MultiSite environment.
Exceptions 1. The ClearCase MultiSite Shipping Server, which can work through a firewall because you can configure the shipping server host to use specific ports to send packets through the firewall using the CLEARCASE_MIN_PORT & CLEARCASE_MAX_PORT variables. Review technote 1207525 for more information about these variables. 2. When using Network Address Translators (NAT), review technote 1167693 for information on the supported configuration for ClearCase clients using NAT hardware. 3. If you run the Rational ClearCase Web client (CCWeb) on a host running Windows XP with SP2, you must add ccweb.exe to the firewall’s exception list.
Note: In some cases, when ccweb is not on the exception list, Windows firewall displays an empty error dialog.
Known Problems
Review the following technotes as examples of the kinds of results you may encounter if desktop firewall software is in use on a ClearCase host: 1122554 - Unable to allocate port in specified range 1128548 - albd_rgy_get_entry call failed: RPC: Timed out 1121619 - Overlapped I/O operations in progress Microsoft Windows Vista
WORKAROUNDS:
Page 187 of 341
ClearCase Environment – How do I 1. The only workaround to the WAN issue is to use ClearCase Web Interface (CCWeb) or ClearCase Remote Client (CCRC) where the Web Server is configured within the firewall. 2. You can configure your personal firewall to work with ClearCase by allowing all Rational ClearCase processes unimpeded access through the personal firewall.
Note: You can not configure a corporate firewall to work with ClearCase.
For example, Windows XP and later comes standard with a personal firewall system on the host operating system. You can enable the firewall and configure ClearCase to work around it as described below: Windows XP Firewall Refer to the IBM Rational ClearCase Platforms Guide under the topic of Issues when using Windows Firewall which describes a method to register all ClearCase executables with the Windows Personal Firewall.
The ClearCase 2003.06.16 (Service Release 6) Release Notes contains a section in Chapter 2 - Restriction and Guidelines for using ClearCase titled Microsoft Windows XP Service Pack 2 (SP2) security measures that describes a method to register all ClearCase executables with the Windows Personal Firewall.
Note: Review technote 1147107 on how to check if the personal firewall is enabled on RedHat® Linux®. Microsoft® Windows® Vista™ Firewall
The firewall that comes with Windows Vista can affect Rational ClearCase in that it will block the albd_server service from communicating with remote servers.
The firewall can be disabled or it can be configured for specific rules for certain programs.
Please refer to the following article on how to configure the new Vista firewall, cg0106. Upgrading and compatibility issues 162. How do I - update an IBM Rational 7.1.x install through IBM Installation Manager Individual iFix patches and Fix Packs are released for various Rational 7.1.x products. Fix Packs and iFixes are updates that contain only defect fixes and no (or very little) enhancements. Below are the installation steps to apply the iFix or Fix Pack to your Rational product (or products). Note: The installation manager may display a message such as the following indicating that a new version is available. If your machine doesn't have access to the ibm.com website, and you click Yes to update, you will receive a message that it can't find Installation Manager 1.3.0. At this point you can download the IBM Installation Manager from the link referenced below and create a local repository. Refer to IBM Installation Manager, Version 1.3 for installation instructions.
1. Add the new repository to Install Manager
Page 188 of 341
ClearCase Environment – How do I a. Navigate to File -> Preferences
b. Select the Repository Tab and Click “Add Repository”
Page 189 of 341
ClearCase Environment – How do I c. Add the Repository location
d. Select OK and return to the Installation Manager main menu
Page 190 of 341
ClearCase Environment – How do I 2. Select Update to start the Update for all products installed using the Installation Manager
3. Select Next to scan all products for updates
Page 191 of 341
ClearCase Environment – How do I
4. Select the Products that have updates available to apply them.
Page 192 of 341
ClearCase Environment – How do I 5. Rectify any install problems that may be referenced.
6. Select Next to agree to the licensing terms.
7. Select Update to begin the update process.
Page 193 of 341
ClearCase Environment – How do I
8. Reboot the machine, if necessary.
Page 194 of 341
ClearCase Environment – How do I 163. How do I – understand ClearCase Compatibility Across Releases Even the simplest Rational ClearCase operation invokes a communications chain that can involve several components.
For example, the act of checking out a file element involves a client program (running on the developer's workstation), which executes in a particular view (located on that workstation or elsewhere) and uses a particular VOB (typically located on a dedicated VOB server host).
If all components in this operation are running the same version of Rational ClearCase, compatibility is guaranteed. Refer to document 7008656 V.R.M.F. Maintenance Stream Delivery Vehicle terminology explanation for further details about 7.x versioning terminology.
This table provides a list of client, view server, VOB server combinations that are expected to work and those that are expected to fail.
Client View Server VOB Server Supported Configuration for View Interaction ? 2003.06.xx 2003.06.xx 2003.06.xx Yes 2003.06.xx 7.0.x 2003.06.xx No 2003.06.xx 7.1 2003.06.xx No 2003.06.xx 2003.06.xx 7.0.x Yes 2003.06.xx 7.0.x 7.0.x Yes 2003.06.xx 7.1 7.0.x Yes 2003.06.xx 2003.06.xx 7.1 Yes 2003.06.xx 7.0.x 7.1 Yes 2003.06.xx 7.1 7.1 Yes Client View Server VOB Server Supported Configuration for View Interaction ? 7.0.x 2003.06.xx 2003.06.xx No 7.0.x 7.0.x 2003.06.xx No 7.0.x 7.1 2003.06.xx No 7.0.x 2003.06.xx 7.0.x No 7.0.x 7.0.x 7.0.x Yes 7.0.x 7.1 7.0.x Yes 7.0.x 2003.06.xx 7.1 No 7.0.x 7.0.x 7.1 Yes 7.0.x 7.1 7.1 Yes Client View Server VOB Server Supported Configuration for View Interaction ? 7.1 2003.06.xx 2003.06.xx No 7.1 7.0.x 2003.06.xx No 7.1 7.1 2003.06.xx No 7.1 2003.06.xx 7.0.x No 7.1 7.0.x 7.0.x Yes 7.1 7.1 7.0.x Yes 7.1 2003.06.xx 7.1 No 7.1 7.0.x 7.1 Yes 7.1 7.1 7.1 Yes
164. How do I – understand about upgrading ClearCase and ClearQuest to version 7.0.1 When upgrading IBM® Rational® ClearCase® (CC) to version 7.0.1, does IBM Rational ClearQuest® (CQ) also have to be upgraded to version 7.0.1, even if it is at version 7.0?
Answer Both products will need to be upgraded to the same release 7.0.1. Page 195 of 341
ClearCase Environment – How do I Both Products must be at the same VRMF (Version, Release, Modification, Fix pack) level. This is Key for the UCM - ClearQuest Integration, when using the UCM-CQ Integration you must be at the same VRMF level to remain in a supported configuration.. For example: If you are using ClearCase 7.0.1.1, you must be at ClearQuest 7.0.1.1 as well. If one product is at version 7.0.1.0 and the other is at 7.0.1.1 this is an unsupported configuration. 165. How do I – understand why db_server process on VOB server consuming 100% of a CPU after upgrading to RHEL 4 Update 5 VOB servers that have recently upgraded to RHEL 4 Update 5 intermittently see a db_server process consuming 100% of a CPU - all in user mode. The problem has not been seen on RHEL 4 Update 4
Cause Defect APAR PK58605 has been opened to investigate this issue.
Diagnosing the problem The following behavior will be seen when running into this issue:: 1. A db_server process is consuming 100% of a CPU in a tight (user space) loop By a tight user space loop, we mean:
a. the db_server process is consuming 100% CPU and
b. the CPU it is using is in user mode not system mode. (See #2 below)
2. You can check to see if you have the problem by running "top" and checking to see if a db_server process is consuming 100% of a CPU. You can also run the "sar" command - and check the heading %user in typical sar output such as:
# sar -u 1 10 Linux 2.6.9-55.EL (miami) 12/21/2007
11:33:44 AM CPU %user %nice %system %iowait %idle 11:33:45 AM all 99.90 0.00 0.00 0.00 0.10 11:33:46 AM all 100.00 0.00 0.00 0.00 0.00 11:33:47 AM all 100.00 0.00 0.00 0.00 0.00 11:33:48 AM all 99.99 0.00 0.00 0.00 0.01 11:33:49 AM all 99.00 0.00 0.99 0.99 0.01 11:33:50 AM all 100.00 0.00 0.00 0.00 0.00 11:33:51 AM all 99.00 0.00 0.00 0.00 1.00 11:33:52 AM all 100.00 0.00 0.00 0.00 0.00 11:33:53 AM all 100.00 0.00 0.00 0.00 0.00 11:33:54 AM all 99.99 0.00 0.00 0.00 0.01
Resolving the problem
There is currently no fix for this defect WORKAROUNDS: 1. Avoid installing RHEL 4 Update 5 on VOB servers
2. Revert to RHEL 4 Update 4 where the problem has not been seen
To temporarily work around the issue, kill the db_server that is consuming CPU and continue to monitor the CPU utilization.
Note: It may take a couple of days for the problem to re-appear.
166. How do I – upgrade ClearCase between major version numbers When upgrade ClearCase between major version numbers (i.e. v5 to v6 or v6 to v7, etc...) the order must be Registry server host first followed by VOB server host then View server hosts and then clients. Licensing wise, if you have a dedicated host, it does not appear to matter what version of ClearCase it is running, however, upgrading first or at the same time as the Registry server host would be a good idean. Page 196 of 341
ClearCase Environment – How do I
Note: You cannot have you VOB server or View server hosts running at higher major number than your Registry and in additional to that View server hosts cannot be ahead of the VOBs, therefore, as long as the Registry is at say v7 then your VOB hosts could be at a mix of v6 and v7 but v6 ClearCase Views would not be able to access VOBs hosted on a v7 server.
There is another issue with major versions, because for instanced a v6 sites cannot import ClearCase MultiSite VOBs that were created on a v7 ClearCase VOB server host. So ClearCase MultiSite is not quite so architecturally independent as it seems, VOB created on Windows VOB server host can be MultiSited to and imported on for instance Linux host but only if they are running the same ClearCase version or the creating host is running at lower version of ClearCase.
Since v2002-05-00 when you do ClearCase major version upgrade (i.e. v5 to v6 or v6 to v7 or even v5 to v7) there is an architecturally dependent script in /opt/rational/clearcase/
The can be particularly annoying if you are running "multitool restorereplica" to recover a VOB because you cannot run multitool syncreplica –import
The rgy_upgrade command can be run independently with a -tag
If you do a "cleartool lsvob" you can tell if the rgy_upgrade command has run successfully because all the MultiSited VOBs should be suffixed by (Replicated) in the output, therefore, this may be a MultiSite dependency but that is not stated by IBM Rational. 167. How do I - preserve files when upgrading ClearCase on UNIX and Linux Before Upgrading - Files to Preserve: Backup the following files to preserve any customizations: 2003.06.00 and later File or directory Purpose /var/adm/rational/clearcase/config/* All directories should be saved. They contain ClearCase Web configuration files; MultiSite® shipping parameters, database configuration and more. /var/adm/rational/clearcase/config/db.conf Config file that determine the lockout values for the db_server processes /var/adm/rational/clearcase/rgy This directory contains the Registry information /var/adm/rational/clearcase/license.db Database file that contains the ClearCase licenses /var/adm/rational/clearcase/scheduler/tasks This directory contains the Scheduled tasks /var/adm/rational/clearcase/ccweb ClearCase Web views. The contents will include the directories for each user that has logged into CCWeb. # cleartool schedule -get > jobs_definitions.txt This will save customized definitions. After the upgrade, you can restore the definitions: # touch empty-schedule # cleartool schedule -set empty-schedule (this command will delete all current jobs) # cleartool schedule -set jobs_definitions.txt /opt/rational/clearcase/config/clearmake List of clearmake scripts that can be modified /opt/rational/clearcase/config/magic/default.magic Custom extension, mapping to new file types, type managers and more. /opt/rational/clearcase/config More scripts that the scheduler jobs use; only save Page 197 of 341
ClearCase Environment – How do I if you have customized any scripts /opt/rational/clearcase/config/services/albd.conf ALBD parameters /opt/rational/clearcase/etc/clearcase Lockmgr parameters, ClearCase MIN and MAX env variables and more.
2002.05.00 and previous File or directory Purpose var/adm/atria/config/* All directories should be saved. They contain ClearCase Web configuration files; MultiSite® shipping parameters, database configuration and more. /var/adm/atria/config/db.conf Config file that determine the lockout values for the db_server processes /var/adm/atria/rgy This directory contains the Registry information /var/adm/atria/ccweb ClearCase Web views. The contents will include the directories for each user that has logged into CCWeb. /var/adm/atria/license.db Database file that contains the ClearCase licenses /var/adm/atria/scheduler/tasks This directory contains the Scheduled tasks # cleartool schedule -get > jobs_definitions.txt This will save customized definitions. After the upgrade, you can restore the definitions: # touch empty-schedule # cleartool schedule -set empty- schedule (this command will delete all current jobs) # cleartool schedule -set jobs_definitions.txt /usr/atria/config/clearmake List of clearmake scripts that can be modified /usr/atria/config/magic/default.magic Custom extension, mapping to new file types, type managers and more. /usr/atria/config More scripts that the scheduler jobs use; only save if you have customized any scripts /usr/atria/config/services/albd.conf ALBD parameters /usr/atria/etc/atria_start Lockmgr parameters, ClearCase MIN and MAX env variables and more.
168. How do I – resolve an Incompatible versions of ClearCase software and/or databases issue Attempts to create a VOB from a client at a lower version that the server (for example a 2003.06.00 client storing a VOB on a 7.0 server) results in the following error: %>cleartool mkvob -tag \vob1 \\<7.0server>\ccstg_d\VOBs\vob1.vbs cleartool: Error: Unable to create versioned object base database "\\<7.0server>\ccstg_d\VOBs\vob1.vbs". cleartool: Error: Incompatible versions of ClearCase software and/or databases: "\\<7.0server>\ccstg_d\VOBs\vob1.vbs". cleartool: Error: Unable to create versioned object base "\\<7.0server>\ccstg_d\VOBs\vob1.vbs". Clients of a lower release cannot create new VOBs on servers with a new release.
Solution Page 198 of 341
ClearCase Environment – How do I This is expected behavior and working as designed. The internal VOB database protocol for each version of ClearCase is different from release to release and will result in the above error when VOB creation is attempted.
Note: A 2003.06.00 client may access a 7.0 VOB server, but the client may not create a VOB. Review the Installation Guide for each release to preview the client/server compatibility tables.
You must create the VOB from a client or server at the same release as the server where the VOB will be stored. 169. How do I – resolve a ClearCase GUIs fail on 64 bit Linux and Solaris operating system issue Why attempts to use IBM® Rational® ClearCase® GUIs on 64-bit Linux® and Solaris® operating systems results in a failure to launch the GUIs.
Cause An example failure can be seen while opening the ClearCase Project Explorer: clearprojexp: error while loading shared libraries: libMrm.so.3: cannot open shared object file: No such file or directory Another example failure can be seen while running cleartool diff -g on Solaris: ./ld.so.1: /opt/rational/clearcase/lib/mgrs/directory/xcompare: fatal: relocation error: file /opt/rational/clearcase/sun5/shlib/libatriafxds. so: symbol __1c2n6FIpv_0_: referenced symbol not found bash: ./ld.so.1:: No such file or directory bash-2.05b$ cleartool: Error: Child process aborted with signal 9 bash: cleartool:: command not found bash-2.05b$ cleartool: Error: Unable to invoke operation "xcompare" for manager "directory": -1 bash: cleartool:: command not found bash-2.05b$ cleartool: Error: (Operation pathname was: "/opt/rational/clearcase/lib/mgrs/directory/xcompare")
This problem occurs because you do not have the 32-bit lib x11 libraries installed, only the 64-bit libraries are installed. The ClearCase GUIs run in 32-bit mode and therefore require the 32-bit libraries.
Note: ClearCase 7.0 requires the 32 bit libraries of Open Motif package on 64bit Linux hosts,
Solution Install the proper 32-bit libraries (such as openmotif-2.2.3-5.RHEL3.2 or later) on the operating system in order to use the ClearCase GUIs 170. How do I - understand why the ClearCase GUIs fail on Linux and Solaris operating system The following error can be seen while opening the ClearCase Project Explorer: clearprojexp: error while loading shared libraries: libMrm.so.3: cannot open shared object file: No such file or directory
Running xclearcase on RHEL results in the following error: /opt/rational/clearcase/bin/xclearcase: error while loading shared libraries: libMrm.so.3: cannot open shared object file: No such file or directory
The following errors can be seen while running cleartool diff -g on Solaris: ./ld.so.1: /opt/rational/clearcase/lib/mgrs/directory/xcompare: fatal: relocation error: file /opt/rational/clearcase/sun5/shlib/libatriafxds. so: symbol __1c2n6FIpv_0_: referenced symbol not found bash: ./ld.so.1:: No such file or directory bash-2.05b$ cleartool: Error: Child process aborted with signal 9 bash: cleartool:: command not found bash-2.05b$ cleartool: Error: Unable to invoke operation "xcompare" for manager "directory": -1 bash: cleartool:: command not found Page 199 of 341
ClearCase Environment – How do I bash-2.05b$ cleartool: Error: (Operation pathname was: "/opt/rational/clearcase/lib/mgrs/directory/xcompare")
Another example failure can be seen while attempting to start xclearcase: Warning: locale not supported by Xlib, locale set to C Warning: X locale modifiers not supported, using default Warning: Cannot convert string "-*-*-medium-r-normal--14-*-*-*-*-*- gbk-*" to type FontSet Warning: Unable to load any usable fontset Warning: Name: FONTLIST_DEFAULT_TAG_STRING Class: XmRendition Conversion failed. Cannot load font.
Warning:Cannot convert string "-*-fixed-medium-r-normal--14-*-*-*-*- *-big5-*" to type FontSet Warning:Unable to load any usable fontset Warning: Name: FONTLIST_DEFAULT_TAG_STRING Class: XmRendition Conversion failed. Cannot load font.
Warning: Name: FONTLIST_DEFAULT_TAG_STRING Class: XmRendition Conversion failed. Cannot load font.
Warning:Cannot convert string "-misc-fixed-medium-r-normal--14-*-*-*- *-*-*-*" to type FontSet Warning:Unable to load any usable fontset Warning: Name: FONTLIST_DEFAULT_TAG_STRING Class: XmRendition Conversion failed. Cannot load font.
Warning: Name: FONTLIST_DEFAULT_TAG_STRING Class: XmRendition Conversion failed. Cannot load font. While attempting to open any xclearcase GUI interface in RHEL5, the following error message appears
[vob]# /usr/atria/bin/xclearcase /usr/atria/bin/xclearcase: error while loading shared libraries: libMrm.so.3: cannot open shared object file: No such file or directory
Cause This problem occurs because you do not have the 32-bit lib x11 libraries installed, only the 64-bit libraries are installed. The ClearCase GUIs run in 32-bit mode and therefore require the 32-bit libraries.
Note: ClearCase 7.0 requires the 32 bit libraries of Open Motif package on 64bit Linux hosts,
Diagnosing the problem On Solaris, you can verify that all necessary GUI libraries are installed by running ldd against the xclearcase executable. Example:
# ldd /usr/atria/bin/xclearcase libatriamotif.so => /opt/rational/clearcase/sun5/shlib/libatriamotif.so libatriaui.so => /opt/rational/clearcase/sun5/shlib/libatriaui.so libMrm.so.4 => /usr/lib/libMrm.so.4
Page 200 of 341
ClearCase Environment – How do I libXm.so.4 => /usr/lib/libXm.so.4 libXt.so.4 => /usr/openwin/lib/libXt.so.4 libSM.so.6 => /usr/openwin/lib/libSM.so.6 libICE.so.6 => /usr/openwin/lib/libICE.so.6 libXp.so.1 => /usr/openwin/lib/libXp.so.1 libXext.so.0 => /usr/openwin/lib/libXext.so.0 libX11.so.4 => /usr/openwin/lib/libX11.so.4 On Linux verify that all necessary GUI libraries are installed by running ldd against the xclearcase executable.
[vob]# ldd /usr/atria/bin/xclearcase linux-gate.so.1 => (0x006db000) libatriami.so => /opt/rational/clearcase/shlib/libatriami.so (0x00db3000) libatriaabl.so => /opt/rational/clearcase/shlib/libatriaabl.so (0x00448000) libatriamotif.so => /opt/rational/clearcase/shlib/libatriamotif.so (0x00b19000) libatriaui.so => /opt/rational/clearcase/shlib/libatriaui.so (0x00cff000) libatriauc.so => /opt/rational/clearcase/shlib/libatriauc.so (0x007ef000) libatriauo.so => /opt/rational/clearcase/shlib/libatriauo.so (0x004eb000) libatriagutl.so => /opt/rational/clearcase/shlib/libatriagutl.so (0x00ad3000) libatriagu.so => /opt/rational/clearcase/shlib/libatriagu.so (0x001f7000) libatriacmdsyn.so => /opt/rational/clearcase/shlib/libatriacmdsyn.so (0x00110000) libatriacmd.so => /opt/rational/clearcase/shlib/libatriacmd.so (0x00e3a000) libatriamsadm.so => /opt/rational/clearcase/shlib/libatriamsadm.so (0x00a08000) libatriamsinfobase.so => /opt/rational/clearcase/shlib/libatriamsinfobase.so (0x009b2000) libatriasumcmd.so => /opt/rational/clearcase/shlib/libatriasumcmd.so (0x00176000) libatriasum.so => /opt/rational/clearcase/shlib/libatriasum.so (0x00f7c000) libatriasquidad.so => /opt/rational/clearcase/shlib/libatriasquidad.so (0x00260000) libatriasquidcore.so => /opt/rational/clearcase/shlib/libatriasquidcore.so (0x002ad000) libatriaadm.so => /opt/rational/clearcase/shlib/libatriaadm.so (0x001fb000) libatriasplit.so => /opt/rational/clearcase/shlib/libatriasplit.so (0x00e08000) libatriamntrpc.so => /opt/rational/clearcase/shlib/libatriamntrpc.so (0x00a9d000) libatriavob.so => /opt/rational/clearcase/shlib/libatriavob.so (0x072e0000) libatriaview.so => /opt/rational/clearcase/shlib/libatriaview.so (0x00319000) libatriaccfs.so => /opt/rational/clearcase/shlib/libatriaccfs.so (0x001ca000) libatriacm.so => /opt/rational/clearcase/shlib/libatriacm.so (0x00513000) libatriadbrpc.so => /opt/rational/clearcase/shlib/libatriadbrpc.so (0x00d56000) libatriaXbae.so => /opt/rational/clearcase/shlib/libatriaXbae.so (0x00b76000) libatriaclient_meters.so => /opt/rational/clearcase/shlib/libatriaclient_meters.so (0x00d28000) libMrm.so.3 => not found libXm.so.3 => not found libXt.so.6 => /usr/lib/libXt.so.6 (0x00c81000) libSM.so.6 => /usr/lib/libSM.so.6 (0x001d7000) libICE.so.6 => /usr/lib/libICE.so.6 (0x00c34000) libXp.so.6 => /usr/lib/libXp.so.6 (0x0095a000) libXext.so.6 => /usr/lib/libXext.so.6 (0x00bf9000) libX11.so.6 => /usr/lib/libX11.so.6 (0x00581000) libm.so.6 => /lib/libm.so.6 (0x003a7000) libatriaxdr.so => /opt/rational/clearcase/shlib/libatriaxdr.so (0x006dc000) libatriacredmap.so => /opt/rational/clearcase/shlib/libatriacredmap.so (0x001e0000) libatriatbs.so => /opt/rational/clearcase/shlib/libatriatbs.so (0x0036e000) libatriaks.so => /opt/rational/clearcase/shlib/libatriaks.so (0x00878000) libatriamvfs.so => /opt/rational/clearcase/shlib/libatriamvfs.so (0x001ef000) libezrpc.so => /opt/rational/clearcase/shlib/libezrpc.so (0x00bd3000) libncurses.so.5 => /usr/lib/libncurses.so.5 (0x06dbe000) libcrypt.so.1 => /lib/libcrypt.so.1 (0x06d8e000) libnsl.so.1 => /lib/libnsl.so.1 (0x0022a000) libdl.so.2 => /lib/libdl.so.2 (0x003a1000) libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x02d12000) libgcc_s.so.1 => /lib/libgcc_s.so.1 (0x00c0b000) libc.so.6 => /lib/libc.so.6 (0x066da000) libXau.so.6 => /usr/lib/libXau.so.6 (0x0050a000) libXdmcp.so.6 => /usr/lib/libXdmcp.so.6 (0x00398000) /lib/ld-linux.so.2 (0x00245000) You can also list which GUI libraries are missing by running ldd against the xclearcase executable as follows:
Page 201 of 341
ClearCase Environment – How do I Example: [vob]# ldd /usr/atria/bin/xclearcase | grep not # note that this will display libraries file that are required but are not available. libMrm.so.3 => not found libXm.so.3 => not found
Resolving the problem LINUX:
Verify if 32-bit library files are installed on the client system. If missing, install the proper 32-bit libraries (such as openmotif-2.2.3-5.RHEL3.2 or later on Linux) on the operating system in order to use the ClearCase GUIs.
SOLARIS:
Open a command prompt in /usr/lib directory and search for library files.
Example:
%>pwd /usr/lib
%>file /usr/lib/*X11* /usr/lib/libX11.so: ELF 32-bit MSB dynamic lib SPARC Version 1, dynamically linked, not stripped, no debugging information available /usr/lib/libX11.so.4: ELF 32-bit MSB dynamic lib SPARC Version 1, dynamically linked, not stripped, no debugging information available /usr/lib/libX11.so.5: ELF 32-bit MSB dynamic lib SPARC Version 1, dynamically linked, not stripped, no debugging information available These libraries are installed by default on Solaris. If these libraries are missing, the system administrator must reinstall them. Use the ldd command to examine the libraries that clearprojexp is trying to load. root> ldd /usr/atria/bin/clearprojexp
If the libraries are missing, the system administrator must reinstall them. RHEL 5:
Install OpenMotif package: rpm -i openmotif22-2.2.3-18.i386.rpm 171. How do I – understand upgrading to version 7.0 of Rational Software Development Platform - Team products Upgrading to the 7.0 release of the IBM® Rational® Software Development Platform - Team products, the tools that formerly were packaged in the Rational Suites, requires advanced planning. This technote highlights some key requirements you should know before you get started.
Solution The Rational 7.0 release introduces numerous changes to how Rational software is installed and updated. The following is a summary of some of the changes you need to be aware of prior to planning an upgrade to 7.0. Refer to technote 1213439 for a summary of installation issues and considerations to be aware of. All Rational 7.0 product documentation is product specific. Earlier versions of the some Rational Products where available as part of a bundled Suite, and shared common documentation such as a Rational Server products installation guide. This eliminates the need to refer to multiple manuals for one specific product. Some Rational 2003 products must be uninstalled prior to installing the 7.0 versions of any of the Rational products. For example, you cannot run version 2003.06.15 of Rational ClearQuest® with version 7.0 of Rational ClearCase®. If a Rational 2003 product was installed as part of Rational Suite, all Rational products that were installed as part of the Suite, are uninstalled when you install the 7.0 version. Note: The 7.0 Installation program will uninstall any of the affected products for you. It is not necessary to manually uninstall any earlier products.
Page 202 of 341
ClearCase Environment – How do I
The following table lists the Rational Team products (pre-7.0 versions) that will be uninstalled by the Rational 7.0 Common Installer. Products that are included with the Rational Professional Bundle (known as the Software Development Platform - Desktop products) do not need to be uninstalled when installing 7.0 versions of the Rational Team products. Rational Team products that will be Rational Desktop products that will not be uninstalled uninstalled Rational ClearCase Rational Application Developer for WebSphere Rational ClearQuest Software Rational ProjectConsole Rational Functional Tester Rational PurifyPlus Rational Manual Tester Rational RequisitePro Rational Performance Tester Rational Rose Rational Performance Tester Extension for Citrix Rational SoDA Presentation Server Rational Suite Rational Performance Tester for z/OS Rational TestManager Rational Software Architect Rational Software Modeler Rational Systems Developer Rational Web Developer for WebSphere Software Rational Method Composer Rational Data Architect
Note: You must review the Rational Installation and Upgrade Guides for upgrade information related to your specific Rational products. Additional information can also be found in the product release notes.
All Rational documentation can be downloaded from IBM Publications Center. After selecting your "country/region/language," you will be able to search for the publications by their publication number. If you are looking for previous product versions, you can search the publications site for those as well. Plugins & Integrations 172. How do I - integrate Microsoft Word 2007 with ClearCase 7.0 This technote explains how to activate the IBM® Rational® ClearCase® Component Object Model (COM) Add-in in Microsoft® Word 2007.
Content 1. Open Microsoft Word 2007.
2. Click the Office Button and Select Word Options > Add –In
Page 203 of 341
ClearCase Environment – How do I
3. Select the ClearCase Word Integration and click GO
Page 204 of 341
ClearCase Environment – How do I
4. Select the ClearCase Word Integration check box and click OK
5. Restart Word.
6. Upon opening Word 2007, the Add-Ins Menu list will now appear on tool bar with ClearCase options included.
The following ClearCase Menu options will now be viewable:
Page 205 of 341
ClearCase Environment – How do I
If the following error is received the first time opening Word after performing the integration, you must copy the
Cannot find the template clearcase.dot. Rerun the Microsoft Integration Configuration Program and re-start the Office application. 173. How do I – understand how the IBM Rational ClearCase SCM Adapter adds ClearCase functionality to the Eclipse workbench. The Rational ClearCase SCM Adapter is designed to allow Eclipse users to have access to ClearCase functionality in the Eclipse workbench. It is supported on Eclipse versions later than 3.2.2 and all Rational ClearCase versions later than 7.0.x. It will function with earlier versions of ClearCase but it is not officially supported for the earlier releases. This plugin requires ClearCase to be installed on the system. Installation Instructions For Eclipse versions 3.2.2 to 3.3.x inclusive: Download the zip file appropriate for your operating system. Extract the contents of the file to a directory in your file system. In Eclipse, select Help > Software Updates > Manage Configuration. In the Product Configuration window, click the Add an Extension Location link in the Eclipse platform pane. The Browse for Folder dialog prompts you to choose an extenstion location, expand the My Computer entry and navigate to the directory that contains the contents of the extracted zip file. Expand the Eclipse folder and click OK. The Install/Update dialog prompts you to restart the workbench. Click Yes. In the Eclipse window, click Window > Customize Perspective. In the Customize Perspective dialog box, click the Commands tab, ensure that the ClearCase option under the Available command groups column is checked, and click OK. Note: This installation procedure will NOT disable previous versions of the ClearCase SCM Adapter feature. You MUST disable the earlier versioned features manually in the Manage Configuration sheet in order to ensure proper functionality. Following this procedure, the ClearCase menu option appears in the main menu of your Eclipse window, the ClearCase icons appear, and the installation of the ClearCase SCM Adapter is complete.
For Eclipse versions 3.4.x and later: Download the zip file appropriate for your operating system. Extract the contents of the file to a directory in your file system. Open the p2 eclipse updater (Help > Install New Software...) click "Add...". In the dialog popup, click the button marked "Local...". Navigate to the location where you unpacked the zip file, and select the "eclipse" folder, and click "OK". Click "OK" again. Select the available packages and click "Finish". Note: For Eclipse on Solaris systems, note that the Linux version of the Rational ClearCase SCM Adapter and the Solaris version are the same. The Linux version of the Rational ClearCase SCM Adapter is designed to install into Solaris based versions of Eclipse. Download package Download RELEASE DATE LANGUAGE SIZE(Bytes) Download Options
ClearCase SCM Adapter (Windows) 10/31/2008 English 1671237 HTTP
ClearCase SCM Adapter (Linux) 10/31/2008 English 1207819 HTTP
ClearCase SCM Adapter (Solaris) 10/31/2008 English 1207819 HTTP Page 206 of 341
ClearCase Environment – How do I Download RELEASE DATE LANGUAGE SIZE(Bytes) Download Options
ClearCase MVFS Adapter (All) 10/31/2008 English 458035 HTTP 174. How do I – understand about base ClearCase and ClearQuest V2 integration Setup and FAQ This technote provides information on where additional documentation can be found about the config.pl script which controls the Base ClearCase and ClearQuest integration.
Documentation for version 7.1 For additional information regarding the setup of the Base ClearCase and ClearQuest V2 integration in version 7.1, refer to the Setting up the base ClearCase integration with Rational ClearQuest topic of the ClearCase Information Center.
Documentation for version 7.0 Additional information regarding the setup of the Base ClearCase and ClearQuest V2 integration in version 7.0 can be found in the Guide to Managing Software Projects manual in Chapter 13, pages 203 and 204.
Documentation for version 2003.06 On-line documentation can be found: HTML PDF links Distributed Documentation UNIX® and Linux®:
/opt/rational/clearcase/doc/books
Microsoft® Windows®:
C:\Program Files\Rational\ClearCase\doc\books The instructions for setting up the integration can be found in Chapter 13 of the Managing Software Projects manual for ClearCase 2003.06.00.
In addition to the comments in the config.pl script itself, there is a README file in the following location...
The README contains the information on the following topics: Release Notes: A summary of changes for the current release Configuration File: Guidelines for the most common changes and documentation on the ClearQuest Schema definitions Trigger Source Code: Information on the PERL source code and support policy Basic setup for the Base ClearCase and ClearQuest V2 integration in version 7.x and 2003.06:
Default location of config.pl in version 7.1:
Default location of config.pl in version 7.0:
Default location of config.pl in version 2003.06:
There is a Readme file in the same directory, which covers the basic guidelines for editing the config.pl file. 1. Apply the ClearCase 1.0 package to the ClearQuest schema and upgrade user databases. 2. Create triggers: Start > ClearCase Administration > Integrations > ClearQuest Integration Configuration. When configuring a mixed UNIX/Windows environment, the suggested method to configure the integration is through the Windows ClearQuest Integration Configuration GUI. Page 207 of 341
ClearCase Environment – How do I Note: You can manually install the integration triggers on UNIX / Windows without using the Windows CQConfig tool as documented below. A. Select the desired radio button under the checkout/checkin policy options B. Select the V2 radio buttons, as V1 is configured by default C. Enter the path to the globally used config.pl (in UNC format) D. If applicable, select the desired radio button under the branch/element restrictions and identify types 3. Modify the PERL script (config.pl) to reflect your environment. A. Replace the following string with your
Base ClearCase and ClearQuest integration post operation checkin trigger This following describes the functions of the Base ClearCase and ClearQuest integration post-operation checkin trigger.
The ClearCase and ClearQuest integration can use two to four triggers: cq_co_trigger checkouts cq_unco_trigger undo checkouts cq_ci_trigger checkins cq_postci_trigger post checkin operations
The cq_ci_trigger launches the association dialogue to allow you to pick a ClearQuest record to associate with a ClearCase element (commonly referred to as a file). This trigger also sets the hyperlink between ClearCase and ClearQuest. However, at the time this trigger is launched, the element has not been not completed its checkin. At this point, the element is in an intermediate state, which means a new version has not yet been created, and the version has not been given its unique identifier (OID) in the ClearCase vob.
After the cq_ci_trigger has run, the cq_postci_trigger launches. It is at this point that the element is fully checked in. The trigger verifies the OID of the element and supplies the fully extended ClearCase path, which appears in the ClearQuest record cc_change set field. Installing triggers on UNIX / Windows without using the Windows CQConfig tool: Note: The trigger scripts provided below are only valid if you are using a local config.pl file. If a Global Config.pl file is being used, the CQCC\config.pl needs to be modified for each execwin and execunix line to reflect the UNC path to the Global config.pl file cleartool mktrtype -element -all -preop checkin -execwin "cqcc_launch.bat CQCC\config.pl -entitydef defect " -execunix "cqcc_launch CQCC/config.pl -entitydef defect " -c "ClearQuest Integration" cq_ci_trigger cleartool mktrtype -element -all -postop checkin -execwin "cqcc_launch.bat CQCC\config.pl -postop - entitydef defect " -execunix "cqcc_launch CQCC/config.pl -postop -entitydef defect " -c "ClearQuest Integration" cq_postci_trigger cleartool mktrtype -element -all -postop checkout -execwin "cqcc_launch.bat CQCC\config.pl -postop - entitydef defect " -execunix "cqcc_launch CQCC/config.pl -postop -entitydef defect " -c "ClearQuest Integration" cq_co_trigger cleartool mktrtype -element -all -preop uncheckout -execwin "cqcc_launch.bat CQCC\config.pl -entitydef defect " -execunix "cqcc_launch CQCC/config.pl -entitydef defect " -c "ClearQuest Integration" cq_unco_trigger
To force the users to make an association: Page 208 of 341
ClearCase Environment – How do I Preop Check-in Trigger
cleartool mktrtype -element -all -preop checkin -execwin "cqcc_launch.bat CQCC\config.pl – required -entitydef defect " -execunix "cqcc_launch CQCC/config.pl –required -entitydef defect " -c "ClearQuest Integration" cq_ci_trigger
Postop Check-in Trigger
cleartool mktrtype -element -all -postop checkin -execwin "cqcc_launch.bat CQCC\config.pl - postop -entitydef defect " -execunix "cqcc_launch CQCC/config.pl -postop -entitydef defect " -c "ClearQuest Integration" cq_postci_trigger
Postop Check-out Trigger
cleartool mktrtype -element -all -postop checkout -execwin "cqcc_launch.bat CQCC\config.pl - postop -required -entitydef defect " -execunix "cqcc_launch CQCC/config.pl -postop - required -entitydef defect " -c "ClearQuest Integration" cq_co_trigger
Preop UnCheck-out Trigger
cleartool mktrtype -element -all -preop uncheckout -execwin "cqcc_launch.bat CQCC\config.pl - entitydef defect " -execunix "cqcc_launch CQCC/config.pl -entitydef defect " -c "ClearQuest Integration" cq_unco_trigger
Related information How to use the new ClearQuest Web in a V2 Base ClearCas Configuring the base ClearCase and ClearQuest V2 Integr How to configure multiple queries for different Database 175. How do I – understand why the ClearCase menu options bundle is not visible in the menu Eclipse 3.4.1 or 3.4.2 Java EE Bundle does not have the Capabilities tab under Preferences, therefore, there is no way to make the ClearCase menu visible.
Cause This is a known issue with Eclipse as shown in this record https://bugs.eclipse.org/bugs/show_bug.cgi?id=235089
Resolving the problem To make the ClearCase menu visible complete this procedure: 1. Start Eclipse 2. Create a new workspace 3. Close Eclipse 4. Locate this file, org.eclipse.ui.workbench.prefs:
C:\Documents and Settings\
UIActivities.com.rational.clearcase=true 6. Restart Eclipse
The ClearCase menu option will now be visible 176. How do I – understand the setting up and using the Rational Method Composer - Rational ClearCase Integration How do you configure and use the IBM Rational ClearCase integration in Rational Method Composer? Supported versions of ClearCase for the integration Product Version Platform Patch level ClearCase 2002.05.00 Windows clearcase_p2002.05.00.NT-32 or later ClearCase LT 2002.05.00 Windows clearcase_lt_p2002.05.00.NT-11 or later ClearCase 2002.05.00 Linux clearcase_p2002.05.00-38 or later ClearCase LT 2002.05.00 Linux clearcase_lt_p2002.05.00-17 or later Page 209 of 341
ClearCase Environment – How do I ClearCase 2003.06.00 Linux clearcase_p2003.06.00-11 or later ClearCase LT 2003.06.00 Linux clearcase_lt_p2003.06.00-6 or later ClearCase 2003.06.13 Windows ClearCase 2003.06.13 or later ClearCase LT 2003.06.13 Windows ClearCase LT 2003.06.13 or later ClearCase 7.0 Windows ClearCase 7.0 or later ClearCase LT 7.0 Windows ClearCase LT 7.0 or later Installing the Rational ClearCase SCM Adapter for Eclipse 1. Start Rational Method Composer 2. Click Help -> Software Updates -> Find and Install... 3. Select Search for new features to install 4. Click Next 5. Click New Remote Site... 6. Enter IBM Rational ClearCase SCM Adapter for the Name 7. Enter http://www3.software.ibm.com/ibmdl/pub/software/rationalsdp/clearcase/60/update for the URL 8. Click OK 9. Click Finish 10. Select IBM Rational ClearCase SCM Adapter 11. Click Next 12. Accept the license agreement and click Next 13. Click Finish 14. Click Install All 15. Click Yes to restart the workbench Note: To install Rational ClearCase Remote Client (CCRC), follow the directions above, substituting "ClearCase Remote Client" for the Name, and substituting the URL of step 7 for one of the following URLs:
CCRC version 6.14.x http://www3.software.ibm.com/ibmdl/pub/software/rationalsdp/clearcase/ccrc/614/update
CCRC version 7.x http://www3.software.ibm.com/ibmdl/pub/software/rationalsdp/clearcase/ccrc/70/update
Note: Verify the version CCRC is applicable to the version of Eclipse for your version of Rational Method Composer 7.x, as explained in Technote 1237978 Adding library.7x to Source Control
If the content that is being authored will need to reference Rational Unified Process content, place the library.71 under source control. 1. Click Start > Run... 2. Type in cmd 3. Click OK 4. Type in clearfsimport -r "C:\Program Files\IBM\Rational\SDP\Rational Method Composer 7.1\library.71" "
Page 210 of 341
ClearCase Environment – How do I 6. Click OK
7. Click Window > Open Perspective -> Other... 8. Select Resource 9. Click OK 10. Click ClearCase > Connect to Rational ClearCase 11. Click OK
12. Click Window > Open Perspective > Other... 13. Select Authoring 14. Click OK Enabling the ClearCase Menu for the Authoring perspective 1. Click Window > Customize Perspective... 2. Click the Commands tab Place a check in ClearCase and click OK
Page 211 of 341
ClearCase Environment – How do I
Subsequent Team Access to Controlled Projects 1. Start Rational Method Composer 2. In the Open Method Library dialog, click Browse... 3. Navigate to
Setting Team Preferences for the SCM Adapter 1. Click Window > Preferences 2. Expand Team 3. Select ClearCase SCM Adapter Click Advanced Options... 177. How do I - enable tracing for the V2 Base ClearCase-ClearQuest Integration Diagnostic tracing allows for the collection of data used for troubleshooting problems with the V2 integration on both Microsoft Windows and UNIX platforms.
Answer WINDOWS To enable V2 tracing on a Windows client, or on the PC that hosts the central config.pl file for the environment, open the config.pl file on the host and configure the parameters listed below. The config.pl file is normally located in the following directories, depending on version. For 7.1.x:
#------# CQCC_LOG_ERRORS: [ENV] [DEFAULT: ""] # Values: "", INFO, WARN, ERROR, FATAL &SetConfigParm("CQCC_LOG_ERRORS", "ERROR");
#------# CQCC_DEBUG: [ENV] [DEFAULT: 0] # Values: 0 (off), 1(basic), 2(details) Page 212 of 341
ClearCase Environment – How do I &SetConfigParm("CQCC_DEBUG", "2");
#------# CQCC_TIMER: [ENV] [DEFAULT: 0] # &SetConfigParm("CQCC_TIMER", "1");
#------# CQCC_LOG_OUTPUT: [ENV] [DEFAULT: OFF] # Values: OFF, OVERWRITE, APPEND, # OVERWRITE_THREADS, APPEND_THREADS &SetConfigParm("CQCC_LOG_OUTPUT", "OVERWRITE");
Once these are set and the config.pl file saved, reproduce the issue. The log file will be created in one of the following locations: 1. If CQCC_CACHE_ROOT is enabled, it will be held in the cache folder (referenced in the config.pl file). 2. If caching is not enabled, it will be held in the Windows account's application data folder: C:\Documents and Settings\
UNIX: To enable V2 tracing on UNIX-based environments, set the CQCC_DEBUG Environment Variable to 2:
> set CQCC_DEBUG 2
Reproduce the issue and the V2 trace log will be located right in the UNIX account's home directory. To disable tracing, reset the environment variable for 0. 178. How do I – understand the issue “ClearCase SCM Adapter and Eclipse 3.4.1 with the Java EE Bundle is not visible in the menu” Eclipse 3.4.1. Java EE Bundle does not have the Capabilities tab under Preferences, therefore, there is no way to make the ClearCase menu visible.
Cause This is a known issue with Eclipse as shown in this record https://bugs.eclipse.org/bugs/show_bug.cgi?id=235089
Resolving the problem To make the ClearCase menu visible complete this procedure: 1. Start Eclipse 2. Create a new workspace 3. Close Eclipse 4. Locate this file, org.eclipse.ui.workbench.prefs:
C:\Documents and Settings\
UIActivities.com.rational.clearcase=true 6. Restart Eclipse
The ClearCase menu option will now be visible. 179. How do I – display the settings for the base ClearCase-ClearQuest integration The command cqcc_launch has a -test argument that displays the various configuration settings behind the V2 integration. On a machine with the integration actively configured, simply run the following from the command line: cqcc_launch -test Output similar to the following with appear:
IOBase::Initialize localhost: myservername.example user: User: NUL Series Key: NO_SERIES.xxxx Page 213 of 341
ClearCase Environment – How do I PARM: C:\Documents and Settings\user\Application Data\Rational\CQCC PARM_USER: C:\Documents and Settings\user\Application Data\Rational\CQCC ATRIA: HELPAPP: start TEMP: C:\DOCUME~1\user\LOCALS~1\Temp
TriggerCQCC::ConfigureClasses: Running Perl 5.008006 Trigger: CQCC::TriggerCQCC ClearCase: CQCC::CCase ClearQuest: CQCC::CQPerlAPI MessageCatalog: CQCC::MsgCat_English
TriggerBase::ProcessArguments: Operation: test() (Optional) (TestMode) LoadCache reading C:\Documents and Settings\user\Application Data\Rational\ QCC\cqcc_cache
Parm CACHE_APPLY_TO_ALL = 0 Parm CACHE_CHECKOUT_NOT_SELECTED = 0 Parm CACHE_DESIRED_ASSOCS = Parm CACHE_RECENT_ASSOCS = Parm CACHE_SERIES = 0 Parm CACHE_VOLIST = Parm CLEARCASE_BEGIN_SERIES = Parm CLEARCASE_COMMENT = Parm CLEARCASE_ENABLE_ATE_MESSAGES = FALSE Parm CLEARCASE_END_SERIES = Parm CLEARCASE_OP_KIND = Parm CLEARCASE_PN = Parm CLEARCASE_PPID = Parm CLEARCASE_SERIES_ID = Parm CLEARCASE_VOB_PN = Parm CLEARCASE_XPN = Parm CM_CLEAN_HRS = 4 Parm CM_CQSESSION_STALE_MINS = 30 Parm CM_LOCK_BREAK_MINS = 5 Parm CM_LOCK_WARNING_MINS = 1 Parm CM_STALE_HRS = 8 Parm CM_WIN_UNIX = FALSE Parm CQCC_ASCII_CHECK_ENABLE = ON Parm CQCC_ASSOC_BATCHFILE = STANDARD Parm CQCC_ASSOC_BATCH_AUTORUN = TRUE Parm CQCC_ASSOC_BATCH_CONFIRM = OFF Parm CQCC_ASSOC_BATCH_ENABLE = FALSE Parm CQCC_ASSOC_BATCH_SERIES = FALSE Parm CQCC_AUTO_ASSOCIATE = Parm CQCC_AUTO_ASSOCIATE_ENABLE = TRUE Parm CQCC_CACHE_MGMT = Parm CQCC_CACHE_ROOT = Parm CQCC_COMMENT_PATTERN = Parm CQCC_CONVERT_ERROR_MAX = 50 Parm CQCC_CQWEB_ONLY = FALSE Parm CQCC_CQWEB_VERSION = 2.0 Parm CQCC_CTRL_C = TRUE Parm CQCC_DATABASE = SAMPL Parm CQCC_DATABASE_ENTITY_LIST = SAMPL: defect, enhancementrequest Parm CQCC_DEBUG = 2 Parm CQCC_ENTITY = defect Parm CQCC_GUI_ENABLE = ON Parm CQCC_I18N_ENABLE = ON Parm CQCC_JOURNAL_FILE = Page 214 of 341
ClearCase Environment – How do I Parm CQCC_JOURNAL_MODE = OFF Parm CQCC_LOG_ERRORS = ERROR Parm CQCC_LOG_OUTPUT = OVERWRITE Parm CQCC_MULTIPLE_ASSOCS = TRUE Parm CQCC_MULTISITE = FALSE Parm CQCC_POSTCHECKIN_COMMIT = FALSE Parm CQCC_POSTCHECKIN_VERIFY = FALSE Parm CQCC_QUERY_ENABLE = LOCAL Parm CQCC_QUERY_FILTER = Parm CQCC_QUERY_NAME = STANDARD Parm CQCC_QUERY_OID = FALSE Parm CQCC_QUERY_TYPE = LOCAL Parm CQCC_REPLICA_NAME = Parm CQCC_RESTRICTIONS_TIMEOUT = 300 Parm CQCC_SESSION_ID = main Parm CQCC_TIMER = 0 Parm CQUSER = Parm ClearCaseInterface = CQCC::CCase Parm ClearQuestInterface = CQCC::CQPerlAPI Parm DesiredAssocList = Parm IOBaseInterface = CQCC::IOBase Parm MessageCatalogInterface = CQCC::MsgCat_English Parm REPLICA_NAME = Parm REQUIRED = FALSE Parm SAVE_SERIES_CACHE = FALSE Parm SILENT = FALSE Parm TESTMODE = TRUE Parm TriggerInterface = CQCC::TriggerCQCC Parm USER = TriggerBase::DispatchOperation $self->Op_test()
This command will also test the integration for connectivity, access to record types, and querying:
Test Mode: Trying to connect to Perl API ClearQuest User is: admin Connecting to DB SAMPL in IntCCCQ1
CQUser name is admin
In CQuest::SetCQUser CQUSER = admin
CQuest::SaveCQUser returns 1
Entity names in database SAMPL: UCM_Project TMSuiteLog TMExternalFile TMTestCase users cc_vob_object TMConfigurationValue groups Requirement TMConfigurationAttribute cc_change_set TMFileLocation BaseCMActivity RAProject TMComputer TMIteration TMConfiguration TMConfiguredTestCase Page 215 of 341
ClearCase Environment – How do I attachments TMTestSuite BTBuild EnhancementRequest UCMUtilityActivity TMTestPlan ratl_replicas ReqProStuff TMTestType RequirementMap TMAssetRegistry TMComputerGroup TMTestLog Defect Email_Rule history
PerformQuery: entity defect database SAMPL query STANDARD Owner eq admin State in Submitted,Assigned,Opened id State P S Headline SAMPL00000042 Submitted 2 1 test
SAMPL00000042 Submitted 2 1 test ResourceMgr releasing ALL IOBase::ExitHandler - exit status: 0 180. How do I – get the Eclipse plugins A list of the latest ClearCase Eclipse plugins can be found at the following site: http://www- 128.ibm.com/developerworks/rational/library/content/03July/2500/2834/ClearCase/clearcase_plugins.ht ml 181. How do I – understand about Eclipse plug-in compatibility and version support for the ClearCase SCM Adapter ClearCase Supported SCM Adapter
Eclipse Platforms SCM Comments version Adapter Windows® Windows Windows SUSE® RedHat® Solaris® Version Server Vista Shipped with RAD 3.2 2000, XP 2003 No 9 4.0 8, 9, 10 7.0.x.x 7.0.x.x Shipped with WID 6.0.50 6.02 98, ME, NT, 6.0.49 3.1 2000, XP No No 9 2.1, 3.0, 8 4.0 Shipped with RAD 6.0.48 6.01 Contained critical bugfix to support 98, ME, NT, 6.0.25 RAD v6 3.0 2000, XP No No 9 2.1, 3.0 No Shipped with RAD 6.0.23 6.0
Notes: The SCM Adapter is based on Eclipse 3.0, so it can be used by all Eclipse 3.0.x, 3.1.x, 3.2.x or layered products.
The SCM Adapter is not an OSGI compliant plug-in. Page 216 of 341
ClearCase Environment – How do I All JVMs that are supported by the corresponding Eclipse versions are supported with the SCM Adapter
Supported Desktop Products Version Rational Application Developer for WebSphere Software 6.x and 7.x Rational Software Architect, Rational Software Modeler, Rational Systems 6.x and 7.x Developer Rational Performance Tester 6.x and 7.x Rational Method Composer 7.1 WebSphere Developer for zSeries 6.x and 7.x WebSphere Integration Developer 6.x
ClearCase versions supported ClearCase patch level required
ClearCase 2003.06.00 on Windows Service Release 3 or later
ClearCase LT 2003.06.00 on Windows Service Release 3 or later
ClearCase 2003.06.00 on UNIX and Linux clearcase_p2003.06.00-13 or later
ClearCase LT 2003.06.00 on UNIX and Linux clearcase_lt_p2003.06.00-8 or later
ClearCase 7.0 (Windows, UNIX and Linux) 7.0.0.0-RATL-RCCLT-IFIX01 or later
ClearCase LT 7.0 (Windows, UNIX and Linux) 7.0.0.0-RATL-RCC-IFIX01 or later
Change History 17 January Added row for CCLT and clarified first note 2008 11 September Added related link to TN 1233091 2007 10 August Updated 7.x version numbers 2007 7 March 2007 Created new SCM Adapter table originally stored in technote 1238283
182. How do I - install the SCM Adapter for Eclipse version 3.4.1
After installing the SCM adapter plugin for Eclipse the ClearCase Perspectives are unavailable.
Cause If you have followed the steps identified in the following documentation which are for Eclipse 3.4, those steps are incomplete for this particular version of Eclipse under the 'Installing the ClearCase SCM adapter' heading.
IBM Team programming with Rational ClearCase Setting up the ClearCase SCM Adapter for Eclipse Version 3.4 04 Nov 2008 Updated 30 Dec 2008 http://www.ibm.com/developerworks/rational/downloads/08/cc_plugin_eclipse3.4/
Resolving the problem The following additional steps are required to enable the ClearCase Perspective and menus in Eclipse 3.4.1: 1. Download the file com.rational.clearcase.win32-20081031A.zip if you are running on Windows or the com.rational.clearcase.linux-20081031A.zip file if you are running on Linux or Solaris. Extract the contents of the file to a directory in your file system.
Page 217 of 341
ClearCase Environment – How do I 2. In Eclipse, select Help > Software Updates > Manage Configuration. In the Product Configuration window, click the Add an Extension Location link in the Eclipse platform pane.
3. The Browse for Folder dialog prompts you to choose an extension location, expand the My Computer entry and navigate to the directory that contains the contents of the extracted zip file. Expand the Eclipse folder and click OK.
4. The Install/Update dialog prompts you to restart the workbench. Click Yes
5. Once Eclipse starts again select Window > Preferences > General > Capabilities > Enable All > Apply > Ok The ClearCase menu should now be visible and can now be modified if desired under the Customize Perspective menu. 183. How do I – understand the supported Rational integrations with ClearCase and ClearQuest What are the supported IBM Rational product integrations with IBM Rational ClearCase and IBM Rational ClearQuest version 7.1 products?
Answer This table applies to the following Rational products: Rational Application Developer (RAD)
Rational Software Architect family
o Rational Software Modeler (RSM)
o Rational Systems Developer (RSD)
o Rational Software Architect (RSA)
o Rational Software Architect Standard Edition (RSASE)
o Rational Software Architect for WebSphere Software (RSAWS)
Rational Functional Tester (RFT)
Rational Manual Tester (RMT)
Rational Performance Tester (RPT)
Product ClearCase 7.1 ClearCase ClearQuest 7.1 Remote Client 7.1 Rational Application Developer Supported Not Supported Supported 7.0.x Rational Application Developer Supported Supported Supported with 7.5.x Limitations Rational Software Architect Supported Not Supported Supported family 7.0, 7.0.5.x (RSM, RSD, RSA) Rational Software Architect Supported Supported Supported with
Page 218 of 341
ClearCase Environment – How do I family 7.5.x Issues Limitations (RSM, RSASE, RSAWS) Rational Functional Tester Not Supported Not Supported Not Supported 7.0.1.x Rational Functional Tester Not Supported Not Supported Supported 8.0.x Rational Manual Tester 7.0.1.x Not Supported Not Supported Not Supported Rational Performance Tester Not Supported Not Supported Not Supported 7.0.1.x Rational Performance Tester Supported Not Supported Supported 8.0.x
Limitations TN #1321462: The Report Server for ClearQuest does not currently support running reports that are created in Eclipse 3.4
Issues TN #1330934: Welcome and help home page content incorrectly displayed after installing Rational ClearCase Remote Client using Update Manager
Related information The Report Server for ClearQuest does not currently sup Welcome and help home page content incorrectly displaye
Cross Reference information
Segment Product Component Platform Version Edition Linux, Software Rational Integrations: Solaris, 7.1 Development ClearQuest IBM Windows Rational Application Software Developer Integrations: Windows, 7.0, 7.5 Development for IBM Linux WebSphere Software Rational Software Integrations: Linux, Software 7.0 Development IBM Windows Architect Rational Software Integrations: Linux, 7.0.1, Functional Development IBM Windows 8.0 Tester Rational Software Integrations: Windows, 7.0.1, Performance Development IBM Linux 8.0 Tester
Page 219 of 341
ClearCase Environment – How do I Rational Software Integrations: Manual Windows 7.0.1 Development IBM Tester Rational Software Software Integrations: Linux, 7.5, Architect for Development IBM Windows 7.5.1 WebSphere Software Rational Software Software Integrations: Linux, 7.5, Architect Development IBM Windows 7.5.1 Standard Edition 7.0, 7.0.5, Rational 7.0.5.1, Software Integrations: Windows, Software 7.0.5.2, Development IBM Linux Modeler 7.0.5.3, 7.5, 7.5.1 7.0, Rational Linux, 7.0.5, Software Systems Integrations Solaris, 7.0.5.1, Development Developer Windows 7.0.5.2, 7.0.5.3
184. How do I – understand the Permission denied error accessing a dynamic view through Apache on Windows issue After setting up Apache on Windows to view the contents of a VOB through a dynamic view, the VOB root folder is seen as well as the contents of the VOB; however, attempts to open a file (which is read-only) returns a permission denied error. The Apache error log (/var/log/httpd/error_log) contains the following entries:
[Mon Jun 07 20:55:43 2004] [error] [client 192.168.1.3] mod_mime_magic: can't read `/var/www/html/index.php' [Mon Jun 07 20:55:43 2004] [error] [client 192.168.1.3] (13)Permission denied: file permissions deny server access: /var/www/html/index.php
Cause All users who want to read content from a VOB must be a member of the elements group or the element has to give others read access. The same rule applies for the Apache process. By default the Apache process runs as LOCAL_MACHINE\system account. For the ClearCase MVFS the local system account is identified as NOBODY. Apache will report the error below if others (nobody or world) have no read access on the files.
Access forbidden! You don't have permission to access the requested object. It is either read-protected or not readable by the server. If you think this is a server error, please contact the webmaster.
Resolving the problem There are two possible options to solve this problem. 1. Change the file permissions so that others have read access. For example; change the file permissions with a cleartool protect -chmod command from 770 to Page 220 of 341
ClearCase Environment – How do I 775.
OR Have the Apache process run as a user who is member of the directory and file element group that are to be published. 185. How do I – understand about the ClearCase 7.0 integration with Apache Ant A supported integrated development environment (IDE) with Apache ANT has been made available as of Rational ClearCase 7.0. IMPORTANT: Currently, there is no supported integration (MVFS auditing capabilities) between ClearCase version 2003.06.00 and previous, its build tools (omake or clearmake) with Apache Ant.
Review the following documentation for more detail regarding the Ant build auditing. Build Documentation for ClearCase
IBM Rational ClearCase Guide to Building Software, 7.0, Windows GI11-6364-00
IBM Rational ClearCase Guide to Building Software, 7.0, Linux and UNIX GI11-6363-00 OVERVIEW: A jar file has been supplied that implements an ANT listener. This listener must be specified on ANT's command line. It will be notified by ANT of build events, which ClearCase will use to start and stop auditing, and to create config records and derived objects.
This release provides only build auditing, such as recoding the build. It does not provide build avoidance, such as using the results of the build in the future to determine whether rebuilds are necessary.
WORKAROUND: Ant does provide several optional tasks for working with ClearCase. More information can be found on the Apache Web Site at http://ant.apache.org/manual/OptionalTasks/clearcase.html 186. How do I - integrate Microsoft Word 2007 with ClearCase 7.0 1. Open Microsoft Word 2007. 2. Click the Office Button and Select Word Options > Add –In
Page 221 of 341
ClearCase Environment – How do I
3. Select the ClearCase Word Integration and click GO
Page 222 of 341
ClearCase Environment – How do I
4. Select the ClearCase Word Integration check box and click OK
5. Restart Word.
6. Upon opening Word 2007, the Add-Ins Menu list will now appear on tool bar with ClearCase options included.
The following ClearCase Menu options will now be viewable:
Page 223 of 341
ClearCase Environment – How do I
187. How do I - remove the ClearCase integration with Microsoft Word
ClearCase 2003.06.00 and 7.0 Instruction on how to disable the Microsoft Office Integration can be found in the On-line Help files included with the product (Start > Programs > IBM Rational > IBM Rational ClearCase > Online Help)
Click Start > Run and type the following command. regsvr32 -u ccmsoaddin.dll
This removes the Rational ClearCase integration with Microsoft Office from your machine and unregisters the integration .DLL.
ClearCase 2002.05.00 In order to remove the integration you must remove the clearcase.dot file. This file is located in different places depending on what version of Windows is installed.
Page 224 of 341
ClearCase Environment – How do I Search for a file named clearcase.dot file on the Windows host.
The search will return at least two files.
One of the files will be located in the following directory:
C:\Program Files\Rational\ClearCase\bin.
Note: Do not remove the clearcase.dot file from the bin directory.
You will want to remove the clearcase.dot file from the following location
C:\Documents and Settings\
After you remove the clearcase.dot file from this path, close all Word applications. The next time you open Word the ClearCase option is gone from the Word menu. 188. How do I - disable the PowerPoint or Excel integrations with ClearCase Use the following steps to disable the integration: 1. Open Microsoft PowerPoint or Microsoft Excel 2. From the Tools drop-down menu, select COM Add-Ins... Note: COM Add-Ins... may not be on the Tools menu items. Follow the instructions below to add the COM Add-Ins... to the tools option. 3. Uncheck the Add-In related to the ClearCase Integration: ClearCase PowerPoint Integration
ClearCase Excel Integration
Page 225 of 341
ClearCase Environment – How do I
4. Click OK to exit out of the applet 5. This will remove the ClearCase menu bar item
Instructions to add the COM Add-Ins... item to the Tools drop-down menu: 1. From the Tools menu, choose Customize... 2. On the Commands tab, select Tools in the Categories pane (on the left) 3. From the Commands pane (on the right), scroll down and highlight COM Add-Ins...
4. Drag COM Add-Ins... from that dialog applet out to the Tools menu bar item and release.
5. Click Close to exit the Customize applet 189. How do I – understand why the ClearCase Menu option does not appear on the Menu Bar in Microsoft Word or Excel IBM® Rational® ClearCase® Menu option is not present on the Menu Bar in Microsoft® Word or Excel even though the Integration between the two applications completed successfully.
Cause
Page 226 of 341
ClearCase Environment – How do I There may be a conflict between another 3rd party plug-in or application which is not part of the Rational Toolset that is already integrated with Microsoft Word or Excel such as Acrobat PDF Maker and Adobe Acrobat.
Resolving the problem If possible, you will need to disable the other plug-ins or add-ins before integrating ClearCase and Microsoft Word or Excel. Since you will not notice this issue until the integration has already been completed, you need to do the following: 1. Open Microsoft Word or Excel 2. Select Tools > Templates and Add-ins 3. Locate the other application already installed and disable that specific add-in. The option in the GUI should appear similar to the one below:
Note: Depending on what version of Microsoft Word or Excel you are using the option to locate the plug- ins and add-ins might differ from the option stated above. Once the other add-ins have been disabled, close down Microsoft Word or Excel and re-open it. If the ClearCase Menu option still does not appear, than the other add-in will not only need to be disabled, but also un-integrated and completely removed from Microsoft Word or Excel. This issue has happened specifically with Acrobat PDF Maker and Adobe Acrobat. The instructions to manually remove Acrobat PDF Maker are below: Removing Acrobat PDFMaker If you experience problems with Acrobat PDFMaker, be sure to remove it before you reinstall it. To remove Acrobat PDFMaker from Office XP, delete the following items: The PDFMaker folder in Program Files \ Adobe \ Acrobat 6.0 The PDFMaker.dot file in Program Files \ Microsoft Office \ Office 10 \ Startup The PDFMaker.xla file in Documents and Settings\ [user name] \Application Data\Microsoft\Excel\XLSTART Note: Similar steps as those listed above need to be followed when removing any 3rd Party application that is integrated with ClearCase. 190. How do I – understand about ClearCase variables run within a batch file Cleartool commands that use variables fail when run from a batch file on Windows. The very same command functions properly when run outside of the batch file from a command prompt.
Example 1: cleartool find . -type f -exec "cleartool co -nc %CLEARCASE_PN%" -print
The command runs fine by itself from the command line but you get the following error when you try to run it from a batch file:
Page 227 of 341
ClearCase Environment – How do I cleartool: Error: Element pathname required. Usage: checkout | co [-reserved] [-unreserved [-nmaster]] [-out dest-pname | -ndata] [-ptime] [-branch branch-pname | -version] [-nwarn] [-c comment | -cfile pname | -cq | -cqe | -nc] [-query | -nquery] pname ... .\test2.h@@
Example 2: cleartool find . -nxn -vers "created_since(yesterday)" -exec "cleartool desc - fmt %u\t%c %CLEARCASE_XPN%" -print cleartool: Error: Bad command line: unterminated quoted string cleartool: Error: Can't exec "(null)": The operation completed successfully.
Cause In the context of a batch file, the % character has a special meaning, and is used to represent parameters passed to the batch file at run time. For this reason, when using the % character in a batch file to represent an environment variable (such as %CLEARCASE_PN% or %CLEARCASE_XPN%), it can be misinterpreted.
Resolving the problem The solution is to escape the % character by preceding each % with a second %. So the above command would now look like: cleartool find . -type f -exec "cleartool co -nc %%CLEARCASE_PN%%" -print Corrected command syntax for the error in Example 2 in symptom above: This following is an example of a command that failed and the change that made it work. Before (fails in batch file): cleartool find . -nxn -vers "created_since(yesterday)" -exec "cleartool desc - fmt %u\t%c %CLEARCASE_XPN%" -print After (works in batch file): cleartool find . -nxn -vers "created_since(yesterday)" -exec "cleartool desc - fmt %%u\t%%c %%CLEARCASE_XPN%%" –print 191. How do I - change the XML Diff/Merge Type Manager How to reconfigure the default IBM® Rational® ClearCase® XML type manager to use a 3rd party application to address UTF8 and other issues when using ClearCase diff merge tools.
Cause Defect APAR PK37578 was submitted to address problems using XML files in Microsoft® Visual Studio .NET projects.
Problem #1 When two different versions of an XML file have lines inserted into the same place, attempts to diff or merge to the base contributor results in an add-add conflict. This conflict in turn causes the xmldiffmrg tool to only allow the contributors from the base to be selected. A workaround is to use the text file diff merge (see Problem #2).
Example:
Note: Options 2 and 3 do not set the changes for those contributors. Only Option 1 reflects the selected change. Page 228 of 341
ClearCase Environment – How do I
Note: A similar problem occurs for delete-delete and modifiy-modify conflicts as well.
Problem #2 The algorithm used by xmldiffmrg is different than the text diff merge (cleardiffmrg). Currently xmldiffmrg parses one file at a time. While parsing the file it builds a tree and then uses a bottom-up approach to compare the tree to look for xml differences. The xmldiffmrg does not consider two different versions of the file with lines inserted into the same place (as seen in the example above) as a difference; however the text diff tool will.
Example: Contributor 2 and 3 were selected as the result using cleardiffmrg.
This work around is acceptable in most cases; however, problems arise when the XML file use UTF8 or other unicode types in the file. (See Problem #3.)
Problem #3 Using the text diff/merge tool as a workaround may solve the contributor issue, however, the text diff/merge tool does not work correctly with UTF8 character sets. So if your XML projects/files are configured to use UTF8 (or any type of Uni-Code) the text diff merge tool will not handle these files properly. Review technote 1150092 for more information about XML and the Windows 1252 encoding scheme as an example.
With all of these issues, how can you configure ClearCase to successfully diff and merge XML files?
Solution Change the type manager that is managing your XML file types to use a 3rd party XML Diff and Merge solution. KDiff3 is the XML diff/merge of choice selected in this example.
About KDiff3 (http://KDiff3.sourceforge.net/#news) KDiff3 compares and merges two or three text input files or directories KDiff3 shows the differences line by line and character by character KDiff3 provides an automatic merge-facility KDiff3 has an editor for comfortable solving of merge-conflicts Page 229 of 341
ClearCase Environment – How do I KDiff3 supports Unicode, UTF-8 and other file encodings o KDiff3 handles UTF8, windows-1251, windows-1252, ISO_8859-15, and some Japanese encodings. o Encoding auto detection for Unicode files with byte order mark "BOM" at the file start KDiff3 prints differences KDiff3 provides excellent performance results on large files. KDiff3 is easy to install and easy to use. KDiff3 runs on a variety of platforms o GNU/Linux with KDE3, o Any UNIX platform that is supported by the Qt-libs from Trolltech, o Microsoft Windows.
Configuring Native ClearCase to use KDiff3 Note: These instructions need to be implemented on every client that needs to diff and or merge XML files using this method. 1. Download and install KDiff3 from SourceForge (http://sourceforge.net/project/showfiles.php?group_id=58666) 2. Open the Type Manager map file with a text editor.
Note: The map file is located in the ccase-home-dir/lib/mgrsC directory.
Windows: C:\Program Files\Rational\ClearCase\lib\mgrs UNIX/Linux: /opt/rational/clearcase/lib/mgrs
Review the ClearCase Command Reference Guide on the topic of type_manager (cleartool man type_manager) for more information. 3. For any type manager that use xmldiffmrg, replace the xmldiffmrg executable with the path to KDiff3.
What need to be changed in the map file?
merge/compare -- CLI merge/compare xcompare/xmerge -- GUI compare/merge
Example: _xml2 compare ..\..\..\..\KDiff3\KDiff3.exe _xml2 xcompare ..\..\..\..\KDiff3\KDiff3.exe _xml2 merge ..\..\..\..\KDiff3\KDiff3.exe _xml2 xmerge ..\..\..\..\KDiff3\KDiff3.exe
Note: The mapfile uses a relative path from its current location to find the executable. In this example, KDiff3 was installed to the default directory on Windows (C:\Program Files\KDiff3) thus the relative path defined in the map file reflects as such. 4. Stop and Restart ClearCase
Configuring the ClearCase Remote Client (CCRC) to use KDiff3 Change directories to the CCRC install location > plugins > com.ibm.rational.clearcase.compare_merge.
Where
CCRC 7.0 on Windows Example: C:\Program Files\IBM\Rational\ClearCase\CCRC\plugins\ com.ibm.rational.clearcase.compare_merge.win32x86_7.0.1.CU02 Copy the KDiff3 executable from its installation path to the com.ibm.rational.clearcase.compare_merge.
Known Issues Native ClearCase Issue:
When updating ClearCase (patch, iFix, FixPack), the map file will be overwritten with every client update. As a result, a copy of this file will have to be maintained outside of the ClearCase directory and Page 230 of 341
ClearCase Environment – How do I replaced after each update.
CCRC Issue: When updating CCRC, the plug-in directory com.ibm.rational.clearcase.compare_merge.
Note: You can control when the updates occur by preventing CCRC from looking for updates automatically. This is done by clicking Window > Preferences > Install/Update > Automatic Updates and disabling automatic updates.
Once this is done, you can control when to look for, download and install CCRC updates.
Note: To obtain updates, click Help > Software Updates > Find and Install. Review technote 1196280 for additional alternatives.
DISCLAIMER: All references made to 3rd party applications in this document are referred to here as "the Program". IBM is not providing program services of any kind for the Program. IBM is providing the Program on an "AS IS" basis without warranty of any kind. IBM WILL NOT BE LIABLE FOR ANY ACTUAL, DIRECT, SPECIAL, INCIDENTAL, OR INDIRECT DAMAGES OR FOR ANY ECONOMIC CONSEQUENTIAL DAMAGES (INCLUDING LOST PROFITS OR SAVINGS), EVEN IF IBM, OR ITS RESELLER, HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
After installing and configuring KDiff3 (or 3rd party application of your choice) to work as the type manager for XML files, attempts to diff or merge XML files from native ClearCase or CCRC will result in a clean
KDiff3 screenshot:
Page 231 of 341
ClearCase Environment – How do I 192. How do I – use the ClearCase Automation Library (CAL) The ClearCase Automation Library (CAL) (referred to as CAL) provides a set of COM interfaces to ClearCase 4.0 or later on the Windows 32-bit platforms. These interfaces are intended both as an integration platform and also as an API that can be used to extend or customize ClearCase. CAL can also be used to develop stand alone applications, write scripts, or embed macros in other applications that interact with ClearCase on some level.
Perl When using Perl the Win32::OLE module is required. This module is furnished in standard with the free ActiveStates Perl for Windows distribution. After installing this module, normal COM interface can be used with the Perl Object Oriented programming way.
Example: use Win32::OLE;
my $cal_ct = Win32::OLE->new('ClearCase.ClearTool') or die "Could not create the ClearTool object\n";
my $cclsvob = $cal_ct->CmdExec('lsvob');
print "Here is the return of lsvob using the CAL interface in Perl:\n$cclsvob";
Visual Basic Examples:
Get a CAL object representing a ClearCase version (M:\view\vob\file@@\main\3), create the ClearCase.Application object, and then get the version from the Application object.
Dim CC as New ClearCase.Application Dim Ver as CCVersion Set Ver = CC.Version("M:\view\vob\file@@\main\3")
Note that the example uses an extended path to refer to the version. This is not a requirement. The same ClearCase contexts that work for cleartool operations or in GUI applications work in CAL as well.
For example, if the code were running from the directory M:\view\VOB, and the intention was to choose the version selected by the view, the example could have been coded as
Set Ver = cc.Version("file")
After execution Ver holds a CAL CCVersion object representing M:\view\VOB\file@@\main\3.
Now Ver can be used to query properties of the version.
For example, to print the version number of the version, use
MsgBox "Version Number " & Ver.VersionNumber
1. Create a pop-up of available views on a local host in VB:
Here is an example of using CAL to connect to the ClearTool object and issue an lsview -host; capture the output of the lsview in an array and then populate a list box with the values.
' Connect to the top-level ClearTool object Dim ClearTool As New ClearCase.ClearTool On Error Resume Next ' Issue a cleartool command using the IClearTool's default property (CmdExec) MsgBox "Output from CmdExec:" & vbCrLf & ClearTool("lsview -host
Page 232 of 341
ClearCase Environment – How do I 2. Add an existing file to source control. Note: This works on view private files that already exist 'Define a new cleartool Dim CC As New ClearCase.ClearTool 'For the return code Dim CT_error As String 'Check out the directory to be modified CT_error = CC.CmdExec("co -nc Z:\VOB_tag\dir1\dir2") ' Add element to source control CT_error = CC.CmdExec("mkelem -nc -ci Z:\VOB_tag\dir1\dir2\file.txt") 'check in the directory CT_error = CC.CmdExec("ci -nc Z:\VOB_tag\dir1\dir2") Note: The object used is of 'cleartool' type. This means that the command to run is sent to cleartool. In this example all path- and filenames are hard-coded. (No errors are trapped to keep the example as small as possible).
3. Applying a pre-existing attribute to a branch type The following example applies an existing attribute to the predefined "main" branch type. Tip: The key is to get the attribute type from the ClearCase VOB using the AttributeType() property.
' Connect to the top-level ClearCase application object Dim CC As New ClearCase.Application Dim VOB As CCVOB
' Get a VOB from the top-level ClearCase application object Set VOB = CC.VOB("\TestVOB1")
Dim AtType As CCAttributeType Dim Branch As CCBranchType
'Get an existing Attribute type. This attribute type MUST exist. Set AtType = VOB.AttributeType("FooBar")
'Get an existing branch type, note lack of leading backslash Set Branch = VOB.BranchType("main")
'Apply the attribute. AtType.Apply Branch, , "Test", True 193. How do I – understand the example of the Rational ClearCase Automation Library (CAL) from a Rational Rose script The Rational ClearCase Automation Library (CAL) is documented in one chapter of the ClearCase on-line help.
The Rational Rose Extensibility Interface (REI) is documented in one chapter of the Rose on-line help.
Both APIs can be used together from a Rose script or from an Automation-enabled program, to allow a user to customize the ClearCase commands that can be invoked from a Rose top-level or context menu.
The following example is a Rose script that shows how to use the CAL to invoke cleartool commands from a Rose Top Level menu.
The first step consists of creating an instance of the IClearTool interface with the instructions:
Dim CL As Object Set CL = CreateObject("ClearCase.ClearTool")
Then the following line issues a ClearTool checkout command and writes the output to the Rose log: roseapp.writeerrorlog CL("co -nc "+fullpath)
Here "fullpath" is a string representing the full path of one Rose .cat file. The above works because the interface IClearTool has one default method:
Function CmdExec(CommandString As String) As String that executes a ClearTool subcommand and returns a status message. Page 233 of 341
ClearCase Environment – How do I
There are many other ClearCase functions, besides those offered by ClearTool. To access these other functions, another object needs to be created:
Dim CC As Object Set CC = createObject("ClearCase.Application")
Given this object, it is possible to test, for example, if a file is already checked out, with the following logic:
Dim CheckedOutFile As Object 'ICheckedOutFile interface On Error Resume Next Set CheckedOutFile = CC.CheckedOutFile(fullpath) If Err.Number <> 0 Then 'the file was not checked out, so we can check it out roseapp.writeerrorlog CL("co -nc "+fullpath) Else roseapp.writeerrorlog fullpath+" was already checked out" End If
Putting it all together, the following subroutines check out selected .cat files:
'Option Checkout selected units Sub CheckOutUnit(CC As Object, CL As Object, theCU As ControllableUnit ) If (theCU.isControlled ) Then Dim fullpath As String fullpath = theCU.getFileName Dim CheckedOutFile As Object On Error Resume Next Set CheckedOutFile = CC.CheckedOutFile(fullpath) If Err.Number <> 0 Then roseapp.writeerrorlog CL("co -nc "+fullpath) Else roseapp.writeerrorlog fullpath+" was already checked out" End If End If End Sub
Sub CheckOutSelectedUnits Dim theModel As model Set theModel = roseapp.currentModel Dim theItems As ItemCollection Dim theitem As roseitem Set theItems = themodel.getselectedItems Dim theCU As ControllableUnit
Dim CL As Object Set CL = CreateObject("ClearCase.ClearTool") Dim CC As Object Set CC = createObject("ClearCase.Application")
Dim i As Integer For i = 1 To theItems.count Set theItem = theItems.getat(i) If theItem.canTypeCast(theCU) Then Set theCU = theItem.typecast(theCU) Call CheckoutUnit(CC,CL,theCU) End If Next i
End Sub
Note: The Save All Units option is meant to be used after having checked out all the units (CheckOut all Units option). If you do not check out the units, the message, "File unit_name.cat is write protected by the operating system" appears.
Page 234 of 341
ClearCase Environment – How do I The check in/check out status is not always refreshed in the Rose browser. Review technote 1128258 for more details.
194. How do I – understand the location of the ClearCase ClearQuest integration Perl triggers Version 7.0 Windows: 1. Open Windows Explorer and navigate to the directory where ClearCase is installed (by default C:\Program Files\Rational\ClearCase) 2. Open the lib\CQCC folder. 3. Read the contents of the README file
Note: The README file provides general information. Review the contents of the Perl modules (the files ending with .pm in that folder) for more detailed information concerning the trigger. UNIX and Linux: 1. Open a command windows and cd to the ClearCase installation directory (by default /opt/rational/clearcase) 2. cd to lib/perl5/CQCCTrigger/CQCC 3. Read the contents of the README file for instructions of using or modifying the Perl triggers. Version 2002.05.00 and 2003.06.00 Windows: 1. Open Windows Explorer and navigate to the directory where ClearCase is installed (by default C:\Program Files\Rational\ClearCase) 2. Open the lib\perl5\CQCCTrigger folder. 3. Read the contents of the README file
Note: The README file provides general information. Review the contents of the Perl modules (the files ending with .pm in that folder) for more detailed information concerning the trigger. UNIX and Linux: 1. Open a command windows and cd to the ClearCase installation directory:
2002.05.00: /usr/atria
2003.06.00: /opt/rational/clearcase 2. cd to lib/perl5/CQCCTrigger/CQCC Read the contents of the README file for instructions of using or modifying the Perl triggers. 195. How do I – understand central caching in the ClearCase and ClearQuest V2 integration What does central caching do in the IBM® Rational® ClearCase® and IBM Rational ClearQuest® v2 integration?
Central cache management A new optional configuration parameter (CQCC_CACHE_ROOT) enables storing the trigger information in a shared central cache directory rather than in the user's local directory. This central cache is required to support Rational ClearCase Remote Client servers and is an option in other situations to ensure that Rational ClearQuest transactions in association batches always are posted reliably. A new Rational ClearCase scheduler task provides a central cache manager that automatically scans for unposted Rational ClearQuest transactions and cleans up stale directories and files.
The CQCC_CACHE_ROOT configuration parameter changes the storage of the user's information between trigger calls from the local machine to a central cache location that you specify. Caching the information in a central directory tree has the following advantages: Facilitates administration of association batches ensuring that they are posted in a timely fashion and provide oversight of user errors (when error logging is enabled). Enables support of the integration on a Rational ClearCase remote client server where there are no "home directories" and hence is required for Rational ClearCase remote client deployment. 196. How do I - use the cleartool schedule command to run the Cache manager How can I use the IBM® Rational® ClearCase® cleartool schedule command to run Cache manager when using the v2 integration with IBM Rational ClearQuest®?
Page 235 of 341
ClearCase Environment – How do I Running the cache manager using the cleartool schedule command You can run the cache manager using the cleartool schedule command: 1. Ensure that the cache manager runs under the proper group.
On Microsoft® Windows®, the cache manager must run as a member of the Rational ClearCase group on the host computer.
On UNIX®, the cache manager must run as the root user, using the "su – username" command so that you are running as the root user with your own environment enabled).
2. Verify that the cache manager task is defined in the Rational ClearCase scheduler:
a. From a command-line interface, run this command:
cleartool schedule –get –tasks
b. Look for the Base CC/CQ Integration Central Cache Manager task.
3. Verify that the cache manager job is defined in the Rational ClearCase scheduler:
a. From a command-line interface, run this command:
cleartool schedule –get Look for the Daily Base CC/CQ Integration Central Cache Manager job. 197. How do I – understand the ClearCase could not get an object ID (OID), error when checking in a new element version when using the V2 Base ClearCase and ClearQuest integration issue The full error message is as follows:
Two possible resolutions the error, FATAL : ClearCase could not get an object ID (OID) for
Cause One possible cause for this error is that the Microsoft® Windows® System environment variable Path has been superseded by another path statement in the User environment variable Path. This could be caused by installation of new software. Specifically the %SystemRoot%\system32 statement cannot be accessed. This issue has also been known to occur as a result of the TMPDIR environment variable pointing to a directory that does not exist.
Another possible cause of this issue is the use of special characters in element names. This issue has been identified as a product defect and has been logged under APAR#PK32751, which has been resolved in ClearCase 7.0.
Resolving the problem Check to see if there are any suspicious path statements in Environment Variables > System variables > Path and be sure that the %SystemRoot%\system32... statements are near the beginning of the path. Also validate that the path defined in the TMPDIR environment variable points to a valid directory or a new directory which has been created for use with the TMPDIR environment variable. 198. How do I - setup the V2 ClearCase ClearQuest integration to list out all records on a check out or check in How do I modify the V2 IBM® Rational® CleaCase® and IBM Rational ClearQuest® integration to display all records when a Check out or Check in is performed.
The user performing the check out will only see the records that list the user as owner and in the Submitted, assigned, and Open state using the default configuration. Page 236 of 341
ClearCase Environment – How do I
If the user would like to see all records in any owned by any user when a check out or check in is done, the config.pl needs to be edited: 1. Open your config.pl in a text editor 2. In the CQShema(s) section update the following:
Change From # CQSchema(s): # A CQschema definition defines the important field names that # your local change request entities (record types) use. It also # defines one or two queries that are used by the trigger to # provide the QUERY option the end user sees, and the optional # restrictions checked before associations are made. See README # for more details
$s = &DefineCQSchema(NAME=>"MainSchema", ENTITY_LIST => "defect", RESTRICTIONS => "STANDARD");
$s->ChangeFieldMap(OWNER => "Owner", STATE => "State", ID => "id", HEADLINE => "Headline", PRIORITY => "Priority", SEVERITY => "Severity", RATL_MASTERSHIP => "ratl_mastership",
# Other mappable names QUERY_STATES => "Submitted,Assigned,Opened", MODIFY => "modify" );
$s->SetQuery("STANDARD", "
$s->SetResultSet("STANDARD", "
Change TO # CQSchema(s): # A CQschema definition defines the important field names that # your local change request entities (record types) use. It also # defines one or two queries that are used by the trigger to # provide the QUERY option the end user sees, and the optional # restrictions checked before associations are made. See README # for more details
$s = &DefineCQSchema(NAME=>"MainSchema", ENTITY_LIST => "defect", RESTRICTIONS => "STANDARD");
$s->ChangeFieldMap(OWNER => "Owner", STATE => "State", ID => "id", HEADLINE => "Headline", PRIORITY => "Priority", SEVERITY => "Severity", RATL_MASTERSHIP => "ratl_mastership",
# Other mappable names QUERY_STATES => "Submitted,Assigned,Opened", MODIFY => "modify" );
$s->SetQuery("STANDARD", Page 237 of 341
ClearCase Environment – How do I #"
$s->SetResultSet("STANDARD", "
M:\view\vob23>cleartool desc "new text document.txt@@\main\2" version "new text document.txt@@\main\2" created 2007-06-19T12:20:11-04 by user.clearcase@VITAL Element Protection: User : VITAL\user : r-- Group: VITAL\clearcase : r-- Other: : r-- element type: text_file predecessor version: \main\1 Hyperlinks: CrmRequest "defect" -> "v2_200000002"
UCM Integration desc output example:
M:\ucmCq_project_int\ucmCq_component>cleartool desc test.txt version "test.txt@@\main\ucmCq_project_Int\1" created 2007-06-11T15:24:37-04 by plabbe.clearcase@VITAL Element Protection: User : VITAL\user : r-- Group: VITAL\clearcase : r-- Other: : r-- element type: text_file predecessor version: \main\ucmCq_project_Int\0 Attached activities: activity:ucmCQ00000050@\ucmCQ_projectvob "This is an integration test" This is the result of additional switches must be added to the cleartool desc command to view the actual record ID.
Solution To display the Record ID of an element when using the Base V2 Integration of ClearCase and ClearQuest, use the following cleartool desc command:
>cleartool desc -s -ahlink CrmRequest "
M:\view\vob23>cleartool desc -s -ahlink CrmRequest "new text document.txt"
-> "v2_200000002" or
M:\view\vob23>cleartool desc -l -ahlink CrmRequest "new text document.txt" new text document.txt@@\main\2
Hyperlinks: CrmRequest@469@\paul23 "defect" -> "v2_200000002"
To display the Record ID of an element when using the UCM Integration of ClearCase and ClearQuest, use the following cleartool desc command: cleartool desc -fmt "%[activity:]%p"
ClearCase Environment – How do I
For example:
M:\ucmCq_project_int\ucmCq_component>cleartool desc -fmt "%[activity:]%p" test.txt ucmCQ00000050 200. How do I – understand conjunction junction, what's your function: more ClearCase integration strategies Though not, perhaps, as catchy as a Saturday morning cartoon, this latest article by Darren Pulsipher and Christian Buckley offers more useful tips about using ClearCase. "Command Line, Perl, and COM...they'll get you pretty far." This article was first published in May, 2002 and refers to ClearCase v2003 Conjunction Junction, what's your function? Hooking up words and phrases and clauses. Conjunction Junction, how's that function? I got three favorite cars That get most of my job done. Conjunction Junction, what's their function? I got "and", "but", and "or", they'll get you pretty far.
("Conjunction Junction" by Bob Dorough) Remember that old Saturday morning cartoon educational series "Schoolhouse Rock?" For many of us who grew up in the 1970s, those brief musical interludes were a memorable part of our adolescence. We came to know most of the songs and storylines, and were sometimes even able to apply them to our schoolwork. Each of the cartoons were only a couple minutes long, but each contained an important message -- from conjugating a verb, to the "ins" and "outs" of multiplication, to the legislative process of moving a bill through the American Congress -- and each episode drove home that message with a catchy (albeit, sometimes irritating) song. That's how we like to approach these articles -- a little repetition, some light humor (albeit, sometimes irritating), and a solid message that you can retain, and, hopefully, apply to your current -- and future -- projects. The goal of the Schoolhouse Rock cartoons, as we interpret it, was to provide a foundation in the basic components of grammar, math, and science. Think of these lessons as points of integration into the larger subject matter -- APIs, if you will. Through these educational snapshots, and by learning the basic protocols of each subject, we were able to make the connection to the larger data set and the wealth of learning opportunities behind them. Well, IBM® Rational® ClearCase® does not come with any cute cartoon characters performing songs and dancing (although I'm sure it has passed through the mind of someone on their marketing team), but they do offer a variety of points of entry into the tool. In fact, ClearCase, as we're sure you've come to realize, offers an enormous array of options and configurations. In previous articles, we've talked about the different integration points for ClearCase and other tools. We've tried to demonstrate many the different tools available in your tool chest -- from the "no-brainers" to the more complex/less deployed tools -- all of which can be integrated and configured to your heart's content. It's all about building the "perfect system," right? For those purists who are on the path to ClearCase enlightenment, there are really just two implementation approaches that can be used when integrating tools into your perfect system. And while we are not providing music to which our readers can sing along (we had trouble coming up with rhymes for things like "Perl module" and "ClearCase::CtCmd::exec"), we hope the integration message we share will come in handy down the road. To paraphrase the lyric above, "We got 'Command Line' and 'Perl' and 'COM', and they'll get you pretty far." Selecting your approach Well every person you can know, And every place that you can go, And any thing that you can show, You know they're nouns. A noun's a special kind of word, It's any name you ever heard. I find it quite interesting, A noun's a person, place, or thing.
("A Noun is a Person, Place or Thing" by Lynn Ahrens) The messages were so simple back then, but memorable. While ClearCase is slightly more complex than identifying a noun or an adverb, there are really just two approaches to implementation: wrapper scripts and triggers. And hey! "Wrapper" is both and adjective and an adverb! (sorry) Included below are a brief overview of each of these approaches, followed by a detailed view of how to implement your scenarios using command line, Perl, and COM, including the benefits, limitations, and an example of each. Feel free to sing along: Wrapper scripts This approach replaces the common commands that actors of your system use to get work done. This approach is commonly known as "helper scripts," and we have seen every kind imaginable -- everything from a simple view creation script that makes sure that view storage is always placed in the same area, to very complex defect tracking ClearCase integrations that use data from several different tools to automatically create views for users.
Page 239 of 341
ClearCase Environment – How do I Wrapper scripts are great for helping the user get their work done more effectively. However, they're not as useful when you're dealing with curious (i.e. control-freak) engineers who can't keep their hands off the hardware. This type of engineer is constantly cruising through "cleartool man" to find out ALL of the commands that you, the configuration management lead, have tried to hide from him by providing scripts to do everything. You just can't make some people happy. One way of controlling the curious engineers is to train them on the basics of ClearCase, and, more importantly, on the use model and philosophy of using ClearCase in your organization (a point typically forgotten, even among the most experienced CM managers). If they know why you are doing things, they are more apt to respect process and your management role. Triggers Another way to control engineers within the ClearCase environment is through triggers. In previous articles, we have discussed the different types of triggers and how they can be used to control process and to enforce the use model that you want your actors to follow. Triggers can also be used to coordinate information between multiple tools. Most of the coordination between tools should be handled with post-exec triggers, unless, of course, the behavior of a particular ClearCase command depends on the output of commands from another tool, such as those used in a defect tracking system. For more details on the many different types of triggers and their uses, check out our other articles entitled Trigger Happy: Overcoming Entropy in Software Development and Trigger Happier: More Tools for Overcoming Entropy in Software Engineering.
Implementation options Once you've finished singing, and have mapped all of the use cases within your system to one or both of these implementation approaches, it is time to make another decision -- how to implement your scenarios. Your first thought might be to just write the ClearCase commands using shell scripts or Window batch scripts. But before you jump, let's review the different options available for implementing your design: ClearCase command line interface, ClearCase Perl Module (CmdCt), and the ClearCase Automation Library (CAL). 1. ClearCase Command Line The ClearCase command line interface is robust, and allows any operation you can image with your ClearCase VOBs and views. Most systems have several scripts that use the command line interface to integrate systems together. Basically, if the user can type it on the command line, you can put it into a script. In addition, you can choose any scripting language you wish -- but be sure to choose a language that works on all of the platforms within your system. Perl tends to be the most popular scripting language for multi-platform system integrations. Benefits (pros) The benefit of using this approach is that it is simple and straightforward. You can quickly prototype your script by first typing it on the command line. Most of the time you'll find that scripts are written by individual users for those repetitive tasks that have to be done day in and day out. "Progress has not followed a straight ascending line, but a spiral with rhythms of progress and retrogression, of evolution and dissolution." (Johann Wolfgang Von Goethe) With this option: All ClearCase operations are available It is easy to prototype Mimics the user's calls to ClearCase commands Limitations (cons) Although there are many benefits to writing scripts that just call command line interfaces, there are also some downsides to using the command line: Command line interfaces can, and likely will change Error handling is basically pass or fail Reasons for failure must be parsed from the stderr and stdout. This can change from one release to another Querying for information from ClearCase requires some parsing of stdout and stderr Example Issuing a cleartool command (cleartool) $theResults = `cleartool lsview`; if($!) { die("cleartool returned error: $@\n" . $theResults); } print $theResults, "\n"
In this simple example, the stdout and stderr are both in $theResults. In order to separate them, you will have to set up file descriptors to handle the different streams of information. It is better handled using the ClearCase Perl Module, which separates these out for you. 2. ClearCase Perl Module (CtCmd) Page 240 of 341
ClearCase Environment – How do I IBM Rational Software recently released a ClearCase Perl Module that can be downloaded from Rational or from www.cpan.org. This allows Perl script writers to access the ClearCase commands directory, and gives you better access to error codes and error handling. The Perl module basically consists of one sub to allow scripts to call cleartool commands -- ClearCase::CtCmd::exec. The ClearCase::CtCmd::exec() subroutine takes either a string or a list as an input argument, and returns a three-element Perl array as output. The first output element is a status bit containing 0 on success, 1 on failure. The second output element is a scalar string corresponding to stdout, if any. The third element contains any error message corresponding to output on stderr. Benefits (pros) If you are already focused on multi-platform solutions, or if you are already using Perl as your scripting language, this module handles the error handling more efficiently for you. Handles most of the cleartool command options Simplifies error handling over the standard calling ClearCase commands Easy to prototype, much like the cleartool command line option. You can write the exact command that the user make use of in the string passed to exec. Limitations (cons) The limitations of this option are very similar to the limitations of the cleartool command option. However, because of the implementation of the Perl Module, there are some additional limitations: You cannot use "-ver" and "-verall". Options on any commands All single characters preceded by a hyphen must be quoted Other Perl characters such as "%,@, and $" must be quoted The output still needs to be parsed to get data for which you are querying. Example (Taken from examples in the CtCmd documentation.) Issuing a cleartool command (CtCmd) use ClearCase::CtCmd;
@aa=ClearCase::CtCmd::exec("lsview"); my $status_now = $aa\\\[0\\\]; my $stdout = $aa\\\[1\\\]; my $error = $aa\\\[2\\\]; die("Cleartool returned error: ", $error, "\n") if($status); print $stdout, "\n";
3. CAL (ClearCase Automation Library) COM Interface Finally, the ClearCase Automation Library is a COM interface that allows you to access and manipulate ClearCase data on Windows platforms ONLY. This will not work on UNIX platforms, so make sure that the scripts you write with the CAL only need to run on a Windows machine. You can use CAL to write scripts, stand-alone programs, or macros embedded in other applications. The CAL approach does not deal with the command line interface at all, and gives you access to objects in the VOB. This approach means that you can manipulate ClearCase in ways that the command line may not readily allow. This can decrease the execution time to run your programs, and gives you better control of your data. For a great introduction to this interface, take a look at Mark McLaughlin's article Saying Hello to CAL (the ClearCase Automation Library): The ClearCase COM Interface Isn't So Scary After All. Benefits (pros) Error checking is more exact No need to parse the output of stdout or stderr. You can work with the objects directly Queries can be more exact and decrease the amount of time to run Integration with other tools that run on Windows boxes can be tightly integrated Multiple languages can be used to implement solutions Single commands can be written that would normally take several command line commands Scripts don't need to change as the output of commands change. It is less likely that the API will change than the output of running the commands Limitations (cons) Windows platform only! Common commands may require more code than just calling the cleartool command There is definitely a learning curve. The object model is much harder to get your head around than the cleartool command set and options Does not provide access to all ClearCase functionality. For example, with CAL: o You cannot create VOBs o You cannot access build capabilities o You cannot access view profiles Page 241 of 341
ClearCase Environment – How do I o You cannot get properties or perform operations on symbolic links or derived objects Limited to operations that cleartools and the ClearCase GUI can perform CAL runs as an in-process COM server; it is not a DCOM application Examples (Examples taken from the CAL documentation) Issuing a cleartool command (Perl) # The syntax used here was compatible with ActiveState build 522. use Win32::OLE; # Connect to the top-level ClearTool object my $ct = Win32::OLE->new('ClearCase.ClearTool') or die "Could not create ClearTool object\n"; $output = $ct->CmdExec("pwvlsview") or die("Cleartool returned error: ", Win32::OLE->LastError(), "\n"); print $output;
Displaying information about all branches sprouting from a version (Perl) use Win32::OLE; # Connect to the top-level ClearCase object my $cc = Win32::OLE->new('ClearCase.Application') or die "Could not create Application object\n"; # Loop over the branches sprouting from a version and display their # paths using the default property of ICCBranch, and other information my $ver = $cc->Version("b:\\caroltest\\testelem.c@@\\main\\0") or die("Could not get version: ", Win32::OLE->LastError(), "\n"); my $path = $ver->Path; my $subbranches = $ver->SubBranches; my $enum = Win32::OLE::Enum->new($subbranches); while (defined(my $branch = $enum->Next)) { print($branch->Path, " branch sprouting from ", $path, " has ", $branch->Versions->Count, " version(s); latest version is ", $branch->LatestVersion->VersionNumber, "\n"); }
Taking the Next Step I'm just a bill, Yes, I'm only a bill, And I'm sitting here on Capitol Hill. Well, it's a long, long journey To the capital city, It's a long, long wait While I'm sitting in committee, But I know I'll be a law someday... At least I hope and pray that I will, But today I'm still just a bill.
("I'm Just a Bill" by Dave Frishberg) Are you finding your next few tasks a little daunting? The key to any new development effort, as with the messages embedded within each of the Schoolhouse Rock clips, is to keep things simple. How do you keep it simple? Well, we recommend you start by approaching your project with "baby steps". Take some time to understand each of your implementation options, do some reading (the Rational area of Developerworks is a great place to get started), and don't be afraid to ask questions. Like the little bill sitting on capital hill, building your "perfect system" takes time and patience. And if you find yourself trying to sway your project team (or members of Congress) on certain aspects of your proposed solution, just remember -- it's all about baby steps. "The reason men oppose progress is not that they hate progress, but that they love inertia." (Elbert Hubbard) So understand your options, take baby steps, and build some inertia. Once you've made some progress, maybe your team will accept the fact that you break out in song every so often. 201. How do I - have 2 VOBs on the same machine accessing different ClearQuest databases When using the Base integration between ClearCase and ClearQuest on Windows, there is only one trigger set up, this trigger points to only one database. It is possible to set the integration up so that 2 VOBs are linked to 2 different databases: 1. The Windows trigger must be set to V2-PERL. When using this option, the integration parameters are defined in a perl file called config.pl, available under:
Page 242 of 341
ClearCase Environment – How do I 4. Then select the second VOB: VOBName2. Choose V2 as Windows Trigger Selection and change CQCC\config.pl to CQCC\config_VOBName2.pl. You can now customize those Perl files so that they access whichever database you want and associate whichever record type(s). 202. How do I - change the source control provider to ClearCase How do I change my source code control (SCC) provider on Microsoft® Windows® to IBM® Rational® ClearCase® if two or more SCC compliant providers are installed?
Answer Note: This solution contains information about modifying the system registry. Before making any modifications to the Microsoft® Registry Editor, it is strongly recommended that you make a backup of the existing registry. For more information describing how to back up the registry, refer to the Microsoft Knowledge Base article 256986.
Change Source Code Control Providers To change source control providers, follow these steps: 1. Open Registry Editor (Click Start > Run type regedit) 2. In the Registry Editor, expand the following registry key:
HKEY_LOCAL_MACHINE\SOFTWARE\SourceCodeControlProvider\InstalledSCCProvide rs 3. In the right pane, double-click the registry key of the source control provider that you want to use (for example, ClearCase), and then copy the data of this key to the clipboard (for example, Software\Atria\ClearCase). 4. In the left pane, click SourceCodeControlProvider. 5. In the right pane, double-click ProviderRegKey. 6. In the Edit String dialog box, replace all of the text in the Value Data box with the contents of your clipboard, and then click OK. 7. Close the registry editor. 8. Restart your application for the changes to take effect. 203. How do I – understand the unable to read registry value: Software\Atria\ClearCase\SCCServerName issue Why do attempts to connect IBM® Rational® ClearCase® to an Integrated Development Environment (IDE) through the Source Code Control (SCC) interface on Microsoft® Windows® results in the error Unable to Read Registry Value: Software\Atria\ClearCase\SCCServerName and provides instructions to resolve the issue.
Cause The registry value is defined properly but the security permissions are too restrictive.
Resolving the problem The security permissions on the registry value must be open enough to allow the user read access in order for the IDE to read the value and connect to ClearCase properly. To correct the problem, perform the following steps: 1. Log on to the client host as a user with local administrative privileges. 2. Click Start > Run > type regedt32 Note: regedit will not allow you to edit the registry value security permissions; you must use regedt32. 3. Navigate to the HKEY_LOCAL_MACHINE/Software/Atria/ClearCase registry key. 4. Click the SCCServerName value. 5. Click the Edit > Permissions... menu choice. 6. Click Add 7. Type: Everyone and in Enter the object names to select entry field. 8. Click Check Names 9. Click OK 10. In the Permissions for Everyone entry field, click Allow on the Read permission. Note: Full Control can also be allowed but the minimum access level must be Read 11. Click OK and close the Registry Editor. 204. How do I – understand about SCC compliance and Rational ClearCase SCC is an acronym for Source Code Control. The SCC API is an interface specification, defined by Microsoft® that defines hooks for a number of common source control operations.
Page 243 of 341
ClearCase Environment – How do I An application (typically an "integrated" development environment (IDE) of any kind) can provide source control functions without implementing the functions itself. If an SCC compliant code control system is installed, the application dispatches code control operations to the source control tool (e.g. Visual Studio > ClearCase). ClearCase on UNIX®, Linux® and Microsoft Windows® is compliant with the SCC standards. This means that any application that is SCC compliant should be able integrate with Rational ClearCase on a basic level; however, this does not mean that IBM Rational supports this integration. For any IDE that claims SCC compliance, but does not have a supported integration with ClearCase, please defer all problems and questions to the support team of the IDE vendor. An example of a non-ClearCase supported SCC integration is detailed in technote 1243448. 205. How do I - enable SCC trace operations with ClearCase To trace a problem with a supported SCC integration with Rational ClearCase, follow these instructions: Note: The following directions require you to edit the registry using the Windows Registry Editor. However, editing the Windows Registry incorrectly can cause serious problems that may require you to reinstall your operating system. Use Registry Editor at your own risk. Before proceeding review the Microsoft KB article, KB256986 - Description of the Microsoft Windows Registry. 1. Open Windows registry editor (Start > Run type regedit) 2. Navigate to the Key:
HKEY_CURRENT_USER\Software\Atria\ClearCase\CurrentVersion\ 3. If there is no subkey named SCC, create one (Edit > New > Key) 4. Add a new DWORD Value (Edit > New > DWORD value) a. The Value name must be DebugTrace b. The Value data (hexadecimal) must be one of the following values: 0 - No messages are output anywhere 1 - Messages to Source Control window only 2 - Messages to
Note: This is a completely dynamic piece of code, so a change to the registry value will be picked up as soon as a new piece of ClearCase integration code is activated.
If initialization debug information is needed and the IDE is already running after the registry key is set, restart the IDE to collect the necessary debug information. Review the related information below for more details about SCC compliance and Rational ClearCase. ClearCase context menus 206. How do I – understand why Menu Choices cannot be added or modified in ClearCase 7.1 Context Menu Editor This technote identifies a defect that can occur in IBM Rational ClearCase 7.1 where menu choices cannot be added or modified using the Context Menu Editor.
Symptom In the ClearCase 7.1 Context Menu Editor when attempting to add [New...] or modify [Properties...] a Menu Item from Available Menu Choices, the Command Type field is blank, and the drop-down list of values is just several blank lines.
Page 244 of 341
ClearCase Environment – How do I
Since Command Type is a mandatory field for a Menu Item, the [OK] button never goes active.
Cause This issue has been identified as a product defect under APAR PK82891.
Diagnosing the problem Steps to Reproduce: 1. Open the Context Menu Editor: Click Start > Run > type clearmenuadmin.exe 2. Under the Available Menu Choices click [New...], or highlight an existing item and click [Properties...] Resolving the problem Page 245 of 341
ClearCase Environment – How do I There is currently no resolution for this defect. WORKAROUND To workaround this problem: The Context Menu Editor can be used to import customizations done in earlier versions of ClearCase. 1. If you have ClearCase 7.0.x available, create a customization file from there using the Menu Editor and save the file:
Configuration > Save to File... On the ClearCase 7.1 client do the following to import the customization file:
Configuration > Load from File ... 207. How do I – customize the ClearCase Windows Interface ClearCase on Windows presents the ability to customize the graphical user interfaces of Windows Explorer and ClearCase Explorer.
The tool that allows you to change the behavior of existing dialog boxes in Windows and ClearCase Explorer is ClearCase Context Menu Editor (tool called clearmenuadmin typical found in C:\Program Files\Rational\ClearCase\bin\clearmenuadmin.exe) which is available on all ClearCase Windows installations.
With the Context Menu Editor it is possible to: Create new commands and other menu items available to ClearCase context menus. Change properties of built-in and custom ClearCase context menu items. Add items to or remove items from ClearCase context menus. Test the changes to ClearCase context menus. How to Display the Context Menu Editor To display the Context Menu Editor click Start > Run type clearmenuadmin Below is a screenshot of the basic interface of the tool. This document will give some basic guidance of the tools potential and will help define some common terminology.
Creating a new context menu choice First select the application for which the command shortcut will appear. In our example we will work on a shortcut for Windows Explorer.
Page 246 of 341
ClearCase Environment – How do I
Defining Object Type and State You must define an Object Type and Object State, these determine the context or conditions the menu choice will be available to users.
We will define that our command shortcut for notepad will be available on file objects that are checked in and we will assume the user will only select one (single selection) at a time. Note: Multiple Selection Specifies that the shortcut applies only to multiple selections of the object type and state indicated.
Defining Menu Item Properties
Under available menu choices, click the New button. You will be presented with the Menu Item Properties dialog box.
The Menu Item Properties dialog box defines the following shortcut menu command properties: Menu Text: The label that appears in the shortcut menu item. Help Text: Brief information about the menu item. Command Type: The type of program that the shortcut invokes, Command type Description About Dialog Opens an About dialog box CheckItem Check box with label Executable Starts the executable named in the Command box Executable/Regentry Starts the executable that is the value of the Registry key named in the Command box OLE Automation Uses OLE automation Separator Separator Command: The path (including the file name) of the program that the shortcut executes. Initial Directory: The directory that is set as current when the program runs. Arguments: Arguments to be passed to the program when it runs. Comment: A comment for the shortcut. In this example we will create a very simple context menu shortcut that will allow users to display the contents of text files. Modify the Menu Item Properties dialog box with the following information.
Page 247 of 341
ClearCase Environment – How do I
Click OK After the dialog closes, you should see the new menu shortcut "FileContents" presented in the Available Menu Choices list. This context menu is not yet implemented.
The shortcut isn't in bold type; bold menu items are available and will be on the “This Menu Contents” list to the left. You can add and remove menu options using the Add or Remove buttons. The below illustration indicates that the new Menu Choice "FileContents" has been added (as it is in the Menu Contents on the left and is now in bold type).
Implementing a Context Menu Shortcut.
Page 248 of 341
ClearCase Environment – How do I To have a context menu show up, you need to apply the configuration. This will modify the Windows registry on the local computer
Sharing context menu configurations Exporting menu changes to a distributed group If you need to implement this context menu against many users instance of ClearCase this can be accomplished by distributing a registry file (.reg) that can be generated using the options in the tool Configuration > Save to File… Importing menu changes If you need to introduce a pre-defined menu configuration, Import the changes from a generated Windows Registry key Configuration> Load from File … 208. How do I - change ClearCase context menus without loading an export file HKEY_CURRENT_USER\Software\Atria\ClearCase\CurrentVersion\ContextMenus
There are 2 subkeys to this:
MsExplorer -- Windows Explorer Context menus. DetailsView -- ClearCase Explorer (formerly known as ClearCase Details) Context menus.
The .reg file saved through the ClearCase Menu Admin GUI was not designed to be auto-applied to both sections for the current user: It puts the data in HKEY_LOCAL_MACHINE versus HKEY_CURRENT_USER. This permits the customization to be set up for future users, but will not affect a user whose profile has already been set up. It only contains one or the other of the 2 categories of context menus. It will not save both sets -- Windows Explorer and ClearCase Details -- of customizations in one file.
As a result, the .reg file has to be edited to make the settings work for a given user. To make the changes apply to the current user, for both the Windows Explorer and the ClearCase Explorer, perform the following operations on the registry import file created by clearmenuadmin: 1. Edit the .reg file and replace all instances of HKEY_LOCAL_MACHINE with HKEY_CURRENT_USER 2. Copy and paste the keys saved in the .reg file and edit the key path changing MsExplorer to DetailsView (or vice versa). 3. Create a "String" value named "HKEY_LOCAL_MACHINE\Software\Atria\ClearCase\CurrentVersion\ContextMenus\Configured" and set the value to "TRUE". This is needed to tell the ClearCase explorer and Windows Explorer "shell extension" that custom menus are in use.
The resulting .reg file would look something like this:
------snip ------REGEDIT4 Page 249 of 341
ClearCase Environment – How do I
[HKEY_LOCAL_MACHINE\SOFTWARE\Atria\ClearCase\CurrentVersion\ContextMenus] "Configured"="TRUE"
[HKEY_CURRENT_USER\Software\Atria\ClearCase\CurrentVersion\ContextMenus\DetailsView]
[HKEY_CURRENT_USER\Software\Atria\ClearCase\CurrentVersion\ContextMenus\DetailsView\MenuTable ]
[HKEY_CURRENT_USER\Software\Atria\ClearCase\CurrentVersion\ContextMenus\DetailsView\MenuTable \11] "Text"="Compare..." "HelpText"="Compare the selected item with other versions or files." "DoHelpSubst"="FALSE" "DispType"="Executable" "Exe"="cleardlg" "Params"="/diffother $filelist" "DirParams"="$Dir" "ShowDlg"="FALSE" "Comment"="Test #2"
[HKEY_CURRENT_USER\Software\Atria\ClearCase\CurrentVersion\ContextMenus\MsExplorer]
[HKEY_CURRENT_USER\Software\Atria\ClearCase\CurrentVersion\ContextMenus\MsExplorer\MenuTable]
[HKEY_CURRENT_USER\Software\Atria\ClearCase\CurrentVersion\ContextMenus\MsExplorer\MenuTable\ 11] "Text"="Compare..." "HelpText"="Compare the selected item with other versions or files." "DoHelpSubst"="FALSE" "DispType"="Executable" "Exe"="cleardlg" "Params"="/diffother $filelist" "DirParams"="$dir" "ShowDlg"="FALSE" "Comment"="Test #2" ------snip ------
Please note that a more complex entry would have a larger number of added items, and a custom menu table.
The steps are identical regardless of the complexity of the context menu items being created.
Once the registry files are created, changing context menu sets is a simple matter of launching the reg file and saying "yes" to the prompt... clearprompt 209. How do I – understand the supplement to the Command Reference Guide about clearprompt The ability to create prompts that have new lines is different on Windows than on UNIX and Linux. The following example illustrate how to create prompts with new lines.
Note: Documentation defect APAR IC48978 has been submitted to have the example added in the Reference Guide.
Windows: clearprompt proceed -prompt "Line1\nLine2\nLine3" -newline
Note: For multiple lines - keep inserting \n for line-breaks wherever required.
Example: clearprompt proceed -prompt "Line1\nLine2\nLine3" -newline
Page 250 of 341
ClearCase Environment – How do I
UNIX and Linux: clearprompt proceed -prompt "Line1 Line2 Line3" -pre
Documentation 210. How do I – use the ClearCase Information Centre There is a new IBM® Rational® ClearCase® Information Centre (March 2007). With the information center, you can view, browse, and search on-line information related to the ClearCase product family. Try it out today!
Information Centers provide a powerful on-line interface for finding technical information on a particular product, offering, or product solution. The Information Centers are designed to: Help you plan, install, configure, use, tune, monitor, troubleshoot, and maintain the product Contain reference material such as product commands, parameters, and system values Note: The information centre is built upon open source software developed by the Eclipse Project. You can access the ClearCase 7.0 Information Center through the ClearCase Support Web Page (as seen in the below illustration):
Page 251 of 341
ClearCase Environment – How do I
Note: Language of the content displayed in an information center is determined by the Language setting in your browser, if the content is available in that language. From the Information Center, all the major documentation for version 7.0 of ClearCase, ClearCase LT and ClearCase MultiSite can be accessed.
Review the information in the Using this information centre section to find out how to make this new technology work best for you. Temporary files and (.)dot files 211. How do I – understand the temporary files created by ClearCase What are those temporary dot files in my IBM® Rational® ClearCase® view and what should be done with them?
Answer During certain operations ClearCase creates temporary files with particular name extensions. The following is a list of the most common temporary files you may see in your view from time to time. Note: All of these files are view-private files. .mkelem Files being added to source control from the GUI will use this extension during an "Add to Source Control" operation. If you see this file in your view during the mkelem process, that is OK. If you still see the file after the mkelem operation is complete, that is not ok. You will likely need to rename the file (remove the .mkelem extension) and add it to source control again. This can be seen when your antivirus software is scanning the mvfs. Refer to technote 1149511 Support Policy for Anti-Virus and ClearCase for further information. .checkin These are files you may see either in the middle of a checkin process or they may have been left over after cleartool checkin -from in older ClearCase versions (2002.05.00 and prior). .contrib These files contain the saved contents of a merge operation. The .contrib files are generally used to compare the file's previous contents with its new after-merge version. They can be safely removed from your view. See technote 1322745 for information About removing .contrib files that were mistakenly added to source control. .keep Optional files created which saves a copy of the version prior to uncheckout. They can be safely removed from your view. .loading These files represent the transition of elements being loaded into a snapshot view. If you see these files in your view, it is recommended that you remove them and update the view again to obtain any versions that were not properly loaded. .merge These files are created in the process of a merge and are used to resolve merge conflicts. They can be safely removed from your view. .unloaded Files with this extension contain a list of the files removed from a snapshot view. They can be safely removed from your view. .hijacked If you hijacked a version that is not the latest version in the VOB, a subsequent checkout .checkedout operation prompts you to merge the hijacked file with the newer version in the VOB (see Hijacked version may not be the latest version). This results in the renaming of the hijacked file to
ClearCase Environment – How do I
Related information Explanation of .contrib files in UCM About .being-deleted files in the cleartext pool 212. How do I – understand about .dmp files in the ClearCase log directory Dump (*.dmp) files are created as of ClearCase 7.0 and later for the purposes of assisting Support with specific ClearCase issues. The dump files are generated for different reasons. Some are created due to any unhandled exception of albd_server (parent) process. For example view_server.1482.dmp. Some are created as a result of the child process (of the albd) failing. For example cccredmgr.3096.dmp.
The naming convention of the dump file is as follows:
C:\Program Files\Rational\ClearCase\var\log
These files range in size (depending on the nature of the information collected for the given process). There is a ClearCase task that can manage the cleanup of these dmp files on a weekly basis. The task of cleaning up these dump files is stored in the job titled Weekly Local Tasks.
The Weekly Local Tasks Job calls the ccase_wk.bat script and when run will remove any dump files in the log directory. Note: The Weekly Local Tasks Job is not scheduled by default. It must be manually enabled to perform this task.
WORKAROUND: In the event your server is running low on disk space and these dump files are accumulating at a rate where the cleanup needs to be run more frequently than a week, the following workaround can be implemented to help alleviate the stress on the server.
To cleanup the .dmp files more frequently than a week, add the following code into a batch file and schedule it using the ClearCase or Windows scheduler:
DISCLAIMER: All source code and/or binaries attached to this document are referred to here as "the Program". IBM is not providing program services of any kind for the Program. IBM is providing the Program on an "AS IS" basis without warranty of any kind. IBM WILL NOT BE LIABLE FOR ANY ACTUAL, DIRECT, SPECIAL, INCIDENTAL, OR INDIRECT DAMAGES OR FOR ANY ECONOMIC CONSEQUENTIAL DAMAGES (INCLUDING LOST PROFITS OR SAVINGS), EVEN IF IBM, OR ITS RESELLER, HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. del /q /f "%CLEARCASEHOME%\var\log\*.dmp" >NUL: 2>&1 Page 253 of 341
ClearCase Environment – How do I 213. How do I – understand the .PID file The .pid file is located in the VOB and View storage directory. On UNIX and Linux the .pid is a one-line text file that lists the process ID of the VOBs or Views associated processes. On Windows the .pid is a place holder file for memory that tracks the process ID of the VOBs or Views associated processes.
Example: (View on UNIX) %> ls -al /net/host1/viewstore/view1.vws total 28 drwxr-xr-x 6 jdoe clearuser 512 Mar 9 14:40 . drwxrwxrwx 21 root other 512 Mar 21 07:20 .. -r--r--r-- 1 jdoe clearuser 436 Dec 28 14:02 .access_info drwxr--r-- 3 jdoe clearuser 512 Apr 5 04:30 admin -rw-r--r-- 1 jdoe clearuser 221 Jul 26 2005 .compiled_spec -rw-r--r-- 1 jdoe clearuser 44 Jul 26 2005 config_spec drwxr-xr-x 2 jdoe clearuser 512 Apr 5 04:30 db -r--r--r-- 1 jdoe clearuser 6 Jul 26 2005 .hostname drwx------2 jdoe clearuser 512 Apr 5 04:30 .identity -rw-r--r-- 1 jdoe clearuser 7 Mar 9 14:40 .pid -r--r--r-- 1 jdoe clearuser 373 Jul 26 2005 readme.txt drwxr-xr-x 59 jdoe clearuser 1024 Apr 5 04:30 .s -r--r--r-- 1 jdoe clearuser 80 Jul 26 2005 .view -rw-r--r-- 1 jdoe clearuser 2 Mar 9 14:41 view_db.state Note: To view the contents of the .pid on UNIX, use the cat command. Example:
%> cat /net/host1/viewstore/view1.vws/.pid 18763
Example: (VOB on Windows)
C:\>dir \\host1\ccstg_e\VOBs\my_test_vob.vbs Volume in drive \\host1\ccstg_e is Secondary Volume Serial Number is FC87-7DF3
Directory of \\host1\ccstg_e\VOBs\my_test_vob.vbs
04/05/2006 09:53 AM
Note: Attempts to read an active .pid file on Windows will result in the following error:
C:\>type \\host1\ccstg_e\VOBs\my_test_vob.vbs\.pid The process cannot access the file because another process has locked a portion of the file. BACKUP CONSIDERATIONS: Depending on how your backups are run, access errors may be reported during attempts to back-up or copy the .pid file. This can be ignored as the file is recreated when needed and does not require to be backed-up.
Page 254 of 341
ClearCase Environment – How do I Virtualisation 214. How do I – understand that Clearlicense -hostid may return invalid results on Red Hat Linux if XEN kernel is running This technote identifies an issue that can occur in IBM Rational ClearCase (CC) where clearlicense -hostid may return invalid results on Red Hat Linux if XEN kernel is running.
Symptom When attempting to set up a license server on a Red Hat Enterprise Linux server running the XEN kernel, license keys may not be generated correctly using the output of the "clearlicense -hostid" command. When the XEN kernel is in use, the output of "clearlicense -hostid" will be a string that includes the output of the "hostid" command instead of the hardware address of the first physical network card. Licenses generated using that output will not function reliably.
Cause This issue has been identified as a product defect, APAR PK77799
Resolving the problem There is currently no resolution for this issue.
WORKAROUND The known workarounds include: 1. Reinstall the server OS, being sure to disable kernel Virtualization support. This will ensure that the license server is not running an XEN kernel. 2. Boot the license server using a non-xen kernel. Note: License keys generated using the output of "ifconfig -eth0" appear to work in limited testing, but this is not currently the recommended solution as the testing was very limited. 215. How do I – understand ClearCase Licensing and the MAC address on virtual machines ClearCase is supported on virtual machines; however, it is not recommended to use a virtual machine as a license server since the MAC address, which is used to generate a ClearCase License, could change. If the MAC address does not match the virtual machine network card, then the ClearCase licenses for that host will no longer work. If you are using a virtual machine as a license server, it may be important to understand how ClearCase determines the MAC address used to generate a ClearCase license.
ClearCase checks each interface it finds until one returns with no error.
In some cases this operation will succeed but return zero for the MAC address (which is known to occur with virtual machine specifically on the s390 and zLinux platforms but can be on others as well).
If this happens, ClearCase will generate a MAC address by attempting to return a stable host identifier for the current system that is similar to the IEEE 802.3 MAC address.
The intent is that if this node does not have a MAC address for some reason (which may be the case when running a virtual machine on s390 or zLinux), then this id can be used to generate a ClearCase license string.
Note: Since the MAC address generated by ClearCase under these circumstances is not guaranteed to be unique like the hardware MAC address, it may have more of a chance of colliding with some other node. For the purposes of generating a ClearCase license in a vast majority of configurations, the likelihood of collision is small; however, in the cases where nodes collide impacting the MAC address generated by ClearCase, you will be required to generate new license keys.
Guest operating systems on virtual machines used as a license server may also fall victim to problems when the IP address or hostname changes. If ClearCase has generated a MAC address based on the logic above, then a change to the IP address and or hostname will result in ClearCase generating a new MAC address, thus DHCP on VMs used as a license server would be problematic. 216. How do I – understand why the Linux Virtual server clients report errors after VOB server crashes or is rebooted Following a VOB server crash or reboot, the following symptoms are experienced: Users on a virtual server client boxes (in this case running LINUX) experience errors creating elements (and possible other situations not founded yet) such as the following:
Page 255 of 341
ClearCase Environment – How do I $ cleartool mkelem -c "CR 21801 adding new lv cache cleaner" lv_cache_cleaner.ksh text_file_delta: Error: Unable to open file "/vobstore/hicrlv.vbs/s/sdft/27/2f/tmp_4875.1": Operation not permitted cleartool: Error: Type manager "text_file_delta" failed create_element operation. cleartool: Error: Unable to create element "lv_cache_cleaner.ksh".
Cause When dealing with a "virtual server" configuration, especially with the linux OS, you have to reboot systems in the right order because of any NFS mounting in place (e.g., /vobstore).
Resolving the problem Option 1 1. Shutdown the client box (in this case, the virtual server running Linux) first.
2. Then, you reboot the VOB server.
3. After a successful reboot, then you startup the virtual box remount, and restart ClearCase.
Important Note: You must do all the work for the virtual box from the console and NOT from an ssh session, like coming in using Putty.
Option 2 Note: This is another scenario worth noting that may work, but is not as proven.
If you know the VOB server needs to be rebooted (a non-crash scenario of course), followup these steps: 1. Unmount the NFS files systems for the VOBs
2. Stop ClearCase on the virtual box
3. Reboot the VOB server
4. Remount the NFS file systems
Restart ClearCase on the box Interop environment 217. How do I - configure UNIX or Linux clients to access Windows VOBs 1. Both the UNIX or Linux and Windows systems must be running version 2002.05.00 or higher.
2. CCFS must be enabled on the Windows VOB server(s)
Note: CCFS only supports the use of snapshot views; refer to technote 1146338 for more details on CCFS.
Example: Click Start > Settings > Control Panel and double-click the ClearCase icon. Next click Options and then select Use CCFS to access UNIX VOBs
3. A Windows domain must also be selected from the drop down list on which the VOB server resides. Select the corresponding Windows domain in the Use this domain to map UNIX user and group names box.
Page 256 of 341
ClearCase Environment – How do I
4. There must be identical accounts (users and groups) on both Windows and UNIX that match in both spelling and case.
Example:
Windows User = DOM1\user1 Windows group = DOM1\group1
UNIX User = user1 UNIX group = group1
5. The same ClearCase primary group must be set for all users on both UNIX and Windows
6. Both UNIX and Windows hosts running ClearCase must use the same ClearCase Registry server.
7. There must be two separate regions established on the registry server: a Windows region and a corresponding peer UNIX region.
Note: Views cannot be "shared" between UNIX and Windows in this configuration. Setup 1. Check user and group mapping Check the user and group mapping with the credmap command. A. Run credmap from the Windows VOB server. The credmap utility is located in the C:\Program Files\Rational\ClearCase\etc\utils directory. credmap UNIX_host
where "UNIX_host" is the Net Bios name of the UNIX client trying to access the Windows VOB. The first part of the output listed from this command lists the user's credentials on the Windows VOB server. The second part corresponds to the user's credentials against the UNIX client host. Page 257 of 341
ClearCase Environment – How do I
C:\Program Files\Rational\ClearCase\etc\utils>credmap UNIX-client Identity on local system: User: DOMAIN\user1 (NT:S-1-5-21-141845252-1443263951-584457872-1439) Primary group: DOMAIN\group1 (NT:S-1-5-21-141845252-1443263951-584457872- 1023) Groups: (10) Everyone (NT:S-1-1-0) BUILTIN\Users (NT:S-1-5-32-545) BUILTIN\Administrators (NT:S-1-5-32-544) DOMAIN\Domain Users (NT:S-1-5-21-141845252-1443263951-584457872-513) DOMAIN\test (NT:S-1-5-21-141845252-1443263951-584457872-1509) DOMAIN\clearuser (NT:S-1-5-21-141845252-1443263951-584457872-1022) DOMAIN\Domain Admins (NT:S-1-5-21-141845252-1443263951-584457872-512) LOCAL (NT:S-1-2-0) NT AUTHORITY\INTERACTIVE (NT:S-1-5-4) NT AUTHORITY\Authenticated Users (NT:S-1-5-11)
Identity on host "UNIX-client": User SID: UNIX:UID-22319 Primary group SID: UNIX:GID-20 Group SID list: (10) NOBODY NOBODY NOBODY NOBODY UNIX:GID-50 NOBODY NOBODY NOBODY NOBODY NOBODY
B. Run credmap from the UNIX client.
Note: The credmap utility is located in the /usr/atria/etc/utils or /opt/rational/clearcase/etc/utils directory.
credmap VOB_Server
where VOB_Server is the Net Bios name of the Windows VOB server host.
The first part of the output listed from this command lists the user's credentials on the on the UNIX host and the second part corresponds to the user's credentials on the Windows VOB server. If the user's "Primary Group" on Windows does not match the user's "Primary Group" on UNIX or comes back with a (-2) or a NOBODY, this configuration will not work.
UNIX-client.user1# credmap VOB-Server Identity on local system: User: nis.com/user1 (UNIX:UID-22319) Primary group: nis.com/group1 (UNIX:GID-20) Groups: (0)
Identity on host "VOB-Server": User SID: SID:3.01050000000000050000001508746304560675cf22d61e900000059f Primary group SID: SID:3.01050000000000050000001508746304560675cf22d61e90000003ff Group SID list: (0)
2. Create the UNIX snapshot view Create a snapshot view on the UNIX client. The view must be created with the -tmode option using STRIP_CR mode in this configuration.
For example:
UNIX-client.user1# cleartool mkview -snapshot -tag interop_strip_cr -tmode strip_cr - Page 258 of 341
ClearCase Environment – How do I colocated_server /net/UNIX-client/viewstore/interop_srtip_cr.vws Created view. Host-local path: UNIX-client:/viewstore/interop_srtip_cr.vws/.view.stg Global path: /net/UNIX-client/viewstore/interop_srtip_cr.vws/.view.stg It has the following rights: User : user1 : rwx Group: group1 : rwx Other: : r-x Created snapshot view directory "/net/UNIX-client/viewstore/interop_srtip_cr.vws".
Review the ClearCase Administrators Guide on the topic of Creating a view on a NAS device for details regarding creating a view with storage located on a network attached storage device.
3. Create the VOB tag for the UNIX region Tag the VOB in the UNIX region from the Windows host. The VOB tag must be made from the Windows region and stored in the UNIX region using the "-region" switch. Also, the VOB tag is created using a forward slash rather than the standard back slash on Windows.
Example describe output:
M:\interop\interop>cleartool describe vob:\interop versioned object base "\interop" created 11-Apr-02.20:23:28 by user1.group1@Windows-VOB Server VOB family feature level: 3 VOB storage host:pathname "VOB-Server:C:\vobs\interop.vbs" VOB storage global pathname "\\VOB-Server\vobs\interop.vbs" database schema version: 54 VOB ownership: owner DOMAIN\user1 group DOMAIN\group1 Attributes: FeatureLevel = 3
Note that the share name may be different than the directory name. The local path must be used. For example, C:\Clearcase_Storage\VOBs is the local path and \\HOST\ccstg_c\VOBs is the UNC path using the share name.
Tag the VOB using the command:
M:\interop\interop>cleartool mktag -vob -tag /interop -region UNIX-client_region - ngpath C:\vobs\interop.vbs
Again, remember to use a forward slash (/) and not a back slash (\). Also, it is important that the -ngpath switch must be used in this configuration.
4. Load the VOB Load the VOB into the snapshot view on UNIX via the load rules in the config_spec. Remember to navigate into the view root of the snapshot view before editing the config_spec. For example:
UNIX-client.user1# cd /net/UNIX-client/viewstore/interop_srtip_cr.vws UNIX-client.user1# cleartool edcs
element * CHECKEDOUT element * /main/LATEST load /interop ~ ~ ~ ~ "/var/tmp/tmp19973" 3 lines, 58 characters Set config_spec and load snapshot view "interop_strip_cr"? [yes] y . . . Page 259 of 341
ClearCase Environment – How do I Loading "interop/lt_vobs/pvob.vbs/vob_oid" (41 bytes). Loading "interop/lt_vobs/pvob.vbs/vob_server.conf" (625 bytes). Done loading "/interop" (118 objects, copied 486 KB). Log has been written to "/net/UNIX-client/viewstore/interop_srtip_cr.vws/update.11- Apr-02.20:21:29.updt".
Note: If the entire VOB or multiple VOBs are loaded in the snapshot view at once, loading will take some time.
5. Set to the view and work on the VOB Set into the UNIX view root and work in the VOB as normal.
Note: Make sure the snapshot views are in the correct Text mode (strip_CR) before creating new elements or checking out files; otherwise problems similar to the below example will occur.
Example: A file called vob_server.conf was checked out for editing in the above VOB.
A. With a STRIP_CR view (good configuration): # vob_server configuration file # # The values in this configuration file are read when the # vob_server starts up # # Deferred Deletion # ======# When activated deferred deletion causes the vob_server # to delay removing containers in the source pool which # have been replaced by newer containers. This ensures # consistency when backup programs may be traversing # the directory structure (either the old or the new # container will be found, if not both). # # DeferredSourceContainerDeletion: # set to "yes" to activate deferred deletion # and "no" to disable it. DeferredSourceContainerDeletion=no ~ ~ ~ ~ ~ ~ ~ "vob_server.conf" 18 lines, 625 characters
B. Without a STRIP_CR view (bad configuration due to ^M in the file): # vob_server configuration file^M #^M # The values in this configuration file are read when the ^M # vob_server starts up^M #^M # Deferred Deletion^M # ======^M # When activated deferred deletion causes the vob_server^M # to delay removing containers in the source pool which^M # have been replaced by newer containers. This ensures^M # consistency when backup programs may be traversing^M # the directory structure (either the old or the new^M # container will be found, if not both).^M #^M # DeferredSourceContainerDeletion:^M # set to "yes" to activate deferred deletion^M # and "no" to disable it.^M DeferredSourceContainerDeletion=no^M ~ Page 260 of 341
ClearCase Environment – How do I ~ ~ ~ ~ "vob_server.conf" 18 lines, 643 characters
To check that the view is in the correct text mode, run: cleartool lsview -properties -full
For example:
UNIX-client.user1# cleartool lsview -prop -full interop_strip_cr interop_strip_cr /net/UNIX-client/viewstore/interop_srtip_cr.vws/.view.stg Created 11-Apr-02.20:19:50 by user1.group1@UNIX-client Last modified 12-Apr-02.07:24:57 by user1.group1@UNIX-client Last accessed 12-Apr-02.07:24:57 by user1.group1@UNIX-client Last read of private data 12-Apr-02.07:24:57 by user1.group1@UNIX-client Last config spec update 11-Apr-02.20:21:30 by user1.group1@UNIX-client Last view private object update 12-Apr-02.07:24:57 by user1.group1@UNIX- client Text mode: strip_cr Properties: snapshot readwrite Owner: nis.com/user1 : rwx (all) Group: nis.com/group1 : rwx (all) Other: : r-x (read)
Related information Adding multiple domains to CC Control Panel Credentials are not recognized by the remote host Removing the domain name from AllowedDomainList 218. How do I – understand the mnode settings and the username.map file with reference to SaMBa The following error may be printed on the client desktop:
Windows – Fatal Application Exit mvfs: ERROR: view=
05/03/04 11:33:06 view_server(3184): Error: view_server.exe(3184): Error: Unable to construct cleartext for object "0xA16A" in VOB "myhost.mydomain.com:/vobs/myvob.vbs": error detected by ClearCase subsystem
05/03/04 11:33:06 view_server(3184): Error: view_server.exe(3184): Error: Type manager "text_file_delta" failed construct_version operation.
05/03/04 11:33:06 view_server(3184): Warning: text_file_delta: Error: Unable to open file "\\myhost.mydomain.com\vobs\myvob.vbs\s /sdft\17/f/0-61614bfee27841349bf7ad2e50eb5487-y1": Invalid argument
This problem can occur if: 1. The information in the SaMBa username map file, samba.conf, is incorrect, or if SaMBa is configured to point to the wrong username map file or 2. The Windows client's MVFS Maximum Mnode settings are incorrect.
Solution Check the following: 1. Login to the SaMBa SWAT tool and make sure the correct username map file, samba.conf, is specified. Then, check the username map file to make sure all entries are correct. Consult your SaMBa man pages for assistance where required. 2. If there are no problems with the username map file, make sure that the MVFS Mnodes settings are correct for use with SaMBa.
Page 261 of 341
ClearCase Environment – How do I To do this, open the Windows Control panel and click the ClearCase > MVFS Performance tab > Mnodes section. The settings of interest are: Maximum number of Mnodes to keep on the VOB free list Maximum number of Mnodes to keep on the cleartext free list
Note: You will need to check Override to modify the value. 3. The required Mnode settings are specific to the SaMBa installation: For 32-bit mode Samba installations, these Mnode values are both required to be set to 200 For 64-bit mode Samba installations, these Mnode values are both required to be set to 800
Note: The above settings are only for the Maximum Mnode values, and you do not need to adjust the Minimum Mnode values with respect to this issue. The default MVFS cache sizes scale automatically based on host memory and are appropriate for a wide range of client needs. 219. How do I – understand the ClearCase and Samba: A Supported Configuration This document serves to supplement the Samba setup documentation and the IBM® Rational® ClearCase® Administrator's Guide concerning supported configurations for Microsoft® Windows® clients to access a VOB on a UNIX® or Linux® server.
This document is meant to supplement the Samba vendor documentation and the IBM Rational ClearCase Administrator’s Guide concerning the instructions to setup the basic Samba configuration and integration, respectively.
220. How do I – configure usernames and primary groups in a ClearCase Interop environment – they must be identical On UNIX (and Linux), Rational ClearCase relies on group IDs to implement workgroup sharing and to maintain strict access control. To access UNIX VOBs and views correctly, each Windows user's username and primary group name must match that user's username and primary group name on UNIX.
Note: The case and spelling must be identical between the operating systems for both the usernames and primary groups. You can use the credmap
See technote 1231082 for more information on how the primary group impacts clients using the ClearCase Remote Client (CCRC). If another group other than Domain Users is required, then the variable CLEARCASE_PRIMARY_GROUP can be set as a user environment variable for each single user. Note: DO NOT set this variable as a system variable. It is MANDATORY to remove the CLEARCASE_PRIMARY_GROUP when set as a system environment variable as it can cause the system to crash. This environmental variable can ONLY be set it as a user environment variable.
To view or change environment variables: 1. Right-click My Computer, and then click Properties.
Page 262 of 341
ClearCase Environment – How do I 2. Click the Advanced tab.
3. Click Environment variables.
4. Click one the following options, for a user variable: • Click New to add a new variable name and value. • Click an existing variable, and then click Edit to change its name or value. • Click an existing variable, and then click Delete to remove it. VALUE The value of this variable is set to any group in your Windows domain to which you are a member.
You can set value using one of three methods: Domain qualified group name (recommended)
Group name
SID (only used for special circumstances involving Domain migrations)
ClearCase will use the specified group as defined by the variable but only during element creation. For all other commands like checkout or checkin the variable is not used. Below are some examples to help illustrate the use of the variable (when it is used and when it is not).
In a Windows ONLY environment (VOBs and views on Windows) the following is true: See technote 1132158 for more information on how the variable requirements change when the VOBs are on UNIX®. VARIABLE NOT REQUIRED: The CLEARCASE_PRIMARY_GROUP variable IS NOT needed under the following conditions:
**************************** CHECKOUT/CHECKIN **************************** 1. If the users have their primary group defined on the domain controller.
Page 263 of 341
ClearCase Environment – How do I
Note: All other scenarios assume the the primary group is not set on the domain controller. 2. If the user is a member of the group to which an object is owned AND they are NOT a member of more than 32 groups, they can checkout/checkin without the CLEARCASE_PRIMARY_GROUP variable set.
3. If the user is a member of the group to which an object is owned AND if the VOB is owned by MORE THAN ONE group AND the user is a member of MORE THAN ONE of the groups in the VOBs group list, ClearCase will still have no problem (upon checkin the correct group will be used); hence, the CLEARCASE_PRIMARY_GROUP variable does not need to be set.
4. If the user is a member of the group to which an object is owned AND they are a member of more than 32 groups, the CLEARCASE_GROUPS variable must be set to that group so they can checkout/checkin; hence, the CLEARCASE_PRIMARY_GROUP variable does not need to be set. See technote 1124574 for more information on the CLEARCASE_GROUPS variable.
************ MKELEM ************ 5. If the users have their primary group defined on the domain controller.
Note: All other scenarios assume the the primary group is not set on the domain controller.
6. If the VOB is owned by ONE group AND a user is a member of that one group AND the user's group list does NOT exceed 32, they can create elements in that VOB without the CLEARCASE_PRIMARY_GROUP variable set.
7. If the VOB is owned by MORE THAN ONE group AND a user is ONLY a member of ONE of those groups AND the user's group list does NOT exceed 32, they can create elements in that VOB without the CLEARCASE_PRIMARY_GROUP variable set.
VARIABLE REQUIRED: The CLEARCASE_PRIMARY_GROUP variable IS needed under the following conditions. Note: All other scenarios assume the the primary group is not set on the domain controller.
**************************** CHECKOUT/CHECKIN **************************** 1. If the user is a member of the group to which the object is owned AND they are a member of more than 32 groups, the CLEARCASE_PRIMARY_GROUP variable can be set to that group so they can checkout/checkin.
Note: If the CLEARCASE_GROUPS variable is used instead (as number 3 above suggests), then this statement is not true.
************ MKELEM ************ 2. If the VOB is owned by MORE THAN ONE group AND a user is a member of MORE THAN ONE of those groups AND the user's group list does NOT exceed 32, they need the CLEARCASE_PRIMARY_GROUP variable set in order to create elements in that VOB.
3. If the VOB is owned by MORE THAN ONE group AND a user is a member of MORE THAN ONE of those groups AND the user's group list DOES exceed 32, they need the CLEARCASE_PRIMARY_GROUP & CLEARCASE_GROUPS variable set in order to create elements in that VOB.
222. TROUBLESHOOTING: Here are some related technotes to problems where the CLEARCASE_PRIMARY_GROUP variable was set incorrectly: Technote 1123759 describes a memory reference error caused by the CLEARCASE_PRIMARY_GROUP being set as a system variable. Technote 1149989 describes an issue where users receive "access denied" errors accessing files from Windows Explorer but not from Command Prompt or ClearCase Explorer. Technote 1127717 describes an MVFS audit problem while using clearmake. Technote 1122432 describes a problem where the creds utility reports "can't get primary gid". Page 264 of 341
ClearCase Environment – How do I Technote 1148970 describes a problem creating ClearCase views or VOBs with an error "unable to translate unix gid -1 to NT SID" because the variable was not set correctly. Technote 1150717 describes a problem where users can't create a new view and receive the error Unable to create security descriptor the security id structure is invalid.
Related information About ClearCase permissions on Windows MVFS limitation on the number of ClearCase groups Differences for cleartool mkelem on Windows and UNIX Incorrect syntax on pages 332 and 333 SID filtering and CLEARCASE_PRIMARY_GROUP conflict Primary Group defaults to Domain Users About the CLEARCASE_GROUPS variable 223. How do I – understand about the Primary Group requirements for element creation What is the difference in behavior on Microsoft® Windows®, Linux®, and UNIX® concerning the IBM® Rational® ClearCase® Primary Group requirements as it relates to element creation?
Answer Does the Rational ClearCase element creation operation have the same Primary Group requirements on both Windows and UNIX/Linux?
No, the mkelem command has different Primary Group requirements on Windows and UNIX/Linux. UNIX/Linux: In order to create an element in a VOB, the user's Primary Group must match a group in the VOB's group list.
WINDOWS: As long as the user "is a member of" a group in the VOB's group list and the parent directory where the element will be created is owned by the group to which you are a member, that user will be able to create elements in the VOB.
If, however, the user is a member of more than one of the VOB's groups, the CLEARCASE_PRIMARY_GROUP will need to be set to one of these. See technote 1135509 for more information about the CLEARCASE_PRIMARY_GROUP variable.
Below are examples showing this difference.
UNIX/Linux:
%> cleartool describe vob:/vobs/protect versioned object base "/vobs/protect" created 09-Jan-03.16:31:47 by vobadm (vobadm.group1@UNIX-host) VOB family feature level: 3 VOB storage host:pathname "UNIX-host:/export/home/user1/vobstore/protect.vbs" VOB storage global pathname "/net/UNIX-host/export/home/user1/vobstore/protect.vbs" database schema version: 54 VOB ownership: owner atria.com/vobadm group atria.com/group2 Attributes: FeatureLevel = 3
UNIX-host% id -a uid=22319(user1) gid=20(group1) groups=20(group1),2(group2)
Note: User1 is a member of both group1 and group2, and the Primary Group of user1 is set to group1. The VOB, however, is owned by group2.
%>/usr/atria/etc/utils/credmap UNIX-host Identity on local system: User: atria.com/user1 (UNIX:UID-22319) Primary group: atria.com/group1 (UNIX:GID-20) Groups: (1) atria.com/group2 (UNIX:GID-2) Page 265 of 341
ClearCase Environment – How do I
Identity on host "UNIX-host": User SID: UNIX:UID-22319 Primary group SID: UNIX:GID-20 Group SID list: (1) UNIX:GID-2
%> cleartool mkelem -nc test.txt cleartool: Error: Can't create object with group (group1) that is not in the VOB's group list. cleartool: Error: Unable to create element "test.txt".
******************************************************* *******************************************************
WINDOWS:
B:\protect>cleartool describe vob:\protect versioned object base "\protect" created 09-Jan-03.16:44:32 by user1.group1@WIN_HOST VOB family feature level: 3 VOB storage host:pathname "WIN_HOST:C:\ClearCase_Storage\vobs\protect.vbs" VOB storage global pathname "\\WIN_HOST\ccstg_c\vobs\protect.vbs" database schema version: 54 VOB ownership: owner DOMAIN\vobadm group DOMAIN\clearuser Attributes: FeatureLevel = 3
B:\protect>creds Login name: DOMAIN\user1 USID: NT:S-1-5-21-2025429265-1993962763-1957994488-1027 Primary group: DOMAIN\group1 (NT:S-1-5-21-2025429265-1993962763-19579488-1026) Groups: (8) DOMAIN\None (NT:S-1-5-21-2025429265-1993962763-1957994488-513) Everyone (NT:S-1-1-0) DOMAIN\clearuser (NT:S-1-5-21-2025429265-1993962763-1957994488-1011) BUILTIN\Administrators (NT:S-1-5-32-544) BUILTIN\Users (NT:S-1-5-32-545) LOCAL (NT:S-1-2-0) NT AUTHORITY\INTERACTIVE (NT:S-1-5-4) NT AUTHORITY\Authenticated Users (NT:S-1-5-11)
Note: User1 is a member of both group1 and clearuser, and the Primary Group of user1 is set to group1. The VOB, however, is owned by clearuser.
B:\protect>cleartool mkelem -nc test.txt Created element "test.txt" (type "text_file"). Checked out "test.txt" from version "\main\0".
B:\protect>cleartool ci -ident -nc test.txt Checked in "test.txt" version "\main\1".
B:\protect>cleartool ci -nc . Default: Added file element "test.txt". Checked in "." version "\main\1".
B:\protect>cleartool describe test.txt version "test.txt@@\main\1" created 09-Jan-03.16:48:00 by user1.group1@WIN_HOST Element Protection: User : DOMAIN\user1 : r-- Group: DOMAIN\clearuser : r-- Other: : r-- element type: text_file predecessor version: \main\0 Page 266 of 341
ClearCase Environment – How do I
Note: The element is owned by the group clearuser 224. How do I – understand about the CLEARCASE_GROUPS variable Windows This variable is used to counteract a limitation to the MVFS whereby any user who is a member of more than 32 Microsoft Windows groups (domain or local) can run into access problems. See technote 1131881 for additional information about the MVFS limitation. Users should set CLEARCASE_GROUPS as a Windows User variable in order to specify which subset of those groups Rational ClearCase should consider when checking the user's access rights. If the user environment variable CLEARCASE_GROUPS exists for any user, ClearCase will consider the semicolon-separated list of groups specified in the value of this variable first when determining (or displaying) which groups a user belongs. In essence, when you log in to Windows, you receive an Access Token. ClearCase will process these tokens in the order Windows provides them (which is completely random and cannot be configured in any way). ClearCase will stop processing the tokens after 32 groups have been reached. The CLEARCASE_GROUPS variable is the only way to work around this behavior. When the variable is set, ClearCase will look at each group name in CLEARCASE_GROUPS list in the order the list was written and compare that to the Windows Access Tokens provided. If the group name matches a group in the Windows Access Token, then ClearCase will create a ClearCase Access Token for that group to use. Note: If a group is listed in the variable to which the user is no longer a member, that group will be ignored, and the others will all be used in sequence.
When the CLEARCASE_GROUPS variable is exhausted, ClearCase will go back to the Windows Access Token list, and any group that has not already been added to the ClearCase token, will be added from the remaining list in the order provided, until all groups in the Windows token are used (if below 32) or the 32 group limit is reached.
Example:
CLEARCASE_GROUPS=DOMAIN\ClearCase Users;DOMAIN\group1;DOMAIN\group5
Note: Review the APAR below for the work around and solution to the problem related to creating a semi-colon separated list.
The list can contain domain or local groups, and need not contain the group specified in CLEARCASE_PRIMARY_GROUP. See technote 1135509 for more information about the CLEARCASE_PRIMARY_GROUP variable. If the user is a member of additional groups not specified in CLEARCASE_GROUPS, ClearCase will consider those groups after it has considered the groups listed in CLEARCASE_GROUPS, up to a limit of 32 groups. Page 267 of 341
ClearCase Environment – How do I Log off Microsoft Windows and log back on to enable the CLEARCASE_GROUPS variable.
CLEARCASE_GROUPS is not supported on Windows 98 or Windows Me.
History: The CLEARCASE_GROUPS workaround is only available to ClearCase 4.x with the below patches (or any later patch that obsoletes any of the following patches): clearcase_p4.0.NT-21 clearcase_p4.1.NT-17 clearcase_p4.2.NT-1 Further, this feature does not work in ClearCase version 2002.05 before patches clearcase_p2002.05.00.NT-15 clearcase_p2002.05.00.NT-14 This feature is built in to ClearCase 2003.06.00 and later.
UNIX and Linux The CLEARCASE_GROUPS variable was introduced to UNIX and Linux as of ClearCase 7.0 and is used ONLY as part of a larger work around to help alleviate the problem related to the 16 group limitation issue. Review technote 1207807 for more details along with information about the second part of the work around which involves a new utility called setgroup-swap. 225. How do I – understand about MVFS limitations on the number of ClearCase groups a user may belong ClearCase does enforce a limitation on the number of ClearCase groups a user may belong to. The MultiVersion File System (MVFS) can process a maximum of 32 groups at a time. By default, the MVFS will recognize only the first 32 groups of a user's group list as displayed by the output of the creds utility. The environment variables, CLEARCASE_GROUPS and CLEARCASE_PRIMARY_GROUP, can help to resolve or alleviate some of the issues that may arise due to this limitation.
1. The CLEARCASE_GROUPS variable:
Windows has no set order in which it will list a user's group membership. For example, if a user belongs to groups 1 - 35, the groups listed by Windows during one login might start with 1, 7, 32, 28, etc..., but at the next login they might be listed as 12, 33, 9, 18, etc... So, if a user belongs to more than 32 groups, there is no way to guarantee from Windows alone what groups the MVFS will know about. To counteract this functionality for ClearCase purposes, the CLEARCASE_GROUPS variable can be used to define which groups (up to 32) will be presented to the MVFS.
Note: The 32 group limitation for MVFS exists regardless of how these groups are or are not used with ClearCase. EXAMPLE A user might belong to more than 32 groups, only some of which are actually used with ClearCase data. If so, the CLEARCASE_GROUPS variable can be set only to those groups (up to 32) that are pertinent to ClearCase.
A user might belong to more than 32 groups, all of which are used with ClearCase data.
In this case, the CLEARCASE_GROUPS variable can be set to the 32 most important groups. If the user needs to use one of the remaining groups with ClearCase, the CLEARCASE_GROUPS variable will need to be redefined by adding the desired groups and removing an equal number of other groups.
For example, a user belongs to groups 1 - 35, and has set the CLEARCASE_GROUPS variable to include groups 1 - 32. If the user later needs to use groups 33 - 35, the CLEARCASE_GROUPS variable can be changed, say, to list groups 4 - 35 (groups 33 - 35 have been added to the list and groups 1 - 3 have been removed).
Alternatives:
Create a second user account for use with these "extra" groups.
Page 268 of 341
ClearCase Environment – How do I Use the CLEARCASE_PRIMARY_GROUP variable as detailed below. 2. The CLEARCASE_PRIMARY_GROUP variable:
The CLEARCASE_PRIMARY_GROUP environment variable does not need to be set to one of those assigned to CLEARCASE_GROUPS or to one of those listed in creds output in order to be functional. Consequently, CLEARCASE_PRIMARY_GROUP offers a means by which a 33rd group can, in effect, be set and acknowledged by the MVFS. So, even if 32 groups are already assigned to the CLEARCASE_GROUPS variable, a 33rd group could be made functional by assigning it to the CLEARCASE_PRIMARY_GROUP variable.
3. Setting the CLEARCASE_GROUPS and CLEARCASE_PRIMARY_GROUP variables:
In order for the MVFS to read the value assigned to the CLEARCASE_GROUPS and CLEARCASE_PRIMARY_GROUP environment variables, the following steps are necessary: 1. Create/modify the environment variable (as a User variable, not a System variable)
2. Log off (or restart)
3. Log in Note: Although the creds command output may contain the new group information immediately after either or both of these variables have been set, the MVFS is not guaranteed to read these new settings until after the user has logged off and logged back in. On rare occasions these settings may not take effect even after the log off/log in. If so, a restart of the system should be done.
For more information concerning the CLEARCASE_PRIMARY_GROUP and or the CLEARCASE_GROUPS variables, see the links under Related information.
Related information About the CLEARCASE_PRIMARY_GROUP variable CLEARCASE_PRIMARY_GROUP and CCWEB About the CLEARCASE_GROUPS variable
226. How do I – understand the maximum groups on UNIX and Linux for use with ClearCase The maximum number of groups a user can belong to on UNIX or Linux is 16. The 16 group limitation is not controlled by ClearCase, rather the architecture from which the RFC (Request for Comments) for RPC (Remote Procedure Call) Standards Track emanates. The original RFC for RPC was RFC#1050 published in 1988 which had a limitation of 10 additional GID's:
UNIX Authentication: The caller of a remote procedure may wish to identify himself as he is identified on a UNIX(tm) system. The value of the credential's discriminant of an RPC call message is "AUTH_UNIX". The bytes of the credential's opaque body encode the following structure:
struct auth_unix { unsigned int stamp; string machinename<255>; unsigned int uid; unsigned int gid; unsigned int gids<10>; };
This was updated and superseded by RFC#1831, published in 1995 which increased the number of additional GID's to 16.
APPENDIX A: SYSTEM AUTHENTICATION
The client may wish to identify itself, for example, as it is identified on a UNIX(tm) system. The flavour of the client credential is "AUTH_SYS". The opaque data constituting the credential encodes the following structure: Page 269 of 341
ClearCase Environment – How do I
struct authsys_parms { unsigned int stamp; string machinename<255>; unsigned int uid; unsigned int gid; unsigned int gids<16>; };
APAR PK10876 has been submitted to address this behavior.
Solution This defect has been resolved through use of a workaround in ClearCase 7.0.
WORKAROUND: You will be required to use a wrapper utility to process any ClearCase commands when a user is a member of more than 16 groups.
DOCUMENTATION: setgroup-swap
Allows users who are a member of more than 16 groups to use ClearCase commands.
Applicability Product Command type ClearCase executable
Platform UNIX and Linux Synopsis Use ClearCase functionality when user membership exceeds 16 groups.
Description Due to the RPC limitation imposed by UNIX and Linux, users who are members of more than 16 groups cannot properly process RPC calls for ClearCase use. To work around this issue, you can use the setgroup-swap utility (found in the /opt/rational/clearcase/etc/utils directory) to work in conjunction with the CLEARCASE_GROUPS variable to define an ordered list of groups for ClearCase to package and process RPC calls in accordance with RFC#1831 guidelines and restrictions.
Restrictions Identities You must have one of the following identities: root (UNIX and Linux) Note: This identity is required to chmod the setgroup-swap utility to apply the setuid permission. After that, no special identities are required. Options and arguments By default setgroup-swap does not have any options. The only arguments that are required is the ClearCase command you wish to run. Instructions Ensure ClearCase 7.0 is installed Ensure the setgroup-swap executable is owned by root and the setuid bit is set to root. Ensure the setgroup-swap executable is in the path for the shell. Note: Use the appropriate shell syntax for your environment to set the PATH variable. Set the CLEARCASE_GROUPS variable to define which of the 16 groups you want to use with ClearCase. Note: Use the appropriate shell syntax for your environment and set the CLEARCASE_GROUPS variable as a colon-separated list. Run the setgroup-swap before the ClearCase command. Example
% cleartool -ver ClearCase version 7.0.0 (Fri May 05 12:38:05 EDT 2006) 7.0.0.0-RATL-RCC-IFIX01 (Thu Jun 29 23:33:44 EDT 2006) @(#) MVFS version 7.0.0.0-IFIX01 (Tue May 16 00:02:04 2006) cleartool 7.0.0.0 (Fri Apr 21 00:16:51 EDT 2006) db_server 7.0.0.0 (Fri Apr 21 00:15:07 EDT 2006) VOB database schema version: 54 Page 270 of 341
ClearCase Environment – How do I
% pwd /opt/rational/clearcase/sun5/etc/utils
% ls -al setgroup-swap -r-xr-xr-x 1 root other 7676 Dec 2 2005 setgroup-swap
% chmod 4555 setgroup-swap
% ls -al setgroup-swap -r-sr-xr-x 1 root other 7676 Dec 2 2005 setgroup-swap
% PATH=$PATH:/opt/rational/clearcase/
% CLEARCASE_GROUPS="group1:group2:group3:group4:group5:group6:^ group7:group8:group9:group10:group11:group12:group13:^ group14:group15:group16"; export CLEARCASE_GROUPS
% setgroup-swap usage: ./setgroup-swap
% setgroup-swap cleartool mkview -tag testview -host testhost^ -gpath /net/homes/testuser/testview.vws -hpath^ /net/homes/testuser/testview.vws ^ /net/homes/testuser/testview.vws 227. How do I – understand the access denied accessing files from Windows Explorer but not from Command Prompt (CLEARCASE_GROUPS) issue When trying to open a directory inside an IBM® Rational® ClearCase® VOB using the Microsoft® Windows® Explorer, an "Access is denied" dialog box appears. Opening a command shell or ClearCase Explorer and accessing the same directory works without a problem.
Cause All users that are members of more than 32 Windows groups and using the CLEARCASE_GROUPS variable are receiving Access Denied error from Windows Explorer, but not from the command line. This is due to the fact that Windows only opens one process for explorer.exe. This process opens before the CLEARCASE_GROUPS variable is read. When any additional Windows Explorer sessions are needed, they are opened through the thread of the original process. These new sessions do not receive a new process ID, thus the ACLs on the original process and any subsequent threads contain the original list of groups for the user and not the reordered groups from the CLEARCASE_GROUPS variable. See technote 1124574 for more information about the CLEARCASE_GROUPS variable.
Solution In order to resolve this issue, you will need to perform the following steps: 1. Force Windows Explorer to generate a new process ID, using one of the following methods. a. Open Windows Explorer b. Select Tools > Folder Options... c. Click the View tab d. Check the option "Launch folder windows in a separate process"
OR
2. Follow this Microsoft Article http://support.microsoft.com/default.aspx?scid=kb;en-us;156366
If this appears to be a problem only with the CLEARCASE_PRIMARY_GROUP variable, please refer to technote 1149989.
Page 271 of 341
ClearCase Environment – How do I 228. How do I – understand the CEARCASE_GROUPS EV when more than 32 groups and accessing 770 directories issue. The CLEARCASE_GROUPS environment variable appears not to work properly with groups listed after the 32nd group (i.e. as listed by creds -w when CLEARCASE_GROUPS is *not* set). Access is denied when attempting to enter directories with 770 permissions owned by a group listed after the 32nd group after having booted disconnected from the network, and then later connecting. This problem does not occur if the 770 directory is owned by a group listed before the 32nd group.
The only proper way to start ClearCase is once it is "in the network". A work-around is to execute "...\etc\utils\ntlogon_util -r" after the machine has been properly added to the network. 229. How do I – Create ClearCase VOBs and Views in ClearCase Interoperation environment with UNIX® or Linux® with Microsoft® Windows® - you can’t Attempts to create a VOB or a View via the Windows GUI will result in error, currently the only way to create VOBs and View it to create them on the UNIX server hosts. 230. How do I – Create a snapshot view from Windows stored on a ClearCase UNIX server A snapshot view can be created on UNIX or Linux from Windows if the view storage directory is generated using a registered storage location that does not have a global path.
If the cleartool mkview -snapshot command syntax contains a UNC (Universal Naming Convention) path, then the operation will fail.
Snapshot views cannot be shared between operating systems, even though they can be created across platforms; therefore, views created from Windows are only for use on Windows. 231. How do I – resolve a checkout fails from Windows only in an interop environment issue Attempts to perform a checkout from a view on Microsoft® Windows® where the VOB resides on UNIX® or Linux® results in the following error:
[Rational ClearCase Explorer] X Error Checking out 'Y:\MyVOB\filename.ext' . Checked out version, but could not copy data to "Y:\MyVOB\filename.ext" in view: Invalid argument. Correct the condition, then uncheckout and re-checkout the element. Unable to check out "Y:\MyVOB\filename.ext" .
Another symptom is getting prompted for a username and password when trying to access the SaMBa® share over the network (outside of Rational ClearCase). For example, from Start > Run > type \\UNIX_Server\SaMBa_Share > click OK and it prompts for a username and password.
When using SaMBa as an interop package for use with Rational ClearCase, there should not be a prompt for a username and password to gain access to the SaMBa share over the network. If there is, then Rational ClearCase operations will fail, like the above checkout error.
SaMBa is configured to use domain authentication, but the error is happening because the domain controller for username and password validation is not specified in the smb.conf file.
Solution You need to configure SaMBa to do all its username and password validation using a specific Windows server, such as the domain controller or a backup domain controller.
In the global section of smb.conf, add the line, password server =
For more information and directions on modifying the smb.conf file, refer to the smb.conf man page or Page 272 of 341
ClearCase Environment – How do I go to http://www.netadmintools.com/html/5smb.conf.man.html.
For general details on SaMBa, refer to the documentation found at http://www.SaMBa.org. 232. How do I – understand the specific Samba 3.0.24 configuration required for ClearCase IBM® Rational® ClearCase® has been certified for use with Samba 3.0.24. Due to changes made in the default behavior of Samba, a specific Samba configuration is required in order for ClearCase to work properly.
Content In order to configure Samba in a supported fashion to use ClearCase, follow the instructions outlined in the ClearCase Administrator's Guide.
In order for ClearCase to properly support Samba 3.0.24, the following change needs to be added to the global section of smb.conf on the Samba server: host msdfs = No
This change explicitly disables the use of the Microsoft Distributed File System (DFS) which is not currently supported with ClearCase. 233. How do I – understand ClearCase configuration in a domain environment with a one-way trust A one-way trust is sufficient to support a ClearCase environment so long as the configuration meets the following standards: 1. The resource domain trusts the master domain.
MASTER <------RESOURCE
2. All users log into the master domain.
3. The ClearCase client and servers have their machine accounts in the resource domain.
The clearcase_albd and ClearCase group accounts reside in the resource domain or the master domain.
Note: Since the machine account of the clients reside in the resource domain a two-way trust is not necessary even when creating local views; however, if you require certain users to have ClearCase Administrative privileges, the clearcase_albd account must be in the same domain as the user accounts. 234. How do I – understand usernames and primary groups in a ClearCase Interop environment All Windows users' usernames and their primary groups must have matching usernames and primary groups on UNIX (and or Linux) in a Rational ClearCase Interop environment. On UNIX (and Linux), Rational ClearCase relies on group IDs to implement workgroup sharing and to maintain strict access control. To access UNIX VOBs and views correctly, each Windows user's username and primary group name must match that user's username and primary group name on UNIX. Note: The case and spelling must be identical between the operating systems for both the usernames and primary groups.
As seen in the below table, on Windows, the username, dev1, with the primary group, ccusers, has a matching counterpart on UNIX as dev1 with primary group, ccusers. Windows UNIX (or Linux) Username: dev1 username: dev1 Primary Group: ccusers Primary Group: ccusers To verify that the username and primary group are the same on Windows and UNIX, use the credmap utility from Windows, and compare that output to the id (or id -a) output from UNIX. For details on using credmap, run cleartool man credmap.
Example: credmap output: G:\Documents and Settings\hakank>credmap unix_server Identity on local system: Page 273 of 341
ClearCase Environment – How do I User: domain\dev1 (NT:S-1-5-21-2052111302-1417001333-682003330-1004) Primary group: domain\ccusers (NT:S-1-5-21-2052111302-1417001333-682003330-1009) Groups: (32) domain\Doamin users (NT:S-1-5-21-2052111302-1417001333-682003330-1038) Everyone (NT:S-1-1-0) HKTEST\1 (NT:S-1-5-21-2052111302-1417001333-682003330-1010) HKTEST\10 (NT:S-1-5-21-2052111302-1417001333-682003330-1019) BUILTIN\Users (NT:S-1-5-32-545) ------snip------
Identity on host "unix_server": User SID: UNIX:UID-500 Primary group SID: GID-244 Group SID list: (32) NOBODY NOBODY UNIX:GID-20 G:\Documents and Settings\developer> id -a output: id -a unix_server% uid=500(dev1) gid=244(ccusers) groups=20(users) 235. How do I - understanding NOBODY in the credmap output Why does NOBODY appear in the credmap output if the usernames and groups do not match when I'm trying to configure IBM® Rational® ClearCase® Interoperation (Interop) with Microsoft® Windows®, UNIX® and Linux®?
Answer The supported Rational ClearCase Interop configuration requires that the user's username and primary group name are identical on Windows and UNIX (and or Linux), refer to technote 1146784 for more details. In an interop environment, where a user's username and or primary group does not match then NOBODY gets reported in the credmap output to identify the discrepancy. This is true whether you have configured Windows clients to access UNIX VOBs or if you have configured UNIX clients to access Windows VOBs (technote 1141329). The credmap utility is available on both Windows and UNIX, run cleartool man credmap for more details on this utility. The user's username matches on both operating systems, but the primary group does not. Therefore, the Primary group on Windows is set to Domain\ccusers, and the Primary group SID on UNIX is set to NOBODY.
Identity on local system: User: Domain\user1 (NT:S-1-5-21-2106544897-1487...) Primary group: Domain\ccusers (NT:S-1-5-21-2106544897-14...) Groups: (7) Everyone (NT:S-1-1-0) BUILTIN\Administrators (NT:S-1-5-32-544) BUILTIN\Power Users (NT:S-1-5-32-547) BUILTIN\Users (NT:S-1-5-32-545) NT AUTHORITY\INTERACTIVE (NT:S-1-5-4) NT AUTHORITY\Authenticated Users (NT:S-1-5-11) LOCAL (NT:S-1-2-0)
Identity on host "UNIX_Host": User SID: UNIX:UID-59835 Primary group SID: NOBODY Group SID list: (2) NOBODY UNIX:GID-20
Note: NOBODY reported in the Groups section of the Windows output, or in the Group SID list section of the UNIX output is not a problem. This is only referring to any additional groups that the username may belong to, but those groups may not exist on both operating systems, nor is that required. Currently, there is no alternative for the supported configuration, which requires matching usernames and primary groups. The following change requests (RFEs) have been opened concerning the ability to have non-matching usernames and groups: Page 274 of 341
ClearCase Environment – How do I RATLC00588462 - Enable Microsoft Windows clients to access UNIX VOBs and Views, but not require the UNIX/Linux groups to depend on Windows groups; so they do not have to be identical. RATLC00585414 - Create a CLEARCASE_USER NT environment variable to map a Windows user(name) to a UNIX/Linux user(name). 236. How do I - recover ClearCase functionality after users and groups moved to a new domain This technote helps to address a situation whereby users and groups have been moved to a new Windows domain, which had a negative impact to the ClearCase objects associated with their original domain accounts. As a result of the change, ClearCase objects such as VOB storage, View storage, elements, and metadata will all need to be reprotected so that their ownership properly reflects the SIDs of the users and groups in the new domain.
Legend In the text below these references are used: "clearcase group" = ClearCase administrators group that is used by your site.
"clearcase_albd" = ClearCase service account used by your site.
"vobadmin" = User account that has ClearCase administrator privileges. "ccusers" = ClearCase users non-admin group
1. Verify that the clearcase_albd account, the ClearCase administrator account, Users group and the ClearCase administrators group are correctly setup in the NEW_DOMAIN. Make sure you can successfully login to the NEW_DOMAIN as the clearcase_albd user and make note of the password for that user which will be required in later steps.
Important: The user accounts should have their primary group set to the ClearCase users group (which is not the ClearCase administrators group).
Refer to the Privileged users and groups section of the IBM Rational ClearCase Administrator's Guide for additional information about these users and groups.
2. Add the clearcase_albd user and any ClearCase administrator user accounts to the NEW_DOMAIN\clearcase group (which is the ClearCase administrators group).
Refer to technote 1146253 "About ClearCase privileged users on Windows" for supplemental information about these accounts that have ClearCase administrative privileges.
3. On EVERY Windows ClearCase client that has the ability to create local views and vobs (as noted in ClearCase Doctor), you must edit the Windows Service named Atria Location Broker. On the 'log on' tab for this service, you will need to change the old clearcase_albd user to the NEW Domain and NEW clearcase_albd user with it's valid password. This change requires local administrator privileges.
From the Windows Control Panel:
a. Open > Administrative Tools > Services
b. Double-click the Atria Location Broker service
c. Select the Log On tab
d. Update the Logon account information:
The account should be Domain qualified (NEW_DOMAIN\clearcase_albd) and the correct user password must be entered and confirmed for the clearcase_albd.
Page 275 of 341
ClearCase Environment – How do I
4. On EVERY Windows ClearCase client AND server machine, you must edit the ClearCaseGroupName registry key to identify the new Domain qualified clearcase group in the new domain (NEW_DOMAIN\clearcase).
CAUTION: The following directions require you to edit the registry using the Windows Registry Editor. However, editing the Windows Registry incorrectly can cause serious problems that may require you to reinstall your operating system. Use Registry Editor at your own risk. Before proceeding review the Microsoft article, 256986 - Description of the Microsoft Windows Registry.
The ClearCaseGroupName registry key is located under: HKEY_LOCAL_MACHINE\Software\Atria\ClearCase\CurrentVersion
The registry key is created automatically for ClearCase and is used to specify the name of the privileged group used by ClearCase, such as: ClearCaseGroupName: REG_SZ : NEW_DOMAIN\clearcase
5. If moving VOBs from one Windows VOB server to another Windows VOB server along with the domain change, you must ignore Steps 6 through 12, and instead, follow the steps under Moving a VOB to a different Domain in IBM Rational ClearCase Administrator's Guide.
6. Log in as a ClearCase administrator on the VOB server and run the command 'cleartool protectvob' on every VOB to change to the new domain user and group owner. Answer "y" (yes) to both questions you are prompted with.
Example:
In this example, the "vobadmin" ClearCase admin account is being used and the ClearCase user's group "ccusers" is that users primary group. The command will look like the following for a VOB called Ghost: "cleartool protectvob -chown vobadmin -chgrp ccusers \\ccserver\ccstg_d\VOBs\Ghost.vbs"
Verify the change with a describe of the VOB: "cleartool describe -l vob:\Ghost"
Page 276 of 341
ClearCase Environment – How do I 7. On the VOB server, stop the ClearCase services in the ClearCase Control panel:
8. Run fix_prot to fix the protections on the VOB storage directory.
Note: Steps 9 through 12 below are further explained in the IBM Rational ClearCase Administrator's Guide underFixing Protection Problems; refer to the manual for any examples or additional information.
cc-home-dir\etc\utils> fix_prot -r -root -chown vobadmin -chgrp ccusers \\ccserver\ccstg_d\VOBs\Ghost.vbs
Refer to:
Technote 1142606 About fix_prot for supplemental information about using the fix_prot command.
Technote 1143292 About ClearCase permissions on Windows for additional permissions requirements.
9. On the VOB server, re-start the ClearCase services in the ClearCase Control panel:
Page 277 of 341
ClearCase Environment – How do I 10. Run the scrubber utility to remove cleartext containers that don't need to be reprotected. Example: scrubber -e -k cltxt \\ccserver\ccstg_d\VOBs\Ghost.vbs
11. Reprotect ALL elements and metadata for each of the VOBs. You will do this by running the vob_sidwalk command. Be sure to read and understand the reference manual page for vob_sidwalk before completing. (From command line you can bring up the reference manual page by typing 'cleartool man vob_sidwalk')
Example:
In the following scenario we are reassigning ownership to the VOB owner and group that were set in Step 6 above.
To reassign ownership of all objects in the VOB to the new SIDs of the VOB owner and group, use a command like the following:
vob_sidwalk -unknown -execute vob-tag SIDfile-path
When invoked with the -unknown and -execute options, vob_sidwalk maps unresolvable user SIDs to the SID of the VOB owner and maps unresolvable group SIDs to the SID of the VOB’s group.
The SIDfile-path is the location to create the vob_sidwalk file.
Make sure you first read and understand the reference manual page for vob_sidwalk before proceeding with running this command.
Note: If you are running vob_sidwalk against a VOB that is a ClearCase MultiSite replica sibling, the changes are not propagated to other siblings in the replica family. Refer to technote 11944774 (About vob_sidwalk changes and propagation between MultiSite replicas) for further details.
12. Run the checkvob utility to fix storage pool protections if the checkvob report any problems with protections.
cleartool checkvob -protections -pool \\ccserver\ccstg_d\VOBs\Ghost.vbs cleartool checkvob -force -fix -protections -pool \\ccserver\ccstg_d\VOBs\Ghost.vbs
13. On EVERY Windows ClearCase client AND server machine that has a CLEARCASE_PRIMARY_GROUP user environment variable setting change the value to the new domain's ClearCase users group (such as, ccusers in this example). If the CLEARCASE_PRIMARY_GROUP user environment variable does not exist and the group is not currently set as the Windows user's primary group, then you MUST create it exactly as shown here (all capital letters with underscores between them). The variable should be Domain qualified as NEW_DOMAIN\ccusers.
To view or change environment variables:
. Right-click My Computer, and then click Properties.
a. Click the Advanced tab.
b. Click Environment Variables.
c. Click one the following options, for a user variable:
Click New to add a new variable name and value.
Click an existing variable, and then click Edit to change its name or value.
Page 278 of 341
ClearCase Environment – How do I Click an existing variable, and then click Delete to remove it.On Windows 2000
14. ALL views owned by the users or groups that moved to the new domain will need to be reprotected following the steps below for each view:
. Log in as the ClearCase admin user from the view host.
a. Take ownership (using standard Windows functionality) of the groups.sd and identity.sd files within the view storage directory for each view (such as, myview.vws), and move these 2 files to a temporary directory.
b. Stop the ClearCase services in the ClearCase Control Panel as noted in step 7 above.
c. Run the fix_prot command as following, which is similar to step 9 above except this occurrence is against a view storage:
fix_prot -r -root -chown
This will recreate the identity.sd file and groups.sd file and re-establish protections on the view. After this is successful, you can delete the OLD identity.sd file and groups.sd files that were previously moved to a temporary location.
d. Start the ClearCase services in the ClearCase Control Panel. Refer to technote 1143292 About ClearCase permissions on Windows for additional permission requirements.
15. Test ClearCase functionality to ensure that all operations and access has been restored.
237. How do I – understand about ClearCase permissions on Windows The Microsoft Windows New Technology File System (NTFS) protects objects using security descriptors. File Access Table (FAT) file systems do not use security descriptors. Therefore, IBM Rational recommends using the NTFS file system for maximum security of data. This technote will address ClearCase permissions as they pertain to NTFS.
There are required Windows permissions for various directories (VOBs, views, shares, and install) to enable ClearCase to function properly and without error. Some ClearCase operations will generate access and permission denied errors if certain directories or shares have the wrong permissions.
Note: ClearCase does not have a built-in authentication mechanism. ClearCase relies on the Microsoft Windows permissions model to enforce security using Microsoft Windows groups, user accounts, file system and share permissions to enforce security models.
Important Advisory This information is intended for use by the ClearCase Administrator (or systems administrator), who is responsible for configuring the ClearCase environment.
Note: This document provides specifications for ClearCase use, but general security and access controls for any network and its applications should be evaluated by a certified system and/or network administrator who can verify the appropriate configuration for your production requirements.
To setup protections for ClearCase, we recommend that you first read and understand the details covered in the IBM Rational ClearCase Administrator's Guide. If you do not have a hard copy, the document is available in soft copy, cc_admin.pdf, on any host with ClearCase installed, and is located by default in C:\Program Files\Rational\ClearCase\doc\books.
The goal of this technote is to supplement the IBM Rational ClearCase Administrator's Guide by providing considerations and guidelines to assist with managing the protections in a ClearCase environment. Due to the broad variances of protections that can be implemented to address the security needs in different environments, this technote cannot provide specifications that will be true for all cases.
Non-ClearCase vs ClearCase Protections It is important to understand that protections for non-ClearCase objects, such as shares used as storage Page 279 of 341
ClearCase Environment – How do I locations or the install directory, are managed using operating system commands, while protections of ClearCase objects (VOBs, views, elements, versions, and other VOB objects) are managed using ClearCase utilities and commands.
In short, non-ClearCase objects are directories (or folders) that are created using operating system functions, where as ClearCase objects are created using ClearCase functions or have been added to source control.
For information on the ClearCase utilities and commands used for changing VOB and view storage protections, see the IBM Rational ClearCase Administrator's Guide and the IBM Rational ClearCase Command Reference manual.
ClearCase Administrative Access Privileged users in ClearCase have rights to create, modify, and delete any ClearCase object. Access to these permissions should be restricted to ClearCase Administrators and the ClearCase Process Account (Atria Location Broker Service - ALBD). Access is controlled by membership in the ClearCase Administrators group.
This group which is designated during the setup and installation of ClearCase is referred to as the ClearCase privileged group. By default, this group is called clearcase. Some defining characteristics of the ClearCase (or privileged) group are: The account under which whose identity Atria Location Broker Daemon (ALBD) runs has to be a member of this group, such as clearcase_albd.
This group has Full Control of the view and VOB storage directories.
Members of this group are considered ClearCase Administrators.
Note: The ClearCase privileged group must never be used as the primary group on a VOB or set as a primary group for ClearCase access.
Windows Permissions for ClearCase Windows permissions are composed of three elements: Security Descriptors
File Permissions
Directory Permissions
Security Descriptors
Security descriptors contain information about ownership of objects: who owns the object, who can access the object, and the types of access allowed for the object. A discretionary access control list (DACL) is a component of a security descriptor which is viewable and modifiable by users with read access to the object. Note that the terms DACL and access control list (ACL) are used interchangeably.
VOB and view storage directories (ending with .vbs and .vws ) use identity.sd and groups.sd files that describe ownership, regardless of the file system on which they reside. The contents of these files can be viewed using the cacls command.
Additional information regarding the VOB and view’ access control list can be found in the Troubleshooting Section in the IBM Rational ClearCase Administrator's Guide
Note: If permissions on the VOB or view storage directories (.vbs or .vws) are manually modified from the operating system level, ClearCase may not recognize the access control list (ACL) format of those permissions and you will need to run fix_prot on the VOB or view storage directory. Review technote 1142606 for directions on running fix_prot. Also, see the VOB and View Administration sections in the IBM Rational ClearCase Administrator's Guide. ClearCase Server Storage Locations or Shares:
These permissions are controlled by the operating system and not by ClearCase. However, these settings can impact ClearCase operations.
Page 280 of 341
ClearCase Environment – How do I Whether you are using the mkstgloc command to create your VOB/view storage location or you simply share out a directory on the server for storing VOBs and views (for example viewstore or vobstore), the Windows share permissions on the folder must be as follows:
a. ClearCase Administrative Group (clearcase) - Full Control (both VOBs and views)
b. ClearCase Users Groups - Full Control on the share (views only)
c. ClearCase Users Groups - Change on the share (for VOBs) for the following groups:
VOB's Primary Group
Additional groups on VOBs group list
Note: See technote 1147041 for more details on server storage locations.
ClearCase Home directory and all subdirectories
a. ClearCase Administrative group (clearcase) - Full Control
b. ClearCase Home = C:\Program Files\Rational\ClearCase Recommendations Due to the fact that share and NTFS permissions combine for the most restrictive when accessed over the network, the easiest way to control access to the VOB and view storage directories is to use share access controls, and leave the underlying NTFS directories as "Everyone: Full Control".
For more information regarding share and NTFS permissions, please refer to the following: http://www.microsoft.com/technet/technetmag/issues/2006/01/HowITWorksNTFS/?related=/technet/tec hnetmag/issues/2006/01/HowITWorksNTFS http://technet2.microsoft.com/windowsserver/en/library/d043701a-5a2e-4001-b659- 0c23c90f76f61033.mspx?mfr=true http://technet2.microsoft.com/windowsserver/en/library/87b011ec-b1b4-4baf-8ab0- 53147b22a4201033.mspx?mfr=true http://support.microsoft.com/kb/301195 Since User Access Rights can be modified on the view or VOB server to limit who has the right to logon locally, this would limit the impact of using “Everyone: Full Control” on the NTFS file system. This permission would only apply to users who have interactive logon rights. For more information regarding interactive logons and user rights, please refer to: http://support.microsoft.com/kb/823659 Changing this type of access should not impact users who access shares over the network.
However, if the security restrictions in your environment do not allow the use of “Everyone: Full Control”, you will have to align your share and NTFS permissions to get the correct results. It is up to your administrator to determine what Windows permissions are appropriate for your environment based on your security requirements. As stated above, IBM Rational can only specify generic guidelines, which should be reviewed by a certified system and/or network administrator as it is not possible to address specific permissions for every environment.
The following permissions are the minimum required for ClearCase to function correctly. If Windows security (disk, registry, policies, etc) has been set in a manner that is too restrictive for ClearCase to function properly, additional modifications may be required for your environment. The share permission levels and the ClearCase functions they permit are: Full Control -
This is the minimum level of permission needed to create VOBs and Views.
This level is needed because the cleartool process creates and protects the VOB/View database. Changing the ACL on a file in a share requires "Full Control" access through that share.
Change - Page 281 of 341
ClearCase Environment – How do I This is the minimum share permission level (read and write) to use, but not create, a ClearCase VOB or view.
This is needed because a number of ClearCase commands will be directly modifying files in VOB storage pools, and file system commands may be indirectly modifying files in a view's pools. The minimum NTFS permissions required to use, but not create, a VOB or a view are: Full Control for the ClearCase Administrators Group on both the VOB and view shared folders
Read, List Folder Contents, Read & Execute, Write for the ClearCase User Groups on the view shared folder.
Read, List Folder Contents, Read & Execute for the ClearCase User Groups on the VOB shared folder. The minimum NTFS permissions required to create a VOB or a view are: Full Control for the ClearCase Administrators Group on both the VOB and view shared folders.
Full Control for a user (if you want a specific user to be able to create a VOB but do not want them to be added to the ClearCase Administrators Group) on the VOB shared folder. This user must be a member of VOB's primary group.
Full Control for the ClearCase User Groups to allow view creation on the view shared folder Permission examples when accessing a shared folder:
An example of how permissions combine:
ClearCase Administrators group has Full Control on the share
ClearCase Users group has Change on the share to use VOBs or views
Everyone has Full Control on NTFS The effective permissions when accessing the shared folder over the network are:
ClearCase Administrators group has Full Control
ClearCase Users group has Change
An example of combined permissions that would cause a problem:
ClearCase Administrators group has Full Control on the share and NTFS
ClearCase Users Group has Change on the share and Full Control on NTFS
Everyone has Read on NTFS The effective permissions when accessing the shared folder over the network are:
ClearCase Administrators group has Read
ClearCase Users group has Read
Note: If the Everyone group was removed from the NTFS permissions, the effective permissions accessing the share over the network in Example 2 would be the same as Example 1.
Note: Refer to the Preserving NTFS ACLs when copying a VOB or view storage directory section of the ClearCase Administrators Guide for information about special considerations regarding the NETWORK group ACLs on a NAS.
Page 282 of 341
ClearCase Environment – How do I 238. How do I – understand the “Cannot bind an admin_server handle on Windows” issue The following error is reported when attempting to create a view or VOB or when trying to start a view. cleartool: Error: Cannot bind an admin_server handle on "host1": error detected by ClearCase subsystem. Note: If you are attempting to create a VOB or view on a NAS filer and receive the Cannot bind an admin_server handle error, review technote 1124253 for more details.
Cause The error is caused by any one of a number of different programs conflicting with Rational ClearCase on the local machine. IMPORTANT: The program could be legitimate and purposely installed on a system or it could also be spyware that is running unknowingly on a system. If the program is legitimate, please contact the vendor for information about moving it down the protocol stack. In either case, these problematic programs can be running on top of the TCP/IP stack on a Windows system which prevents ClearCase from functioning properly, such as the system's performance being impacted by freezing or hanging when accessing objects in a view.
Examples: Attempts to create a dynamic view results in the following errors: During View creation using the View Creation Wizard:
Error creating view '
During VOB creation using the VOB Creation Wizard:
Error creating VOB VOB Creation Wizard Error: Cannot bind an admin_server handle on "
Attempts to run cleartool getlog returns the following errors:
>cleartool getlog -all -full admin_contact_call_V1: RPC: Unable to receive; errno = [WINSOCK] Connection reset by peer
>cleartool getlog -all -full cleartool: Error: Problem starting admin_server for host
Page 283 of 341
ClearCase Environment – How do I
Additional errors in the ClearCase logs (as well as the Event Viewer logs) related to this problem: admin log: admin_contact_call_V1: RPC: Unable to receive; errno = [WINSOCK] Connection reset by peer albd log:
Albd(496): Error: Server admin_server.exe (pid=3144) on "" died on startup; marking it as "down". cccredmgr log: cccredmgr(556): Warning: OpenProcessToken failed: Error 5: No additional description available for this system error.
Event Viewer - System Log:
Application popup: admin_server.exe - Application Error : The exception unknown software exception (0xccccdead) occurred in the application at location 0x7c81eb33. view log: view_contact call failed: RPC: Unable to receive; errno = "WINSOCK¨ Connection reset by peer
Resolving the problem In order to check to see if you have a program that is conflicting with ClearCase follow the instructions below: 1. Click on Start > Run type winmsd and hit the Enter key.
Note: A window will pop up that says System Information.
2. In the left hand pane of the window, expand the Components item.
3. Then expand Network and click on Protocol.
4. In the right hand pane of the window you will see an Item and a Value column.
Note: The first entry should be MSAFD Tcpip [TCP/IP] and the second should be MSAFD Tcpip [UDP/IP].
Page 284 of 341
ClearCase Environment – How do I
If the first item does not list MSAFD Tcpip [TCP/IP] and lists something else, then spyware is more than likely to be running on the system.
Example:
Item Value Name OSMIM --> MSAFD Tcpip [TCP/IP] ConnectionlessService False GuaranteesDelivery True GuaranteesSequencing True MaximumAddressSize 16 bytes MaximumMessageSize 0 bytes MessageOriented False MinimumAddressSize 16 bytes PseudoStreamOriented False SupportsBroadcasting False SupportsConnectData False SupportsDisconnectData False Page 285 of 341
ClearCase Environment – How do I SupportsEncryption False SupportsExpeditedData True SupportsGracefulClosing True SupportsGuaranteedBandwidth False SupportsMulticasting False
Note: This is an example of the MarketScore spyware application signature.
You will need to run a spyware removal tool to completely remove this program from the system. If the first item lists something like SlipStream over MSAFD Tcpip [TCP/IP] then a conflicting program is installed on the ClearCase host. Remove this program by using the Add or Remove Programs in the Windows Control Panel.
239. How do I - add multiple domain names to the CredmapAllowedDomainList This technote explains how to properly add multiple Windows® domain names to the CredmapAllowedDomainList registry entry located in the IBM® Rational® ClearCase® control panel.
Solution There are two ways to add a list of different domains to the CredmapAllowedDomainList registry entry:
1. In order to specify multiple domains in the ClearCase Control Panel (Start > Run type: cc.cpl) section titled "Use this domain to map UNIX user and group names", use a comma separated list with no spaces (e.g., DOMAIN1,DOMAIN2,DOMAIN3.) Example BEFORE:
Page 286 of 341
ClearCase Environment – How do I Example AFTER:
Note: Upon revisiting the ClearCase Control Panel, the Domain section will change from a drop down menu to a text box.
2. Another way to do this would be to modify the registry. Note: This solution contains information about modifying the system registry. Before making any modifications to the Microsoft® Registry Editor, it is strongly recommended that you make a backup of the existing registry. For more information describing how to back up the registry, refer to the Microsoft Knowledge Base article http://support.microsoft.com/kb/256986. a. Open registry editor (Start > Run and type regedit) b. Change in to the CurrentVersion key located at
HKEY_LOCAL_MACHINE\Software\Atria\ClearCase\CurrentVersion c. Double click the value CredmapAllowedDomainList d. Add the domain one under the other.
Page 287 of 341
ClearCase Environment – How do I Example:
Note: Domains are added one below the next. Licensing 240. How do I - reset the license usage statistics reported by clearlicense The statistics represent the activity since the license server was last started. It is a thread generated by the albd_server. To reset the following clearlicense license usage statistics you must stop/start the albd_server. This will (unfortunately) shut down clearcase. licenses revoked since last start of period
license requests denied active users bumped by preferred user
241. How do I - Denying users from pulling a ClearCase license Denying users can be done in the license database file, license.db, using the -nuser switch. The license file can contain any number of –nuser lines, each of which specifies one or more users (by name or by numeric ID). The specified users cannot obtain a license and thus cannot use the product. Note: The –user and –nuser lines can be intermixed. If a user is named in both kinds of line, the first entry is used. On Windows, this is done in the ClearCase Properties applet: 1. Go to Start > (Settings >) Control Panel > double-click the ClearCase icon > select the Licensing tab 2. Enter -nuser Domain/user_name after the -license declarations
Page 288 of 341
ClearCase Environment – How do I Note: All lines in the license.db file must be terminated with a new line character (or Enter).
On UNIX or Linux: 1. Edit the license.db in var/adm/atria or var/adm/rational/clearcase, depending on your ClearCase version. 2. Enter -nuser user_name after the -license declarations.
Note: All lines in the license.db file must be terminated with a new line character (or Enter).
Example (applicable to all operating systems):
-license ClearCase ATRIA *.1 NONE 1235678.12345678.02 -nuser user1 242. How do I – know the ClearCase commands that DO NOT require a ClearCase license The following cleartool sub-commands DO NOT require a ClearCase Atria License: setview startview edcs setcs man help apropos pwv
243. How do I - switch between Atria and FLEXlm licensing This technote describes how you can switch from Atria licensing to using FLEXlm licensing, and from FLEXlm to Atria licensing after installation. Switching from Atria licensing to FLEXlm licensing To switch from Atria licensing to FLEXlm licensing, follow these steps. 1. Identify the name of the FLEXlm license server host. 2. On the client machine, stop ClearCase. 3. Copy the /opt/rational/clearcase/config/rcl/flexlm_host.template file to /var/adm/rational/clearcase/config directory and rename it as flexlm_host. 4. Verify that this file has read access for all users. 5. Open the flexlm_host file and replace the word hostname with the name of the FLEXlm license server host. Example: SERVER venus ANY
ClearCase Environment – How do I 7. Restart ClearCase. The license should be checked out from the specific FLEXlm license server. Switching from FLEXlm to Atria licensing To switch from FLEXlm licensing to Atria licensing, follow these steps. 1. Identify the name of the Atria license server host. 2. Stop ClearCase. 3. Go to the /var/admin/rational/clearcase/config directory. 4. Create a file titled license_host, open it, and add the ClearCase license server host name on the first line. 5. Remove the flexlm_host file. Restart ClearCase. 244. How do I - configure ClearCase 7.1.x on UNIX to support multiple license servers ClearCase versions 7.0 and 7.1 add the ability to access licenses using the Acresso Flex/LM license API. This license toolkit permits you to configure the following license server configurations, among others: Redundant license servers serving licenses from the same pool of licenses. This permits continued use of licensed tools in the event of a license server failure.
Multiple non-redundant license servers. This can permit, among other things, license "reuse" across the organization as licenses not in use in one region can be used by users in other regions if their local license servers are temporarily out of licenses. However, IBM Rational ClearCase appears to only use the /var/adm/rational/clearcase/config/flexlm_host file to determine the license server to access. Any attempt to configure that file to support multiple license servers may fail with any one of a number of errors, including: cleartool: Error: Lic err from FLEXlm: Invalid (inconsistent) license key The key word here is "appears." ClearCase can, and does, use the "standard" Flex/LM environment variables to configure licensing in addition to the /var/adm/rational/clearcase/config/flexlm_host file. The following environment variables can be set to configure multiple license server support in Rational ClearCase: RATIONAL_LICENSE_FILE Flex/LM calls this a "Vendor-specific license file" environment variable, often referring to it as "VENDOR_LICENSE_FILE." This environment variable is used by all IBM Rational tools that use Flex/LM licensing. This environment variable points to the file containing the license information, or to the license servers. On Unix, non-redundant servers are separated by colons, for example: RATIONAL_LICENSE_FILE=27000@license1:27000@license2
If you are using redundant servers, you must have sets of 3 redundant servers, and separate them by commas. You *can* have multiple redundant server sets, but it is not recommended at this time.
FLEXLM_NO_CKOUT_INSTALL_LIC This license file will prevent the Flex/LM toolkit from updating (or creating) the ~/.flexlmrc file on a successful license checkout. If this environment variable is not set, the normal behavior is to update or add a "RATIONAL_LICENSE_FILE" line in this file specifying the server used in the last successful license checkout. If you are using multiple license servers in multiple geographic regions, saving that information could result in degraded client performance if the license server in this file is not local.
FLEXLM_DIAGNOSTICS This environment variable can be set to provide additional license checkout status when configuring the license file environment variables. In this context, you can use it to monitor successful license checkouts to determine what server a given license client process used to get a license.
LM_LICENSE_FILE (not recommended) This environment variable is the global license file specification for all Flex/LM enabled products. Rational tools will use this environment variable if the RATIONAL_LICENSE_FILE environment variable is not set. We do not recommend using this environment variable for ClearCase licensing since adding servers to this variable could impact the performance of other Flex/LM- enabled applications.
Page 290 of 341
ClearCase Environment – How do I To fully take effect, these environment variables need to be set in any context that ClearCase tools would reasonably be needed. Generally speaking, this means that license information needs to be set in the following locations: System-wide shell startup scripts. Those scripts include (depending on the shell):
o /etc/profile (sh-derived shells, including sh, bash, zsh)
o /etc/csh.cshrc (csh-derived shells, including csh and tcsh)
ClearCase startup script in:
o /opt/rational/clearcase/etc/clearcase (ClearCase 7.0)
o /opt/ibm/RationalSDLC/clearcase/etc/clearcase (ClearCase 7.1)
RWP/IHS server configuration:
o RWP/WAS startup scripts.
a. /var/adm/rational/common/ewas/conf/ewas_startup (ClearCase 7.1)
b. /var/adm/rational/common/ihs/conf/ihs_startup (ClearCase 7.1)
c. /opt/rational/common/rwp/bin/rwp_startup (ClearCase 7.0)
o Web server configuration files.
a. /var/adm/rational/common/rwp/conf/ccrc.conf (ClearCase 7.0)
b. /var/adm/rational/common/ihs/conf/ccrc.conf (ClearCase 7.1) One suggested configuration: 1. Ensure that the /var/adm/rational/clearcase/config/flexlm_host file exists and has the correct syntax. This is necessary because the presence of this file tells ClearCase to use Flex/LM licensing. Since the license information will be configured using environment variables, the following 2 lines can be the exact contents of this file: SERVER nonexistent-host ANY 27000 USE SERVER
2. Add lines similar to the below lines at the beginning of the ClearCase Startup script, immediately after the initial comments: FLEXLM_DIAGNOSTICS=3 FLEXLM_NO_CKOUT_INSTALL_LIC=1 RATIONAL_LICENSE_FILE=27000@server1:27000@server2:27000@server3 export FLEXLM_DIAGNOSTICS RATIONAL_LICENSE_FILE FLEXLM_NO_CKOUT_INSTALL_LIC
3. Add the lines from step 2 to the eWAS startup script (ClearCase 7.1) at /opt/ibm/RationalSDLC/common/eWAS/bin/was_boot or the IHS startup script (ClearCase 7.0.x) at /opt/rational/common/rwp/bin/rwp_boot. This should be done after the initial comments in the file. This is needed to allow ClearCase Remote Client (CCRC) users to also "roll over" to the other license servers.
4. Add the same lines to the top of /etc/profile, after the initial comment block. (There may be conditional statements in that shell startup script that would cause the script to exit before reaching these environment variable settings otherwise.)
5. Add lines similar to the below lines to the /etc/csh.cshrc file, also after the initial comment block: setenv FLEXLM_DIAGNOSTICS 3 setenv RATIONAL_LICENSE_FILE 27000@server1:27000@server2:27000@server3 setenv FLEXLM_NO_CKOUT_INSTALL_LIC 1
6. Configure WAS or RWP to pass license information to the processes that handle user activity:
Page 291 of 341
ClearCase Environment – How do I 1. ClearCase 7.0: Add the following lines to /var/adm/rational/common/rwp/conf/ccrc.conf immediately prior to the line: PassEnv RATIONAL_LICENSE_FILE PassEnv FLEXLM_DIAGNOSTICS PassEnv FLEXLM_NO_CKOUT_INSTALL_LIC
2. ClearCase 7.1: ClearCase 7.0: Add the following lines to /var/adm/rational/common/ihs/conf/ccrc.conf immediately prior to the line: PassEnv RATIONAL_LICENSE_FILE PassEnv FLEXLM_DIAGNOSTICS PassEnv FLEXLM_NO_CKOUT_INSTALL_LIC
7. Locate any .flexlmrc files in user (including root user) home directories and either delete them or remove any "RATIONAL_LICENSE_FILE" lines.
8. Once you have verified that the multiple license server support is working as desired, remove the lines setting/exporting FLEXLM_DIAGNOSTICS and restart ClearCase. This can be extended to provide a single point of control for license information by doing the following: 1. Create the license configuration file in a central location. In this example, the license files are "/net/server2/export/licinfo/lic-evs.sh" and "/net/server2/export/licinfo/lic-evs.csh". The permissions on this file should be 555.
2. Ensure that the desired license environment variables are set in those files. For example: (/net/server2/export/licinfo/lic-evs.sh) #!/bin/sh FLEXLM_DIAGNOSTICS=3 FLEXLM_NO_CKOUT_INSTALL_LIC=1 RATIONAL_LICENSE_FILE=27000@server1:27000@server2:27000@server3 export FLEXLM_DIAGNOSTICS RATIONAL_LICENSE_FILE FLEXLM_NO_CKOUT_INSTALL_LIC (/net/server2/export/licinfo/lic-evs.csh) #!/bin/csh setenv FLEXLM_DIAGNOSTICS 3 setenv RATIONAL_LICENSE_FILE 27000@server1:27000@server2:27000@server3 setenv FLEXLM_NO_CKOUT_INSTALL_LIC 1
3. Ensure that all servers that will use this file mount the filesystem containing the environment setup files *before* ClearCase and IHS/RWP start.
4. Configure WAS or RWP to pass license information to the processes that handle user activity:
1. ClearCase 7.0: Add the following lines to /var/adm/rational/common/rwp/conf/ccrc.conf immediately prior to the line: PassEnv RATIONAL_LICENSE_FILE PassEnv FLEXLM_DIAGNOSTICS PassEnv FLEXLM_NO_CKOUT_INSTALL_LIC
2. ClearCase 7.1: ClearCase 7.0: Add the following lines to /var/adm/rational/common/ihs/conf/ccrc.conf immediately prior to the line: PassEnv RATIONAL_LICENSE_FILE PassEnv FLEXLM_DIAGNOSTICS PassEnv FLEXLM_NO_CKOUT_INSTALL_LIC
5. Locate any .flexlmrc files in user (including root user) home directories and either delete them or remove any "RATIONAL_LICENSE_FILE" lines.
6. Add the appropriate "source" commands to the following files, in most cases, the best place to put the "source" lines is immediately following the copyright notice.
1. The commands to add are:
For startup scripts and /etc/profile:
Page 292 of 341
ClearCase Environment – How do I if [-e "/net/server2/export/licinfo/lic-evs.sh"]; then source /net/server2/export/licinfo/lic-evs.sh fi
For /etc/csh. cshrc
if (-e "/net/server2/export/licinfo/lic-evs.csh") then source /net/server2/export/licinfo/lic-evs.csh endif
2. Where to add the commands:
ClearCase 7.0 startup scripts:
o /opt/rational/clearcase/etc/clearcase
o /opt/rational/common/rwp/bin/rwp_startup
ClearCase 7.1 startup scripts:
o /opt/ibm/RationalSDLC/clearcase/etc/clearcase
o /var/adm/rational/common/ihs/conf/ihs_startup
o /var/adm/rationa/common/ewas/conf/ewas_startup
Shell startup files:
o /etc/profile (sh-derived shells, including sh, bash, zsh)
o /etc/csh.cshrc (csh-derived shells, including csh and tcsh) After performing the steps above, the license configuration can be changed by editing the files in step 1, restarting the ClearCase, IHS/RWP, and eWAS services, and having the end users log out and back in.
Related information flexlm_host file created incorrectly during install 245. How do I – understand why windows user is consuming two ClearCase licenses when license server is hosted on UNIX or Linux The output of a clearlicense command is showing that a ClearCase user who is running on a Windows host is consuming two ClearCase Licenses. ------clearlicense output from the Windows host: ------ACTIVE users: User Priority Time-out in stevek none 29 minutes (at 11:27:37) twp1 none 29 minutes (at 11:27:08) abc1 none 24 minutes (at 11:22:15) abc1 none 23 minutes (at 11:21:48) efg1 none 17 minutes (at 11:15:16) hij1 none 16 minutes (at 11:14:41) xyz1 none 15 minutes (at 11:14:04) xyz1 none 15 minutes (at 11:13:37)
------clearlicense output from the UNIX server: ------ACTIVE users: User Priority Time-out in stevek none 29 minutes (at 11:27:39) twp1 none 29 minutes (at 11:27:10) abc1 none 24 minutes (at 11:22:17) Page 293 of 341
ClearCase Environment – How do I SID:3.010500000000000500000015f4d90be5eb188420ac5cfa9c00000473 ghc1 none 17 minutes (at 11:15:18) jgk1 none 16 minutes (at 11:14:43) SID:3.010500000000000500000015f4d90be5eb188420ac5cfa9c000006db xyz1 none 15 minutes (at 11:13:39)
Cause The ClearCase View Server and Client machine do not have matching domain mapping settings.
Diagnosing the problem You can enable auditing of the licensing activity to help troubleshoot this issue.
Add the following line to the ClearCase license file "license.db" (be sure to include the hyphen at the beginning of the line):
-audit
(then you will need to bounce the server or at least restart the atria services) From the albd log output below we can see that two different ip addresses are both grabbing a license.
2008-05-18T13:01:48-07 albd_server(24848): Ok: ClearCase license RENEWED for use r dgh1, SID UNIX:UID-1412, on 9.34.55.113. Timeout Sun May 18 13:31:48 2008. 17 of 17 concurrent licenses in use. 2008-05-18T13:03:21-07 albd_server(24848): Ok: ClearCase license RENEWED for use r dgh1, SID UNIX:UID-1412, on 9.34.55.37 . Timeout Sun May 18 13:33:21 2008. 17 of 17 concurrent licenses in use. From the above output we were able to determine that one of the licenses was taken by the ClearCase Window's View Server and the other was from the Windows ClearCase client
Resolving the problem On the Windows ClearCase View Server set the Domain field to a domain that is appropriate for your environment. Go to the Window's ClearCase View Server and check for the following. 1. ClearCase Control Panel, under the Options tab. a. Below the SMTP HOST b. You should see this: "Use this Domain to map Unix user and group names" 2. Domain: => If that field is blank, then click on the down arrow and chose a domain that is appropriate for you environment.
Note: For help information explaining the use of this field, click the question mark icon, ?, in the upper right corner of the window, then click the Domain: field.
Page 294 of 341
ClearCase Environment – How do I
Permissions 246. How do I – understand the this application has failed to start because the application configuration is incorrect issue When any directory in the directory tree to which an executable resides has permission of 770, the executable (even if protected as 777) will fail to fire with one of the following errors: Windows Explorer or ClearCase Explorer: This application has failed to start because the application configuration is incorrect. Reinstalling the application may fix this problem. Command Line: The system cannot execute the specified program. Note: The same error results if the executable is a view private file. This problem has been logged as a defect in APAR PK14674.
Solution There is no resolution to this defect currently..
WORKAROUND: Set all of the directory permissions in the directory tree leading to the executable to 775 or higher. 247. How do I – understand the access denied errors executing an element in a proxy group configuration issue Why do attempts to run an executable that is an element in an IBM® Rational® ClearCase® VOB configured for use in a Microsoft® Windows® multiple domain setup results in an Access Denied error.
Cause The permissions on the Other are not set correctly in the proxy environment. Verify the permissions by running a cleartool describe on the element. If executing the element is failing, chances are the permissions are set to 770 (where Other has no Read or Execute rights).
Example: Z:\view\VOB\dir\cleartool describe -long notepad.exe version "notepad.exe@@\main\1" created 09-Jun-06.13:39:52 by CCAdmin-ClearUsers@host "created by clearfsimport" Element Protection: User : Domain\CCAdmin : r-x Group: Domain\CCUsers : r-x Other: : --- element type: compressed_file predecessor version: \main\0 Page 295 of 341
ClearCase Environment – How do I
Cause 2 If the file element does have the correct permissions (where Read and Execute are set) then the directory where this file resides may not have the executable bit set. Verify the permissions by running a cleartool describe on the directory.
Example: Z:\view\VOB\dir\>cleartool describe –long . directory version ".@@\main\1" created 01-Jun-06.11:05:43 by CCAdmin-ClearUsers@host "created by clearfsimport" Element Protection: User : Domain\CCAdmin : rwx Group: Domain\CCUsers : rwx Other: : --- element type: directory predecessor version: \main\0
Cause 3 If the permissions on the directory and element are set correctly, the user may not be a member of the group to which the element is owned (based on the output from the cleartool describe command). Run the creds utility (creds -w) and look for the following:
Note: Review technote 1221403 for more details about the creds utility.
1. See if your primary group matches that of the group to which the element is owned.
Example:
C:\Program Files\Rational\ClearCase\etc\utils>creds -w Login name: Domain\jdoe USID: NT:S-1-5-21-4179696171-2760821386-689065543-500 Primary group: Domain\CCUsers (NT:S-1-5-21-4179696171-2760821386-689065543-1011) 2. If the primary group does not match, see if you are a member of the group to which the element is owned. The information is located inthe Groups section of the creds output.
Example: C:\Program Files\Rational\ClearCase\etc\utils>creds -w Login name: Domain\jdoe USID: NT:S-1-5-21-4179696171-2760821386-500 Primary group: Domain\Users (NT:S-1-5-21-4179696171-2760821-1011) Groups: (7) Domain\CCUsers (NT:S-1-5-21-4179696171-2760821386-513) Everyone (NT:S-1-1-0) BUILTIN\Administrators (NT:S-1-5-32-544) BUILTIN\Users (NT:S-1-5-32-545) NT AUTHORITY\INTERACTIVE (NT:S-1-5-4) NT AUTHORITY\Authenticated Users (NT:S-1-5-11) LOCAL (NT:S-1-2-0) 3. If the group is in the groups list of the creds output, check to see if the number of groups to which you are a member exceeds 32 groups. The number in parenthesis next to the Groups output displays the total number of additional groups you are a member.
Example:
C:\Program Files\Rational\ClearCase\etc\utils>creds -w Login name: Domain\jdoe USID: NT:S-1-5-21-4179696171-2760821386-500 Primary group: Domain\Users (NT:S-1-5-21-4179696171-2760821-1011) Groups: (36) Domain\CCUsers (NT:S-1-5-21-4179696171-2760821386-513) Everyone (NT:S-1-1-0)
Solution The ClearCase Administrator's Guide (Appendix B, Rational ClearCase and Windows domains) states that when setting VOB element permissions, all elements in any VOB that are accessed by users who are members of proxy groups must allow Read rights for Other. Page 296 of 341
ClearCase Environment – How do I
What it does not state explicitly (but can be inferred) is that the same holds true for elements that need to be executed as well. In order to run any elements in a VOB configured with a proxy group setup, the Other group needs "Execute" rights (775).
Run the cleartool protect command on the element to change the permissions for Other to 775.
Example:
Z:\view\VOB\dir\cleartool protect -chmod 775 notepad.exe
Solution 2 The issue where the directory to which the element resides does not have execute permissions has been reported as defect APAR PK14674. See technote 1222178 for more details and related workaround.
Solution 3 1. If the user is a member of the group on the domain controller, but the group is not set as the primary group, set the variable CLEARCASE_PRIMARY_GROUP as instructed in the ClearCase Administrator's Guide. Review technote 1135509 for more information about the variable. 2. If the user is not a member of the group to which the element is owned, you need to add the user to the groups on the domain controller.
Note: The user must log off and log back in for the change to take affect. Verify the user is a member of the group. If the user is a member of more that 32 groups (as reported by creds -w), you will need to set the CLEARCASE_GROUPS variable. Review technote 1124574 for more information about the variable. Support policies 248. How do I – understand about ClearCase support for Microsoft Windows 7 Operating system Does IBM Rational ClearCase support the Microsoft Windows 7 operating system?
Request for enhancement (RFE) RATLC01282967 has been opened requesting ClearCase 7.x support for Microsoft Windows 7
Refer to RATLC01282967 on the Rational Software RFE Community for further information or to post comments and add yourself to the watchlist for this RFE.
Refer to Rational RFE Community homepage for details. Updated information about ClearCase system requirements including operating system support is available in the following technotes: Technote 1302974 System Requirements for ClearCase 7.1 Technote 1239315 System Requirements for ClearCase 7.0.x.x 249. How do I – understand the Support Policy for ClearCase on Solaris Branded Zones Rational has added ClearCase support for Solaris Branded Zones. This support is available for both Solaris 8 and Solaris 9 Branded Zones running on Solaris 10 SPARC for ClearCase 7.0.x.x. ClearCase Branded Zone support requires one of the following ClearCase updates: ClearCase 7.0.0.8
ClearCase 7.0.1.7 In addition, ClearCase support for Solaris 8 and 9 Branded Zones requires: Solaris Containers 1.0.1 Solaris 10 10/08 (Update 6) Solaris patch 137137-09 (or later) Solaris patch 140408-01 (or later) Refer to Sun documentation for information about how to configure and install a Solaris 8 or 9 Branded Zone. The ClearCase documentation for support of Solaris Non-Global Zones also applies to ClearCase running in Branded Zones. Refer to see Technote 1258546 for information on running ClearCase in a Non-Global Zone.
Request for Enhancement, (RFE) RATLC01259417, had been submitted to add support for Branded
Page 297 of 341
ClearCase Environment – How do I Zones; this RFE remains open at this time as support for Branded Zones in ClearCase 7.1.x is not yet available. You can view or post comments for RATLC01259417, on the RFE community 250. How do I – understand the Support Policy for ClearCase on Linux 1. Support for Linux kernels in the current Rational ClearCase releases
From within the latest shipped patch release of Rational ClearCase release, IBM Rational will support all Linux kernel versions and patches supported by the vendor for all Linux OS versions supported by the ClearCase release. This includes not only the initial kernel version supported by the vendor for an OS version, but also kernels or patches for which the vendor subsequently announces support for that operating system version.
Note: This does not include customized kernels provided by the vendor to specific customers. Only the kernels provided by the vendors which are available to the public are supported.
Further Clarification: Refer to the following technotes for details regarding the supported kernels for the various ClearCase versions:
Technote 1136950 System Requirements for ClearCase 2003.06.xx Technote 1239315 System Requirements for ClearCase 7.0.x.x Technote 1302974 System Requirements for ClearCase 7.1 Technote 1224586 System Requirements for the ClearCase Remote Client 2. Support for new operating system releases in the current Rational ClearCase release
When a new version of a supported Linux Operating System is released, Rational ClearCase will consider adding support for the new version after 90 days review. The latest release of ClearCase will be tested and any previous ClearCase releases (even though supported) will be evaluated on a case by case basis. 3. Support for new kernels, service packs and operating systems in previous Rational ClearCase releases
Support for new kernels, service packs and operating systems will be provided only for the currently shipped Rational ClearCase release.
However, if a new release of Rational ClearCase running on clients is incompatible with the previous release of Rational ClearCase running on servers, IBM Rational will also provide support in the previous release for new kernels supported by the vendor for those OS versions supported by the previous Rational ClearCase release. Support for new vendor OS versions will not be provided in the previous Rational ClearCase release.
For example, Rational ClearCase 2002.05.00 servers are not compatible with Rational ClearCase 2003.06.00 clients, so IBM Rational will continue to provide support for new kernels in Rational ClearCase 2002.05.00 for the Linux vendor OS versions while Rational ClearCase 2003.06.00 is the currently shipping release. However, new Linux vendor OS versions will not be supported in Rational ClearCase 2002.05.00 while Rational ClearCase 2003.06.00 is the currently shipping release. 4. Support requiring Rational ClearCase patch
When support for new Linux kernels, service packs or operating systems requires changes to the Rational ClearCase product, support will be available through the normal patch process and is expected to be delivered within 90 days of the Linux vendor’s announced support. 5. Support not requiring Rational ClearCase patch
When support for new Linux kernels, service packs or operating systems requires no changes to the Rational ClearCase product, support will be available as soon as testing is completed and can be expected within 90 days of the Linux vendor’s announced support. Support will be announced through an update to the Rational ClearCase supported platforms and operating systems web page. 6. Obsolete kernels
IBM Rational reserves the right to drop support for Linux kernels that IBM Rational feels no longer warrant our support effort. This would generally apply to kernels that have long been superseded by more desirable versions. Users would not be required to move off these kernels, but IBM Rational will no longer test them for future patches and releases. 7. Custom Linux kernels
Linux vendor kernels that have been modified by third parties that are not officially supported by the Linux vendor themselves are not supported in Rational ClearCase at this time. 8. Different kernels for different CPUs
IBM Rational specifies support for specific operating system and kernel versions for specific CPUs. The same operating system and kernel version on a different chipset is not supported.
For example, Red Hat 2.1 kernel 2.4.9 e3 is supported on the Intel x86 kernel. It is not supported on other CPUs such as the Itanium or Alpha. 9. Secure Linux (SELinux) and ClearCase
If the security feature of Linux known as SELinux is enabled on a ClearCase host, normal operations can fail. ClearCase is currently not supported on Secure Linux (SELinux). Change request RATLC00762574 has been submitted requesting support for ClearCase on SELinux.
Page 298 of 341
ClearCase Environment – How do I 10. General Rational ClearCase policy
This Linux kernel support policy is still subject to existing IBM Software support policy described in the IBM International Program License Agreement Software Support Lifecycle policy. 11. Not supported
PAE - Physical Address Extension is not supported Related information TOC: ClearCase Matrices and Support Policies 251. How do I – understand about disk encryption software use with ClearCase Currently disk encryption software is not supported with Rational ClearCase. For example: Pointsec provides Full Disk Encryption Software for Desktop PCs. Change request (RFE) RATLC00762173 has been submitted to provide support for Pointsec with ClearCase.
252. How do I – understand the support Policy for Microsoft Windows Vista The information below provides details about the support requirements for running Rational ClearCase or ClearCase LT on Windows Vista.
Rational ClearCase clients are supported on Windows Vista.
IMPORTANT: Before reviewing the list below, refer to technote 1257474 for a list of known restrictions and limitations with this release of ClearCase support on Windows Vista.
Version Server Client Operating Platform Comments System ClearCase 7.0.0.1, 7.0.1, and 7.1 No Yes 32-bit Requires patch 7.0.0.1 IFix02 or later
64-bit * CCLT on 64-bit Windows Vista will not be supported CCLT Windows Vista 7.0.0.1 and 7.0.1 No Yes 32-bit Business Only
Requires Eclipse and JRE versions that Enterprise Edition support Vista.
Eclipse 3.2.2 or greater and IBM JRE CCRC Eclipse IDE (plug-in) Windows Vista 1.4.2 SR7 or greater recommended. 7.0.1.CU02 or later -- Yes Ultimate -- Review CCRC System Requirements MultiSite ClearCase MultiSite is not supported 7.0.0.1, 7.0.1, and 7.1 No No -- -- CCRC RCP Client ** Review CCRC System Requirements 7.0.1.D06 or later Yes ------
* IMPORTANT: FlexLM licensing is not supported on Windows Vista 64-bit editions. Atria Licensing is required on 64- bit editions. Review technote 1128958 for more details about Atria Licensing if required.
** ClearCase Remote Client (CCRC) Rich Client Platform (RCP) is also known as the stand-alone CCRC client.
Note: For the purposes of this technote, ClearCase Server is defined as a host storing VOBs. You can store views on a Client. With respect to MultiSite, this installation is designed for servers only. Clients do not need MultiSite installed to access replicated VOBs.
Feature Enhancements
Change request, (RFE) RATLC01358603, has been opened to allow MVFS support for Windows Vista SP1. Support for Windows Vista SP1 was added in 7.0.0.3 and 7.0.1.2 and later.
UAC is not supported. Change request, (RFE) RATLC01027748, is open for Rational ClearCase to support UAC.
Page 299 of 341
ClearCase Environment – How do I Refer to the following technotes for further information about ClearCase system requirements:
Technote 1239315 System Requirements for ClearCase 7.0.x.x
Technote 1302974 System Requirements for ClearCase 7.1 Before upgrading an existing Rational ClearCase 7.0.0.x or 7.0.1.x client to Microsoft Windows Vista
If you are upgrading to Microsoft Windows Vista on a computer that is currently running Rational ClearCase, you must follow this procedure:
1. Move all hosted view storage to another machine (for the purposes of preparing for the OS upgrade as well as backing up the views).
2. Uninstall Rational ClearCase.
3. Upgrade your computer's operating system to Microsoft Windows Vista.
4. Create a Rational ClearCase release area from version 7.0.0.1 or version 7.0.1. For details on creating a Rational ClearCase release area and installing Rational ClearCase, review the Rational ClearCase, ClearCase Multisite, and ClearCase LT Installation and Upgrade Guide (pdf copy GI11-6365-00).
Note: If you are upgrading an existing Rational ClearCase 7.0.x release area, the only allowable upgrade path to Rational ClearCase Version 7.0.0.1 IFix02 is from either of these two releases:
Rational ClearCase Version 7.0.0.1 Rational ClearCase Version 7.0.0.1 IFix01
For version 7.0.0.1, apply Rational ClearCase version 7.0.0.1 IFix02 or later to that release area.
Note: Rational ClearCase Version 7.0.0.1 IFix02 is specifically designed to support Microsoft Windows Vista. Do not install this version of Rational ClearCase on any other versions of Microsoft Windows. Use Rational ClearCase Version 7.0.0.1 IFix01 instead.
Installing Rational ClearCase on Microsoft Windows Vista
Installing ClearCase 7.1:
Follow the instructions documented in the IBM Rational ClearCase 7.1 Release Notes
Installing ClearCase versions prior to 7.1:
Install Rational ClearCase from the newly created release area.
Note: In Microsoft Windows Vista, you cannot install Rational ClearCase directly from a CD or using a downloaded installation or upgrade patch. You can only install from the updated release area. 253. How do I – understand the support policy for ClearCase use across multiple Active Directory forests Rational ClearCase version 4.2 and later are supported for use in an Active Directory environment; however, that support is limited to use within a single forest. All users and ClearCase servers must reside within the same forest. Note: For a Windows NT® 4 domain to work with Active Directory, Active Directory must be set to mixed mode. The relationship between an Active Directory domain and a Windows NT 4 domain is not the same a the relationship between 2 Windows NT 4 domains (even when Active Directory is in mixed mode). While support for ClearCase is provided in a multiple Windows NT 4 domain environment, when integrated with Active Directory, mixed-mode Active Directory domains (in different forests) are not equivalent to Windows NT 4 domains, thus this is not a supported configuration. Change request (RFE) RATLC00731489 has been submitted to add functionality to span across multiple forests. Review IBM Rational ClearCase Administrator's Guide for additional information on multiple user account domain support.
Related information Domain configurations compatible with Rational ClearCase Using active directory universal groups
Page 300 of 341
ClearCase Environment – How do I 254. How do I – understand the support Policy for ClearCase and Xen on Linux What is the support policy for IBM® Rational® ClearCase® on the Linux® operating system running the Xen™ virtual machine monitor?
Answer Xen is a virtual machine monitor (VMM) for x86 that supports execution of multiple guest operating systems. Xen is Open Source software, released under the terms of the GNU General Public License. Rational has not qualified the compatibility of ClearCase on Linux using the Xen VMM. Currently this is not supported.
Change request (RFE) RATLC01034042 has been submitted to support Xen with ClearCase.
A known problem identified on a Xen host was revealed during VOB creation. Creating VOBs on a Xen image with glibc version < 2.4 results in the following error:
%>cleartool mkvob -tag /stgloc_vob1 -stgloc stgloc_vob1 Comments for "/tmp/stgloc_vob1/stgloc_vob1.vbs": testing . cleartool: Error: Error from VOB database: "/tmp/stgloc_vob1/stgloc_vob1.vbs". cleartool: Error: Trouble opening VOB database: "/tmp/stgloc_vob1/stgloc_vob1.vbs". cleartool: Error: Unable to create versioned object base "/tmp/stgloc_vob1/stgloc_vob1.vbs".
This is an error with glibc. The glibc version 2.4 or greater must be used.
An error similar to the above issue is described in the Xen FAQ 255. How do I – understand ClearCase Support for Red Hat Linux 5.0 Support for RHEL 5.0 has been added in the following patches with the restrictions listed below:
UNIX/Linux
7.0.1 7.0.1.0-RATL-RCC-IFIX01
7.0.0.1 7.0.0.1-RATL-RCC-IFIX04 Review the System Requirements for ClearCase 7.x for more details on which operating systems are supported with ClearCase.
Restrictions: Review technote 1281877 for details about the RHEL 5 changes to using mlocate instead of slocate as its file locator and DB catalog tool along with the potential impact to the system after a ClearCase installation. do I – understand the support Policy for ClearCase on Linux 1. Support for Linux kernels in the current Rational ClearCase releases
In the currently shipping Rational ClearCase release, IBM Rational will support all Linux kernel versions and patches supported by the vendor for all Linux OS versions supported by the ClearCase release. This includes not only the initial kernel version supported by the vendor for an OS version, but also kernels or patches for which the vendor subsequently announces support for that operating system version. 2. Support for new operating system releases in the current Rational ClearCase release
When a new version of a supported Linux Operating System is released, Rational ClearCase will consider adding support for the new version after 90 days review. The latest release of ClearCase will be tested and any previous ClearCase releases (even though supported) will be evaluated on a case by case basis. 3. Support for new kernels, service packs and operating systems in previous Rational ClearCase releases
Support for new kernels, service packs and operating systems will be provided only for the currently shipped Rational ClearCase release.
However, if a new release of Rational ClearCase running on clients is incompatible with the previous release of Rational ClearCase running on servers, IBM Rational will also provide support Page 301 of 341
ClearCase Environment – How do I in the previous release for new kernels supported by the vendor for those OS versions supported by the previous Rational ClearCase release. Support for new vendor OS versions will not be provided in the previous Rational ClearCase release.
For example, Rational ClearCase 2002.05.00 servers are not compatible with Rational ClearCase 2003.06.00 clients, so IBM Rational will continue to provide support for new kernels in Rational ClearCase 2002.05.00 for the Linux vendor OS versions while Rational ClearCase 2003.06.00 is the currently shipping release. However, new Linux vendor OS versions will not be supported in Rational ClearCase 2002.05.00 while Rational ClearCase 2003.06.00 is the currently shipping release. 4. Support requiring Rational ClearCase patch
When support for new Linux kernels, service packs or operating systems requires changes to the Rational ClearCase product, support will be available through the normal patch process and is expected to be delivered within 90 days of the Linux vendor’s announced support. 5. Support not requiring Rational ClearCase patch
When support for new Linux kernels, service packs or operating systems requires no changes to the Rational ClearCase product, support will be available as soon as testing is completed and can be expected within 90 days of the Linux vendor’s announced support. Support will be announced through an update to the Rational ClearCase supported platforms and operating systems web page. 6. Obsolete kernels
IBM Rational reserves the right to drop support for Linux kernels that IBM Rational feels no longer warrant our support effort. This would generally apply to kernels that have long been superseded by more desirable versions. Users would not be required to move off these kernels, but IBM Rational will no longer test them for future patches and releases. 7. Custom Linux kernels
Linux vendor kernels that have been modified by third parties that are not officially supported by the Linux vendor themselves are not supported in Rational ClearCase at this time. 8. Different kernels for different CPUs
IBM Rational specifies support for specific operating system and kernel versions for specific CPUs. The same operating system and kernel version on a different chipset is not supported.
For example, Red Hat 2.1 kernel 2.4.9 e3 is supported on the Intel x86 kernel. It is not supported on other CPUs such as the Itanium or Alpha. 9. Secure Linux (SELinux) and ClearCase
If the security feature of Linux known as SELinux is enabled on a ClearCase host, normal operations can fail. ClearCase is currently not supported on Secure Linux (SELinux). Change request RATLC00762574 has been submitted requesting support for ClearCase on SELinux. General Rational ClearCase policy
This Linux kernel support policy is still subject to existing IBM Software support policy described in the IBM International Program License Agreement Software Support Lifecycle policy. 256. How do I – understand the support Policy for High Availability clustering and ClearCase As of ClearCase version 7.0.1, the following solutions are supported for High Availability with Rational ClearCase. SteelEye LifeKeeper Rational ClearCase Solution Veritas Cluster Server 4.1
Review the ClearCase Administrator's Guide on the topic of Configuring Rational ClearCase for high availability for more information. Note: ClearCase 2003.06.00 and 7.0.0.x are not supported in High Availability clustered server configurations for any operating system. There are a variety of change requests (RFEs) to add support of this functionality with ClearCase on different operating systems: RATLC01012276 - Microsoft Cluster Server Refer to record ID 88 on the IBM Rational Software RFE Community for updated information or to provide feedback.
RATLC00585651 - Sun Cluster Page 302 of 341
ClearCase Environment – How do I RATLC00586733 - AIX HA-CMP Cluster systems RATLC00587506 - HP ServiceGuard This RFE has been closed as the decision was made by Product Management to exclude the resolution of this feature enhancement from future upgrades and releases of ClearCase.
Refer to technote 1131230 Support Policy for Windows Server Datacenter Edition and ClearCase for information about Windows Datacenter Edition support. Information about ClearCase Remote Client (CCRC)
A ClearCase VOB server can be aliased and if this host has a problem, then a new host can be configured using the same alias name. This cuts down the time a view or VOB needs to be restored, reregistered, tagged and allows the new host to be ClearCase functional in a short amount of time. However, with CCRC the physical hostname is used by the CCRC clients so aliasing the hostname or clustering is not currently supported in CCRC. The CCRC view references are tied to the hostname and not the alias name of the host so restoring the views to an aliased hostname is not an option. 257. How do I – understand ClearCase Support for HP-UX 11.31 Support for HP-UX 11.31 has been added in the following patches with the restrictions listed below:
UNIX/Linux
7.0.1 7.0.1.0-RATL-RCC-IFIX01
7.0.0.1 7.0.0.1-RATL-RCC-IFIX04
Review the System Requirements for ClearCase 7.x for more details on which operating systems are supported with ClearCase.
Restrictions: Local dynamic views and VOBs are not supported on HP-UX 11.31 with the above patches.
Review technote 1273230 for information about a related defect that results from accessing local dynamic views and VOBs in this environment. 258. How do I – understand the support Policy for DFS (Distributed File System) and ClearCase Support policy for DFS (Distributed File System) use as a supported file system for use with IBM® Rational® ClearCase®.
Cause Attempts to start a view or accessing files with from a view that is stored on a DFS server results in the following error: Starting a view results in the following error:
Unable to connect drive to view error 59 The MVFS log reports the following errors:
11/28/00 07:37:07 mvfs(0): INFO: MVFS version 4.1+ (Sep 7 2000 10:24:25) 11/28/00 07:37:07 mvfs(0): INFO: IoCreateSymlink failed: MVFS drive symlink already exists. 11/28/00 06:08:13 mvfs(0): Error: mvfs_find_devobj: ntstatus 0xc0000183 11/28/00 06:08:13 mvfs(0): Error: MvfsFsNotification: Unsupported filesystem type (54) 11/27/00 23:21:26 mvfs(0): Error: SReleaseFile: no mdevattp found for fo0x824fd188 devobj 0x820b3030 11/27/00 23:21:26 mvfs(0): Error: mvfs_basefs_drvobj_to_attach: did not find host for fobj 0x824fd188 11/27/00 23:21:26 mvfs(0): Error: MvfsAcquireFile: no mdevattp found for fo 0x824fd188 fop 0x0 devobj 0x820b3030 drvobj 0x8207fa90
The cause of these problems relate to a Distributed File System (DFS) configured on the system, primarily the root replica. DFS is a service that provides an integration of files and shares into one or more logical name spaces, eliminating the need for users to be aware of the physical servers used for data storage on their networks. When MVFS attempts to access information within DFS, error messages as the above appear and the operation fails.
Solution DFS is not a supported configuration with any version of ClearCase. Page 303 of 341
ClearCase Environment – How do I
The decision was made by Product Management to exclude the resolution of change request (RFE) RATLC00625421: ClearCase support for DFS from future upgrades and releases due to the significant architectural changes required to implement the solution. Note: Rational ClearCase and DFS can coexist on the same server as long as ClearCase is not attempting to access any information within DFS. The ClearCase resources, such as the installation directory and view/VOB storage, should not be accessed through DFS.
The only supported resolution is to disable DFS and remove the root replica of the DFS system. Once DFS is removed, the problem will be resolved. Microsoft® Windows®: Note: These are only general guidelines. Consult your operating system guides or help files for more details.
To remove the display of a DFS root: 1. Stop ClearCase Services from the ClearCase Control Panel 2. Open DFS (click Start > Programs > Administrative Tools > Distributed File System) 3. In the console tree, right-click the DFS root node. 4. Click Remove Display of DFS Root, then click Yes. 5. Start ClearCase Services Note: The DFS root is removed from the console, it is not removed from the host computer. User access to the DFS root is not affected by this procedure. UNIX® and Linux® using Samba™: Note: These are only general guidelines. Consult your Samba help files for more details. Ensure the following lines are set accordingly in the smb.conf file to disable DFS: msdfs root = No host msdfs = No
Note: Not all versions of Samba are built to work with DFS. 259. How do I – understand the support Policy for Altiris Server Management Suite with ClearCase 1. Can ClearCase client installs be deployed using Altiris Server Management Suite as the software delivery vehicle?
Answer: The deployment of ClearCase installations using Altiris Server Management Suite is unsupported. However, this does not suggest that it will not work, it just means that this deployment method has not been tested by IBM Rational.
Any problems using Altiris to deploy ClearCase (that cannot be reproduced without using Altiris) will not be investigated by IBM Rational Client Support. Only problems directly with the ClearCase installation can be addressed by our support staff. 2. Are there any known conflicts with ClearCase when Altiris Server Management Suite is installed on a ClearCase host?
Answer: As of this update, there have been no reported conflicts between ClearCase and Altiris Server Management Suite software when they are both installed on the same host.
For information on known issues resulting from application conflicts with Rational ClearCase, refer to technote1240722. Remote Install Solutions ClearCase does not support the use of technologies for performing remote silent installs that get pushed to the clients while they are not logged in, such as the above from Altiris Change request, (RFE) RATLC00720885, was opened to allow remotely distributed silent installs pushed to hosts while not logged in. The decision was made by Product Management to exclude the resolution of this feature from future upgrades and releases of the ClearCase installation due to the significant architectural changes required to implement the solution. Refer to the whitepaper titled Deploying Rational ClearCase using Microsoft SMS for details on a tested procedure that will allow you to deploy ClearCase using Microsoft® Systems Management Service (SMS) without the login requirement discussed above. 260. How do I – understand the support Policy for Microsoft Virtual PC on ClearCase and ClearQuest Microsoft Virtual PC for Windows (formerly Connectix Virtual PC) is a client based software virtualization application that allows simultaneous operating systems to run on a single PC. Each virtual machine Page 304 of 341
ClearCase Environment – How do I emulates a complete hardware system—from processor to network card—in a self-contained, isolated software environment, enabling the simultaneous operation of otherwise incompatible systems.
Frequently Asked Questions about Virtual PC and Rational ClearCase and ClearQuest: Question: Is IBM Rational ClearCase & IBM Rational ClearQuest supported on Virtual PC? Answer: Yes.
Note: So long as the version of the operating system installed on the Virtual PC application is one to which ClearCase and ClearQuest is supported, Virtual PC is supported. IBM Rational ClearCase provides support for the operating systems listed HERE. IBM Rational ClearQuest provides support for the operating systems listed HERE.
Note: IBM Rational ClearCase and IBM Rational ClearQuest do not specify support for specific Virtual PC products in these matrices because Virtual PC itself provides transparency to the operating systems, applications, and middleware that operate above it to which we do support. Question: If I encounter a problem when running ClearCase or ClearQuest in a Virtual PC environment, will IBM Rational provide defect support? Answer: It depends.
For example, any problems related to the ClearCase/ClearQuest UI (user interface) or command functionality can be treated as if it were occurring on the native operating system.
Any problem related to communication or performance or network functionality, IBM support under certain circumstances may have to rule out Virtual PC as a component of the problem since Virtual PC uses a virtual network adapter. If the problem can not be reproduced on the native file system, then IBM Rational will not fix or support those problems as it is Virtual PC specific.
Note: A case by case determination will be made in deciding which defect will be filed and fixed by IBM Rational support. Question: What Virtual PC products has IBM Rational evaluated and are there any known issues to be made aware of? Answer: Virtual PC products are currently broken into three offerings: Virtual PC 2004, 2005, 2007 IBM Rational has evaluated Virtual PC and there are no known issues associated with virtualization of ClearCase and ClearQuest on Virtual PC 2004, 2005, 2007
Virtual Server 2005, 2007 The use of Virtual Server 2005 and 2007 has not been officially evaluated by IBM Rational at this time and therefore is unaware of any issues that may arise. Due to the architecture similarities between Virtual PC, the virtualization of ClearCase and ClearQuest on the Virtual Server 2005 and 2007 should operate as expected. 261. How do I – understand the support Policy for Anti-Virus and ClearCase ClearCase is not certified to run with any specific Anti-Virus applications. Change request (RFE) RATLC00758300 has been submitted requesting a certification process be implemented. The following information is a compilation of support knowledge related to the configuration of Anti-Virus applications to successfully work along side Rational ClearCase. This is not an official recommendation, just lessons-learned to assist you in avoiding known problems when Anti-Virus applications are configured to the contrary. The general issues to consider when configuring Virus scanners on a ClearCase server are as follows:
When and How to Scan: When possible scan manually or on a scheduled basis during down time (non-work time). This limits the performance impact virus scanning can impose during normal operations especially ClearCase use as this impact could be significant depending on client speed, network bandwidth, server performance, and the number of clients accessing VOBs and views on any given host. ClearCase should be shut down on the host being scanned. This avoids any possibility of the scanner affecting or being affected by ClearCase.
When and How NOT to Scan: "Realtime" or "on-access" scans should be avoided. Depending on how aggressive the virus scanner is, "on-access" scanning can disable ClearCase cleartext and source container creation. The final step in the on-access operation is typically to rename temporary containers and ClearCase creates many of these containers as part of it process. Also, on-access scans may lock Page 305 of 341
ClearCase Environment – How do I a file to perform some operations resulting in the inability of ClearCase to rename the file. This may result in errors from vob_server regarding "operation 'rename_container' failed." Virus scanner should not be configured to attempt cleaning or deletion of infected files. These options can lead to corrupted or missing source containers and/or derived objects which in turn can lead to a dramatic increase in recovery time as the corrupted/missing containers have to be rebuilt.
What to Scan: Scan the VOB source pools. Be aware that binary files that have been added to source control may be compressed and inaccessible to the virus scanner unless the scanner can scan inside of zip files. Scan VOB cleartext pools. Be aware that the file names in this directory bear little relation to their real names, so a scan by extension (.txt, .exe etc...) will not properly scan. Scan VOB DO pools. This may protect against file infectors that may find a freshly built executable during a build and make a few minor changes. If that file is then winked in through another build, a virus-infected file would be publicly available. This would at least provide notification. Scan View storage directories. This would catch new files added to a directory by a virus and view private files modified by a virus.
What NOT to Scan: Do not scan the MVFS "view" drive ("M:" by default). Scans on this drive will scan all views started on this system and all VOBs mounted on this system. The cleartext lookup/creation phase of a file open in MVFS can lead to serious performance degradation as the scan attempts to open all files in the view. Avoid scanning mapped drives to the MVFS. Scanning drives mapped to views is generally considered redundant as long as the view storage directories are being scanned. Similar performance problems related to scanning the MVFS drive itself can manifest itself during mapped drives scans as well. 262. How do I – understand the Rational Support Policy Addendum for VMware support About VMware VMware is a third-party software product that provides a hypervisor environment. This environment enables multiple Intel operating systems (for example, Microsoft® Windows® and Linux®) to execute concurrently on the same physical (Intel®/x86 based) machine. VMware itself is transparent to the "guest" operating systems and the applications or middleware which operate above those operating systems.
Below is an addendum to the official policy that outlines the support specific questions around ClearCase, ClearQuest and RequisitePro.
Frequently Asked Questions about VMware and Rational ClearCase and ClearQuest:
Question: Is IBM Rational ClearCase, ClearQuest and RequisitePro supported on VMware?
Answer: Yes. Note: So long as the version of the operating system installed on the VMware application is one to which ClearCase and ClearQuest is supported, VMware is supported.
IBM Rational ClearCase provides support for the operating systems listed HERE.
IBM Rational ClearQuest provides support for the operating systems listed HERE.
IBM Rational RequisitePro provides support for the operating systems listed HERE.
Note: IBM Rational ClearCase, ClearQuest and RequisitePro do not specify support for specific VMware products in these matrices because VMware itself provides transparency to the operating systems, applications, and middleware that operate above it to which we do support.
Question: If I encounter a problem when running ClearCase, ClearQuest or RequisitePro in a VMware environment, will IBM Rational provide defect support?
Answer: It depends. Page 306 of 341
ClearCase Environment – How do I For example, any problems related to the UI (user interface) or command functionality can be treated as if it were occurring on the native operating system.
Any problem related to communication or performance or network functionality, IBM support under certain circumstances may have to rule out VMware as a component of the problem since VMware uses a virtual network adapter. If the problem can not be reproduced on the native file system, then IBM Rational will not fix or support those problems as it is VMware specific.
Note: A case by case determination will be made in deciding which defect will be filed and fixed by IBM Rational support.
Question: What VMware products has IBM Rational evaluated and are there any known issues to be made aware of?
Answer: VMware products are currently broken into three offerings: VMware Workstation IBM Rational has evaluated VMware Workstation and there are no known issues associated with virtualization of ClearCase and ClearQuest on VMware Workstation 5.
VMware GSX Server IBM Rational has evaluated VMware GSX Server and there are no known issues associated with virtualization of ClearCase and ClearQuest on VMware GSX Server 3.1.
VMware ESX Server IBM Rational has evaluated VMware ESX Server and there are no known issues associated with virtualization of ClearCase and ClearQuest on VMware ESX Server 2.5 or 3.x.
Question: Which version of VMware does Rational support for Enterprise environments and are there any considerations that need to be accounted for be deploying?
Answer: Rational supports VMware ESX Server for enterprise environments. A GSX configuration is not suitable for large-scale server consolidations. Deployments other than ESX would not provide an enterprise operating environment for Rational applications.
Note: VMware provides a stable virtual machine solution; however, for deployment of enterprise applications there is a cost associated with managing these configurations. Literature on VM deployments does discuss the lowering of Total Cost of Ownership (TCO) and there are benefits to the consolidation of multiple systems. For deployment of certain enterprise applications on virtual machines, there is some management overhead to consider for these environments.
1. Administrators should closely manage these deployments by monitoring the utilization of resources within these shared subsystems.
2. While there are benefits to consolidation of servers, running production databases like those used for ClearQuest and ClearCase on these shared configurations could lead to performance problems, application failures, or downtime as additional users or virtual machines are added over time.
There are a number whitepapers that should be consulted before considering virtual machine deployment for ClearCase and ClearQuest.
IBM Redbooks®: Server Consolidation with VMware ESX Server. VMware Solutions White Papers 263. How do I – understand support for IBM SWG products in a VMware® environment Software support services for IBM SWG products in a VMware® (virtualization) environment This technote outlines the IBM Remote Technical Support policy for IBM Software Group (SWG) software products running on VMware® images. Such as VMware® ESX Server or VMware® Server.
IBM's Remote Technical Support policy statement for VMware® environments: IBM Remote Technical Support will accept usage/defect-related service requests for IBM SWG IPLA products running in a VMware® ESX Server or VMware® Server environment. If it appears that the problem is unique to the VMware® environment, IBM may require the client to recreate the Page 307 of 341
ClearCase Environment – How do I problem in a non-VMware® environment. If the client has purchased an IBM ServicePac Agreement® (for VMware®), the IBM VMware® support team can assist in reproducing the problem in accordance with the terms of that agreement.
Notes: 1. The above applies to service requests within scope for Passport Advantage support as per the "Software Support Handbook" at url: http://techsupport.services.ibm.com/guides/services.html
2. The above statement is for Remote Technical Support only and does not indicate whether IBM products are "certified" to operate in a VMware® environment. "Official" environment statements are made in individual IBM product announcements.
3. VMware® is a third-party (non-IBM) software product that provides a hypervisor environment. For ad ditional VMware® vendor and product information go to url: http://www.vmware.com
Questions & Answers: 1. Does IBM provide remote technical support for IBM software products when running in a VMware® environment? Ans: Yes. If a client has a valid support contract (e.g. Passport Advantage Software Maintenance (SWMA)) and encounters a problem when running an IBM product in a VMware® environment, IBM will provide remote technical support for the IBM product.
2. Does IBM provide support for VMware® ESX & VMWare Server itself? Ans: Yes. IBM has a Business Partner relationship with VMware®. IBM support for VMware® ESX & VMware Server is available through an IBM ServicePac for Remote Technical Support from IBM Global Services (IGS) url: http://www-1.ibm.com/services/us/index.wss/offering/its/a1000229 For supported product listing and details see url: http://www-1.ibm.com/services/us/its/pdf/remotesupportxseries.pdf
3. Does IBM provide remote technical support for IBM software products that are not "certified" or state that they support the VMware® environment? Ans: Yes. Regardless of the individual IBM product "official" environment statement, clients who have a valid License Agreement and an IBM Support Contract (e.g. Passport Advantage Software Maintenance (SWMA)) will receive remote technical support for the IBM software running in a virtual machine environment (such as the VMware® ESX Server environment).
4. Will IBM correct all defects for IBM products that are running in a VMware® environment? Ans: Not necessarily. As under other operating environments, IBM does not warrant that all code defects will be corrected. IBM will issue defect correction information, a restriction, or a bypass to IBM products if the defect is also applicable in a native physical machine environment (i.e. without the virtualization software). That determination may require that the problem be recreated in a native environment by the client. If the problem does not occur or cannot be recreated in a native environment, it will not be considered an IBM product defect. 264. How do I – understand the support Policy for ClearCase with FLEXlm on HP-UX IA64 What is the support policy for using IBM® Rational® ClearCase® with FLEXlm on HP-UX® IA64?
When installing Rational ClearCase on HP-UX IA64, the second license model option for Rational Common Licensing cannot be selected, though it appears as an available ClearCase license model: bash-2.03# ./site_prep Updating release area '/clearcase/ccase_rls/7.0.0/hp11_pa' For any of the queries that follow, help is available by entering 'help', 'h' or '?' at the prompt. Page 308 of 341
ClearCase Environment – How do I Please specify the ClearCase license model type (1=ClearCase (Atria) Licensing; 2=IBM Rational Common Licensing (powered by FLEXlm software)) : 1
Selecting option #2 does nothing and prevents FLEXlm from being installed. This is due to the fact that there is currently no support for FLEXlm on the HP-UX IA64 (Itanium) platform. Note: See technote 1148578 for directions on How to determine if HP-UX uses a 32-bit kernel or 64-bit kernel. Change request (RFE) RATLC01013977, is open to provide support for FLEXlm on HP-UX IA64 when using Rational ClearCase. 265. How do I – understand the support policy for ClearCase on Macintosh OS X ClearCase (native client) is not supported on Macintosh OS X operating system.
Review the following technotes for a list of the current supported platforms and operating systems for ClearCase: System Requirements for ClearCase 2003.06.00 System Requirements for ClearCase 7.0.x System Requirements for ClearCase 7.1
At this time there is no plan to support the ClearCase native client on Macintosh OS X, and it has not been tested for use on X11.
Change request (RFE) RATLC00984512 has been submitted to add this functionality to allow the ClearCase Remote Client (CCRC) to install on Mac OS. RFE RATLC00984512 has been resolved. ClearCase 7.1 introduced support limited to CCRC only, as plug-in to Eclipse IDE. Refer to the ClearCase 7.1 system requirements document listed above for further information. Caching 266. How do I – understand about the ClearCase cache directory What are the files in the IBM® Rational® ClearCase® cache directory ClearCase_check and is it safe to remove them.
The cache directories are located as follows:
UNIX® and Linux®: /var/adm/rational/clearcase/cache/
Microsoft® Windows® C:\Program Files\Rational\ClearCase\var\cache ClearCase_check cache Location on Windows: C:\Program Files\Rational\ClearCase\var\cache\ClearCase_check Location on UNIX/Linux: /var/adm/rational/clearcase/cache/ClearCase_check/ /var/adm/rational/clearcase/cache/MultiSite_check/ Note: The MultiSite_check directory will not appear on systems that do not have or use MultiSite.
These directories contain several zero-length files:
Example: UNIX/Linux:
[ClearCase_check]$ ls -al total 8 drwxrwxrwx 2 vobadm vobadm 4096 Oct 20 2005 . drwxrwxrwx 4 root root 4096 Mar 9 17:07 .. -rwx------1 cmoir cmoir 0 Feb 9 22:02 cmoir -rwx------1 testuser testuser 0 May 11 2006 testuser -rwx------1 1000 502 0 Sep 9 2005 testuser2 -rwx------1 vobadm vobadm 0 Dec 19 15:55 vobadm
Windows: Page 309 of 341
ClearCase Environment – How do I C:\Program Files\Rational\ClearCase\var\cache\ClearCase_check>dir /d Volume in drive C has no label. Volume Serial Number is 8017-F8A8
Directory of C:\Program Files\Rational\ClearCase\var\cache\ClearCase_check
[.] [..] clearcase_albd 1 File(s) 0 bytes 2 Dir(s) 36,241,784,832 bytes free These files are created by user access to a ClearCase server.
Note: On UNIX/Linux, the user creates ClearCase processes, where on Windows, the clearcase_albd is the only account managing processes. This is why there are user accounts on UNIX/Linux and only the clearcase_albd account on Windows. The cached information relates to the UID/SID of the user and GID/SID of the group accessing ClearCase on the host so that credential look-up is improved.
UNIX/LINUX ONLY: Entries without a name associated to UID or GID, such as testuser2 above, may be a source of security concern in some companies. Can these files be removed?
Older or incorrect entries can be safely removed, especially the ones with bad UID/GIDs, as they likely do not represent current users of the system. Once removed, ClearCase will recreate the entry if necessary. Note: It is recommended not to remove any files that have a recent timestamp.
CCshmemV3 cache files (Windows only)
Another file stored in the cache directory is the CCshmemV3 cache files. These files are cached credentials data from users that have logged into the system.
The files with the appended Windows SID can be safely removed as well as these will add up to be a significant amount of space if many different users are logging into a system.
Example: (CCshmemV3.S-1-5-21-141845252-1443263951-584457872-1365)
Note: If deleting one of these files results in an "Access is denied" error message, the message indicates ClearCase is still using the file you are trying to delete. ClearCase environment 267. How do I – deploy the ClearCase and ClearQuest Help systems on an intranet server Learn how to modify the Help systems for the native (non-Eclipse) ClearCase and ClearQuest products to run on a single intranet server, allowing access to the documentation from remote clients
Content Understanding the IBM Eclipse Help System (IEHS) startup modes
The Help system that is installed with ClearCase and ClearQuest 7.1 can run in two modes: standalone mode and information center mode. By default, the Help system is configured to run in standalone mode, which means that when you start the Help system directly from ClearCase and ClearQuest (by clicking the Help button in a dialog, or by selecting the Help option in a menu) it runs on your local client machine, and other machines/clients cannot access it. You have the option to reconfigure the Help system to run in information center mode on a server, which will provide you with a Web-based information center that all of your client machines can access (a Page 310 of 341
ClearCase Environment – How do I central Help system for all users of the product).
Understanding the structure of the Help system
The ClearCase and ClearQuest Help systems include: Version 3.1.1 of IEHS (An IBM-branded version of the Eclipse Help System) Startup and shutdown scripts ClearCase documentation plug-ins and features ClearQuest documentation plug-ins and features
The startup and shutdown scripts installed with ClearCase and ClearQuest are configured to start the Help system in standalone mode. You can add new startup scripts that use information center mode instead, and have users point to this new instance of the Help system on the server for their documentation. Users will access the server-based Help system with a browser, not from their ClearCase and ClearQuest clients (Help calls from the clients will continue to open up the local instance of IEHS).
Overview of the setup/customization process
To customize the Help system, you will follow these basic steps:
1. Create the new IC_start and IC_end scripts. 2. Move the startup.jar and config.ini files. 3. Run the IC_start script to start the server. 4. Access the IC from a browser on a remote machine. 5. Run the IC_end script to shut down the server.
If you have both ClearCase and ClearQuest installed, you can choose to create a single Help system for both products, or separate the documentation into two Help systems. For more information, see the Using the customized IEHS with multiple Rational products section of this document.
The following sections explain the customization process in more detail.
1. Creating the new startup and shutdown scripts
To configure IEHS to start in information center mode, you need to create a new set of startup (IC_start) and shutdown (IC_end) scripts. You will store your new scripts in the same location as the original scripts. The scripts are located in the following locations (using default installation paths): ClearQuest Windows: C:\Program Files\IBM\RationalSDLC\ClearQuest\doc ClearCase Windows: C:\Program Files\IBM\RationalSDLC\ClearCase\doc ClearCase UNIX and Linux: /opt/rational/clearcase/doc 1a. Creating IC_start.bat and IC_end.bat [Windows]
On a Windows system, create two new files, IC_start.bat and IC_end.bat with the following contents: IC_start.bat
"C:\Program Files\IBM\RationalSDLC\common\JAVA5.0\jre\bin\java" -classpath "C:\ProgramFiles\IBM\IMShared\plugins\org.eclipse.help.base_3.1.0\helpbase.jar" org.eclipse.help.standalone.Infocenter -eclipsehome "C:\Program Files\IBM\IMShared" -port 8889 -command start -clean -noexec
IC_end.bat
"C:\Program Files\IBM\RationalSDLC\common\JAVA5.0\jre\bin\java" -classpath "C:\ProgramFiles\IBM\IMShared\plugins\org.eclipse.help.base_3.1.0\helpbase.jar" org.eclipse.help.standalone.Infocenter -eclipsehome "C:\Program Files\IBM\IMShared" -port 8889 -command shutdown -noexec 1b. Creating IC_start.sh and IC_end.sh [UNIX and Linux]
On a UNIX or Linux system, create two new files, IC_start.sh and IC_end.sh with the following contents:
IC_start.sh #!/bin/sh /opt/IBM/RationalSDLC/common/java/jre/bin/java –classpath /opt/IBM/IMShared/plugins/org.eclipse.help.base_3.1.0/helpbase.jar org.eclipse.help.standalone.Infocenter -eclipsehome /opt/IBM/IMShared -command start -port
ClearCase Environment – How do I IC_end.sh #!/bin/sh /opt/IBM/RationalSDLC/common/java/jre/bin/java –classpath /opt/IBM/IMShared/plugins/org.eclipse.help.base_3.1.0/helpbase.jar org.eclipse.help.standalone.Infocenter -eclipsehome /opt/IBM/IMShared -command shutdown -port
Several files need to be moved to the “-eclipsehome” location that we use in the new scripts. You should make copies of the files and paste them in their new locations, rather than actually moving them.
2a. Moving the startup.jar and config.ini files [Windows]
Copy startup.jar from C:\Program Files\IBM\RationalSDLC\ClearQuest\doc\eclipse\ and paste it in C:\Program Files\IBM\IMShared\.
Copy config.ini from C:\Program Files\IBM\RationalSDLC\ClearQuest\doc\eclipse\configuration and paste it in C:\Program Files\IBM\IMShared\configuration\. 2b. Moving the startup.jar and config.ini files [UNIX or Linux]
Copy startup.jar from /opt/rational/clearcase/doc/eclipse/ and paste it in /opt/IBM/IMShared/. Copy config.ini from /opt/rational/clearcase/doc/eclipse/configuration/ and paste it in /opt/IBM/IMShared/configuration/. 3. Starting up the Help system
Run the new IC_start script. The Help system starts up and runs in the background. On Windows, a command window opens and remains open as long as the Help system is running. You should now be able to access the InfoCenter from a remote machine
4. Opening the Help system from a remote machine
To view the information center from a remote machine, open a browser and type the URL http://
5. Shutting down the Help system
When you are done using the InfoCenter, shut it down by running the IC_end script
Using the customized IEHS with multiple Rational products
If you have both ClearCase and ClearQuest installed, you can choose to create a single Help system for both products, or separate the documentation into two Help systems. The following sections explain the different options. Running a single Help system for ClearCase and ClearQuest
If you have both ClearCase and ClearQuest installed, and you want to combine the Help systems into one information center, you only need to create the IC_start and IC_end scripts in one of the product directories. For example, create and run the scripts in C:\Program Files\IBM\RationalSDLC\ClearQuest\doc\, C:\Program Files\IBM\RationalSDLC\ClearCase\doc\, or /opt/rational/clearcase/doc/. Documentation plug-ins for both products are stored in the same location: C:\Program Files\IBM\IMShared\plugins\ or /opt/IBM/IMShared/plugins/.
When you run the startup script and open the IC in a browser, you will see both the ClearCase and ClearQuest plug-ins in the table of contents.
Separate Help systems for ClearCase and ClearQuest
If you want to keep the documentation for ClearCase and ClearQuest separate, and run two different information centers, there are a few additional steps that you need to follow:
1. Create two sets of the IC_start and IC_end scripts, one set in each of the product directories C:\Program Files\IBM\RationalSDLC\ClearQuest\doc\ C:\Program Files\IBM\RationalSDLC\ClearCase\doc\ or /opt/rational/ClearCase/doc/ Page 312 of 341
ClearCase Environment – How do I 2. Copy the ClearQuest-specific documentation plug-ins and features to the ClearQuest directory in the installation location.
3. Copy the ClearCase-specific documentation plug-ins and features to the ClearCase directory in the installation location.
4. Copy the Eclipse-specific Help plug-ins and features to the eclipse folder in the installation location.
5. Modify the IC_start and IC_end scripts to point to the new plug-in locations. In all of the IC_start and IC_end scripts, change the “-eclipsehome” option to “-eclipsehome eclipse” Also, make sure that you specify different port numbers for each IC. See the following sections for lists of the Eclipse, ClearCase, and ClearQuest Help plug-ins and features that you need to copy. Eclipse-specific Help plug-ins
Copy the following folders and jar files from C:\Program Files\IBM\IMShared\plugins\ (Windows) /opt/IBM/IMShared/plugins/ (UNIX and Linux) to C:\Program Files\IBM\RationalSDLC\ClearCase\doc\eclipse\plugins\ (Windows) /opt/rational/clearcase/doc/eclipse/plugins/ (UNIX and Linux) and C:\Program Files\IBM\RationalSDLC\ClearQuest\doc\eclipse\plugins\ (Windows)
Folders: com.ibm.help.hs.doc_3.1.1 com.ibm.help.ic.doc_3.1.1 org.apache.lucene_1.4.3 org.eclipse.help.base_3.1.0 org.eclipse.help.debug_1.0.0 org.eclipse.help.webapp_3.1.0 org.eclipse.help_3.1.0 org.eclipse.tomcat_4.1.30.1
Jar files: com.ibm.watson_0.1.2.jar org.eclipse.core.commands_3.1.0.jar org.eclipse.core.expressions_3.1.0.jar org.eclipse.core.runtime.compatibility_3.1.0.jar org.eclipse.core.runtime_3.1.1.jar org.eclipse.core.variables_3.1.0.jar org.eclipse.help.appserver_3.1.0.jar org.eclipse.help.ui_3.1.1.jar org.eclipse.jface_3.1.1.jar org.eclipse.osgi_3.1.1.jar org.eclipse.swt.win32.win32.x86_3.1.1.jar org.eclipse.swt_3.1.0.jar org.eclipse.ui.forms_3.1.0.jar org.eclipse.ui.win32_3.1.0.jar org.eclipse.ui.workbench_3.1.1.jar org.eclipse.ui_3.1.1.jar org.eclipse.update.configurator_3.1.0.jar org.eclipse.update.core_3.1.1.jar Eclipse-specific Help features
Copy the following folders from C:\Program Files\IBM\IMShared\features\ (Windows) /opt/IBM/IMShared/features/ (UNIX or Linux) to C:\Program Files\IBM\RationalSDLC\ClearCase\doc\eclipse\features\ (Windows) /opt/rational/clearcase/doc/eclipse/features/ (UNIX or Linux) and C:\Program Files\IBM\RationalSDLC\ClearQuest\doc\eclipse\features\ (Windows) /opt/rational/clearquest/doc/eclipse/features/ (UNIX or Linux) Page 313 of 341
ClearCase Environment – How do I
Folders: com.ibm.help.hs.doc.feature_3.1.1 com.ibm.help.ic.doc.feature_3.1.1 ClearCase Help plug-ins
Copy the following Help plug-ins from C:\Program Files\IBM\IMShared\plugins\ (Windows) /opt/IBM/IMShared/plugins/ (UNIX or Linux) to C:\Program Files\IBM\RationalSDLC\ClearCase\doc\eclipse\plugins\ (Windows) /opt/rational/clearcase/doc/eclipse/plugins/ (UNIX or Linux)
Jar files: All jar files named com.ibm.rational.clearcase.*.doc.*.jar com.ibm.ccl.feedreader_1.0.0.v20070912.jar com.ibm.ccl.welcome.bits_7.0.3.v20071001.jar com.ibm.help.common.accessibility.doc_7.5.0.jar com.ibm.help.common.doc_7.5.0.v20080701.jar com.ibm.help.common.nav.doc_7.5.1.v20080722.jar com.ibm.help.common.rational.doc_7.5.0.v20080701.jar com.ibm.help.common.resources.doc_7.5.0.jar com.ibm.help.gallery.cat_7.5.2.v20080701.jar com.ibm.welcome.common.rational.doc_7.5.0.jar com.ibm.rational.team_api.doc_7.1.0.v200810131214.jar com.ibm.rational.team_api_cc_tut.doc_7.1.0.jar com.ibm.rational.crm_migration.doc_7.1.0.jar com.ibm.rational.licensing.doc_7.1.0.v200810131214.jar Note: The date-time stamps on the files in your installation directory may be different than the ones listed here. ClearCase Help features
Copy the following Help features from C:\Program Files\IBM\IMShared\features\ (Windows) /opt/IBM/IMShared/features/ (UNIX or Linux) to C:\Program Files\IBM\RationalSDLC\ClearCase\doc\eclipse\features\ (Windows) /opt/rational/clearcase/doc/eclipse/features/ (UNIX or Linux)
All folders named com.ibm.rational.clearcase.*.doc.* com.ibm.rational.crm.doc.feature_7.1.0.v200810131214 com.ibm.rational.crm.tours.doc.feature_7.1.0.v200810131214 com.ibm.rational.crm.tuts.doc.feature_7.1.0.v200810131214 com.ibm.ccl.welcome.bits.feature com.ibm.help.common.feature com.ibm.help.common.rational.feature Note: The date-time stamps on the files in your installation directory may be different than the ones listed here.
ClearQuest Help plugins
Copy the following Help plug-ins from C:\Program Files\IBM\IMShared\plugins\ (Windows) to C:\Program Files\IBM\RationalSDLC\ClearQuest\doc\eclipse\plugins\ (Windows)
Jar files: All jar files named com.ibm.rational.clearquest.*.doc.*.jar com.ibm.ccl.feedreader_1.0.0.v20070912.jar com.ibm.ccl.welcome.bits_7.0.3.v20071001.jar com.ibm.help.common.accessibility.doc_7.5.0.jar com.ibm.help.common.doc_7.5.0.v20080701.jar com.ibm.help.common.nav.doc_7.5.1.v20080722.jar com.ibm.help.common.rational.doc_7.5.0.v20080701.jar com.ibm.help.common.resources.doc_7.5.0.jar Page 314 of 341
ClearCase Environment – How do I com.ibm.help.gallery.cat_7.5.2.v20080701.jar com.ibm.welcome.common.rational.doc_7.5.0.jar com.ibm.rational.team_api.doc_7.1.0.v200810131214.jar com.ibm.rational.team_api_cq_tut.doc_7.1.0..jar com.ibm.rational.crm_migration.doc_7.1.0.jar com.ibm.rational.licensing.doc_7.1.0.v200810131214.jar Note: The date-time stamps on the files in your installation directory may be different than the ones listed here.
ClearQuest Help features
Copy the following Help features from C:\Program Files\IBM\IMShared\features\ (Windows) to C:\Program Files\IBM\RationalSDLC\ClearQuest\doc\eclipse\features\ (Windows)
All folders named com.ibm.rational.clearquest.*.doc.* com.ibm.rational.crm.doc.feature_7.1.0.v200810131214 com.ibm.rational.crm.tours.doc.feature_7.1.0.v200810131214 com.ibm.rational.crm.tuts.doc.feature_7.1.0.v200810131214 com.ibm.ccl.welcome.bits.feature com.ibm.help.common.feature com.ibm.help.common.rational.feature Note: The date-time stamps on the files in your installation directory may be different than the ones listed here.
Troubleshooting
If the information center does not start up, you can try the following things: Run the IC_end script and then restart the IC. Delete the folders, but not the config.ini file, from the configuration directory and restart the IC. 268. How do I – understand platform specific IPv6 restrictions for ClearCase Linux Dynamic view clients (MVFS) cannot use IPv6. Snapshot view clients, web view clients, and all servers are supported with IPv6.
Solaris All supported Solaris releases fully support IPv6 for all parts of Rational ClearCase.
Windows Rational ClearCase does not support IPv6 on Windows 2000 Server. Windows XP SP2 and later workstation and server releases fully support IPv6 for all parts of Rational ClearCase.
AIX AIX 5.3: Dynamic view clients (MVFS) cannot use IPv6. Snapshot view clients, web view clients, and all servers are supported with IPv6. AIX 6.1: fully supports IPv6 for all parts of Rational ClearCase. Note: this support requires AIX 6.1 SP2 or later (oslevel -s shows 6100-00-02-0750 or later). HP-UX HP-UX 11.23: o Dynamic view clients (MVFS) cannot use IPv6. o Snapshot view clients, web view clients, and all servers are supported with IPv6. HP-UX 11.31: fully supports IPv6 for all parts of Rational ClearCase 269. How do I – understand about the limits for simultaneously mounting VOBs on a single host VOB mount limit on HP-UX®
You can have 8191 simultaneous mounted VOBs, and there can be 1024 simultaneous view-extended paths for each VOB.
Page 315 of 341
ClearCase Environment – How do I VOB mount limit for IBM AIX®
You can have 511 simultaneous mounted VOBs.
There is an open change request (RFE) RATLC00697946 to raise the limit of mounted VOBs on AIX. This RFE has been resolved and the feature has been delivered in ClearCase 7.1.
VOB mount limit for Solaris®
The limit can extend up to 5119 if the mount points are not exported for non-ClearCase usage and 2560 if they are exported for non-ClearCase usage.
There is a limit of 511 VOB mount points per major device and 256 distinct view-extended paths per VOB. However, ClearCase can detect when the number of VOBs (or views) is running up against the limit, and then move to a new major device number.
VOB mount limit for Linux® This applies to 2.4.2 kernels and above.
The number of VOBs that can be mounted simultaneously under Linux is 1024, but this can be increased by editing the value mvfs_majdynmax in the file /var/adm/clearcase/mvfs/vnode_src/mvfs_param.c.
2.6 kernels The default value is 2. This is the maximum number of major device codes that MVFS will allocate for VOB mount points. Each major device number will yield 512 additional VOB mounts. So for 2.6 kernels, the maximum number of VOBs that can be mounted is mvfs_majdynmax * 512
2.4 kernels The default value is 8. This is the maximum number of major device codes that MVFS will allocate for VOB mount points. Each major device number will yield 128 additional VOB mounts.
So for 2.4 kernels, the maximum number of VOBs that can be mounted is mvfs_majdynmax * 128 ADVISORY There are only 256 major device codes so discretion is advised in increasing this number. Once the value has been changed, rebuild and reinstall the vnode module following the instructions in README.txt in that directory. Note: There is a condition that can cause a directory to not mount because it cannot find the VOB storage path name. When this happens, you will see the following error: mntrpc_server: Error: mount.mvfs: Invalid argument Error: The VOB storage directory '/net/
If you wait a little while and try the mount again, the mount should succeed because the automounter will have flushed some of the entries.
VOB mount limit for Microsoft® Windows®
There is a limit of 4095 VOBs that can be mounted on a Windows server. To take advantage of this limit which was increased from 511 to 4095 VOBs you need to be at or above the updates listed below for APAR PK42124.
There are also factors to be considered when the system resources cannot handle the number of processes required; refer to technote 1142584 for more details. However, the limit on the number of processes on a single host can be circumvented by having multiple hosts act as your VOB server.
Defect, APAR PK42124, was opened to address the error below, which is reported when mounting >511 VOBs. cleartool: Error: Unable to mount: error detected by ClearCase subsystem
Defect, APAR PK42124 has been resolved in the following update(s): 7.0.1 Page 316 of 341
ClearCase Environment – How do I
ClearCase Version 7.0.1.1
7.0
ClearCase Version 7.0.0.2
2003.06.16
ClearCase clearcase_p2003.06.16.NT-2007D
270. How do I – Understand about Feature Levels and ClearCase All features in a given Feature Level can be obtained by reading the Release Notes for the version of ClearCase or ClearCase LT® in use. Information on how to raise the feature level of a VOB is available in IBM Rational ClearCase Command Reference, or run cleartool man chflevel from command line. Feature levels can only be raised to a higher feature level and cannot be lowered. For specific directions about raising the feature level of replicated VOBs, see the IBM Rational ClearCase MultiSite Administrator’s Guide. Below is a consolidation of the high level features from each release. Review the Release Notes for that version to obtain more details, as needed.
ClearCase Feature Levels The Feature Level of a VOB dictates what features and or enhancements are available when working in that database. A feature level is an integer that is incremented at each ClearCase family release and introduces features that affect VOBs created in an earlier release. The purpose of raising feature levels is to make all features in a release available to users of the VOB that was created in the earlier release. Feature Level Introduced in version 1 3.2.1 2 4.0 3 2002.05.00
4 2003.06.00
5 7.0 Note: The above table lists the ClearCase versions where a new feature level was first introduced. ClearCase versions not listed are assumed to have the same feature level as it's predecessor version unless explicitly listed above (for example, versions 7.0.1 and 7.1 are feature level 5 which is the same as the predecessor version 7.0). A VOB's feature level is initially set at the time of it's creation and defaults to the feature level of the ClearCase version installed on the server. For instance a new VOB created on a ClearCase 7.0 server will be created as a feature level 5 VOB as you can see from the above chart. Note: New features and/or functionality may not work with clients that support lower feature levels. Refer to the IBM Rational Administrator's Guide under the topic of "Feature Levels" in the ClearCase 7.x Information Centers for further information.
Overview of current features: Feature Level 4: Raising the feature level to 4 (or in the case of a replicated VOB, raising the replicated VOB family to feature level 4), results in the following changes in the VOB: Feature level 3 placed constraints on client/server compatibility in UCM environments. Feature level 4 introduces no additional constraint; it is equivalent to feature level 3 in terms of PVOB client/server compatibility. Also note that read-only streams and single-stream projects are restricted to PVOBs at feature levels 3 and higher (see the reference page for mkstream). The predefined element types xml, html, and rose (if they exist) are renamed to xml_v5.0, html_v5.0, and rose_v5.0, respectively. Similarly, element type names that you have changed are renamed to name_v5.0. The v5.0 types lose their status as well-known element types. Accordingly, when you create new elements, the file-to-type mapping mechanism no longer treats these types as the defaults (see the cc.magic reference page). The type of an existing element does not change; however, you can use chtype to change it. The new predefined element types xml, html, and rose are created. The purpose of replacing these types is to base the type managers on the binary_delta type manager instead of the text_file_delta manager. The cc.magic file maps new elements to these types by default. The element type, xde, is created.
Page 317 of 341
ClearCase Environment – How do I As of Rational ClearCase 2003.06.00, Rational ClearCase Attache is no longer supported. Feature Level 5: Raising the feature level to 5 (or in the case of a replicated VOB, raising the replicated VOB family to feature level 5), results in the following changes in the VOB: A VOB at feature level 5 is able to contain elements that are larger than 2 GB. A UCM project in which the PVOB and all component VOBs are at feature level 5 can take advantage of improvements in several UCM operations.
For more information, review the ClearCase 7.0 release notes on the topic of Improvements in Unified Change Management (UCM) When a replica family is at feature level 5, replication becomes more efficient in cases where the -maxsize option is used with syncreplica. Rational ClearCase 7.0 is the last major release to support VOB feature levels 0, 1, and 2. Rational ClearCase 7.0 does not support VOB database schema 53. Review the ClearCase 7.0 Release Notes and technote 1201579 for more information. Review the IBM Rational ClearCase MultiSite Administrators Guide on the topic of mkreplica (cleartool man mkreplica) for information about feature level restrictions related to creating new MultiSite replicas. 271. How do I – modify the Vtree Browser font appearance in ClearCase 7.0.x This technote provides you with information about a change in IBM Rational ClearCase (CC) 7.0.x which introduced a slider in the version tree browser that allows for zooming and which resulted in the inability to change fonts and graphical elements in the version tree browser.
Cause ClearCase version 7.0.x introduced a change to the vtree browser (a slider) that allows for zooming, resulting in the inability to change fonts and graphical elements in the version tree browser
Answer Note: The following implementation requires ClearCase version 7.0.1.3 or later which provides a resolution for APAR PK64263. Values can be defined in $HOME/.xclearcase such that reasonable defaults are provided for the ClearCase version tree browser.
Example: File.width: 800 File.height: 600 File.x: 0 File.y: 0 Vtree.width: 800 Vtree.height: 600 Vtree.x: 0 Vtree.y: 0
272. How do I – understand the Network Environments for ClearCase What is the expected or known behavior of IBM® Rational® ClearCase® over networks that are non-LAN (Local Area Network) based, such as Wide Area networks (WAN), Metropolitan Area Network (MAN), Remote Access Service (RAS), Virtual Private Network (VPN) or others?
Answer Components within the ClearCase product (thick client) were originally architected to operate within a Local Area Network (typically a network with low latency, or small packet Round Trip Times (RTTs).
Users of the full (non-web) version of ClearCase over connections such as Microsoft® Remote Access Server (RAS), Virtual Private Network (VPN), Wide Area Network (WAN) or Metropolitan Area Network (MAN) will experience performance degradation in the responses of some commands.
ABOUT CLEARCASE PROCESSES Processes running on ClearCase client machines send many Remote Procedure Calls to processes on ClearCase server machines. These RPCs (and their responses) are small, typically 60 to 100 bytes. A ClearCase command, such as a simple checkout operation, will typically generate one to three hundred RPCs.
Reasonable ClearCase performance is attained on networks where the RTT between ClearCase clients and ClearCase server machines is small - of the order of 1 or 2 milliseconds. While the product continues Page 318 of 341
ClearCase Environment – How do I to function as RTTs increase towards 10 ms and 20 ms, performance increasingly degrades in these environments. In networks with RTTs of 100 ms or above, access to the ClearCase databases can be significantly impacted by VOB locks, whose duration increases as the work that is accomplished while holding the lock is delayed by the longer RTTs.
The use of full (non-web) ClearCase over a Wide Area Network, one with RTTs of 100ms or more is not supported. Severe performance degradations, and frequent long VOB locks will be experienced.
The use of ClearCase on networks (such as MANs) with RTTs of 10ms or less is supported and provides degraded but acceptable performance. For example a checkout command, that takes 400ms in a LAN environment will take 1400-2000ms on a network with a 5-10 ms round trip times.
As round trip times approach 20 milliseconds, responses to common ClearCase commands tend to take more than 2 seconds, and this is generally considered unacceptable from a human factors perspective.
Note: The same performance issues also apply when using the integration between ClearCase and ClearQuest where a ClearCase server is accessing a ClearQuest server over a WAN.
WORKAROUNDS: ClearCase MultiSite® IBM Rational ClearCase MultiSite® is an option to ClearCase that extends life cycle management and control of software development assets across geographically distributed environments. Geographically distributed in this context relates to any configuration that is not LAN based. Discuss the MultiSite option with your sales representative to obtain an overview of the solution and its requirements. ClearCase Web (CCWeb) For versions 4.x up to 2003.06.13, the only supported method to use ClearCase over a connection other than a LAN is the ClearCase Web Interface (CCWeb). Review the ClearCase Administrator's Guide for more details on the requirements and configuration instructions for CCWeb setup. ClearCase Remote Client (CCRC)
As of 2003.06.14 (Service Release 4), using ClearCase over RAS, VPN, WAN or MAN is now supported through the use of the ClearCase Remote Client (CCRC).
Note: On UNIX® or Linux®, the following patches need to be applied to a host for an equivalent to Service Release 4: clearcase_p2003.06.00-14 - User Space clearcase_p2003.06.00-15 - RWP (Rational Web Platform) clearcase_p2003.06.00-16 - MVFS
Additional information, including installation instructions, for the ClearCase Remote Client can be found in the 2003.06.14 ClearCase Product Family Release Notes. Visit the IBM Publications Center and search on publication number GI11-4668-04 to download and review these notes on how to install ClearCase Remote Client after the ClearCase Web Server is established.
Note: Instructions on how to setup the stand-alone client as well as the Eclipse plug-in are in this document. 273. How do I – understand the issue that the use of Google Desktop with ClearCase causes conflicts Using ClearCase and Google Desktop on the same machine can lead to some installations and performances problems. Several issues were identified when using Google Desktop which include the following: Major performance issue when updating a snapshot view, comparing files or running a query inside dynamics views. Installation failure of ClearCase (missing MVFS drivers, credential manager service, ALBD configuration...). Even if the installation is reported successful, after rebooting some component might not be installed correctly. Very slow installation process due to the indexing service trying to uncompress and index all the installation packages of ClearCase Cause Google Desktop puts a very heavy load on the host as well as it locks the files during its indexing. Resolving the problem
Page 319 of 341
ClearCase Environment – How do I Google Desktop indexing service should be stopped before any ClearCase installation on the machine. It is best to exclude from indexing all the view drives (network and snapshot), storage locations, release area or installation folder. Avoid using both ClearCase and Google Desktop on the same host if you are experiencing the symptoms listed above. 274. How do I – understand why MVFS crashes if encryption software is installed on the system When a user checks out or checks in elements a ClearCase dynamic view on a Windows host with encryption software installed, the machine restarts or blue screens.
Cause This problem is caused when encryption software is installed and in use on the ClearCase host that is configured to use the MVFS (dynamic views). Examples of encryption software are: CREDANT® Mobile Guardian Reflex Magnetics Disknet Pro SafeBoot®
Note: Change request (RFE) RATLC00769287 was submitted to add support for SafeBoot. The decision was made by Product Management to exclude the resolution of this feature from future upgrades and releases due to the significant architectural changes required to implement the solution.
Defect APAR IC48833 has been submitted to address the MVFS crash issue.
Resolving the problem This defect has been resolved in the following updates:
ClearCase 7.0 7.0.0.0-RATL-RCC-IFIX02
ClearCase 2003.06.16 Service Release 6
Note: The above ClearCase patches will resolve the MVFS crash issues, however, they are not intended to provide support for Encryption Software. WORKAROUNDS: Uninstall the encryption software
or Reinstall ClearCase without the MVFS and use snapshot views only
or Store the view on a system that does not have disk encryption software 275. How do I – understand about the noatime filesystem mount option and ClearCase Why can't an IBM® Rational® ClearCase® VOB or a view storage be mounted on a UNIX® or Linux® filesystem mounted with the noatime option?
Answer Mounting a VOB By default, the file system is mounted with normal access time (atime) recording. The noatime option turns off access time recording regardless of dfratime or nodfratime. If noatime is specified, the file system will ignore access time (atime) updates on files, except when they coincide with updates to the ctime or mtime. VOBs cannot be mounted on a filesystem that uses the noatime mount option because the cleartext scrubber depends on atime information. Without atime, cleartext will get scrubbed more frequently (possibly while an application is using it). The filesystem where the VOB is mounted must use atime.
Mounting the view storage on Linux with -noatime option You should not mount the view storage with -noatime option because the view storage has a view cache that registers inodes. Option -noatime prevents the updating of the inodes list during mounting of the view storage. It is very risky and one can end up in a situation of not finding objects.
Page 320 of 341
ClearCase Environment – How do I 276. How do I – understand why you cannot access files or directories in ncaexported VOB/view from RHEL4 which is fixed in v7.0.1.1 Create and nca export VOB/view combination on a Red Hat Enterprise 4 machine, then mount it on a non-ClearCase machine. The mount occurs without problem, but attempting to access a file or subdirectory in the mount, the following error is seen: unknown error 521
Diagnosing the problem Run ls -la in the mount, that shows question marks, ?, in place of the expected information: drwxrwxr-x 6 cc1 clearusers 261 Oct 16 13:37 . drwxr-xr-x 6 cc1 clearusers 4096 Jan 31 07:44 .. ?------? ? ? ? ? foo ?------? ? ? ? ? foo2 ?------? ? ? ? ? lost+found Also, a network trace shows the GETATTR calls return EBADHANDLE: in the output.
Resolving the problem This defect has been resolved in the following update(s):
7.0.1
ClearCase Version 7.0.1.1
7.0
ClearCase Version 7.0.0.2
WORKAROUND: Mount the VOB/view export on the client machine with NFS 2 (vers=2). 277. How do I – set up the CCASE_NMASTER_TRIG environmental variable The IBM® Rational® ClearCase® environment variable, CCASE_NMASTER_TRIG, impacts a triggers execution and can prevent it from firing.
Cause A pre-op trigger that is expected to fire on mkbranch fails to execute during a checkout operation. The trigger does not fire for the following reasons: The check for mastership on the branch happens first, and The branch is mastered at a different replica, and CCASE_NMASTER_TRIG is not set or its set to 0 or a non-digit value
Solution The environment variable (EV), CCASE_NMASTER_TRIG, can be implemented to bypass the mastership check, which will allow the pre-op trigger on mkbranch to succeed. You must create this EV, and set it accordingly as detailed below: If the EV is set to a non-zero digit, pre-op triggers on mkbranch are allowed to fire before the mastership check is done during a checkout (in a view having relevant auto-mkbranch rules). If the EV is not set, or is set to 0 or a non-digit value, the default behavior is followed, such as mastership is checked first. Note: CCASE_NMASTER_TRIG is an undocumented EV, and it was released in Rational ClearCase 2003.06.14. 278. How do I – resolve non-ClearCase client hangs when attempting to mount an NCA exported view/VOB Omitting the fsid=xyz flag in the IBM® Rational® ClearCase® /etc/exports.mvfs file on Linux® can cause non-ClearCase clients to hang while attempting to mount an Non-ClearCase Access (NCA) exported file system. This is because on startup ClearCase attempts to assign a unique device id to each exported view/VOB combination. On Linux platforms, there can be certain OS limitations with large numbers of exported filesystems in the ClearCase registry, thus omitting the fsid=xyz flag in the /etc/exports.mvfs file can cause a client to hang while attempting to access large number of exported view/VOB combinations.
Page 321 of 341
ClearCase Environment – How do I Therefore, on Linux platforms, the fsid option must be set for all NCA exports. This setting helps avoids certain OS limitations assigning major and minor devices to each export. Note: On UNIX® platforms, this is not necessary since UNIX operating systems are typically able to assign these devices automatically.
To avoid any issues, make sure each exported view/VOB combo has a unique fsid. It is also important that the view is tagged with the -ncaexported flag and also resides local to the exporting machine. 279. How do I – understand about the maximum character length of a version extended path ClearCase commands, such as cleartool find or cleartool lsco, may fail where the 1024 character limit for view extended pathnames is exceeded. Example errors: Depending on the config spec you may see a message like this: cleartool: Error: Operation "view_gpath" failed: File name too long. The error log may contain messages like: Internal Error detected in "../obj_v.c" line 255 cleartool: Error: String buffer too small. Clearmake may fail with the following error: Thursday 12/17/98 07:53:36. host "host1", pid 22466, user "jdoe" Internal Error detected in "../mf_tgt.c" line 3153 clearmake/mf/mf_tgt: Error: Unable to strip leaf from target pathname "/vob/vob1/src/lib/Objs/one.o /vob/vob1/src/lib/Objs/two.o /vob/vob1/src/lib/Objs/three.o /vob/vob1/src/lib/Objs/four.o /vob/vob1/src/lib/Objs/five.o
Note: And so on... entailing a very long expanded macro target name. Solution A version extended path is limited to a total of 1024 characters (in all version of ClearCase) including the period (.), extended naming suffix (@@), and slash (/ or \) characters within the path.
The total number of characters that compose the branching structure cannot exceed the 1024 limit. The names of your branches may need to be shorted to avoid these problems.
With respect to clearmake, shorten the target names so that they are less than 1024 characters. 280. How do I – understand the requirements when IP address, hostname and NIS are changed What must be done in an IBM® Rational® ClearCase® and ClearCase MultiSite® environment when the IP address, hostname or NIS configurations are changed?
Answer NIS & IP Address Changes An Internet Protocol (IP) address change will not harm (or interfere with) Rational ClearCase functionality if all the servers and clients are rebooted immediately afterwards. This will allow the host to flush any reference (or cache) to the old IP address. Changing the IP address of the ClearCase license server on UNIX® or Linux® may require a modification to the /etc/hosts file on the client machines. This error, mvfs: Error: view= vob= No license available from atria license manager. Use clearlicense to display license usage, may occur from client hosts even though nslookup reports the correct IP address. Check the UNIX client to see if it still has the old IP address listed in its /etc/hosts file, instead of the new IP address. Note: If you are using NIS or NIS+, put the actual IP address returned by nslookup.
Hostname Changes The hostname change is more critical as all VOB and view locations are recorded with the hostname by default. You will have to replace all the existing registry entries of the VOBs and views with the new location; cleartool register -replace and cleartool mktag-replace If you change the host name of the license or registry server then you also need to change the configuration of the clients so that they point to the new license and/or registry server. In a MultiSite environment, you will need to run the command: multitool chreplica -host hostname replica:
ClearCase Environment – How do I on each replica to reflect the new hostname and then synchronize with each site to inform them of the hostname change.
Note: If the hostname of the server was inadvertently changed, rename the host back to the original name and restart the host. The clients should then be able to access the server.
281. How do I – understand about alternate_hostnames If your ClearCase host on UNIX or Linux has multiple network interfaces enabled, ClearCase will attempt to use both interfaces at once. This can negatively affect performance; therefore it is important to configure your host with an alternate_hostnames file. Instructions for setting up an alternate_hostname file can be found in the ClearCase Administrator's Guide as well as the ClearCase Reference Guide on the topic of config_ccase (cleartool man config_ccase).
Here is a copy of the relevant section:
If a ClearCase Host Has Multiple Network Interfaces
If any ClearCase host (client or server) has two or more network interfaces, you must create a file on that host which lists each of its host names.
On UNIX, the file is /var/adm/rational/clearcase/config/alternate_hostnames. On Windows, the file is
For example, suppose that the NIS hosts database includes these entries for a UNIX host:
159.0.10.16 widget sun-005 wid 159.0.16.103 widget-gte sun-105
In this case, the alternate_hostnames file on this host must contain these entries: widget widget-gte
Note that only the first host name in each hosts entry must be included in the file.
The file must list each host name on a separate line. There is no commenting facility; all lines are significant. If a host does not have multiple network interfaces, this file must not exist on that host.
IMPORTANT: After you create or modify this file, you must stop and restart Rational ClearCase so that the changes will take effect.
Note: Documentation defect RATLC01013737 has been submitted to address the discrepancy in the Administrator's Guide where it alludes to the support of alternate_hostnames on Windows. This configuration is not supported on Windows.
FAQs 1. Q: Why should ClearCase be any different than any other application when it comes to network routing? Why does ClearCase need a alternative hostname file unlike other applications?
A: ClearCase was not originally written to work on systems with multiple NIC cards. Rather than going back to add the code necessary to handle multiple NIC cars in a more sophisticated fashion, the alternate hostname file is a simple workaround. 2. Q: Does the order in which hostnames are specified matter?
A: Yes. The primary hosts should be listed first. The primary host is defined as the host specified in the cleartool commands and installations. 3. Q: What would be the correct configuration for a server hosting clients on multiple interfaces if there is no real primary host?
A: Answer depends on situation:
Page 323 of 341
ClearCase Environment – How do I * If the system is a ClearCase license, or registry server, use the hostname specified during installation.
* If the system is a VOB or view server, use the host name used by the mkview and mkvob commands.
* If the system is client only, it doesn't matter which is the primary. 4. Q: We use DNS, should the alternate_hostnames file use fully qualified host names (such as host1.ibm.com)?
A: It is recommended to use fully qualified names. Related information Replica creation packet in incoming bay of export host Packet is not applicable to any local VOB replicas
282. How do I – control the date format displayed by cleartool commands using the CCASE_ISO_DATE_FMT environment variable
The environment variable, CCASE_ISO_DATE_FMT, can be used to control the date format that is displayed in the output of cleartool commands when using IBM® Rational® ClearCase® and is available in Rational ClearCase 2003.06.14 and later versions.
This EV was introduced to allow the use of date formats that conform to the ISO 8601 standard. Use of CCASE_ISO_DATE_FMT enables you to influence the date format in which the output of cleartool commands is given.
This can be especially useful, if you want to use the output in a script and if this script needs to run in different environments.
How to use CCASE_ISO_DATE_FMT To set CCASE_ISO_DATE_FMT for a server, set it as a system environment variable on Microsoft® Windows® or set it in atria_start on UNIX® and Linux®.
Default setting: In ClearCase 2003.06.14, the default value is 0. Note: This is true for all subsequent 2003.06 versions. In ClearCase 7.0, the default value is 1.
When set to 1: Dates and times intended to be read only by users are always displayed in the format defined by the operating system, which are controlled by the user's locale and preferences. All dates intended to be interpreted by programs or scripts are displayed using ISO 8601 format. When set to 0: Dates and times are displayed the same way as in previous releases of ClearCase. For most cleartool commands, this is the format defined by the operating system, which is controlled by the user's locale and preferences. Example ISO 8601 standard example:
M:\dynamic_view\test_vob>cleartool describe foo.doc version "foo.doc@@\main\3" created 2006-10-12T07:50:07-04 by jdoe.clearuser@HOST1 Element Protection: User : DOM1\jdoe : r-- Group: DOM1\clearuser : r-- Other: : r-- element type: ms_word predecessor version: \main\2
Setting variable on Windows (for a single command window only):
C:\>set CCASE_ISO_DATE_FMT=0
Setting variable on UNIX/Linux (for a single command window only): Page 324 of 341
ClearCase Environment – How do I
% setenv CCASE_ISO_DATE_FMT 0
Pre-ISO 8601 standard (date default prior to ClearCase 7.0):
M:\dynamic_view\test_vob>cleartool describe foo.doc version "foo.doc@@\main\3" created 12-Oct-06.07:50:07 by jdoe.clearuser@HOST1 Element Protection: 283. How do I – understand about the CCASE_ISO_DATE_FMT environment variable The environment variable (EV), CCASE_ISO_DATE_FMT, is available in Rational ClearCase 2003.06.14 and later versions.
This EV was introduced to allow the use of date formats that conform to the ISO 8601 standard. Use of CCASE_ISO_DATE_FMT enables you to influence the date format in which the output of cleartool commands is given.
This can be especially useful, if you want to use the output in a script and if this script needs to run in different environments.
How to use CCASE_ISO_DATE_FMT You can set CCASE_ISO_DATE_FMT as a user shell environment variable on UNIX® or Linux®. You can set the CCASE_ISO_DATE_FMT as a System Variable on Microsoft® Windows®
Default setting: In ClearCase 2003.06.14, the default value is 0.
Note: This is true for all 2003.06.xx versions. In ClearCase 7.0, the default value is 1.
The following statement was taken from the ClearCase 7.0 Release Notes: ------This release introduces the following changes to command output:
Because the default value of the CCASE_ISO_DATE_FMT environment variable has been changed to 1 in this release, dates and times intended to be read only by users are always displayed in the format defined by the operating system, controlled by the user's locale and preferences. All dates intended to be interpreted by programs or scripts are displayed using ISO 8601 format. ------Section from the Reference Guide:
When set to a value of 1, forces date and time information intended for interpretation by programs or scripts to be formatted as specified by the ISO 8601 standard. (Dates and times intended to be interpreted only by users are always displayed in the format defined by the operating system, controlled by the user's locale and preferences.)
Set to a value of 0 to format dates and times using the defaults from previous ClearCase releases.
The following table shows how the setting of CCASE_ISO_DATE_FMT affects the formatting of date and time display.
CCASE_ISO_DATE_FMT=0 CCASE_ISO_DATE_FMT=1 dd-mmm-yy.hh:mm:ss yyyy-mm-ddThh:mm:ss±hh dd-mmm-yy.hh.mm.ss yyyy-mm-ddThhmmss±hh dd-mmm-yy.hh:mm:ssUTC yyyy-mm-ddThh:mm:ssZ dd-mmm-yy yyyy-mm-dd dd-mmm-yyyy yyyy-mm-dd dd-mmm.hh:mm --mm-ddThh:mm±hh
Default: 1
Page 325 of 341
ClearCase Environment – How do I
Note: For the --mm-ddThh:mm±hh format reference noted in the above table, the first hyphen would be replaced by a 4 digit year when displayed if the date is not in the last 12 months. Review the CCASE_ISO_DATE_FMT section of the ClearCase Command Reference Guide under the topic of env_ccase (cleartool man env_ccase) for more information.
Example
ISO 8601 standard example:
M:\dynamic_view\test_vob>cleartool describe foo.doc version "foo.doc@@\main\3" created 2006-10-12T07:50:07-04 by jdoe.clearuser@HOST1 Element Protection: User : DOM1\jdoe : r-- Group: DOM1\clearuser : r-- Other: : r-- element type: ms_word predecessor version: \main\2
Setting variable on Windows (for a single command window only):
C:\>set CCASE_ISO_DATE_FMT=0
Setting variable on UNIX/Linux (for a single command window only):
% setenv CCASE_ISO_DATE_FMT 0
Pre-ISO 8601 standard (date default prior to ClearCase 7.0):
M:\dynamic_view\test_vob>cleartool describe foo.doc version "foo.doc@@\main\3" created 12-Oct-06.07:50:07 by jdoe.clearuser@HOST1 Element Protection: User : DOM1\jdoe : r-- Group: DOM1\clearuser : r-- Other: : r-- element type: ms_word predecessor version: \main\2
For more information on CCASE_ISO_DATE_FMT, refer to: IBM Rational ClearCase Release Notes 2003.06.14 IBM Rational ClearCase Command Reference, or run cleartool man env_ccase IBM Rational ClearCase Administrators Guide on the topic of CCASE_ISO_DATE_FMT 284. How do I – understand about naming conventions and characters used to create ClearCase objects When creating an object in ClearCase, the object name must be composed according to the operating system stands.
The following list contains the guidelines the be followed to avoid any problems with object names: Object names must contain only letters, digits, and the special characters underscore (_), period (.), and hyphen (-).
Note: A hyphen should not be used as the first character of a name. Review the related information section if you need to remove an object whose name starts with a hyphen. Object names must not be an integer, real number, octal or hexadecimal digit Object names must not be one of the special names . (dot) .. (dot dot) ... (dot dot dot)
Notes concerning Microsoft® Windows®: The Windows operating systems imposes a byte limit on the length of object names. Despite this limit, ClearCase 2003.06.00 and later (Windows version only) can have object names up to 1024 bytes in length.
Windows preserves the case of object names, but is not case sensitive. Page 326 of 341
ClearCase Environment – How do I Windows object names can contain any characters except for the following: ? " / \ < > * | :
Windows has several device names that cannot be used for directory names and will cause different types of conflicts when used. The following is a partial list of names that should not be used as directory names on Windows: AUX CLOCK$ COM1 COM2 COM3 COM4 COM5 COM6 COM7 COM8 COM9 CON LPT1 LPT2 LPT3 LPT4 LPT5 LPT6 LPT7 LPT8
LPT9 NUL PRN
For all other operating systems, consult the operating system documentation for information about the maximum length of object names. 285. How do I – understand about the special characters in file names on UNIX and Linux The operating system shell environment on UNIX and Linux utilize special characters in different ways; therefore you need a way to escape the special characters when creating new files. Note: For more information on your particular shell and what these special characters are used for, execute the UNIX or Linux man command for manual pages on that particular shell. Example: Bourne shell: man sh C shell: man csh Korn shell: man ksh
The way to escape these special characters is to use supplemental syntax (such as quotes or a backslash).
Example: touch my$file
file: Undefined variable
Supplemental syntax of single quotes added: touch 'my$file'
ls -al -rw-rw-r-- 1 user1 user 1815 Feb 19 09:43 my$file
Since ClearCase is limited to the operating system and shell restrictions, making and working with file elements in ClearCase is no different. For example, the conversion of existing files that have "$" in their names into elements using the cleartool mkelem -eltype file {my$file} command. Example 1: % cleartool mkelem -eltype file -nc 'my$file.txt' Created element "my$file.txt" (type "file"). Checked out "my$file.txt" from version "/main/0". % cleartool ci -identical -nc 'my$file.txt' Checked in "my$file.txt" version "/main/1".
In essence, the single quotes become a permanent part of the file syntax necessary to work with the file.
Example 2: (without quotes) % cat my$file.txt file: Undefined variable
% ls -l total 7 drwxrwxr-x 2 user1 user 294 Dec 31 15:24 lost+found -rw-rw-r-- 1 user1 user 0 Feb 19 09:35 my$file.txt Page 327 of 341
ClearCase Environment – How do I
% cleartool file my$file.txt file: Undefined variable
Example 3: (with quotes) % cleartool file 'my$file.txt' my$file.txt: text_file
% cat 'my$file.txt' Wed Feb 19 09:38:04 EST 2003
% cleartool co 'my$file.txt' Checkout comments for "my$file.txt": test of a file name that has a $ part of the file name . Checked out "my$file.txt" from version "/main/1". Example 4: % cleartool rmelem -nc !file.c % file.c: Event not found The shell is misinterpreting this special character as a "history" command. Escape this special character with a backslash (\) character:
% cleartool rmelem -nc \!file.c
In this example a double quote will be unsuccessful:
% /usr/atria/bin/cleartool ls -l version !file.c@@/main/1 Rule: element * /main/LATEST % /usr/atria/bin/cleartool co -nc !file.c file.c: Event not found % /usr/atria/bin/cleartool co -nc "!file.c" file.c": Event not found % /usr/atria/bin/cleartool co -nc '!file.c' file.c': Event not found % /usr/atria/bin/cleartool co -nc \!file.c Checked out "!file.c" from version "/main/1". % /usr/atria/bin/cleartool rmelem !file.c file.c: Event not found % /usr/atria/bin/cleartool rmelem "!file.c" file.c": Event not found % /usr/atria/bin/cleartool rmelem '!file.c' file.c': Event not found % /usr/atria/bin/cleartool rmelem \!file.c CAUTION! This will destroy the element, all its branches and versions, including all data, meta-data and history, and will remove the element from all directory versions that now contain it. Once you destroy the element, there will be no way to restore it to its current state. If you want to preserve the element, but remove references to it from future directory versions, use the "rmname" command.
Element "!file.c" has 1 branches, 2 versions, and is entered in 1 directory versions. Destroy element? [no] y Removed element "!file.c". 286. How do I – remove ClearCase objects whose name begins with a hyphen Attempts to remove a ClearCase object whose name starts with a hyphen or dash will result in the error: cleartool: Error: Unrecognized option
Example: cleartool rmelem %>cleartool rmelem -t1.txt cleartool: Error: Unrecognized option "-t1.txt" Usage: rmelem [-force] [-c comment | -cfile pname | -cq | -cqe | -nc] pname ... Example: cleartool rmtag %>cleartool rmtag -view -viewtag1 cleartool: Error: Unrecognized option "-viewtag1" Page 328 of 341
ClearCase Environment – How do I Usage: rmtag -view [-region network-region | -all] view-tag ... rmtag -vob [-region network-region | -all] [-password tag-registry-password] vob-tag ...
Note: Attempts to provide quotes or escape characters around the name yields the same error. Objects, whether elements or type objects, that have a dash or hyphen as the first character of their name cannot be removed using standard command line efforts due to how cleartool interprets the hyphen as a command line option, and not a name.
Solution WINDOWS and UNIX To remove a ClearCase object (view, VOB, element or other ClearCase objects) with a preceding hyphen (-) character, execute the cleartool command with a double-hyphen argument to prevent cleartool from interpreting the name as an option.
Example: cleartool rmelem %>cleartool rmelem -- -t1.txt CAUTION! This will destroy the element, all its branches and versions, including all data, meta-data and history, and will remove the element from all directory versions that now contain it. Once you destroy the element, there will be no way to restore it to its current state. If you want to preserve the element, but remove references to it from future directory versions, use the "rmname" command.
Element "-t1.txt" has 1 branches, 1 versions, and is entered in 12 directory versions. Destroy element? [no] y Removed element "-t1.txt".
Example: cleartool rmtag %>cleartool rmtag -view -- -viewtag1
UNIX ONLY: Another way to rmove an object whose name begines with a hyphen is to use a ./ before the name.
Example: cleartool rmelem %>cleartool rmelem ./-t1.txt CAUTION! This will destroy the element, all its branches and versions, including all data, meta-data and history, and will remove the element from all directory versions that now contain it. Once you destroy the element, there will be no way to restore it to its current state. If you want to preserve the element, but remove references to it from future directory versions, use the "rmname" command.
Element "./-t1.txt" has 1 branches, 1 versions, and is entered in 12 directory versions. Destroy element? [no] y Removed element "-t1.txt".
For more information on any of the cleartool sub-commands discussed in this technote refer to IBM Rational ClearCase Command Reference, or run cleartool man
This problem has existed for a while, but it is more likely to occur with ClearCase version 7.0 and later. Page 329 of 341
ClearCase Environment – How do I
Cause This issue has been recorded as defect, APAR PK43785.
REMINDER:
It is vital that any backup procedure used in your environment conform to the instructions outlined in the Rational ClearCase Administrator's Guide.
Chapter 10 titled Backing up critical Rational ClearCase data states in the section titled Requirements for VOB and view backup tools the following (for UNIX and Linux specifically): The backup tool must be able to back up the largest file in the VOB. The backup tool should back up files even if they are open for writing. The backup tool should preserve file access times.
Chapter 10 also states that the VOB must be locked during the backup.
Resolving the problem This defect has been resolved in Rational ClearCase version 7.0.1.
ClearCase has increased it's mutex retry period to prevent database errors during login while fssnap is executing.
WORKAROUND:
Stop ClearCase processes prior to using "fssnap".
In the event your VOBs become unusable (inaccessible) due to this problem, the following procedure should resolve the problem: Stop ClearCase Verify all ClearCase db_server and vobrpc_server processes have terminated Move the almd file (not the almd.lck) from db directory in VOB storage (.vbs) area to a temporary location (such as /tmp). Start ClearCase
If a lock of an affected VOB is not possible when this issue occurs, and where stopping ClearCase for all developers may be too invasive to a development department, another option would be the following: Unmount the affected VOB Stop the vob_server process for the VOB Move the almd file (not the almd.lck) from db directory in VOB storage (.vbs) area to a temporary location (such as /tmp). Start the vob_server process for the VOB Mount the affected VOB again Related information Backup software must backup files open for write access 288. How do I – understand about the TZ environment variable The format required for the TZ variable is specified by the operating system. For Microsoft® Windows® search for _tzset() in Microsoft Developer Network (MSDN).
For UNIX® and Linux® see section 8.3 Other Environment Variables in The Single UNIX Specification Version 3.
Summary: TZ=tzn[+ | –]hh[:mm[:ss] ][dzn]
tzn
Three-letter time-zone name, such as PST. You must specify the correct offset from local time to UTC (Universal Time Coordinated).
hh
Difference in hours between UTC and local time. Optionally signed.
Page 330 of 341
ClearCase Environment – How do I
mm
Minutes. Separated from hh by a colon (:).
ss
Seconds. Separated from mm by a colon (:).
dzn
Three-letter daylight-saving-time zone such as PDT. If daylight saving time is never in effect in the locality, set TZ without a value for dzn.
Example: On UNIX, set /etc/TIMEZONE to a value other than a full POSIX string for use with the scheduled ClearCase jobs.
Incorrect Value: TZ=GMT0BST Correct Value: TZ=GMT0BST-1,M4.5.0/2,M10.5.0/2
On Windows, you can refer to this link, Setting TZ Environment Variable on Windows.
289. How do I - define TEMP user environment variables for the clearcase_albd account even if you cannot logon with this account By default, the TEMP and TMP user environment variables are populated for the Windows profile of a user that logs on to a host. You may wish to redefine the default user environment variables for TEMP and TMP for the clearcase_albd service account due to disk space limitations or drive preferences. On some Windows DOMAINS, the clearcase_albd service account is set to log-on as a service, or you may not have access to log-on as this account.# Answer Note: This solution contains information about modifying the system registry. Before making any modifications to the Microsoft® Registry Editor, it is strongly recommended that you make a backup of Page 331 of 341
ClearCase Environment – How do I the existing registry. For more information describing how to back up the registry, refer to the Microsoft Knowledge Base article http://support.microsoft.com/kb/256986. 1. Locate the Windows domain SSID of your clearcase_albd by running the CREDS command as follows:
Note: Review technote 1221403 for more details about the creds utility.
C:\Program Files\Rational\ClearCase\etc\utils\>creds clearcase_albd Windows NT user info (on local system): Domain: MYDOMAIN SID: S-1-5-21-141845252-1443263951-... ("clearcase_albd" is the name of the service account specified at your site which may be different) 2. After taking precautions to backup your Windows registry, open regedit as a local administrator on the host:
Start > Run type regedit 3. Locate the following key: HKEY_USERS\
5. Restart the host for changes to take affect.
Note: The default value for TEMP and TMP in a Windows profile is as follows: %USERPROFILE%\Local Settings\Temp 290. How do I - stop client names from appearing in the ClearCase Administration Console The ClearCase Administration Console (Start > Run type ccadminconsole.msc) will display the client hosts in the ClearCase Network that share the same license or registry server.
Page 332 of 341
ClearCase Environment – How do I Example:
The ClearCase registry server collects information about client hosts that have recently accessed the registry server. The "ClearCase Network" list is populated from a network call to the license server. This information is stored in the client_list.db file which is only read on ClearCase startup and is located in the following directory:
UNIX® or Linux®:
/var/adm/atria (2002.05.00) /var/adm/rational/clearcase (2003.06.00 and later)
Microsoft® Windows®:
C:\Program Files\Rational\ClearCase\var
Follow these instructions to remove information about a specific client. 1. Open the client_list.db file with a text editor (notepad or vi) 2. Remove the unwanted client entries Restart ClearCase Services. 291. How do I - activate ClearCase remote administration on UNIX and Linux Remote administration functionality is only enabled/disabled through the installation process. If you did not select YES to allow remote ClearCase administration when running site_prep during installation, you will need to reinstall ClearCase. You must reinstall Rational ClearCase on the respective host which requires remote administration. Before this can be done, the release area needs to be updated to allow for remote administration. You can rerun the site_prep to enable remote ClearCase administration on the host with the release area stored. Be sure to answer YES to allow remote ClearCase administration.
Page 333 of 341
ClearCase Environment – How do I Review the ClearCase Installation and Upgrade Guide on the topic of Installing Rational ClearCase: Networkwide Resources for more information. 292. How do I – understand about files under source control and the write bit You can set and unset the write bit successfully on an element using the cleartool protect command; however, the effects do not yield expected results. For example, upon changing the write bit using the cleartool protect command, ClearCase reports that the protections were changed successfully:
Z:\base>cleartool protect -chmod 664 wow.txt Changed protection on "wow.txt".
Upon running the cleartool describe command, you will see that the protections did not change: Z:\base>cleartool describe wow.txt version "wow.txt@@\main\2" created 06-Jan-05.07:50:17 by benfabry.user@bfabry Element Protection: User : DOMAIN\joeuser: r-- Group: DOMAIN\users : r-- Other: : r-- element type: text_file predecessor version: \main\1
Note: If you use the GUI to obtain the properties of an element, and look at the Protection tab, you will see that the check boxes for the write bit are greyed out and can not be changed. Answer ClearCase does not use the write bit for file elements. The ability to write to a file is determined by its checkout status.
Only if an element has been checked out can you write to it.
The meaning of the write-access permission varies with the kind of object:
File elements. Write permission is not meaningful for file elements, which can be modified only by checking them out.
Directory elements. Write permission allows users to add view-private objects to directory elements in a dynamic view. (full ClearCase only)
Shared derived objects. Write access allows shared-derived objects to be overwritten with new derived objects during a target rebuild. Note: This information was taken from the context sensitive help. 293. How do I – understand the issue “Is there a Windows equivalent of the CLEARCASE_DBG_GRP EV” CLEARCASE_DBG_GRP is available on UNIX and Linux, and when it is set, it outputs a transcript of the command used when using the xclearcase graphical user interface (GUI), such as button pressed. What is the Windows equivalent of the CLEARCASE_DBG_GRP EV?
Answer Due to differences between UNIX (or Linux) and Windows clients, CLEARCASE_DBG_GRP does not work under Windows and there is no like ClearCase EV for capturing this type of data. Also, ClearCase does not have alternative functionality for getting the command or set of commands used from the Windows GUI, such as ClearCase Explorer. Refer to IBM Rational ClearCase Command Reference under the topic of env_ccase for further details about CLEARCASE_DBG_GRP and other ClearCase environment variables. ClearCase Scheduler 294. How do I – understand that the ClearCase Scheduler incorrectly computes next run time on day of transition to standard time There are multiple situations where the next run time is computed incorrectly on the day of transition to standard time: Page 334 of 341
ClearCase Environment – How do I
Note: The task definition for the below example jobs:
Task.Begin Task.Id: 202 Task.Name: "Take a Nap" Task.Pathname: "naptime.sh" Task.End
1. When the first start time of a repeating job precedes the instant of transition, job execution skips an hour.
Example:
Job.Begin Job.Id: 15 Job.Name: "First start before transition" Job.Description.Begin: Take a short nap Job.Description.End: Job.Schedule.Daily.Frequency: 1 Job.Schedule.StartDate: 2006-01-01 Job.Schedule.LastDate: 2007-12-31 Job.Schedule.FirstStartTime: 00:30:00 Job.Schedule.StartTimeRestartFrequency: 00:30:00 Job.Schedule.LastStartTime: 04:30:00 Job.DeleteWhenCompleted: FALSE Job.Task: 202 # Job.Task: "Take a Nap" Job.Args: -i15 -t15 Job.End
2. When the first start time is after the instant of transition, job execution starts one hour late.
Jobs that should be executed in the last hour of the day are not executed.
Example:
Job.Begin Job.Id: 16 Job.Name: "First start after transition" Job.Description.Begin: Take a short nap Job.Description.End: Job.Schedule.Daily.Frequency: 1 Job.Schedule.StartDate: 2006-01-01 Job.Schedule.LastDate: 2007-12-31 Job.Schedule.FirstStartTime: 22:30:00 Job.Schedule.StartTimeRestartFrequency: 00:14:00 Job.Schedule.LastStartTime: 23:59:59 Job.DeleteWhenCompleted: FALSE Job.Task: 202 # Job.Task: "Take a Nap" Job.Args: -i16 -t15 Job.End
Cause Defect APAR PK45304 has been opened to address this issue.
Resolving the problem Page 335 of 341
ClearCase Environment – How do I Defect APAR PK45304 has been resolved in the following ClearCase version:
ClearCase 7.1 Version 7.1
WORKAROUND The workaround is to examine the scheduled jobs and modify any jobs that meet any of the conditions in the above three example cases. You can then temporarily adjust the runtime of those jobs (after making a backup of the existing scheduled jobs) and reset those jobs after the transition time has passed.
Refer to technote 1316955 Backing up and modify scheduled jobs from the command line for details. 295. How do I – understand why the Daily View Space scheduled jobs making several DNS calls In a ClearCase environment configured with clients that host local views, the Daily View Space scheduled job kicks off (on each of them) at the default time of 4:30A. The job runs cleartool space -generate, for each local view, but to identify which of the views are local to a client, calls are made to the DNS to get the IP address of the view server for each view in the region.
These calls create substantially more network traffic during non-peak hours, and consequently there is an inflated number of call failures due to the sheer amount exceeding how many calls the DNS server can handle. Cause This has been recorded as defect RATLC00695447. Resolving the problem The decision was made by Product Management to exclude the resolution of this defect from future upgrades and releases. This issue does not impact Rational ClearCase use or functionality, but if the Daily View Space scheduled job is left enabled on multiple clients, then there will continue to be an innumerous amount of benign network traffic and DNS failures generated.
WORKAROUND: To stop the DNS queries, the Daily View Space scheduled job on each client host can be deleted using this command: cleartool schedule -host
This will stop the automatic collection and reporting of information about the disk usage of local views. However, the command cleartool space -generate can be run manually to . Also, if space becomes an issue, the operating system will warn if the disk space is low. 296. How do I – use the ClearCase Scheduler without NIS on UNIX or Linux The ClearCase Scheduler (introduced in ClearCase version 4.0) uses an ACL (Access Control List) map for controlling user privileges to add, modify or invoke tasks in the scheduler.
The default format for the ACL is similar to a line like this:
User:domainname/username Full
The domainname section equates to an NIS domain for UNIX/Linux clients and is used to control remote access to the scheduler. The domainname is a required field, and cannot be omitted.
Solution Here is how UNIX and Linux clients that are not part of an NIS domain can use the Scheduler. In the ACL, use an entry with the following syntax:
User:
The
Note: This solution only works on machines that are not part of an NIS domain and cannot be used to grant users 'multi-domain' rights.
Page 336 of 341
ClearCase Environment – How do I 297. How do I – understand the unable to add a user to the Scheduler ACL list where NIS is not defined issue Attempts to add a specific user to the Schedule ACL list without an NIS domain defined results in the following error: cleartool schedule -acl -edit User:user Full cleartool: Error: Unable to edit scheduler ACL: Permission denied.
The domainname is a required field, and cannot be omitted.
Solution Enter the domain name as
298. How do I – understand the ClearCase -nusers switch can only specify single users to allow access to an object issue When restricting access to ClearCase VOB objects using the -nusers switch, only individual usernames can be specified in a comma-separated list without spaces. If there are several users to add to the access control list, it can be cumbersome to enter each username individually, and it would be ideal to have the ability to enter a group instead. Specifying a group in the -nusers list is currently not available.
Change Request (RFE) RATLC00606633 has been opened to add the ability for the -nusers option to specify a group. This will allow you to add several users that are in the same group to the access control list of an VOB object by specifying the group in the -nusers list, rather than individual usernames.
For more information on the commands that the -nusers switch is available, reference the product documentation in the IBM Rational ClearCase Information Center. 299. How do I - move custom ClearCase Scheduler Jobs from one system to another By default jobs 1 through 13 are created and set after the ClearCase is installed. For any custom jobs that have been created, use the following procedure to copy them to another ClearCase server. Dump the existing jobs info from the old ClearCase server into a data file.
Example:
C:\> cleartool schedule -get > jobs.txt Modify the data file for the custom jobs (which are the jobs other than the default ClearCase jobs 1 through 13) and comment (with a # sign) the Job.Id.
Example:
# Job.Id: 16. (Optional) For custom jobs only, if there are any sequential jobs: Comment the Job.Schedule.Sequential.FollowsJob:
Example:
# Job.Schedule.Sequential.FollowsJob: 34 Uncomment the Job.Schedule.Sequential.FollowsJob:
Example:
Job.Schedule.Sequential.FollowsJob: "Backup Test VOB" Copy the data file to the new system. Save the task_registry file from the old machine and copy it into the equivalent directory on the new system. The task_registry file is located in %ClearCase-Home-Dir%\var\scheduler\tasks.
Example: C:\Program Files\Rational\ClearCase\var\scheduler\tasks
Page 337 of 341
ClearCase Environment – How do I Load the jobs info to the new system from the modified data file.
Example:
C:\> cleartool schedule -set jobs.txt
Note: If job B is dependent on job A, make sure that job A is listed prior to job B in the data file. 300. How do I - recreate the ClearCase Scheduler database without losing customized default job information This technote explains how the IBM® Rational® ClearCase® Scheduler database can be replaced if it has become corrupt without fear orf losing the default jobs that have been customized over time.
A possible symptom of a corrupt scheduler database comes in the form of the albd_server process crashing with a memory dump every time the Scheduler runs. If the ClearCase scheduler database becomes corrupt, the ALBD process will: 1. Consider jobs that have terminated to still be running, and/or 2. Think the next scheduled run time for a job is years in the future or
When this happens, the most common warning message reported in the ALBD log is:
"Albd(1064): Warning: Job ... is still running -- skipping scheduled execution." Another indication of a corrupt scheduler database on Windows is that the albd process may crash. In the Windows event viewer you would see errors such as the following when trying to edit or change a scheduled job:
C:\Program Files\Rational\ClearCase\bin\albd_server.exe (pid: 1732, tid: 1744) nt_gendump("C:\Program Files\Rational\ClearCase\var\log\albd_server.1732.dmp"): Unhandled exception was caught!
Resolving the problem Note: This procedure only works for changes that have been made to the default jobs. It does not work for jobs that have been added beyond the default set included with ClearCase. To recreate the scheduler database without losing any customizations, complete these steps: 1. Log in as the ALBD user on Microsoft® Windows® or root on UNIX® and Linux® 2. Save the current schedule:
cleartool schedule -get > oldschedule.txt 3. Save the scheduler's access control list (ACL):
cleartool schedule -get -acl > oldacl.txt 4. Edit the oldschedule.txt file to: Remove all CompletionInfo sections Check the Job.NextRunTime sections to be sure they do not contain invalid values. For example, a job scheduled to run every 10 minutes in 2015. 5. Stop ClearCase: UNIX and Linux: /opt/rational/clearcase/etc/clearcase stop Windows: use the ClearCase Control Panel (Start > Run type cc.cpl) 6. Delete the corrupted scheduler database: UNIX and Linux: rm /var/adm/rational/clearcase/scheduler/db Windows: del "c:\program files\rational\clearcase\var\scheduler\db" 7. Start ClearCase: UNIX and Linux:: /opt/rational/clearcase/etc/clearcase start Windows: use the ClearCase Control Panel (Start > Run type cc.cpl)
This will create a new scheduler database with ONLY the default jobs and ACL. 8. Replace the new schedule with the contents of oldschedule.txt:
cleartool schedule -set oldschedule.txt.
When prompted with, Replace entire schedule? [no], type yes and press Enter. 9. Replace the new ACL with the contents of oldacl.txt:
cleartool schedule -set -acl oldacl.txt
Page 338 of 341
ClearCase Environment – How do I
When prompted with, Replace the ACL? [yes], Press Enter. 301. How do I – “Temporarily disabling jobs in the Scheduler” You can temporarily disable a ClearCase Scheduled Job by changing the job schedule settings. By default, each job is set up to run sequentially, following the previous job ID. You can edit a job and change it to a daily or weekly job with the start date set to days or months ahead. Note: Be sure to keep a copy of the default settings so that you can change back to the default. If necessary, you can edit job information from another host by running: cleartool schedule -edit –schedule
Review the IBM Rational ClearCase Command Reference on the topic of schedule (cleartool man schedule) for more information. On Windows you can change the job schedule settings from the ClearCase Administration Console by going to My Host > Scheduled Jobs and performing the following steps. 1. Right click a scheduled job 2. Select Properties 3. Click the schedule tab 4. Click the Advanced button. 5. Set the start date to a time in the future so the job will not run. 6. Click OK
Here are the default settings for a job. It is scheduled to run after Job 4 completes:
Job.Begin Job.Id: 5 Job.Name: "Daily View Space" Job.Description.Begin: Determine the space consumed by all local views. Job.Description.End: Job.Schedule.Sequential.FollowsJob: 4 # Job.Schedule.Sequential.FollowsJob: "Daily Local Tasks" Job.DeleteWhenCompleted: FALSE Job.Task: 11 # Job.Task: "View Space" Job.Args: Job.NotifyInfo.OnEvents: JobBegin,JobEndOKWithMsgs,JobEndFail Job.NotifyInfo.Using: email Job.NotifyInfo.Recipients: root,[email protected] Job.Created: 16-May-00.16:57:23 by rational.com/root@host1 Job.LastModified: 29-Aug-00.08:58:12 by rational.com/root@host1 Job.Predefined: TRUE Job.LastCompletionInfo.ProcessId: 25149 Job.LastCompletionInfo.Started: 18-Dec-01.04:30:25 Job.LastCompletionInfo.Ended: 18-Dec-01.04:30:44 Job.LastCompletionInfo.ExitStatus: 0x0 Job.End Page 339 of 341
ClearCase Environment – How do I Start date Changes: here we set it to a weekly job, with a start date of 31-Dec-04.
Job.Begin Job.Id: 5 Job.Name: "Daily View Space" Job.Description.Begin: Determine the space consumed by all local views. Job.Description.End: Job.Schedule.Weekly.Frequency: 1 Job.Schedule.Weekly.Days: Fri Job.Schedule.StartDate: 31-Dec-04 Job.Schedule.FirstStartTime: 04:30:13 # Job.Schedule.Sequential.FollowsJob: "Daily Local Tasks" Job.DeleteWhenCompleted: FALSE Job.Task: 11 # Job.Task: "View Space" Job.Args: Job.NotifyInfo.OnEvents: JobEndOKWithMsgs,JobEndFail Job.NotifyInfo.Using: email Job.NotifyInfo.Recipients: root Job.Created: 01-Dec-01.13:38:41 by rational.com/root@host1 Job.LastModified: 17-Dec-01.16:57:32 by rational.com/root@host1 Job.Predefined: TRUE Job.NextRunTime: 01-Jan-02.04:30:13 Job.LastCompletionInfo.ProcessId: 22119 Job.LastCompletionInfo.Started: 17-Dec-01.04:30:13 Job.LastCompletionInfo.Ended: 17-Dec-01.04:30:20 Job.LastCompletionInfo.ExitStatus: 0x0 Job.End In the albd_log, you can see job 5 was not invoked.
12/18/01 04:30:00 albd_server(16565): Ok: Job 1 "Daily VOB Pool Scrubbing" (22373) Started. 12/18/01 04:30:06 albd_server(16565): Ok: Job 1 "Daily VOB Pool Scrubbing" (22373) Completed: OK. 12/18/01 04:30:06 albd_server(16565): Ok: Job 2 "Daily VOB Snapshots" (22376) Started. 12/18/01 04:30:12 albd_server(16565): Ok: Job 2 "Daily VOB Snapshots" (22376) Completed: OK. 12/18/01 04:30:12 albd_server(16565): Ok: Job 3 "Daily Registry Backup" (22469) Started. 12/18/01 04:30:12 albd_server(16565): Ok: Job 3 "Daily Registry Backup" (22469) Completed: OK. 12/18/01 04:30:12 albd_server(16565): Ok: Job 4 "Daily Local Tasks" (22474) Started. 12/18/01 04:30:12 albd_server(16565): Ok: Job 4 "Daily Local Tasks" (22474) Completed: OK. 12/18/01 04:30:20 albd_server(16565): Ok: Job 6 "Daily VOB Space" (22475) Started. 12/18/01 04:30:24 albd_server(16565): Ok: Job 6 "Daily VOB Space" (22475) Completed: OK. Anti-virus software 302. How do I – understand the support Policy for Anti-Virus software and ClearCase Support Policy for Anti-Virus and ClearCase 303. How do I – understand the RPC: Remote system error - [WINSOCK] No buffer space available issue After installing McAfee® Enterprise 8.0 on a Microsoft® Windows® machine, IBM® Rational® ClearCase® omake builds fail with "RPC: Remote system error - [WINSOCK] No buffer space available" and system crashes.
Cause Omake builds are failing after installation of McAfee 8.0 with the following errors:
RPC: Remote system error - [WINSOCK] No buffer space available omake: Error: Error trying to contact view_server for view view:C:\viewstore\oa12.vws: No such file or directory omake: Error: Unable to contact View - oa12 RPC: Remote system error - [WINSOCK] No buffer space available cleartool: Error: Error trying to contact view_server for view view:C:\viewstore\a12.vws: Page 340 of 341
ClearCase Environment – How do I
No such file or directory
Insufficient system resources exist to complete the requested service.
Fatal error C1083: Cannot open source file: '.\Font.cpp': Not enough space
Solution Upgrade to McAfee Virus Scanner 8.10. or
Apply McAfee Virus Scanner 8.0i patch 15 which resolves this issue by adding the ClearCase MVFS to the "do not scan" list of the McAfee filter driver. The patch is available for download on the McAfee website.
Note: This patch will fix a known memory leak issue and resolve other known ClearCase command problems.
Create view fails after uninstalling McAfee Firewall ClearCase commands fail when McAfee 8.x is installed Error running fix_prot with McAfee 8.0 installed Failure removing VOBs & views with McAfee installed Veritas NetBackup and McAfee AntiVirus conflict About McAfee VirusScan Enterprise 8.0i Patch 11
This website is published "as is". There is no warranty of any kind (express or implied) as to the operation of our site, the accuracy of the information or the services or products referred to on it. All warranties are excluded as far as permitted at law. Neither we nor any third party will be liable for any losses or damage that may result from use of the website or as a consequence of any inaccuracies in, or any omissions from, the information which it contains.
Registered Office: SAMECS House 22 Sparrowhawk Way TELFORD TF1 6NH Tel: 01952 248593 Web site: www.samecs.co.uk Register in England No: 4824835 E-Mail: [email protected]
Page 341 of 341