Setting up the CHA

Setting up the CHA involves setting up the CHA server and configuring the application to use the CHA. Setting up the CHA server create the CHAInstance, CHAChildren and CHAControl tables used by the server and deploys the server in WebSphere(R) Application Server. CHA server can work with any one of the three famous Database: DB2(R) v7.2 or v8.1.4 or above, Oracle 8i or 9i, and SQLServer2000.

To set up the CHA server, do the following:
  1. Locate the createCHATable.ddl script file for the operating system and database management system you are using for the database. You can find the scripts under the Branch Transformation Toolkit installation directory in the following path:
    \dbtools\<op_system>\<DBMS>\tableDefinition\cha
    For <op_system>, look in the directory that matches the operating system category on which the database is installed. The directories are:
    • Unix (for AIX(R) , Linux(R) on Intel(R) and zSeries(R) , and Sun Solaris)
    • Windows(R) (for Microsoft(R) Windows 2000, Windows XP and Microsoft Windows 2003)
    • z/OS(R)
    For <DBMS>, look in the directory that matches the database management system that is operating the database. The directories are :
    • DB2
    • SQLServer2000
    • Oracle
  2. Edit the createCHATables.ddl file and customize the size of the CONTEXT field in the CHAInstance table as needed. For Oracle and SQLServer 2000, there is no need to adjust the size of CONTEXT field.
  3. Create the database tables for the CHA.
    • For DB2 on z/OS:
      1. Logon to the z/OS terminal utility.
      2. Go to DB2 admin tools. Select version 8 of DB2.

        Screen capture showing the version 8 of DB2 is selected

      3. Select Option 2 Execute SQL statements. Press Enter.Screen capture of the DB2 Administration menu
      4. Select Option 1 Execute SQL statements from screen input. Press Enter.Screen capture showing the Execute SQL Statements menu
      5. Copy and paste all SQL statements in createCHATables.ddl to screen and execute the SQL statements.Screen capture showing the statements in createCHATables.ddl copied
    • For DB2 on the platforms except z/OS:
      1. From a DB2 command line prompt, use the cd command to go to the directory containing the createCHATables.ddl file you just edited.
      2. Connect to the database in which you want to create CHA tables. For example, if you want to create the tables in the sample database, use the following command:
        db2 connect to sample user username using password
      3. Create the tables using the following command:
        db2 -tvf createCHATables.ddl
    • For Oracle:
      1. In a sqlplus_command_line, use the cd command to go to the directory containing the createCHATables.ddl file you edited.
      2. Connect to the database in which you want to create CHA tables. For example, if you want to create the tables in the sample database, use the following command:
        sqlplus> connect userid/password@sample
      3. Create the tables using the following command:
        sqlplus> start createCHATables.ddl
    • For SQL Server:
      1. Open the SQL Server Enterprise Manager.
      2. In the Enterprise Manager, select Tools > SQL_Query_Analyzer.
      3. In the toolbar, select the database in which you want to create the CHA tables.
      4. Open the createCHATables.ddl file you edited.
      5. Copy the contents of the createCHATables.ddl file into the Query window.
      6. In the toolbar, click Execute Query.
  4. Deploy the BTTCHA.ear into WebSphere Application Server. The deployment settings vary according to the different databases.
    • For DB2 on z/OS:
      1. From the WebSphere Application Server Administration Console, select Security > JAAS Configuration > J2C Authentication Data.
      2. Fill in the username and password for accessing DB2. This creates the J2C Authentication Data Entry for DB2.
        • From the WebSphere Application Server Administration Console, select Resources > JDBC Providers to create a new a DB2 universal JDBC provider (XA).
      3. Restart the WebSphere Application Server.
      4. Create a Data Source for the JDBC provider and fill in the following properties:
        • JNDI Name: the default value is jdbc/CHADataSource
        • Container managed persistence: select the check box
        Settings for JNDI Name and Container managed persistence
        • Component-managed Authentication Alias: choose the Authentication Alias created in step 4.a.
        • Container-managed Authentication Alias: choose the Authentication Alias created in step 4.a.
        Settings for Component-managed Authentication Alias
      5. Specify properties for the Data Source. Driver type use driver 4. currentSQLID use schema name. For other properties, please refer z/OS system configuration.
      6. From the WebSphere Application Server Administration Console, install BTTCHAEAR.ear.
        Note: Select DB2UDBOS390_V8_1 as the database type and fill in JDNI Name field with jdbc/CHADataSource.
      7. From the WebSphere Application Server Administration Console, start the CHA server. If the WebSphere log file, SystemOut.log, has no any error message, the CHA server starts successfully.
    • For DB2 on the platforms except z/OS:
      1. From the WebSphere Application Server Administration Console, select Security > JAAS Configuration > J2C Authentication Data .
      2. Fill in the username and password for accessing DB2. This creates the J2C Authentication Data Entry for DB2.
      3. From the WebSphere Application Server Administration Console, select Resources > JDBC Providers to create a new user-defined JDBC provider using the following necessary parameters:
        • Classpath: ${DB2_JDBC_DRIVER_PATH}/db2java.zip
        • Implementation Class: COM.ibm.db2.jdbc.DB2XADataSource
        • The environment variable DB2_JDBC_DRIVER_PATH must have a correct value.
      4. Restart the WebSphere Application Server.
      5. Create a Data Source for the JDBC provider and fill in the following properties:
        • JNDI Name: the default value is jdbc/CHADataSource
        • Container managed persistence: select the check box
        Settings for JNDI Name and Container managed persistence
        • Component-managed Authentication Alias: choose the Authentication Alias created in step 4.a
        • Container-managed Authentication Alias: choose the Authentication Alias created in step 4.a
        Settings for Component-managed Authentication Alias
      6. Specify databaseName for the Data Source. Use default values for other properties.Specify databaseName for the Data SourceSpecify databaseName for the Data Source
      7. From the WebSphere Application Server Administration Console, install BTTCHAEAR.ear.
        Note: Select DB2UDBNT V8.1 as the database type and fill in JDNI Name field with jdbc/CHADataSource.
      8. From the WebSphere Application Server Administration Console, start the CHA server. If the WebSphere log file, SystemOut.log, has no any error message, the CHA server starts successfully.
    • For Oracle:
      1. Use WebSphere Studio Application Developer to do the EJB to RDB Mapping:
        1. Import BTTCHAEAR.ear file into your WebSphere Studio Application Developer.
        2. Right-click the BTTCHAEJB EJB project, and select Generate > EJB to RDB Mapping. When a dialog box pops up, click next.
        3. In the next dialog box, select Meet in The Middle and click Next.
        4. Fill in the information needed to establish a JDBC connection, and click Next

          Screen capture of the Establish a JDBC connection dialog box

        5. Select the table for import, and click Next.
        6. Select the Match By Name, and Type option and click Finish.
        7. The WebSphere Studio Application Developer workspace will look like the following screen capture:

          Screen capture of the WebSphere Studio Application Developer

        8. From the workspace, drag CHAInstance from Tables View to CHAInstanceForRoot in Enterprise Beans View.
        9. From the workspace, drag CHAInstance from Tables View to CHAInstanceForSession in Enterprise Beans View.
        10. From the workspace, double-click the MYDB1_SCOTT_CHAINSTANCE.tblxmi file to open it. Change the data type of ISROOT column from NUMBER to SAMLLINT.
        11. Likewise, double-click the MYDB1_SCOTT_CHACONTROL.tblxmi file to open it. Change the data type of HASCTXTREEcolumn from NUMBER to SAMLLINT.
        12. Save all the modifications.
        13. Export the workspace as BTTCHAEAR.ear.
      2. From the WebSphere Application Server Administration Console, select Security > JAAS Configuration > J2C Authentication Data.
      3. Fill in the username and password for accessing the Oracle database. This creates the J2C Authentication Data Entry for Oracle databases.
      4. From the WebSphere Application Server Administration Console, select Resources > JDBC Providers to create a new JDBC provider by selecting Oracle JDBC Driver (XA).
      5. Create a Data Source for the JDBC provider and fill in the following properties:
        • JNDI Name: the default value is jdbc/CHADataSourc
        • Container managed persistence: select the check box
        Settings for JNDI Name and Container managed persistence
        • Component-managed Authentication Alias: choose the Authentication Alias created in step 4.b
        • Container-managed Authentication Alias: choose the Authentication Alias created in step 4.b
        Settings for Component-managed Authentication Alias
      6. Specify URL and driverType for the Custom Properties for the Data Source. Use default values for other properties.

        Screen capture of the Custom Properties

      7. From the WebSphere Application Server Administration Console, install BTTCHAEAR.ear.
        Note: Select ORACLE V8.1 as the database type and fill in JDNI Name field with jdbc/CHADataSource and choose to use default bindings.
      8. From the WebSphere Application Server Administration Console, start the CHA server. If the WebSphere log file, SystemOut.log, has no any error message, the CHA server starts successfully.
    • For SQL Server:
      1. Visit ftp://ftp.software.ibm.com/software/websphere/info/tools/DataDirect/datadirect.htm to download a Connect 3.3 driver. Do the following to install the driver:
        1. Open the ConnectJDBC33-JTA.zip file, which is part of the JDBC driver you downloaded.
        2. Copy the sqljdbc.dll file from the zip file to the <SQL Server root>/binn directory. For example, C:\Program Files\Microsoft SQL Server\MSSQL\Binn
        3. Use the ISQL utility to run the instjdbc.sql script from the zip file. The DOS prompt syntax for doing so is:
          >ISQL -U sa -P sa_password -S server_name -i location\instjdbc.sql
          .
          sa is the SQL Server system administrator user ID, sa_password is the password for the system administrator, server_name is the name of the server on which the SQL Server is running, and location is the full path to the instjdbc.sql script. For example,
          >ISQL -U sa -P mypasswd -S Ojai -i c:\instjdbc.sql
          Note: The instjdbc.sql script generates many messages. These messages should be benign and can be ignored in most cases, but you should review the output for any messages that indicate an installation/execution error. The last message should indicate that instjdbc.sql ran successfully.
      2. Start the SQL Server Distributed Transaction Coordinator. After you start the Distributed Transaction Coordinator you'll see the icon in front of the Distributed Transaction Coordinator in the SQL Server Enterprise Server Manager.

        Screen capture showing the SQL Server Distributed Transaction Coordinator started

      3. From the WebSphere Application Server Administration Console, select Security > JAAS Configuration > J2C Authentication Data.
      4. Fill in the username and password for accessing the SQL database. This creates the J2C Authentication Data Entry for SQL databases.
      5. From the WebSphere Application Server Administration Console, select Resources > JDBC Providers to create a new JDBC provider by selecting WebSphere embedded ConnectJDBC driver for MS SQL Server (XA).
      6. Create a Data Source for the JDBC provider and fill in the following properties:
        • JNDI Name: the default value is jdbc/CHADataSourc
        • Container managed persistence: select the check box
        Settings for JNDI Name and Container managed persistence
        • Component-managed Authentication Alias: choose the Authentication Alias created in step 4.c
        • Container-managed Authentication Alias: choose the Authentication Alias created in step 4.c
        Settings for Component-managed Authentication Alias
      7. Specify the following Custom Properties for the Data Source:
        • databaseName
        • serverName
        • portNumber
        • selectMethod

        Screen capture of the Custom Properties

        Use default values for other properties.
      8. From the WebSphere Application Server Administration Console, install BTTCHAEAR.ear.
        Note: Select MSSQLSERVER_2000 as the database type and fill in JDNI Name field with jdbc/CHADataSource.
      9. From the WebSphere Application Server Administration Console, start the CHA server. If the WebSphere log file, SystemOut.log, has no any error message, the CHA server starts successfully.

An application must contain the CHA facade and other related classes contained in the BTTBase.jar and be configured so that the CHA facade can find the CHA server before it can use the CHA.

To set up an application to use the CHA, edit the system configuration files (dse.ini) for the client and server side of the CHA to configure the following settings:

<kColl id="settings">
  ...
  <kColl id="cha-server">
       <field id="ejbInitialContextFactory" 
					value="com.ibm.websphere.naming.WsnInitialContextFactory"/>
	     <field id="rootLocation" value="iiop://zhpf:2809"/>
	     <field id="myLocation" value="iiop://zhpf:2809"/>

	     <field id="CHASessionHome" 
					value="ejb/com/ibm/btt/cha/ejb/CHASessionHome"/>
	     <field id="CHASessionLocalHome" 
					value="java:comp/env/ejb/CHASession"/>

	     <field id="CHAInstanceHome" 
					value="ejb/com/ibm/btt/cha/ejb/CHAInstanceHome"/>
	     <field id="CHAInstanceLocalHome" 
					value="java:comp/env/ejb/CHAInstance"/>
	     <field id="CHAInstanceForRootLocalHome" 
					value="java:comp/env/ejb/CHAInstanceForRoot"/>
	     <field id="CHAInstanceForSessionLocalHome" 
					value="java:comp/env/ejb/CHAInstanceForSession"/>

	     <field id="CHAControlLocalHome" 
					value="java:comp/env/ejb/CHAControl"/>
	     <field id="InitContextTreeLocalHome" 
					value="java:comp/env/ejb/InitContextTree"/>
	     <field id="CHAChildrenLocalHome" 
					value="java:comp/env/ejb/CHAChildren"/>

	     <field id="initTailContextName" value="branchServer"/>

	     <field id="cleanupCHAServer" value="true"/>

	     <field id="isLocalCall" value="false"/>	

	     <field id="supportMultipleCHAServers" value="false"/>
  </kColl>
  ...
</kColl>

If a servlet or EJB calls the CHA facade and they are in the same EAR file as the CHA server, the facade can use the local EJB interface. To set up the CHA facade to use the local interface to access the CHA EJBs:

  1. In the dse.ini file, set the value of isLocalCall to true.
  2. In the servlet or EJB that calls the CHA, establish the EJB local reference for the CHAInstance and CHASession EJBs.

If the servlet or EJB are not in the same EAR file as the CHA server, the facade must use the remote EJB interface. To set up the CHA facade to use the remote interface, set the value of isLocalCall to false in the client side dse.ini file

Related reference
CHAInstance database schema
Default createCHATables.ddl contents