IBM Support

Managing connections with the cqreg command line utility

Technote (FAQ)


How can you manage connections using command line when using IBM Rational ClearQuest on Linux or UNIX based platforms?


Database connections can be managed with the command line utility cqreg, which is stored in the <INSTALLDIR>ClearQuest/bin directory. The command has the following structure:

    Usage: cqreg [initialize | register | unregister | refresh | show | add_dbset | drop_dbset] <options>
    Options include: [-help] [-effort_only] [-force] [-verbose] [-errors] [-home <cq_home>] [-version <cq_version>] [-cq_databases <cq_databases>]

You only need to run these commands on a system-level basis. It does not need to be run per operating system user basis. Type " man cqreg" at the UNIX command prompt to access the on-line help for the cqreg command. Database parameters such as -d must be provided. Here are some more common uses of the cqreg utility:
  • cqreg show: View all connections.
  • cqreg initialize: Creates necessary file structures.

    There should be the following directory structure for ClearQuest UNIX installations:



    If you cannot find .Databases, you may have to create it manually. Create a file called .Databases with the one line below and then rerun initialize:


    All connections will be updated in the file with the connection names following this structure:

    /opt/rational/clearquest/CQDB_rgys/cqdb_registry/<version>/ <connection name>.

  • cqreg drop_dbset: Drops a dbset (connection). If you need to update connections, you drop and add the dbset.
    Example of usage:

    cqreg drop_dbset -dbset <dbset>
    Example of output with errors:

    dropping dbset "7.0.0"

    default database path is not set
    default version is 7.0.0
    opendir failed to open 7.0.0
    no such file or directory.
    cqreg has finished with errors
    If you do not use a connection name that exists, it uses the default for that version and tries to drop it instead. The default connection name is 2003.06.00 for version 2003.x, and 7.0.0 for version 7.x. See more information about the default connection below.
  • cqreg add_dbset:
    Connect options must be surrounded in double quotes.

    Here is an example for Oracle:

    cqreg add_dbset -v ORACLE -s serverHost -d serverSID -u OracleUser -p OraclePass -dbset DesiredConnectionName -co "LOB_TYPE=CLOB"

    Here is an example for SQL Server:

    cqreg add_dbset -v SQL_SERVER -s serverHost -d databaseName -u sqlServerUser -p sqlServerPass -dbset DesiredConnectionName -co ""

    Here is an example for IBM DB2:

    cqreg add_dbset -v DB2 -s serverHost -d databaseName -u DB2ServerUser -p DB2ServerPass -dbset DesiredConnectionName -co ""

    If all is well the output should look like this:

    10:27:25 --- Default DB path is

    10:27:25 --- Default version is 2003.06.00
    10:27:25 --- Add database set 2003.06.00
    10:27:35 --- Master db registry needs to be created
    10:27:35 +++ Master db registry was created successfully
    10:27:35 --- Db registry SAMPL needs to be created
    10:27:35 +++ Db registry SAMPL was created successfully
    10:27:35 --- Db registry TestDB needs to be created
    10:27:35 +++ Db registry TestDB was created successfully
    10:27:35 +++ Database set 2003.06.00 successfully added
    10:27:35 ::: [cqreg has finished]

About the default database path:
When ClearQuest tries to connect to a database, it will first look if the CQ_DATABASES variable has been set, and if set, it will use this variable to determine where the database is registered. With the setenv command, you can set a user or system variable. (This is under the cshell. If using bash, use the env command and then export the env variable with the export command.) If the default database path has not been set, you can set it by entering the variable CQ_DATABASES. This should point to:


Note: Starting with 7.0, ClearQuest uses the Eclipse RCP Client which allows for the creation and managing of database connections with a GUI interface. Access this through the menu option File > Database > Manage Connection.

The ClearQuest Information Centers have additional information about the utility. See the cqreg topic.

Document information

More support for: Rational ClearQuest
Command Line Tools

Software version: 7.0, 7.0.1, 7.1, 7.1.1, 7.1.2, 2003.06.00

Operating system(s): AIX, HP-UX, Linux, Solaris

Reference #: 1320850

Modified date: 31 October 2009