Running the database connection validation utility

If you encounter errors when a WebSphere Commerce utility or process that involves database-related operations runs, use the database connection validation utility to ensure that a database connection established. By default, this validation utility runs as part of the process for some utilities and processes. You can run this utility by itself to validate that a database connection can be properly established with the parameters that are configured for your WebSphere Commerce instance.

About this task

The database connection validation utility retrieves parameters from WebSphere Commerce configuration files to test and validate the connection. The configuration files, which this utility retrieves data from, includes the wc-server.xml and createInstance.properties files. The utility tests the primary connection, which is obtained from the input JDBC URL. The utility also tests the connection through the alldbconnector utility. For more information about the alldbconnector utility, see Connection acquisition for utilities and Ant tasks.

If the primary connection fails, a build exception occurs and the utility constructs a secondary connection to validate. If the secondary connection fails, the utility swallows the exception and outputs an error code within the generated log file. The utility retrieves the information about the primary connection from the input JDBC URL, and retrieves the information for the secondary connection from the database input parameters. For example, if the database is DB2 and the input JDBC URL is a type 4 connection, the utility constructs a type 2 JDBC URL to test and validate a secondary connection.

The database validation connection utility supports all WebSphere Commerce configurations. You can run the utility to validate the following database connections:

Embedded. WebSphere Commerce supports only embedded connections. This utility also tests the Network Client, and ignores any class not found exception
Type 2 and Type 4 connections
Thin and Thick client connections
Native and Toolbox connections

For more information about the tool and the files that the tool retrieves data from, see Database connection validation

Note: You can test the database connection for WebSphere Commerce utilities with parameters and information that is not included within the WebSphere Commerce configuration files. You can overwrite the values for the parameters within the <wcsDbValidation> tag in a configuration file. To overwrite the parameters, you must use a semi-colon, (;), to separate the values. For example, if your database name does not change, you can replace the ${dbName} parameter in the tag to hardcode your database name, such as WCS. If any parameters are missing from the configuration files, the tool attempts to retrieve the missing parameter information from the JDBC URL.

Procedure

Optional: Construct other possible JDBC URLs to test and validate with the database connection validation tool.
If you want to test a particular JDBC URL, you can update the databaseValidation.xml file. This file contains information for the database connection validation tool. This file can be found within the following directory:
- WC_installdir/components/common/xml
- WC_installdir\components/common/xml
- WCDE_installdir\components/common/xml
The validation tool retrieves information for testing and validating database connections from this file. You can modify the ${jdbcURL} parameter within the file to set a specific URL.
Optional: Override any parameters within the databaseValidation.xml file to overwrite parameters that are used to test the database connection.
1. Go to the following directory:
  - WC_installdir/components/common/xml
  - WC_installdir\components/common/xml
  - WCDE_installdir\components/common/xml
2. Open the databaseValidation.xml file for editing. The file contains information for the database connection validation utility. This file can be found within the following directory
3. Search for the following code:
```
<WcsDbValidation validation="3" 
newinstance="false"
propList="wcUserInstallDir[;]instanceName[;]dbUserName[;]dbUserPassword[;]schemaName[;]dbType[;]
          jdbcDriver[;]jdbcURL[;]dbName[;]dbaName[;]dbaPassword[;]loggerconfigfile[;]errordirectory"
valueList="${WCUserInstallDir}[;]${instanceName}[;]${dbUserName}[;]${dbUserPassword}[;]
           ${schemaName}[;]${dbType}[;]${jdbcDriver}[;]${jdbcURL}[;]${dbName}[;]${dbaName}[;]${dbaPassword}[;]
           ${loggerconfigfile}[;]${errordirectory}" />
```
4. Edit the code to change the properties within the propList element and the corresponding values within the valueList element.
5. Save and close the file.
Optional: Change the log level for the tool to configure the level of information that is included within the generated log files when the tool runs.
Change the value for the log level within the validation element. The log level value can be set to the following values:

0

The lowest level of information. Only basic system information and database parameters are included. No connection validation occurs.

1

Level 0 information is included with more system information, which includes the Java class path. Validation of the primary database connection occurs from the input JDBC URL.

2

Level 1 information is included with more system information, which includes the memory heap size. Validation of the primary connection occurs. If the primary connection fails, the secondary database connection occurs.

3

Level 2 information is included. If the newinstance element is set to true, the WebSphere Commerce schema level is included within the log information.
In a command-line utility, go to the following directory:
- WC_installdir/bin
- WC_installdir\bin
- WCDE_installdir\bin
Run the wcsDbValidation command:
- wcsDbValidation.sh instance_name
- wcsDbValidation instance_name
- wcsDbValidation

Results

The results of the connection validation test are included with the log file for the validation tool when the tool runs by itself. If the tool runs when during the process of another WebSphere Commerce utility or process, the results are included within the log file of the caller utility. When you run the utility by iteself, a wcsDbValidation.log log file generates. If you specify your instance name when you run the utility, the instance name is included in the log file name with the format wcsDbValidation-instance_name.log. The log file for the database connection validation tool can be found within the following directory:

WC_installdir/instances/instance_name/logs
WC_installdir\instances\instance_name\logs
WCDE_installdir\logs
WC_installdir/logs