Using ClearQuest after a database copy results in "Access to this database is currently denied" error

A ClearQuest user database is locked after a failed upgrade. If the upgrade is attempted again, the following error message is displayed:


Access to this database is currently denied. The database is locked while upgrading the application.


Note: When you use the installutil, copyschemarepo, and copyuserdb commands, the original databases are locked while the copying is in progress. The original databases are unlocked once the new databases are created. This solution can unlock the original databases if they are not unlocked or if the copy fails.

See technote Procedure to use the copyschemarepo and copyuserdb commands to copy databasesfor details on how to use the copyschemarepo and copyuserdb commands.

When the upgrade process is initiated, ClearQuest temporarily "locks" the database to prevent other transactions from accessing the data while the upgrade is in progress. The lock prevents you from connecting to a database during the upgrade process, which is working as designed.

When a database is locked, you are not allow to access it. When you try to log into ClearQuest, you will denied access.

Once the upgrade transaction has successfully completed, the database lock should be released and you can once again connect to the database. If the upgrade does not complete successfully, the databases are left in a locked state.

Once the original database is unlocked, it is possible to use it again.

To resolve a failed database upgrade, restore the affected user database using a backup that was created just before upgrading it.

Since the backed-up version was not locked at the time it was backed up, the database will no longer be locked after it has been restored.

---

Procedure to manually unlock a user database

Parameter Description

Sample commands to unlock an Oracle database

Sample commands to unlock a Microsoft SQL Server database

Sample commands to unlock an IBM DB2 database

Sample commands to unlock a SQL Anywhere database

Sample commands to unlock a Microsoft Access database

Additional Information

---

Procedure to manually unlock a user database

Use the procedure described below to manually unlock the user database and then retry the upgrade. If it fails again, contact Rational Technical Support for assistance. If the upgrade appears to succeed, then carefully test the resulting user database to ensure that it includes all the latest schema changes. If not, contact Rational Technical Support for assistance.

The syntax and examples of both commands are shown below for ClearQuest 2002, 2003 and ClearQuest 7.
Note: Not all databases and database versions are supported by all ClearQuest versions.

To unlock a user database:

1. Use a ClearQuest command line utility to unlock the database.
2. The installutil unlockschemarepo command is used to unlock a ClearQuest Schema Repository.
3. The installutil unlockuserdb command is used to unlock a ClearQuest user database.
4. To unlock the user database using a ClearQuest command line utility, follow these directions:
5. Open a command prompt window and type the following command:
   
installutil unlockuserdb dbvendor server db dbologin dbopassword connectoptions

   
   To see the required parameters for the command, enter only the following at a command prompt:
   
installutil unlockschemarepo

   OR
   
installutil unlockuserdb


---

Parameter Description

Installutil Parameter	Description
unlockuserdb	Command to unlock a user database. (The remainder of the parameters remain the same for all the commands referenced in this technote).
dbvendor	The database vendor name. Available choices are MS_ACCESS, SQL_ANYWHERE, SQL_SERVER, ORACLE, DB2. Note: Vendor names must be capitalized.
server	hostname for the database server for MS Access - not used for DB2 - machine host name (database alias name if using CQ 2003.06.16 and earlier) for Oracle - machine host name for SQL Anywhere - service name for SQL Server - machine host name of the SQL Server
db	database name for MS Access - \\full\path\to\file.mdb for DB2 - database name containing your user db for Oracle - Oracle SID (SQL*Net Alias for CQ 2003.06.12 and earlier) for SQL Anywhere - \\full\path\to\file.db for SQL Server - database name containing your user db
dbologin	The database owner user log-in.
dbopassword	The database owner password.
connect_options	Optional parameters that vary by vendor. (Refer to the latest ClearQuest Documentation Supplement for details on use of the vendor connect options).

---

Sample commands to unlock an Oracle database

Sample command for ClearQuest versions 2003.06.13 and later that use Oracle with the CLOB datatype:

installutil unlockuserdb ORACLE host_name SID dbologin dbopassword  "LOB_TYPE=CLOB"

Sample command for ClearQuest versions 2003.x and earlier that use Oracle with the Long datatype:

installutil unlockuserdb ORACLE host_name SID dbologin dbopassword "HOST=abc;SID=Oracle;SERVER_VER=8.1,CLIENT_VER=8.1;LOB_TYPE=long"

Note: Parameters do not have to be in quotation marks, unless a parameter is empty, in which case an empty set of double quotation marks ("") should be used as a place holder. Database vendor names must be capitalized.

---

Sample commands to unlock a Microsoft SQL Server database:

Sample command for ClearQuest databases that use Microsoft SQL Server:

installutil unlockuserdb SQL_SERVER host_name database_name dbologin dbopassword  ""

Note: The last argument is the connection options, which for SQL Server could be a port change. The dbologin and dbopassword are the username and password used by ClearQuest to login to the user database defined by the alias or database name. They are not necessarily dbo usernames.

---

Sample commands to unlock an IBM DB2 database:

Sample command for ClearQuest versions 7.0.x and later that use DB2:

installutil unlockuserdb DB2 host_name database_name dbologin dbopassword ""

Sample command for ClearQuest versions 2003.06.16 and earlier that use DB2:

installutil unlockuserdb DB2 alias "" dbologin dbopassword ""

Note: The last argument is the connection options, which for DB2 could be a port change. The dbologin and dbopassword are the username and password ClearQuest uses to log into the user database defined by the alias or database name. They are not necessarily dbo usernames.

---

Sample commands to unlock a SQL Anywhere database:

Sample command for ClearQuest versions 2003.06.00 through 2003.06.15 that use SQL Anywhere version 8:

installutil unlockuserdb SQL_ANYWHERE service_name C:\SybSQLA\sampl.db admin admin SERVER_VER=8.0

The dbo username and dbo password is the account for the Sybase database's database administrator, not the Microsoft Windows account service user.

---

Sample commands to unlock a Microsoft Access database:

Sample command for ClearQuest databases that use Microsoft Access:

installutil unlockuserdb MS_ACCESS "" c:\temp\sampl.mdb "" "" ""

Note: Parameters do not have to be in quotation marks, unless a parameter is empty, in which case an empty set of double quotation marks ("") should be used as a place holder. Database vendor names must be capitalized.

Additional Information: BACKING UP FILES

Always make new database back-ups of your schema repository and user databases prior to making schema changes and performing database upgrades. Failure to create back-up copies can limit your ability to recover from a an upgrade failure, design change issues or other unforeseen failures.

If a backup was not taken before the upgrade and the upgrade fails, you might be able to recover by manually unlocking the database and retrying the upgrade. There are three possible outcomes of this process:

1. The upgrade will succeed and your database will be upgraded successfully.
2. The upgrade will fail because the data has already been partially upgraded.
3. The upgrade will appear to succeed but not all the schema changes will be applied to the user database.

Important notes regarding the upgrading for your user databases:

• Before upgrading a database, make sure no users are connected to it. ClearQuest prevents new users from connecting to a database while you are upgrading it, but does not disconnect users who are connected before you begin the upgrade.
• Always upgrade a test database to the latest schema version before changing your production database. You should also test your changes by using the ClearQuest client, especially if you have modified hook code.
• You cannot roll back a database after you have upgraded it with a newer schema version. To protect your database, you should back up the database before upgrading it.
  

Note: ClearQuest does not provide a mechanism to back up databases. Check your database vendor documentation for details on how to backup your database.