IBM Support

How to specify what client versions can access a ClearQuest database

Technote (FAQ)


Question

How can an IBM Rational ClearQuest administrator specify which client versions are allowed to access a ClearQuest Database?

Answer

ClearQuest version 8.0.1.1 introduces two properties that can be used to specify what client versions are allowed to logon to a ClearQuest database. This is useful to make sure only approved client versions can access the databases. These properties are available for use in databases using Feature Level 8 (FL8). Note that once a database set is upgraded to Feature Level 8, versions of ClearQuest prior to 8.0.1.1 will not be able to logon to the ClearQuest database. Feature Level prevention of down-rev client logon remains as before, and is independent of these new two properties.

The first is a master property, named ALLOWED_CLIENT_VERSIONS. This property is set with the "installutil setmasterproperty" command. The current value of this property can be read with the "installutil getmasterproperty" command. To remove the property, set its value to an empty string.

The second is a schema property, also named ALLOWED_CLIENT_VERSIONS. This property is set with the "packageutil setproperty" command. The current value of this property can be read with the "packageutil showproperties" command. To remove the property, set its value to an empty string. Note: the use of the packageutil command is solely supported for the above described purpose.

The value for both of these properties is the same: a space delimited list of client versions, in user databases. Each item in the list must be separated from the others by one or more spaces. The format of each item is a Version.Release.Modification.Fix (VRMF) version specifier that indicates clients of that version are allowed to logon. Each VRMF item is compared for an exact match with the client version (it is not a minimum version). However, each VRMF item can be shortened to allow any value for the trailing parts that were not included. For example, "8.0.1" would allow client version 8.0.1 and any fixpacks identified as 8.0.1.nn. Similarly, a value of "8.0" would allow any 8.0.n.nn client, and "8" would allow any 8.n.n.nn client.

Note that a test fix release is identified by a fifth value appended to the VRMF release number. This additional value is ignored by the version check.

The master property applies to "administrator" logons, such as with the ClearQuest Designer, User Administration tool, and various command line tools. The master property also applies to "user" logons to a user database, using the ClearQuest Web or Eclipse clients. This also applies to any logon done through ClearQuest APIs. The schema property applies only to logons from any client or via an API to a user database using a schema revision that has the property set.

Note: This restriction via master property does not apply to a super user. A super user can fix any version restriction that may have been set accidentally. The schema property does apply to a super user (unlike the master property).

The master property is checked before the schema property. If the master property does not allow a client to logon, then the logon will fail before the schema property is checked. Generally, using just the master property will be sufficient, but in some cases, the schema property may be needed to further limit the client versions that are allowed to access a particular user database (see example below).

For example, setting the master property to "8.1" would allow version 8.1.n.nn clients to access the schema repository or any of its user databases. If a schema property was then set to "8.1.1", the user databases using that schema would then be further limited to clients of version 8.1.1.nn.

Suppose an administrator has determined they need a fix that was released in versions 8.1.2 and 8.0.1.06. This fix is also available in 8.2. To make sure all users are using a client that has the fix, these versions can be specified as the only ones allowed to access the database. The following command will enable that check for the entire DEV database set:

installutil setmasterproperty DEV admin "password" ALLOWED_CLIENT_VERSIONS "8.2 8.1.2 8.0.1.06"


Suppose further that one of the user databases depends on a fix that is only available in 8.1.2.02, not in 8.0.1.06, and further the schema in that database has not yet been tested with 8.2. The schema for that database can be updated with the schema property to limit the client versions allowed to access the specific user databases that use that schema. Here's an example command for the DefectTracking schema in the DEV database set:

packageutil setproperty -dbset DEV admin "password" DefectTracking ALLOWED_CLIENT_VERSIONS "8.1.2.02"


Note that in order to allow a series of fixpack releases (those with a non-zero value for the F in VRMF), each version would have to be listed explicitly. For example, to allow all versions starting with fixpack 8.0.1.06, the list would have to be "8.0.1.06 8.0.1.07 8.0.1.08 ...".

Note that master properties are replicated in a MultiSite deployment. Setting the ALLOWED_CLIENT_VERSION master property will affect all sites once that change is replicated.


Document information

More support for: Rational ClearQuest
General Information

Software version: 8.0.1.1

Operating system(s): AIX, Linux, Solaris, Windows

Reference #: 1632013

Modified date: 23 September 2013