Configuring IBM's WebSphere V7.0 With CA IDMS Server r17.0

Document ID : KB000022717
Last Modified Date : 14/02/2018
Show Technical Document Details

Introduction:

This document lists the steps needed to configure IBM's WebSphere Application Server v7.0 to work with CA IDMS Server r17. This will prepare WebSphere for support of Java-based applications that use CA IDMS.

Instructions:

In this document we will list the steps needed to configure IBM's WebSphere Application Server v7.0 to work with CA IDMS Server r17. This will prepare WebSphere for support of Java-based applications that use CA IDMS. We will be defining a Type-4 JDBC connection to a back-end IDMS CV running R16 SP2 or later.

  1. To begin, launch the WebSphere Administrative Console application. On Windows this is found here:

    Start -> Programs -> IBM WebSphere -> Application Server v7.0 -> Profiles -> servername -> Administrative console

  2. First we need to create an environment variable that will point to the CA IDMS Server installation directory. To do this, select the "WebSphere variables" item (under the Environment sub-menu as seen below) using the menu tree on the left-hand window pane.

  3. Verify that the Scope value is set properly for your WebSphere configuration. Then click "New".

    Figure 1

  4. Add the following variable (note that the Value specification below assumes you have installed CA IDMS Server in the default directory):

    • Name: IDMS_JDBC_DRIVER_PATH
    • Value: C:\Program Files\CA\CA IDMS Server\Java

  5. Click the Apply button on the bottom of the panel to save your new environment variable in the local configuration. A message will then appear in the message area at the top of the panel indicating that this change still needs to be saved to the master configuration. Click the "Save" link to do this. Note that this must also be done for all changes made in the remaining steps below.

    Figure 2

  6. Next we will create a JDBC Provider for use with CA IDMS Server. To do this, select the "JDBC providers" item under the Resources -> JDBC sub-menu.

  7. Verify the scope value and click the "New" button to create the new Provider.

    Figure 3

  8. Select the "User-Defined" database type from the drop-down list. Fill in the other fields as follows:

    Implementation class name: ca.idms.jdbc.IdmsXADataSource

    • Name: (user-defined)
    • Description: (user-defined)

  9. Click the "Next" button.

    Figure 4

  10. Enter the database class path information as follows:

    ${IDMS_JDBC_DRIVER_PATH}/classes
    ${IDMS_JDBC_DRIVER_PATH}/lib/idmsjdbc.jar

    Note the use of the IDMS_JDBC_DRIVER_PATH environment variable that we defined earlier. Also note that we've added both the "classes" directory and the idmsjdbc.jar file (within the "lib" directory) to our class path. The "classes" directory contains the caidms.properties file, which can be used to tailor the CA IDMS Server JDBC driver's behavior (to turn on tracing for example). Once you've entered the information click the "Next" button on the bottom.

    Figure 5

  11. You will be presented with a summary screen listing the properties for the new JDBC Provider. Verify that everything has been entered correctly and click the "Finish" button.

  12. Now we will create a JDBC data source for use with CA IDMS Server. Select the "Data sources" item under the Resources -> JDBC sub-menu. Then click the "New" button on the window to create the new data source.

    Figure 6

  13. Fill in the basic data source information panel as follows:

    • Data source name: (user-defined)
    • JNDI name: jdbc/(user-defined)

      Note that the JNDI name must begin with "jdbc/". This must also match the name you use to perform the JNDI lookup operation within your application.

  14. Click the "Next" button.

    Figure 7

  15. On the "Select JDBC Provider" panel, choose "Select an existing JDBC provider"; select the name of the CA IDMS Server Provider you specified in step #8, and click "Next".

    Figure 8

  16. On the database specific properties panel, enter the following, then click "Next".

    • Data store helper class name: com.ca.idms.was.IdmsJdbcDataStoreHelper

      Figure 9

  17. On the Setup security aliases panel, select the appropriate settings for your installation, then click the "Next" button.

  18. On the Summary panel, verify the configuration information and click "Finish".

  19. Choose the data source you just defined by clicking on the link in the Name column (in the screen image below, this is "Type 4 Connection to IDMS").

    Figure 10

  20. Under the data source General Properties heading, add a Description if you like, then click the "Connection pool properties" link on the right-hand side under "Additional Properties"

    Figure 11

  21. Modify the default connection pool settings as follows:

    • Minimum connections should be set to zero.
    • Reap time should be set to a lesser value than the default of 180.
    • Unused timeout should be set to a value significantly less than the default of 1800 (30 minutes). This is to avoid resource contention on the back-end IDMS CV.
    • Set Purge policy to "FailingConnectionOnly"

      Be sure to remember your Reap time and unused timeout settings as these will be used to determine the settings of two CA IDMS Server properties in a later step. When you are finished, click the "Apply" button.

      Figure 12

  22. You should now be positioned at the data source panel as in step #19. Once again, click the link for the data source you have just defined. Then click the "Custom properties" link under "Additional Properties".

    Figure 13

  23. WebSphere V7.0 uses Java Reflection to determine all of the property names which are supported by CA IDMS Server. On the Custom properties panel, click on each of the properties listed below to add appropriate values.
    Name                       Value databaseName               Name of IDMS dictionary that includes catalog containing application schemas and tablesexternalWait               Set to numeric value slightly higher than Unused timeout + Reap timenetworkProtocol            "IDMS"password                   Password defined to IDMSportNumber                 Set to the value specified in PORT parameter of listener PTERM in IDMSresourceInterval           Set to numeric value slightly higher than Unused timeout + Reap timeserverName                 IP address or DNS name of mainframe system running IDMSuser                       User ID defined to IDMS
    Click the "Apply" button at the bottom of the panel after you have modified each property (and click the "Save" link to save each one to the master configuration). You may delete any CA IDMS Server property which is not being used. Note that the password property is only required for secured CA IDMS systems.

    Figure 14

    Here's an example of how the Custom properties panel will look like when you finish:

    Figure 15

  24. Return to the Data source panel by choosing the "Data sources" item under the Resources -> JDBC sub-menu on the left-hand pane.

  25. Test your new data source definition from the Data sources panel by selecting its checkbox and clicking the "Test connection" button.

    Figure 16

  26. You should receive a confirmation message that the test connect was successful. If errors occur and you are certain that values have been entered correctly, restart your WebSphere instance and try again.

    Figure 17

Additional Information:

  • CA IDMS Server r17 requires Java 1.6, which is only supported by WebSphere V7.0 or later. Earlier versions of CA IDMS Server can be used with WebSphere V7.0, but this is not recommended.

  • This document was written after testing on Windows. However, the process would be the same on both Linux and UNIX with the exception of the references to the CA IDMS Server installation path.

  • If you wish to enable CA IDMS JDBC Driver tracing while using WebSphere, you can do so by modifying the options in the "caidms.properties" file (which resides in the CA IDMS Server "classes" sub-directory). The following considerations apply:

    • Uncomment the "trace", "trace.file" and "util.nojni" lines in the "caidms.properties" file.

    • Specify an appropriate location for the log file using the "trace.file" option. Any referenced directories must already exist.

    • Important... WebSphere requires that you use forward slashes in your "trace.file" path name. Ex:
      trace=truetrace.file=/temp/caidms.logutil.nojni=true
      Note that when running on Windows, you can also use the ODBC Administrator to enable tracing rather than using the caidms.properties file.

For more information on the configuration of CA IDMS Server please refer to the CA IDMS Server User Guide.