ClearQuest support for Oracle Service Names

Answer

ClearQuest versions 9.0.0.5 and 9.0.1.1 add support for connecting to Oracle with an Oracle Service Name instead of a SID.

A ClearQuest database connection has several fields. Defining a connection using an Oracle service name involves providing proper values for the SID field and the Connect Options field. The Server, User Name, and Password fields are set in the same way as for any other Oracle connection. In the following description, these fields are identified as "fields". The Connect Options field can contain several different connect option values. These are identified as "connect options".

To use a service name, add "Service_Name=<name>" to the Connect Options field and omit the SID connect option. Specify the service name defined in Oracle as the value for "<name>". The name of the "Service_Name" connect option is not case sensitive. The SID field of the database connection parameters must have a non-empty value, even though it will not be used.

The other connect fields, including Server, User Name, and Password are used in the same way as for any other Oracle database connection.

An Oracle service name can take almost any form, such as a simple name, or a name followed by a fully qualified domain name. A typical service name might be "cq_repo.redwood.example.com" for a database on server "redwood" in domain "example.com". In this example, the Service_Name connect option value value added to the Connect Options field would be:

Service_Name=cqrepo.redwood.example.com

Here is what the Oracle properties panel looks like in the Maintenance Tool when defining a connection using this service name. Below the screenshot is the full value of the Connect Options field which is not shown in the dialog. Note that multiple connect options must be separated by a semicolon (";").

Using the SID field as the Service Name (Alternate Method)

Normally, when the Service_Name connect option is used, the value of the SID field must be non-empty, even though the value will be ignored. However, if the value of the Service_Name connect option is exactly "[SID]", the value of the SID field is used as the service name. This makes entering the service name a little easier when creating a new connection in the Maintenance Tool or the ClearQuest Eclipse Client, and makes API access somewhat more consistent.

For these reasons this is the preferred method for using Service Name, even though the field label remains SID.

Here is an example using this alternative method of specifying the Oracle service name for the same connection as before:

Using this alternative method may allow existing scripts using the ClearQuest APIs to work without significant changes, since the SID field can then be treated as the service name, provided the script also includes "Service_Name=[SID]" in the connect options. This simplifies the script since it can handle the service name as a separate value instead of extracting it from the connect options string or inserting it properly into that string.

Note that at the API level, the Oracle SID field corresponds to the database name, which is returned from the CQDatabaseDesc::GetDatabaseName() and CQDatabase::GetDatabaseName() APIs, or set with the CQDatabase::SetDatabaseName() API.


Interaction with the SID Connect Option

When support for Oracle was first added to ClearQuest, an SID connect option was defined for compatibility of database connections for Windows, Linux and the Unix platform. The SID connect option is still valid, but rarely used. Normally, the SID connect option overrides the setting of the SID field. When both Service_Name and SID connect options are used, the SID connect option and SID field will be ignored and the Service_Name connect option will be used instead.