Troubleshooting WebSphere Commerce instance creation with DB2

Technote (troubleshooting)


Problem(Abstract)

You are looking for troubleshooting information when creating IBM WebSphere Commerce Version V5.6.1 instances on AIX, Solaris, and Linux using the DB2 Universal Database. This technote contains the following sections:

- Collecting logs and DB2 settings
- Instance creation prerequisites
- Enabling tracing
- Recreating the WebSphere Commerce instance
- DB2 command reference
- Additional technotes on instance creation

Symptom

If you are going to create a new WebSphere Commerce instance, review the "Collecting logs and DB2 settings" and "Instance creation prerequisites" sections to ensure that no errors occurred during instance creation.

If instance creation failed, review the "Collecting logs and DB2 settings" and
"Instance creation prerequisites" sections. If you can identify the problem, follow the steps under "Recreating the WebSphere Commerce instance" to recreate the instance.

If you are unable to identify the problem, review the "Additional technotes on instance creation" section and enable tracing as described in "Enabling tracing". Then recreate the instance following the instructions in "Recreating the WebSphere Commerce instance".

For more information about instance creation, refer to the "Creating a new WebSphere Commerce instance" section in the WebSphere Commerce installation guides for AIX, Solaris, and Linux, and the Configuration Manager documentation in the Information Center.

IBM WebSphere Commerce Installation Guide for AIX and Solaris Operating System

IBM WebSphere Commerce Installation Guide for Linux


Resolving the problem

Collecting logs and DB2 settings

If instance creation failed, collect and review the following logs. These logs will be requested by the WebSphere Commerce Support Analyst if you require assistance.

1. Logs found in the WC_installdir/instances/instance_name/logs directory:

Log name Purpose
reorg.db2_timestap.log Database population - db2 reorg table all
auction.log Used for auctions
createdb.db2.log Database creation
createsp.db2_timestap.log Stored procedures creation
createsp.db2.error_timestap.log Stored procedures creation - error log
schemacreation_db2_timestap.log Schema creation
schemacreation2_db2_timestamp.log Schema creation
schemacreation_fpX_db2_timestamp.log Schema creation for Fix Pack
populatedbnl.log Database population
populatedbnl.err.log Database population - error log
trace.txt Database population - generated by massloader
messages.txt Database population - generated by massloader
WASConfig.log WebSphere Application Server instance deployment
WASConfig.err.log WebSphere Application Server instance deployment - error log
GenPluginCfg.log WebSphere Application Server plug-in update
instancesUpdate.log Creates instance XML file
EnterpriseApp.log Updates EAR metadata
sec_check.log Security check

The size for all the error logs (the ones which contain "err" on the name) should be zero.

2. Logs found in WC_installdir/instances directory:

WC_installdir/instances/WCSconfig_timestamp.log
WC_installdir/instances/WCSconfig.log

3. Errors displayed on the config_server.sh terminal window.
4. Errors displayed on the config_client.sh terminal window.
5. Screen capture of the Configuration Manager client window showing the error.
6. Use the wcsupport.sh tool to gather information on your system configuration (available with WebSphere Commerce V5.6.0.2 and higher).
7. If you enabled tracing for WebSphere Application Server, the trace.log file.

Also collect information on your system environment by calling the following commands using the WebSphere Commerce non-root user (the user you must use to start the Configuration Manager client and server).

DB2 commands
    • db2ilist -a
    • db2level
    • db2set
    • db2 list node directory show detail
    • db2 list database directory show detail
    • db2 get database manager configuration
    • db2 list applications

AIX, Solaris, and Linux commands
    • set
    • nslookup `hostname`
    • df -k
    • ulimit -a

Redirect the output of all the commands to a file so they can be reviewed by a WebSphere Commerce Support Analyst.

Instance creation prerequisites

For more information about instance creation prerequisites, refer to the WebSphere Commerce Installation Guide.
  1. The database version on both the client and the server must be officially supported by WebSphere Commerce. WebSphere Commerce V5.6 is delivered with DB2 V8.1 Fix Pack 5. WebSphere Commerce V5.6.1 is delivered with DB2 V8.2 Fix Pack 1.

    For the list of supported configurations, follow these links:

    WebSphere Commerce V5.6.1

  2. The system has a resolvable domain name. Use the nslookup fully_qualified_host_name and nslookup ipaddress commands to verify if the domain name and IP address are resolved.
  3. There is at least 1 GB available under the tmp folder and 1 GB on the file system where WebSphere Commerce is installed. When an instance creation fails, the most likely cause, when populating the database or deploying the WebSphere Commerce application (EAR) to the WebSphere Application Server, is insufficient disk space.
  4. The stack quota limit is at least 32768. To check the current limit, type the following in a command window: ulimit -a
  5. The database user used during instance creation is the owner of the client or server instance. The sqllib directory must exist under the database user home directory.
  6. The DB2 environment for the WebSphere Commerce non-root user and the database user has been set. You can execute DB2 commands from the terminal window. The user profile for the non-root user was modified during the WebSphere Commerce installation to include that of the database user.
  7. The Java™ Database Connectivity (JDBC) driver is in the CLASSPATH and the file exists and has the correct permissions:
    1. Log in as the non-root user.
    2. Move to the WebSphere Commerce bin directory. For example:
      cd /usr/WebSphere/CommerceServer56/bin
    3. Call the following command: . ./config_env.sh
    4. Echo the DB2 JDBC driver: echo $DB2_DRIVER
    5. Ensure that the driver exists and it is readable.
  8. The database user belongs to the database administrators group.


Local databases
    1. The server instance is using 32 bits. You can use the db2ilist -a command to verify it.
    2. The local node is cataloged on the system.
    If you are creating a new local database, the database administrator user and the database schema user must be the same. You must use the same user on the Database and Schema panels of the Configuration Manager.

    If you are using an existing local database:
    1. You need to create a remote alias for the database and use the alias instead on the Configuration Manager client:
      1. Create a remote alias for the local database. You can use db2 catalog database dbname as dbalias at node nodename to create the alias.
      2. Use the db2 list database directory show detail command to ensure that the alias has been cataloged.
      3. Attempt to connect to the database using the alias with the following command:
        db2 connect to aliasdbname user dbusernameusing db2userpwd
        (Using a remote alias forces the need for a user and password on the connect command.)
    2. The code set for the database must be UTF8. Use the db2 get database configuration for the database command to verify it.
    3. If you use an existing database, a window will open in the Configuration Manager client asking if you want to populate the database. If the database is empty, you must select yes; if the database has been previously populated, you must select no. If the database contains WebSphere Commerce data but you select yes, the instance creation will fail. It will also fail if the database is empty and you select no.
    4. On the existing database, the following table spaces need to preexist, otherwise the Configuration Manager client will fail to create the schema: TAB8K, TAB16K, Temporary Tablespace TEMPSYS8K, Temporary Tablespace TEMPSYS16K, Temporary Tablespace TEMPSYS32K
    5. The Configuration Manager client uses the following script to create the database:

      db2 -v create database $database using codeset utf-8 territory us
      db2 -v connect to $database user $user using $password
      db2 -v alter bufferpool ibmdefaultbp deferred size 10000
      db2 -v create bufferpool buff8k deferred size 5000 pagesize 8 k
      db2 -v create bufferpool buff16k deferred size 5000 pagesize 16 k
      db2 -v create bufferpool buff32k deferred size 2500 pagesize 32 k
      db2 -v connect reset
      db2 -v connect to $database user $user using $password
      db2 -v "create regular tablespace tab8k pagesize 8 k managed by system using ('tab8k') bufferpool buff8k"
      db2 -v "create regular tablespace tab16k pagesize 16 k managed by system using ('tab16k') bufferpool buff16k"
      db2 -v "create  system temporary  tablespace tempsys8k pagesize 8 k  managed by system  using ('tempsys8k') bufferpool buff8k"
      db2 -v "create  system temporary  tablespace tempsys16k pagesize 16 k  managed by system  using ('tempsys16k')bufferpool buff16k"
      db2 -v "create  system temporary  tablespace tempsys32k pagesize 32 k  managed by system  using ('tempsys32k')bufferpool buff32k"
      db2 -v connect reset
    6. This table contains the default DB2 parameters set by the updateDB2Configuration.sh script. These parameters provide a good starting point for your database, but you will have to tune the configuration for your application if you are installing a production environment.
      applheapsz 1000
      stmtheap 60000
      app_ctl_heap_sz 8192
      locklist 2400
      indexrec RESTART
      logfilsiz 1000
      logprimary 12
      logsecond 10
      pckcachesz 4096
      catalogcache_sz 4096
      cpuspeed (dbm) -1
      DB2BIDI (db2set) YES

Remote databases
    1. The database user ID exists on both the WebSphere Commerce and the database machines. The user has the same password on both systems.
    2. The database administration client is installed on the WebSphere Commerce machine and it is at the same level as the database server. For example, both are DB2 V8.1.0.48.
    3. Client instance is using 32 bits. It is acceptable to have a DB2 server instance on 64 bits and a client on 32 bits. Use the db2ilist -a command to verify your current instance.
      If your server instance is on 64 bits, you need to apply WebSphere Commerce V5.6 Fix Pack 2 or higher. Ensure to complete the "Creating 64-bit stored procedures on a remote DB2 database" section from the WebSphere Commerce V5.6 Fix Pack Installation Guide.
    4. There is a client instance created for the database user (the sqllib directory must exist under the database user home directory).
    5. You can attach to the remote system using both the database user and the WebSphere Commerce non-root user:
      db2 catalog tcpip node nodename remote host name server portnumber  (default port number is 50000)
      db2 attach to
      nodename user username using userpwd
      db2 detach
    If you are creating a new remote database:
      1. The database administrator user and the database schema user must be the same. You must use the same user on the Database and Schema panels on the Configuration Manager.
      2. The database user on the database machine is part of the database administrators group.
      The Configuration Manager client will prompt for host name, node name, and port number. Even though it is not required, it is a good practice to manually catalog the remote node beforehand, to ensure that the connection between the WebSphere Commerce machine and the database machine is working. In order to test the connection:
        1. Use the db2 catalog tcpip node command to catalog database node
        2. Attach to the remote node by using the following command:
          db2 attach to nodename user username using userpwd.
          db2 detach

    If you are using an existing remote database:
      1. The database is cataloged on the WebSphere Commerce machine. The Configuration Manager client will not prompt for the remote database parameters (node name, host name, and port number).
        1. Use the db2 list node directory show detail command to ensure that the database node has been cataloged.
        2. Use the db2 list database directory show detail command to ensure that the remote database has been cataloged.
        3. Attempt to connect to the remote database using the following command:
          db2 connect to dbname user dbusername using dbuserpwd
          db2 connect reset
      2. The code set for the database must be UTF8. Use the DB2 get database configuration for the database command to verify it.
      3. If you select the option to use an existing remote database, a window will open in the Configuration Manager client asking if you want to populate the database. If the database is empty, you must select yes; if the database has been previously populated, you must select no. If the database contains WebSphere Commerce data but you select yes, the instance creation will fail. It will also fail if the database is empty and you select no.
      4. On the existing database, the following table spaces need to preexist, otherwise the Configuration Manager client will fail to create the schema: TAB8K, TAB16K, Temporary Tablespace TEMPSYS8K, Temporary Tablespace TEMPSYS16K, Temporary Tablespace TEMPSYS32K
      5. The Configuration Manager client uses the following script to create the database:

        db2 -v create database $database using codeset utf-8 territory us
        db2 -v connect to $database user $user using $password
        db2 -v alter bufferpool ibmdefaultbp deferred size 10000
        db2 -v create bufferpool buff8k deferred size 5000 pagesize 8 k
        db2 -v create bufferpool buff16k deferred size 5000 pagesize 16 k
        db2 -v create bufferpool buff32k deferred size 2500 pagesize 32 k
        db2 -v connect reset
        db2 -v connect to $database user $user using $password
        db2 -v "create regular tablespace tab8k pagesize 8 k managed by system using ('tab8k') bufferpool buff8k"
        db2 -v "create regular tablespace tab16k pagesize 16 k managed by system using ('tab16k') bufferpool buff16k"
        db2 -v "create  system temporary  tablespace tempsys8k pagesize 8 k  managed by system  using ('tempsys8k') bufferpool buff8k"
        db2 -v "create  system temporary  tablespace tempsys16k pagesize 16 k  managed by system  using ('tempsys16k')bufferpool buff16k"
        db2 -v "create  system temporary  tablespace tempsys32k pagesize 32 k  managed by system  using ('tempsys32k')bufferpool buff32k"
        db2 -v connect reset
      6. This table contains the default DB2 parameters set by the updateDB2Configuration.sh script. These parameters provide a good starting point for your database, but you will have to tune the configuration for your application if you are installing a production environment.
        applheapsz 1000
        stmtheap 60000
        app_ctl_heap_sz 8192
        locklist 2400
        indexrec RESTART
        logfilsiz 1000
        logprimary 12
        logsecond 10
        pckcachesz 4096
        catalogcache_sz 4096
        cpuspeed (dbm) -1
        DB2BIDI (db2set) YES


Enabling tracing

To enable tracing for the Configuration Manager:
    1. Open the Configuration Manager client GUI
    2. Go to Settings > Log Settings.
    3. Select Log level as Debug.
    4. Click OK to close the window.

To enable tracing for database population:
    1. Back up the WC_installdir/xml/loader/WCALoggerConfig.xml file.
    2. Open the file for editing.
    3. Locate the following node: <component name="MassLoader">
    4. Under the logger type "Trace", change the message type from <messageType name="NONE"/> to <messageType name=PUBLIC"/>.
    5. Add the following nodes to the logger type "message" and "typedMessage":

      <messageType name="WARN"/>
      <messageType name="INFO"/>

    After instance creation is complete, you need to revert the changes on these two files: WC_installdir/xml/loader/WCALoggerConfig.xml and WC_installdir/instances/ instance_name/xml/loader/WCALoggerConfig.xml.

Tracing for WebSphere Application Server
    You can enable tracing for the WebSphere Application Server if instance creation fails during the "Configuring WebSphere Application Server for WebSphere Commerce" phase.
    1. Back up the config_server.sh file.
    2. Edit the config_server.sh file and add the following two entries to the Java command line:
      -Dwas.trace.spec="com.ibm.*=all=enabled" \
      -Dwas.trace.file="/tmp/wastrace_log.txt" \


      Ensure that there are no spaces after the final "\".
After the problem has been resolved, remember to disable tracing as it will create unnecessary overhead on future configurations.


Recreating the WebSphere Commerce instance

Before recreating the instance, back up and delete the instance directory in the WC_installdir/instances directory. For example, if your instance is called "demo", back up and delete this directory:
WC_installdir/instances/demo

If you are creating a new local database:
  1. Drop the database and uncatalog the remote database alias.
    db2 drop database rdbname
    db2 uncatalog database
    dbname
  2. Use the following command to ensure that the database has been dropped and the alias has been uncataloged:
    db2 list database directory show detail

If you are creating a new remote database:
  1. Uncatalog the remote database alias:
    db2 uncatalog datase dbname
  2. Log in to the database system and drop the database:
    db2 drop database dbname
  3. To ensure that the database has been dropped, use the following command:
    db2 list database directory show detail

If instance creation failed while configuring the WebSphere Commerce Server or deploying WebSphere Commerce:
  1. Use the WC_installdir/bin/rmCommerceServer.sh command to remove the WebSphere Commerce Server on the WebSphere Application Server.
  2. Log in to the WebSphere Application Server console. The WebSphere Application Server console can be usually accessed on port 9090, for example, http://hostname:9090/admin. server1 must be running in order for the console to work.
  3. Ensure that the Server does not exist. On the left pane, expand Servers and select Application Servers. Ensure that a server with name WC_instance_name is not listed.

When you try to recreate the instance, if the Configuration Manager warns that the instance already exists:
  1. Open the following file: WC_installdir/instances/wcs_instances.
  2. Remove the entry for your instance under "[instance]". For example, if your instance is called "demo" remove the following line:
    demo;local=/opt/WebSphere/CommerceServer56/instances/demo/xml/demo.xml
  3. Ensure that there is no server defined on the WebSphere Application Server named WC_instance_name.


DB2 command reference

CATALOG TCPIP NODE Command

CATALOG LOCAL NODE Command

LIST NODE DIRECTORY Command

LIST DATABASE DIRECTORY Command

ATTACH Command

DETACH Command

DROP DATABASE Command

CATALOG DATABASE Command

UNCATALOG DATABASE Command

db2level - Show DB2 Service Level Command

db2ilist - List Instances Command


Additional technotes on instance creation

Instance creation fails due to missing current directory in PATH

Out of memory error occurs during instance creation

Instance creation fails due to insufficient disk space

Cross reference information
Segment Product Component Platform Version Edition
Commerce WebSphere Commerce Professional Edition Configuration AIX, i5/OS, Linux, Solaris, Windows 5.6.1 Professional Edition
Commerce WebSphere Commerce - Express Configuration i5/OS, Linux, Windows 5.6.1 Express

Rate this page:

(0 users)Average rating

Document information


More support for:

WebSphere Commerce Business Edition
Configuration

Software version:

5.6.1

Operating system(s):

AIX, Linux, OS/400, Solaris, i5/OS

Software edition:

Business Edition

Reference #:

1200714

Modified date:

2013-05-20

Translate my page

Machine Translation

Content navigation