Installing and running JDBC ODA
This section discusses the following:
Installing JDBC ODA
To install the JDBC ODA, use
the Installer for WebSphere Business Integration Server Express
Adapter for JDBC. Follow the instructions in the WebSphere Business Integration Server Express installation guide for Windows, for Linux, or for i5/OS.
When the installation is complete, the following files are installed
in the directory on your system where you have installed the product:
- ODA\JDBC\JDBCODA.jar
- ODA\messages\JDBCODAAgent.txt
- ODA\message\JDBCODAAgent__ll_TT.txt message files specific to
a language ll) and a country or territory (TT).
- ODA\JDBC\start_JDBCODA.bat (Windows only)
- ODA/JDBC/start_JDBCODA.sh (Linux and i5/OS only)
- bin\CWODAEnv.bat (Windows only)
- bin/CWODAEnv.sh (Linux, and i5/OS only)
Note:
Except as otherwise
noted, this document uses backslashes (\) as the convention for
directory paths. For Linux and i5/OS installations,
substitute slashes (/) for backslashes. All product pathnames are relative
to the directory where the product is installed on your system.
Before using JDBC ODA
Before you can run the JDBC ODA, you must:
- Install the appropriate JDBC driver. Follow
the instructions in the WebSphere Business Integration Server Express Installation Guide for Windows or for Linux.
- For i5/OS: The JDBC ODA can connect to any database using a
JDBC driver that supports JDBC 2.0 or later. There are two JDBC
drivers that can be used on i5/OS:
- The native driver named JT400NATIVE_JAR. The pathname is: /QIBM/ProdData/HTTP/Public /jt400/lib/jt400Native.jar.
- The Toolbox for Java driver named JT400_JAR. The pathname is:
/QIBM/ProdData/HTTP/Public /jt400/lib/jt400Native.jar.
- Because the JDBC ODA generates business object names and attribute
names from the names of corresponding database tables and columns,
and because business object names and attribute names must be in
ISO Latin-1, verify that the appropriate database components have
Latin-1 names. If they do not, you have the following choices:
- Create the business object definition manually in Business Object Designer Express.
- Edit the definition generated by the JDBC ODA so that all business
object names and attribute names are in Latin-1.
- Open for editing the Linux shell
file (start_JDBCODA.sh) or Windows batch file (start_JDBCODA.bat) and configure the values described in Table 5.
Table 5. Shell and batch file configuration variables
Variable |
Explanation |
Example |
AGENTNAME |
Name of the ODA |
Linux: AGENTNAME=JDBCODA
Windows: set AGENTNAME=JDBCODA |
AGENT |
Name of the ODA's jar file |
Linux: AGENT=$CROSSWORLDS/ODA/JDBC/JDBCODA.jar
Windows: set AGENT= %CROSSWORLDS%\ODA\JDBC\JDBCODA.jar |
DRIVERPATH |
Path of JDBC driver library; JDBC ODA uses the
driver classes to establish a connection to a specified database |
Linux: DRIVERPATH=$CROSSWORLDS/lib/ \
xwutil.jar:$CROSSWORLDS/lib/ \
xwbase.jar:$CROSSWORLDS/lib/ \
xwsqlserver.jar:$CROSSWORLDS/lib/ \
spy/lib/spy.jar
Windows: set DRIVERPATH=%CROSSWORLDS%\ /
lib\xwutil.jar;%CROSSWORLDS%\lib\ /
xwbase.jar;%CROSSWORLDS%\lib\ /
xwsqlserver.jar;%CROSSWORLDS%\lib\ /
spy\lib\spy.jar |
DRIVERLIB |
Path of the native libraries used by the JDBC
driver |
Linux: After
copying db2jdbc.so to $CROSSWORLDS/lib*
DRIVERLIB=$CROSSWORLDS/lib/db2jdbc.so
Windows: After copying db2jdbc.dll to %CROSSWORLDS%\bin*
DRIVERLIB=%CROSSWORLDS%\bin\db2jdbc.dll
*Alternatively, you can point to the folders where these files exist. |
Add your database driver to the DRIVERPATH in the start script. For example, if you are using DB2, add db2java.zip.
After installing the JDBC driver and setting configuration values
in the shell or batch file, you must do the following to generate
business objects:
- Launch the ODA.
- Launch Business Object Designer Express.
- Follow a six-step process in Business
Object Designer Express to configure and run the ODA.
The following sections describe these steps in detail.
Launching JDBC ODA
You can launch the JDBC ODA with the
startup script appropriate for your operating system.
Launching the ODA on Linux:
start_JDBCODA.sh
Launching the ODA on Windows:
start_JDBCODA.bat
Launching the ODA on i5/OS:
To Start i5/OS, select one of the following methods:
- From the Windows system where the WebSphere Business Integration
Server Express Console is installed, select Programs>IBM WebSphere Business Integration Express>Toolset Express>Administrative Console. Then
specify the OS/400 or i5/OS system name or IP address and a user
profile and password that has *JOBCTL special authority. Select
the ODA from the list of ODAs and select the Start ODA button.
- From the i5/OS command entry run the QSH
CL command and from the QSHELL environment run /QIBM/ProdData/WBIServer44/bin/submit_oda.sh
script with the following parameters in order
pathToODAStartScript jobDescriptionName
where pathToODAStartScript is
the full path to the ODA start script, and
jobDescriptionName is the name
of the job description to use in the QWIBSVR44 library.
- From the OS/400 command entry, run the QSH CL command and from
the QSHELL command entry, run the ODA startup script directly:
start_ODAName.sh.
Stopping the ODA on i5/OS
The way to stop the ODA for i5/OS depends on how it
was started. If you used option 1 or 2 in "Launching the
ODA on i5/OS" then:
- From the Windows system where the WebSphere Business Integration Server Express Console is installed, select IBM Websphere Business Integration Server Express>Toolset Express>Administrative Console. Then specify the OS/400 or i5/OS system name or IP address and a user profile and password that has *JOBCTL special authority. Select the JDBC ODA from the list of ODAs and click the Stop ODA button.
- From the i5/OS command entry, run the CL command: WRKACTJOB
SBS (QWBISVR44). The screen will show all jobs running in the subsystem.
- Scroll through the list to find the jobname that matches the
job description for the ODA. For the ODAName JDBCODA, it is QWBIJDBODA.
- Select option 4 for this job, and press F4 to
prompt for the ENDJOB command. Specify IMMED for the OPTION parameter.
- Press Enter.
If you used option 3 in "Launching the ODA on i5/OS"
to start the ODA, then press F3 from the QSHELL command
entry where you ran the start_ODAName.sh script.
Linux:
start_JDBCODA.sh
You configure and run the JDBC ODA
using Business Object Designer Express. Business Object Designer Express
locates each ODA by the name specified in the AGENTNAME variable of each script or batch file. The default ODA name
for this connector is JDBCODA.
Running multiple instances of JDBC ODA
It is recommended that you change the name of the ODA
when you run multiple instances of it. To create additional uniquely
named instances of the JDBC ODA:
- Create a separate script or batch file for each instance.
- Specify a unique name in the AGENTNAME variable of each script or batch file.
It is recommended that you prefix each name with the name of
the host machine when you run ODA instances on different machines.
Figure 2 illustrates
the window in Business Object Designer Express from which you select
the ODA to run.
Working with error and trace message files
Error and trace message files (the default is JDBCODAAgent.txt) are located in \ODA\messages\, which is under the product directory. These files use the
following naming convention:
AgentNameAgent.txt
If you create multiple instances of the ODA script or batch file
and provide a unique name for each represented ODA, you can have
a message file for each ODA instance. Alternatively, you can have
differently named ODAs use the same message file. There are two
ways to specify a valid message file:
- If you change the name of an ODA
and do not create a message file for it, you must change the name
of the message file in Business Object Designer Express as part
of ODA configuration. Business Object Designer Express provides
a name for the message file but does not actually create the file.
If the file displayed as part of ODA configuration does not exist,
change the value to point to an existing file.
- You can copy the existing message
file for a specific ODA, and modify it as required. Business Object Designer
Express assumes you name each file according to the naming convention.
For example, if the AGENTNAME variable specifies JDBCODA1, the tool assumes that the name of the associated message
file is JDBCODA1Agent.txt. Therefore, when Business Object Designer Express provides
the filename for verification as part of ODA configuration, the
filename is based on the ODA name. Verify that the default message
file is named correctly, and correct it as necessary.
Important:
Failing to correctly specify the message file's
name when you configure the ODA causes it to run without messages.
For more information on specifying the message file name, see
Configure initialization properties.
During the configuration process, you specify:
- The name of the file into which the JDBC ODA writes error and
trace information
- The level of tracing, which ranges from 0 to 5.
Table 6 describes these values.
Table 6. Tracing levels
Trace level |
Description |
0 |
Logs all errors |
1 |
Traces all entering and exiting messages for
method |
2 |
Traces the ODA's properties and their
values |
3 |
Traces the names of all business objects |
4 |
Traces details of all spawned threads |
5 |
* Indicates the ODA initialization values
for all of its properties
* Traces a detailed status of each thread that
JDBC ODA spawned
* Traces the business object definition dump |
For information on where you configure these values, see Configure initialization properties.
