Troubleshooting
Problem
Attempts to use an IBM Rational ClearQuest user database after a database copy or a failed upgrade is performed results in the error "Access to this database is currently denied. The database is locked while upgrading the application.".
Symptom
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.
Cause
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.
Resolving The Problem
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
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
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:
- Use a ClearQuest command line utility to unlock the database.
- The
installutil unlockschemarepo
command is used to unlock a ClearQuest Schema Repository. - The
installutil unlockuserdb
command is used to unlock a ClearQuest user database. - To unlock the user database using a ClearQuest command line utility, follow these directions:
- 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: |
|
Sample command for ClearQuest versions 2003.x and earlier that use Oracle with the Long datatype: |
|
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: |
|
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: |
|
Sample command for ClearQuest versions 2003.06.16 and earlier that use DB2: |
|
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: |
"" 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.
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:
- The upgrade will succeed and your database will be upgraded successfully.
- The upgrade will fail because the data has already been partially upgraded.
- 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.
Was this topic helpful?
Document Information
Modified date:
16 June 2018
UID
swg21133810