Adapter For JDBC Install and Users Guide
Adapter For JDBC Install and Users Guide
User’s Guide
Version 10.3
October 2018
Copyright IBM Corp. 2024, 2025
Document ID: ADAPTER-JDB-IUG-103-20250502
Table of Contents
3 Package Management...........................................................................................................................53
Overview of Package Management...............................................................................................54
Adapter for JDBC Package Management......................................................................................54
Group Access Control......................................................................................................................57
Adapter for JDBC in a Clustered Environment...........................................................................57
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 iii
Table of Contents
6 Adapter Services....................................................................................................................................89
Overview of Adapter Services........................................................................................................90
Before Configuring or Managing Adapter Services....................................................................90
Configuring SelectSQL Services.....................................................................................................91
Configuring InsertSQL Services.....................................................................................................95
Configuring UpdateSQL Services..................................................................................................97
Configuring BatchInsertSQL Services.........................................................................................101
Configuring BatchUpdateSQL Services......................................................................................104
Configuring DeleteSQL Services..................................................................................................108
Configuring CustomSQL Services...............................................................................................110
Configuring DynamicSQL Services.............................................................................................114
Configuring StoredProcedure Services.......................................................................................118
Configuring StoredProcedureWithSignature Services.............................................................122
Configuring ExecuteService Services..........................................................................................129
Testing Adapter Services...............................................................................................................130
Viewing Adapter Services.............................................................................................................131
Editing Adapter Services...............................................................................................................132
Deleting Adapter Services.............................................................................................................132
Validating Adapter Service Values..............................................................................................133
Reloading Adapter Values............................................................................................................134
7 Adapter Notifications.........................................................................................................................135
Overview of Adapter Notifications.............................................................................................136
Before Configuring or Managing Notifications.........................................................................136
Configuring InsertNotifications...................................................................................................137
Configuring UpdateNotifications................................................................................................142
Configuring DeleteNotifications..................................................................................................148
Configuring BasicNotifications....................................................................................................153
Configuring StoredProcedureNotifications................................................................................158
Configuring StoredProcedureNotificationWithSignature........................................................162
Configuring OrderedNotifications..............................................................................................167
Managing Polling Notifications...................................................................................................173
Using the Exactly Once Notification Feature.............................................................................175
Exporting Configured Adapter Notifications............................................................................175
Viewing Notifications....................................................................................................................177
Editing Notifications......................................................................................................................177
Deleting Notifications....................................................................................................................178
Validating Adapter Notification Values......................................................................................178
Reloading Adapter Values............................................................................................................179
iv IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
Table of Contents
10 Administrator APIs...........................................................................................................................189
Administrator APIs........................................................................................................................190
B Built-In Services..................................................................................................................................223
Overview.........................................................................................................................................224
pub.jdbcAdapter:updateNotificationSchema............................................................................224
pub.jdbcAdapter:updateServiceSchema.....................................................................................228
pub.jdbcAdapter:updateConnectionPassword..........................................................................231
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 v
Table of Contents
pub.jdbcAdapter:createConnectionNodes.................................................................................232
pub.pollingNotificationUtils:dropDatabaseObjects..................................................................234
pub.pollingNotificationUtils:getDatabaseObjectsForNotification..........................................235
wm.adapter.wmjdbc.utils:docListToObject................................................................................235
wm.adapter.wmjdbc.utils:objectToDocList................................................................................236
wm.adapter.wmjdbc.admin.service:update...............................................................................236
vi IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
About this Guide
■ Document Conventions .................................................................................................... 8
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 7
This guide describes how to configure and use IBM webMethods Adapter for JDBC. It contains
information for administrators and application developers who want to exchange data with
relational databases.
The basic concepts and tasks for working with relational databases
Document Conventions
Convention Description
Narrowfont Identifies service names and locations in the format folder.subfolder.service, APIs,
Java classes, methods, properties.
Italic Identifies:
Variables for which you must supply values specific to your own situation or
environment.
New terms the first time they occur in the text.
References to other documentation sources.
{} Indicates a set of choices from which you must choose one. Type only the
information inside the curly braces. Do not type the { } symbols.
| Separates two mutually exclusive choices in a syntax line. Type one of these
choices. Do not type the | symbol.
[] Indicates one or more options. Type only the information inside the square
brackets. Do not type the [ ] symbols.
... Indicates that you can type multiple options of the same type. Type only the
information. Do not type the ellipsis (...).
8 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
1 Overview of the Adapter
■ About Adapter for JDBC ................................................................................................. 10
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 9
1 Overview of the Adapter
Using Adapter for JDBC, Integration Server clients can create and run services that execute
transactions to retrieve data from, and insert and update data in, relational databases.
For example, you can use Adapter for JDBC to add a customer to an Oracle database based on
data from another system connected to Integration Server. Or you can use Adapter for JDBC to
poll a Microsoft SQL Server database for customers that have been added to the database, and to
send that data to Integration Server to be inserted into another resource.
For a list of the database versions, JDBC drivers, and platforms that Adapter for JDBC supports,
see IBM webMethods Adapters System Requirements.
For a list of known driver limitations, see “JDBC Driver Specific Properties” on page 257.
Architecture Overview
Adapter for JDBC provides a set of user interfaces, services, and templates that enable you to
create integrations with databases using a JDBC driver. The adapter is provided as a single package
that must be installed on Integration Server. For detailed installation instructions, see “Overview
of Installing, Upgrading, and Uninstalling Adapter for JDBC” on page 48. For software
requirements, see IBM webMethods Adapters System Requirements.
Because Adapter for JDBC uses a JDBC driver to perform operations on databases, the adapter
requires a supported JDBC driver to be installed and loaded in the packages directory of Integration
Server. For more details, see “Installing a JDBC Driver on Integration Server” on page 65.
Adapter connections. Enable Integration Server to connect to database systems at run time.
You must configure an adapter connection before you can configure adapter services or adapter
notifications. For a detailed description of adapter connections, see “Adapter Connections” on
page 13.
Adapter services. Enable Integration Server to initiate and perform database operations on a
database. For example, an adapter service could enable a trading partner to query your
inventory database to determine whether a particular item is currently in stock. You configure
adapter services using adapter services templates, which are provided with Adapter for JDBC.
For a detailed description of adapter services, see “Adapter Services” on page 16.
Adapter notifications. Monitor a database and notify Integration Server when an action (not
initiated by Integration Server) occurs on a particular database table. For example, an adapter
notification could notify Integration Server when an update operation was performed on a
particular database table. For a detailed description of adapter notifications, see “Adapter
Notifications” on page 23.
10 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
1 Overview of the Adapter
The following diagram shows at a high level how an adapter service uses an adapter connection
and a JDBC driver to connect to and perform an operation on a database.
The next diagram shows a business integration where an adapter service is used to update a
database with employee data. The employee data could be provided by several different types of
external Integration Server (IS) clients.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 11
1 Overview of the Adapter
The architecture for integrations using adapter notifications is similar to the architecture for
integrations using adapter services shown above, but it varies according to the type of notification.
The primary difference between these types of integrations is that notifications are initiated by
events that occur on the database, not by actions that occur on Integration Server.
With adapter notifications, you can capture event data from the database and use it to initiate
another action within Integration Server. For example, you could create an adapter notification
to monitor an employee table within a database and whenever an employee is added to the table,
you could post that employee data to a Broker. Broker clients could then subscribe to that
notification's publishable document.
For more information about the architecture for the different types of adapter notifications, see
“Adapter Notifications” on page 23.
Package Management
Adapter for JDBC is provided as a package called WmJDBCAdapter that you manage like any
package on Integration Server.
There are several considerations regarding how you set up and effectively manage your packages
on Integration Server:
12 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
1 Overview of the Adapter
You must create user-defined packages for your connections, adapter services, and notifications.
For details, see “Adapter for JDBC Package Management” on page 54.
You should understand how package dependencies work so you make the best decisions
regarding how you manage your adapter services and notifications. For details, see “Package
Dependency Requirements and Guidelines” on page 55.
You control which development groups have access to which adapter services and notifications.
For details, see “Group Access Control” on page 57.
You should understand how clustering, an advanced feature of Integration Server, works to
effectively manage your adapter services. For details, see “Adapter for JDBC in a Clustered
Environment” on page 57.
Adapter Connections
Adapter for JDBC connects to a database through a JDBC driver at run time. You create one or
more connections at design time to use in integrations. The number of connections you create, and
the types of those connections, depend on the types of databases you are connecting to and your
integration needs. For example, if you are connecting to an Oracle database and a DB2 Server
database, you will need to create connections that are unique to those two databases. Additionally,
if you have multiple installations of the same kinds of databases, you access each using different
connections. For example, if you have a data warehouse system and an ERP system that use your
Oracle database, you create a connection for each system.
Adapter for JDBC connections contain parameters that Integration Server uses to manage
connections to the database so that they can be used by the adapter to provide services. You
configure connections using Integration Server Administrator. You must have Integration Server
Administrator privileges to access Adapter for JDBC's administrative screens.
For instructions on configuring, viewing, editing, enabling, and disabling Adapter for JDBC
connections, see “Overview of Adapter Connections” on page 64. For information about setting
user privileges, see the IBM webMethods Integration Server Administrator’s Guide for your release.
The JDBC driver must be installed on the Integration Server machine and loaded when the server
starts. For instructions, see “Installing a JDBC Driver on Integration Server” on page 65.
For more information about the transaction types supported in Adapter for JDBC, see “Transaction
Management of Adapter Connections” on page 14.
For a complete list of the JDBC drivers that the adapter supports, see IBM webMethods Adapters
System Requirements.
For a list of known driver limitations, see “JDBC Driver Specific Properties” on page 257.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 13
1 Overview of the Adapter
LOCAL_TRANSACTION With this transaction type, all of the operations on the same
connection in one transaction boundary are committed or
rolled back together. A transaction boundary means the scope
of the transaction, from the beginning to the end of a
transaction. It can be in one adapter service, one flow service,
one Java service, or several steps in a flow service.
Note:
All of the connections involved in a two-phase transaction
must support the XA_TRANSACTION transaction type.
Note:
Insert Notifications, Update Notifications, Delete Notifications, and Ordered Notifications
support LOCAL_TRANSACTION mode only.
When you define a connection, the transaction type that you choose determines the type of
transaction management that the connection's operations use implicitly. Implicit transactions,
which include the transaction types in the preceding table, are managed by the Integration Server
transaction manager.
You can also explicitly manage transactions using built-in services. For information about, and
examples of, explicitly managing transactions, see “Transaction Management Overview” on
page 242.
14 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
1 Overview of the Adapter
Adapter for JDBC supports all the isolation level settings supported by your database, for example,
the isolation level SNAPSHOT for MS SQL Server 2005.
The isolation level settings can be specified in the Other Properties field of the Connection
Configuration screen, while configuring a connection. For more information about specifying
these levels, see “Configuring Adapter for JDBC Connections” on page 66.
Connection Pools
Integration Server includes a connection management service that dynamically manages connections
and connection pools based on configuration settings that you specify for the connection. All
adapter services use connection pooling.
A connection pool is a collection of connections with the same set of attributes. Integration Server
maintains connection pools in memory. Connection pools improve performance by enabling
adapter services to re-use open connections instead of opening new connections.
If initialization of the connection pool fails because of a network connection failure or some other
type of exception, you can enable the system to retry the initialization any number of times, at
specified intervals. For information about configuring connections, see “Configuring Adapter for
JDBC Connections” on page 66.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 15
1 Overview of the Adapter
information, see “Changing the Connection Associated with an Adapter Service or Notification
at Design Time” on page 20.
For details, see the IBM webMethods Integration Server Built-In Services Reference for your release.
Adapter Services
To use Adapter for JDBC, you create adapter services. Adapter services allow you to connect to
the adapter's resource and initiate an operation on the resource from Integration Server.
You call adapter services from flow or Java services to interact with database tables. The adapter
services perform database operations by calling JDBC APIs. Integration Server then uses adapter
connections that you defined earlier to execute the adapter services. For details, see “Adapter
Service Transaction Processing” on page 21.
Adapter services are based on templates provided with Adapter for JDBC. Each template represents
a specific technique for doing work on a resource, such as using the SelectSQL template to retrieve
specified information from a database.
An adapter service template contains all the code necessary for interacting with the resource but
without the data specifications. You provide these specifications when you create a new adapter
service.
Creating a new service from an adapter service template is straightforward. Using IBM webMethods
Designer, you assign the service a default adapter connection.
After you select the connection for the adapter service, you select the adapter service template
and supply the data specifications using Designer. Some familiarity with using Designer is required.
For more information, see the IBM webMethods Service Development Help for your release.
16 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
1 Overview of the Adapter
“Configuring InsertSQL
Services” on page 95.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 17
1 Overview of the Adapter
18 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
1 Overview of the Adapter
StoredProcedureWithSignature
Services” on page 122.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 19
1 Overview of the Adapter
Note:
The setAdapterServiceNodeConnection and setPollingNotificationNodeConnection services can be run at
design time only. Do not use them within an Integration Server flow or Java service. You must
run the services directly from Designer by selecting a service and running it.
For details, see the IBM webMethods Integration Server Built-In Services Reference for your release.
Other built-in services enable you to control connections. For more information, see “Built-In
Services for Connections” on page 15.
20 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
1 Overview of the Adapter
For example, a service can be defined to use a default connection that interacts with your company's
production database. However, at run time you can override the default connection and instead
use another connection to interact with the company's test database.
For more information about overriding a service's default connection at run time, see “Dynamically
Changing a Service's Connection at Run Time” on page 79.
For example, consider a service's associated adapter connection that uses an administrator's
credentials at design time to define a connection to a database. At run time, you can override the
administrator's account credentials with individual user credentials to limit access to the database
according to the permission level each user has. This capability also enables you to keep track of
the database operations by the user initiating the service.
For more information, see “Dynamically Changing the User Credentials of a Service's Connection
at Run Time” on page 80.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 21
1 Overview of the Adapter
Step Description
1 An Integration Server client, typically using a flow or Java service, invokes a Adapter
for JDBC service on Integration Server to perform an operation on a database.
2 The adapter service gets a connection from the service's connection pool.
Adapter connections contain connection information for the database, including JDBC
driver parameters.
3 The adapter service uses the JDBC driver to connect to the database.
You created and enabled the adapter connection earlier using Integration Server
Administrator.
4 All adapter services except ExecuteService perform a SQL operation against the database.
The ExecuteService adapter service executes a Java or flow service that needs a
connection object from the connection pool. For more information see “Using a
Connection from the Connection Pool Within a Java or Flow Service” on page 20.
22 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
1 Overview of the Adapter
Step Description
5 Depending on the adapter service type, such as a SelectSQL service, the adapter service
may return data to Integration Server.
If the operation is successful, the service returns the output from the service's database
operation, if applicable.
For more information about how the adapter handles exceptions, see “Overview of
Logging and Exception Handling” on page 196.
Adapter Notifications
An adapter notification monitors a specified database table for changes, such as an insert, update,
or delete operation, so that the appropriate Java or flow services can make use of the data, such
as sending an invoice or publishing it to Integration Server.
Adapter for JDBC notifications are polling-based. That is, Integration Server will invoke the
notification periodically based on the polling interval that you specify when you schedule the
notification as described in “Managing Polling Notifications” on page 173.
Important:
Use the same polling notification on multiple Integration Server instances only in an Integration
Server cluster. For more information about using polling notifications in a cluster, see “Polling
Notification Support in Clusters” on page 43.
Adapter notifications vary somewhat in how they work, depending on the type of the adapter
notification. Be sure to review “Notification Types” on page 25 to understand how their operations
differ.
Note:
To use the JMS protocol with asynchronous notifications, you must first configure a JMS
connection alias on Integration Server. For more information, see the IBM webMethods Integration
Server Administrator’s Guide for your release.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 23
1 Overview of the Adapter
For steps for selecting a publish destination for asynchronous notification messages, see “Overview
of Adapter Notifications” on page 136.
Basic Notification BasicNotification Polls a database table for data using a SQL Select
operation.
24 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
1 Overview of the Adapter
Note:
Stored Procedure Notifications do not support the Exactly Once notification feature because
they do not use publishable document unique IDs.
For more details, see “Using the Exactly Once Notification Feature” on page 175.
Notification Types
There are seven types of notifications: Insert, Update, Delete, Basic, Stored Procedure,
StoredProcedureNotificationWithSignature, and Ordered Notifications. They vary in how they
are structured and operate, as described in the following sections.
These types of notifications operate similarly, with the exception of the type of SQL operation
(insert, update, or delete) that they monitor. The adapter creates the trigger and buffer table when
you enable a notification. The buffer table, which you specified when you configured the
notification, holds the data selected by the trigger. There are no special size constraints for the
buffer tables. The trigger monitors the database table you specified when you configured the
notification and inserts data into the buffer table. When you disable a notification, the adapter
drops the trigger and buffer table.
When you enable a notification, the database trigger monitors the table and inserts the data into
the buffer table. When Integration Server invokes the notification, it retrieves the rows of data
from the buffer table, publishes each row in the notification's publishable document, and then
removes this row from the buffer table.
After you enable these types of notifications, the trigger and buffer table remain in the database
table when you:
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 25
1 Overview of the Adapter
In the meantime, the trigger continues to monitor the table and to insert data into the buffer table.
Integration Server invokes the enabled notification when it restarts, or when it enables or reloads
the package that contains this notification. For more information about how these types of
notifications work, see “Insert, Update, and Delete Notifications Transaction Processing” on
page 27.
For instructions for configuring this type of adapter notification, see “Configuring
InsertNotifications” on page 137, “Configuring UpdateNotifications” on page 142, or “Configuring
DeleteNotifications” on page 148.
For more details about the Integration Server publishable documents, see the Publish-Subscribe
Developer’s Guide for your release.
Adapter connection
Source table
26 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
1 Overview of the Adapter
4. Schedule and enable the adapter notification. When Integration Server Administrator
you enable the notification:
5. Manage the notification. For details, see “Overview Designer and Integration Server
of Package Management” on page 54, “Overview of Administrator
Adapter Notifications” on page 136, and “Overview of
Logging and Exception Handling” on page 196.
Note:
The old value is the value that exists before a value is updated in the selected column of the
database table.
You can set the required output value options while configuring the UpdateNotification in the
Select tab of the UpdateNotification template. For more information about setting the output
value options, see “Configuring UpdateNotifications” on page 142.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 27
1 Overview of the Adapter
Step Description
Adapter connections contain connection information for the database, including JDBC
driver parameters.
You created and enabled the adapter connection earlier using Integration Server
Administrator.
4 The notification retrieves the rows of data from the buffer table.
The buffer table holds the data selected by the trigger. While the adapter notification
remains enabled, the trigger continues to monitor the database table and insert data
into the buffer table.
5 The notification creates the publishable document, which contains a row of data from
the buffer table. The notification publishes the publishable document.
For more details about the Integration Server publishable documents, see the
Publish-Subscribe Developer’s Guide for your release.
6 Using an Integration Server trigger you configured to use the notification's publishable
document, a flow or Java service on Integration Server is invoked to react to the data
changes contained in the publishable document.
After the data is published, the data is removed from the buffer table.
28 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
1 Overview of the Adapter
Basic Notifications
In contrast with Insert Notifications, Update Notifications, and Delete Notifications, Basic
Notifications require that you define a buffer table, and a database trigger or other means of
monitoring database changes so that changes are written into the buffer table.
To monitor database changes, a Basic Notification queries the buffer table. Basic Notifications
provide you with the flexibility to manage buffer tables, such as a table with user privileges, and
to tailor your own database monitoring methods for producing notification data. By default, after
the data is retrieved and processed, it is deleted from the buffer table to ensure that the data is not
processed multiple times. If you do not want to delete the data from the buffer table, and you also
do not want the adapter to publish the data more than once, you can mark the processed data as
published. The notification then only processes the data that is not published. To use this option,
you need to:
1. Add a column of CHAR(1) data type with any name in the database table that you are trying
to use. This column is required to hold the status of the data, that is, whether the data is
processed or not processed.
2. While configuring the Basic Notification, select the newly added column in the Mark ID Column,
see step 1. For instructions about configuring the Basic Notification, see “Configuring
BasicNotifications” on page 153.
For more information about how Basic Notifications work, see “Basic Notifications Transaction
Processing” on page 30.
Adapter connection
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 29
1 Overview of the Adapter
6. Manage the notification. For details, see “Overview of Designer and Integration Server
Package Management” on page 54, “Overview of Administrator
Adapter Notifications” on page 136, and “Overview of
Logging and Exception Handling” on page 196.
30 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
1 Overview of the Adapter
Step Description
Adapter connections contain connection information for the database, including JDBC
driver parameters.
You created and enabled the adapter connection earlier using Integration Server
Administrator.
4 Unlike Insert Notifications, Update Notifications, and Delete Notifications, you create
your own buffer table and trigger, or other means of monitoring database changes. The
diagram and steps listed here assume you are creating your own buffer table and trigger
to monitor for changes.
The buffer table you define will hold the data selected by any trigger you create. The
trigger will monitor the database table and insert data into the buffer table.
5 The notification retrieves the rows of data from the buffer table.
6 The notification creates the publishable document, which contains a row of data from
the buffer table. The notification publishes the publishable document.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 31
1 Overview of the Adapter
Step Description
For more details about the Integration Server publishable documents, see the
Publish-Subscribe Developer’s Guide for your release.
7 Using an Integration Server trigger you configured to use the notification's publishable
document, a flow or Java service on Integration Server is invoked to react to the data
changes contained in the publishable document.
After the data is published, the data in the buffer table will be retained or removed,
depending on how you configured your buffer table and trigger.
For information about configuring this type of adapter notification, see “Configuring
StoredProcedureNotifications” on page 158.
Note:
Stored Procedure Notifications do not support the Exactly Once notification feature because
they do not use publishable document unique IDs. For details about this feature, see “Stored
Procedure Notifications” on page 32.
Adapter connection
Stored procedure
32 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
1 Overview of the Adapter
5. Schedule and enable the adapter notification. When Integration Server Administrator
you enable the notification, the Integration Server
Scheduler invokes the notification and continues to do so
periodically, based on the polling schedule parameters
you created earlier.
6. Manage the notification. For details, see “Overview of Designer and Integration Server
Package Management” on page 54, “Overview of Adapter Administrator
Notifications” on page 136, and “Overview of Logging
and Exception Handling” on page 196.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 33
1 Overview of the Adapter
Step Description
1 A Stored Procedure Notification uses a stored procedure you created in the database to
monitor an operation that happens to a database table, such as an insert, update, or
delete operation.
When the Stored Procedure Notification calls the stored procedure, it stores any output
in the notification's publishable documents.
Adapter connections contain connection information for the database, including JDBC
driver parameters.
You created and enabled the adapter connection earlier using Integration Server
Administrator.
5 The notification retrieves each row of data from the stored procedure.
6 Each row of data is published using the notification's publishable document. Depending
on the stored procedure, the Stored Procedure Notification's publishable documents
can contain any of the following:
34 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
1 Overview of the Adapter
Step Description
Output parameters: if the called stored procedure has any output parameters, they
are contained in any publishable documents for the Stored Procedure Notification.
Return values: if the called stored procedure returns any values, then a return value
is contained in a publishable document for the Stored Procedure Notification.
Single result set (or Oracle REF CURSOR): Stored Procedure Notifications can support
one result set. The result set can contain nested cursors. If a call to the stored
procedure produces a result set, then the single result set is contained in one or more
publishable documents for the Stored Procedure Notification. In some cases, a call
to a Stored Procedure Notification can produce a single result set that contains
multiple records. In this case, each record will have a separate publishable document,
containing one row and one or more columns, that is returned to the adapter.
Note:
When using the result set that contains nested cursors, the performance of Adapter
for JDBC could degrade. Since the nested cursors are recursively processed,
Adapter for JDBC may also return data that may not be required.
For more details about the Integration Server publishable documents, see the
Publish-Subscribe Developer’s Guide for your release.
7 Using an Integration Server trigger you configured to use the notification's publishable
document, a flow or Java service on Integration Server is invoked to react to the data
changes contained in the publishable document.
Ordered Notifications
You use Ordered Notifications to monitor multiple insert, update, or delete operations on one or
more tables for a given database by creating a single notification using the same publishable
document. Similar to Insert Notifications, Update Notifications, and Delete Notifications, Ordered
Notifications use triggers and buffer tables to capture events that happen on specific tables in a
database.
After you enable the Ordered Notification, the trigger, buffer table, and sequence remain in the
database table when you:
In the meantime, the trigger continues to monitor the table and to insert data into the buffer table.
Integration Server invokes the enabled Ordered Notification when it restarts, or when it enables
or reloads the package that contains this notification.
When you disable a notification, the adapter drops the trigger, the buffer table, and the sequence.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 35
1 Overview of the Adapter
For more information about how Ordered Notifications work, see “Ordered Notifications
Transaction Processing” on page 41.
Step Description
1 A Stored Procedure Notification uses a stored procedure you created in the database to
monitor an operation that happens to a database table, such as an insert, update, or
delete operation.
When the Stored Procedure Notification calls the stored procedure, it stores any output
in the notification's publishable documents.
Adapter connections contain connection information for the database, including JDBC
driver parameters.
You created and enabled the adapter connection earlier using Integration Server
Administrator.
36 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
1 Overview of the Adapter
Step Description
5 The notification retrieves each row of data from the stored procedure.
6 Each row of data is published using the notification's publishable document. Depending
on the stored procedure, the Stored Procedure Notification's publishable documents
can contain any of the following:
Output parameters: if the called stored procedure has any output parameters, they
are contained in any publishable documents for the Stored Procedure Notification.
Return values: if the called stored procedure returns any values, then a return value
is contained in a publishable document for the Stored Procedure Notification.
Single result set (or Oracle REF CURSOR): Stored Procedure Notifications can support
one result set. The result set can contain nested cursors. If a call to the stored
procedure produces a result set, then the single result set is contained in one or more
publishable documents for the Stored Procedure Notification. In some cases, a call
to a Stored Procedure Notification can produce a single result set that contains
multiple records. In this case, each record will have a separate publishable document,
containing one row and one or more columns, that is returned to the adapter.
Note:
When using the result set that contains nested cursors, the performance of Adapter
for JDBC could degrade. Since the nested cursors are recursively processed,
Adapter for JDBC may also return data that may not be required.
For more details about the Integration Server publishable documents, see the
Publish-Subscribe Developer’s Guide for your release.
7 Using an Integration Server trigger you configured to use the notification's publishable
document, a flow or Java service on Integration Server is invoked to react to the data
changes contained in the publishable document.
Ordered Notifications ensure that the operations process in the correct order when they occur
sequentially in one transaction; however, order preservation is not guaranteed if the operations
occur in concurrent transactions. For example, see the following diagrams. Examples A and
B will process operations in the correct order. Example C is not guaranteed to process operations
in the correct order.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 37
1 Overview of the Adapter
38 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
1 Overview of the Adapter
For more information about using configuring Integration Server triggers and flow services, see
the IBM webMethods Service Development Help for your release.
The following table lists the tasks required to use this notification:
Adapter connection
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 39
1 Overview of the Adapter
Source tables
4. Schedule and enable the adapter notification. When Integration Server Administrator
you enable the notification, it automatically creates the
database trigger, sequence, and buffer table you
configured when you created the notification. The
Integration Server Scheduler invokes the notification
periodically, based on the polling schedule parameters
you created earlier, and continues to do so.
40 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
1 Overview of the Adapter
5. Manage the notification. For details, see “Overview of Designer and Integration Server
Package Management” on page 54, “Overview of Administrator
Adapter Notifications” on page 136, and “Overview of
Logging and Exception Handling” on page 196.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 41
1 Overview of the Adapter
Step Description
Adapter connections contain connection information for the database, including JDBC
driver parameters.
You created and enabled the adapter connection earlier using Integration Server
Administrator.
4 The buffer table holds the data selected by the trigger. While the adapter remains enabled,
the trigger continues to monitor the database table and insert data into the buffer table.
With Ordered Notifications, the adapter creates the trigger, sequence, and buffer tables
for each operation you want to monitor when you enable the notification. The database
trigger monitors the tables and inserts data into the buffer table. When Integration Server
invokes the notification, the notification will poll all of the buffer tables and publish the
data in the same order in which the operations occurred. This ensures that the order of
the operations is preserved.
5 The notification retrieves the rows of data from the buffer table.
Each Ordered Notification generates one row for each operation. The notification uses
the Operation ID and an Operation Type field you specified when you configured the
notification to uniquely identify this row. The Operation ID is user-defined.
6 The notification creates the publishable document, which contains a row of data, including
the Operation ID and Operation Type, from the buffer table.
7 Using an Integration Server trigger you configured to use the notification's publishable
document, a flow or Java service on Integration Server is invoked to react to the data
changes contained in the publishable document.
The flow service that processes the publishable document for the Ordered Notification
needs to check the Operation ID field in the document and retrieve data from the record
with the name identified by the Operation ID for processing. For example, a flow service
checks to see if the Operation ID has a value of UPDATE. If this is true, then the flow
service picks up the data from the UPDATE record as input and processes it. If the
Operation ID value is INSERT, the flow service picks up data from the INSERT record
as input and processes accordingly.
For more information about using triggers and flow services with Ordered Notifications,
see “Ordered Notifications” on page 35.
After the data is published, the data is deleted from the buffer table.
42 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
1 Overview of the Adapter
For more information about how to use polling notifications in a clustered environment, see
“Polling Notification Support in Clusters” on page 43.
Suspended Database trigger and buffer The polling notification is You can suspend polling
table persist. Table retains removed from the notifications in an
its rows. scheduler and does not Enabled state. You cannot
execute while suspended. suspend polling
Any instances executing at notifications in a Disabled
the time the Suspended state.
state is initiated are
unaffected. You can copy or export
suspended polling
notifications. You cannot
move, rename, or delete
suspended polling
notifications.
The table above applies to Insert Notifications, Update Notifications, Delete Notifications, and
Ordered Notifications. However, the table does not apply to Basic Notifications or Stored Procedure
Notifications because with these, the resource administrator (not Adapter for JDBC) is responsible
for maintaining the trigger and buffer table.
For instructions on enabling, suspending, and disabling polling notifications, see the explanation
of the State field in “Managing Polling Notifications” on page 173.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 43
1 Overview of the Adapter
Important:
Not all JDBC drivers for backends that the adapter supports return synonyms. You can use
synonyms only with some of the supported backends.
For information about working with and creating synonyms, see the documentation of your
database vendor.
The following table lists the adapter services and notifications that support synonyms.
Update Notification
Consider the following limitations when using synonyms with adapter services:
If you want to use synonyms for stored procedures, you cannot use the
StoredProcedureWithSignature adapter service. Use the StoredProcedure service instead.
The SelectSQL, DeleteSQL, InsertSQL, and Update SQL services support synonyms only for
database tables and views.
For information about configuring adapter services, see “Overview of Adapter Services” on
page 90. For information about configuring adapter notifications, see “Overview of Adapter
Notifications” on page 136.
44 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
1 Overview of the Adapter
Update Notification
Consider the following limitations when using synonyms with adapter services:
The SelectSQL, DeleteSQL, InsertSQL, and Update SQL services support synonyms only for
database tables and views.
For information about configuring adapter services, see “Overview of Adapter Services” on
page 90. For information about configuring adapter notifications, see “Overview of Adapter
Notifications” on page 136.
To set this property, use Integration Server Administrator and select Settings > Extended > Edit
Extended Settings. Enter this property in the Extended Settings box:
watt.adapter.JDBC.QueryTimeout=value
where value is the number of seconds the adapter waits for the service or the notification to execute
before stopping the SQL operation and throwing an exception. For more information about setting
the watt properties, see the IBM webMethods Integration Server Administrator’s Guide for your release.
Beginning with Integration Server 8.2 SP3, the adapter supports the local service development
feature in Designer. This feature extends the functionality of the VCS Integration feature to check
package elements and their supporting files into and out of a VCS directly from Designer. For
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 45
1 Overview of the Adapter
more information about local service development and how it compares to the VCS Integration
feature, see the IBM webMethods Service Development Help.
For information about monitored key performance indicators (KPIs) collected for the monitored
adapter components, see the Optimize documentation for your release.
Controlling Pagination
When using the adapter on Integration Server 10.3, you can control the number of items that are
displayed on the adapter Connections screen and Notifications screen. By default, 10 items are
displayed per page. Click Next and Previous to move through the pages, or click a page number
to go directly to a page.
To change the number of items displayed per page, set the watt.art.page.size property and specify
a different number of items.
2. Click Edit Extended Settings. In the Extended Settings editor, add or update the
watt.art.page.size property to specify the preferred number of items to display per page. For
example, to display 50 items per page, specify:
watt.art.page.size=50
3. Click Save Changes. The property appears in the Extended Settings list.
For more information about working with extended configuration settings, see the IBM
webMethods Integration Server Administrator’s Guide for your release.
46 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
2 Installing, Upgrading, and Uninstalling Adapter
for JDBC
■ Overview of Installing, Upgrading, and Uninstalling Adapter for JDBC .......................... 48
■ Requirements ................................................................................................................. 48
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 47
2 Installing, Upgrading, and Uninstalling Adapter for JDBC
Requirements
For a list of operating systems, RDBMSs, and webMethods products supported by Adapter for
JDBC, see IBM webMethods Adapters System Requirements.
Adapter for JDBC has no hardware requirements beyond those of its host Integration Server.
For more information about running multiple Integration Server instances, see the IBM webMethods
Integration Server Administrator’s Guide for your release.
This guide uses the packages_directory as the home directory in Integration Server classpaths.
The packages_directory is Integration Server_directory\instances\instance_name\packages directory.
1. Download Installer .
2. If you are installing the adapter on an existing Integration Server, shut down the Integration
Server.
48 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
2 Installing, Upgrading, and Uninstalling Adapter for JDBC
4. Choose the webMethods release that includes the Integration Server on which you want to
install the adapter. For example, if you want to install the adapter on Integration Server 10.3,
choose the 10.3 release.
If you are installing on an existing Integration Server, specify the webMethods installation
directory that contains the host Integration Server.
If you are installing both the host Integration Server and the adapter, specify the installation
directory to use.
6. In the product selection list, select Adapters > webMethods Adapter 10.3 for JDBC.
You can choose to install the package in the default instance. In this case, IBM webMethods
Installer installs the adapter in both locations, Integration Server_directory\packages and the
default instance packages directory located in
Integration Server_directory\instances\default\packages.
7. After the installation completes, close the Installer and start the host Integration Server.
8. See “Installing a JDBC Driver on Integration Server” on page 65 for instructions on installing
a compatible JDBC driver.
1. Download Installer .
2. If you are installing the adapter on an existing Integration Server, shut down the Integration
Server.
If you are installing on an existing Integration Server, specify the IBM webMethods
installation directory that contains the host Integration Server.
If you are installing both the host Integration Server and the adapter, specify the installation
directory to use.
5. In the product selection list, select Adapters > webMethods Adapter 10.3 for JDBC.
From the Installer dialogue box, select the Microservices Runtime 10.1.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 49
2 Installing, Upgrading, and Uninstalling Adapter for JDBC
In the expanded list of options in libraries, select the Database Driver Libraries 10.1 check
box.
7. After the installation completes, close the Installer and start the host Integration Server.
8. For more information on Microservices Container, see Developing Microservices with IBM
webMethods Microservices Runtime.
Before upgrading you can choose to archive the existing adapter package. Archiving creates a
copy of the adapter package which enables you to revert to the earlier adapter package later if
necessary.
Archiving
To archive the existing adapter
The Archive page is displayed in Integration Server Administrator with the list of all files to
be archived.
Integration Server creates a copy of the adapter package in the Integration Server_directory\
replicate\outbound directory.
Upgrading
To upgrade the adapter:
1. Uninstall the existing adapter and delete the package using the instructions in “Uninstalling
Adapter for JDBC” on page 51.
2. Install Adapter for JDBC using the instructions in “Installing Adapter for JDBC” on page 48.
50 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
2 Installing, Upgrading, and Uninstalling Adapter for JDBC
Reverting
To revert to the earlier adapter
1. Uninstall the existing adapter and delete the package using the instructions in “Uninstalling
Adapter for JDBC” on page 51.
5. Select the Release file name from the drop-down list and click Install Release.
1. Shut down the host Integration Server. You do not need to shut down any other webMethods
products or applications that are running on your machine.
2. Start IBM webMethods Uninstaller, selecting the webMethods installation directory that
contains the host Integration Server.
3. In the product selection list, select Adapters > webMethods Adapter 10.3 for JDBC. You can
also choose to uninstall documentation.
Uninstaller removes all Adapter for JDBC-related files that were installed. However, Uninstaller
does not delete files created after you installed the adapter (for example, user-created or
configuration files), nor does it delete the adapter directory structure. You can go to the
Integration Server_directory\packages directory and Integration Server_directory\instances\default\
packages directory. Delete the WmJDBCAdapter directory.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 51
2 Installing, Upgrading, and Uninstalling Adapter for JDBC
52 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
3 Package Management
■ Overview of Package Management ................................................................................ 54
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 53
3 Package Management
When you create connections, adapter services, and adapter notifications, define them in
user-defined packages rather than in the WmJDBCAdapter package. Doing so will allow you to
manage the package more easily.
As you create user-defined packages in which to store connections, adapter services, and adapter
notifications, use the package management functionality provided in IBM webMethods Designer
and set the user-defined packages to have a dependency on the WmJDBCAdapter package. That
way, when the WmJDBCAdapter package loads or reloads, the user-defined packages load
automatically. See the following diagram:
Package dependencies ensure that at startup the Integration Server automatically loads or
reloads all packages in the proper order: the WmART package first, the adapter package next,
and the user-defined packages last. The WmART package is automatically installed when you
install Integration Server. You should not need to manually reload the WmART package.
If the connections and adapter services of an adapter are defined in different packages, then:
A package that contains the connections must have a dependency on the adapter package.
Packages that contain adapter services must have a dependency on their associated
connection package.
Keep connections for different adapters in separate packages so that you do not create
interdependencies between adapters. If a package contains connections for two different
adapters, and you reload one of the adapter packages, the connections for both adapters will
reload automatically.
Integration Server will not allow you to enable a package if it has a dependency on another
package that is disabled. That is, before you can enable your package, you must enable all
packages on which your package depends. For information about enabling packages, see
“Enabling Packages” on page 55.
Integration Server will allow you to disable a package even if another package that is enabled
has a dependency on it. Therefore, you must manually disable any user-defined packages that
have a dependency on the adapter package before you disable the adapter package. For
information about disabling packages, see “Disabling Packages” on page 56.
You can name connections, adapter services, and notifications the same name provided that
they are in different folders and packages.
Enabling Packages
All packages are automatically enabled by default. Use the following procedure when you want
to enable a package that was previously disabled.
To enable a package
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 55
3 Package Management
3. Click No in the Enabled column. The server displays a and Yes in the Enabled column.
Note:
Enabling an adapter package will not cause its associated user-defined packages to be
reloaded. For information about reloading packages, see the IBM webMethods Service
Development Help for your release.
Important:
Before you manually enable a user-defined package, you must first enable its associated
adapter package (WmJDBCAdapter).
Disabling Packages
When you want to temporarily prohibit access to the elements in a package, disable the package.
When you disable a package, the server unloads all of its elements from memory. Disabling a
package prevents Integration Server from loading that package at startup.
Important:
If your adapter has multiple user-defined packages, and you want to disable some of them,
disable the adapter package first (WmJDBCAdapter). Otherwise, errors will be issued when
you try to access the remaining enabled user-defined packages.
To disable a package
3. Click Yes in the Enabled column for the package that you want to disable. The server issues
a prompt to verify that you want to disable the package. Click OK to disable the package.
When the package is disabled, the server displays No in the Enabled column.
Remain disabled until you explicitly enable it using Integration Server Administrator.
Important:
56 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
3 Package Management
Do not rename packages you export; the rename function is comparable to moving a package,
and when you import the renamed package, you lose any triggers, connections, and notifications
associated with this package.
For details about importing and exporting packages, see the IBM webMethods Service Development
Help for your release.
For information about assigning and managing ACLs, see the IBM webMethods Service Development
Help for your release.
Integration Server 10.3 supports the caching and clustering functionality provided by Terracotta.
Caching and clustering are configured at the Integration Server level and Adapter for JDBC uses
the caching mechanism that is enabled on Integration Server. Adapter for JDBC does not explicitly
implement any clustering or caching beyond what is already provided by Integration Server.
Load balancing. This feature, provided automatically when you set up a clustered environment,
allows you to spread the workload over several servers, thus improving performance and
scalability.
Failover support. Clustering enables you to avoid a single point of failure. If a server cannot
handle a request, or becomes unavailable, the request is automatically redirected to another
server in the cluster.
Note:
Integration Server clustering redirects HTTP and HTTPS requests, but does not redirect FTP
or SMTP requests.
Scalability. You can increase your capacity even further by adding new machines running
Integration Server to the cluster.
For details on Integration Server clustering, see the IBM webMethods Integration Server Clustering
Guide for your release.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 57
3 Package Management
Important:
Adapter for JDBC supports enabling the same polling notification on multiple Integration Server
instances connecting to the same backend database to achieve automated failover, only when
the multiple Integration Servers share the same ISInternal database. If you attempt to use the
same polling notification on multiple Integration Servers pointing to the same backend database
but using separate ISInternal databases, you may encounter abnormal results.
With Integration Server 10.3, Adapter for JDBC uses Integration Server Scheduler to support
polling notifications. On enabling a polling notification, a new Integration Server scheduled task
is created, which polls the backend resource at the given interval. Do not manually edit or change
scheduled tasks. Each polling notification creates an Integration Server scheduled task. When a
notification is disabled, the scheduled task in Integration Server is removed.
Important:
All adapter polling notifications must be in a disabled state on all nodes in the Integration Server
cluster before you disable the cluster.
The IS Internal functional alias (specified on the Settings > JDBC Pools screen) is configured
with a database.
Note:
You can make scheduled notification tasks visible in the Server > Scheduler page in Integration
Server Administrator by setting watt.pkg.art.scheduler.notificationtask.display=true
Configuring this property is required only for debugging or for editing the polling notification
schedule interval.
58 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
3 Package Management
For more details about adapter services in clusters, see “Clustering Considerations and
Requirements” on page 60.
To ensure consistency, we recommend that you create all packages on one server, and replicate
them to the other servers. If you allow different servers to contain different services, you might
not derive the full benefits of clustering. For example, if a client requests a service that resides in
only one server, and that server is unavailable, the request cannot be successfully redirected to
another server.
For information about replicating packages, see the IBM webMethods Integration Server Administrator’s
Guide for your release.
1. Shut down Integration Server Administrator. For the procedure to do this, see the IBM
webMethods Integration Server Administrator’s Guide for your release.
Integration Server_directory\config\redir.cnf
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 59
3 Package Management
The following considerations and requirements apply to Adapter for JDBC in a clustered
environment.
Integration Server All Integration Servers in the cluster must be the same version, with the
versions same service packs and fixes applied.
Adapter packages All adapter packages on one Integration Server should be replicated to
all other Integration Servers in the cluster.
Adapter connections If you configure a connection to the database, this connection must appear
on all servers in the cluster so that any Integration Server in the cluster
can handle a given request identically.
Adapter services If you configure a specific InsertSQL Adapter Service, this same adapter
service must appear on all servers in the cluster so that any Integration
Server in the cluster can handle the request identically.
Adapter notifications If you configure a specific Insert notification, this same adapter notification
must appear on all servers in the cluster so that any Integration Server
in the cluster can handle the request identically.
60 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
3 Package Management
For information about replicating adapter packages, connections, adapter services, and adapter
notifications across multiple Integration Servers in a cluster, see “Replicating Packages to Integration
Servers” on page 59.
For example, if you have a cluster of two Integration Servers with a connection configured to a
database that supports a maximum of 100 connections opened simultaneously, the total number
of connections possible at one time must not exceed 100. This means that you cannot configure a
connection with an initial pool size of 100 and replicate the connection to both servers, because
there could be possibly a total of 200 connections opened simultaneously to this database.
In another example, consider a connection configured with an initial pool size of 10 and a maximum
pool size of 100. If you replicate this connection across a cluster with two Integration Servers, it is
possible for the connection pool size on both servers to exceed the maximum number of database
connections that can be open at one time.
For information about configuring connections for Adapter for JDBC, see “Overview of Adapter
Connections” on page 64.
For more general information about connection pools, see the IBM webMethods Integration Server
Administrator’s Guide for your release.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 61
3 Package Management
62 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
4 Adapter for JDBC Connections
■ Overview of Adapter Connections .................................................................................. 64
■ Dynamically Changing the User Credentials of a Service's Connection at Run Time .... 80
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 63
4 Adapter for JDBC Connections
1. Install IBM webMethods Integration Server and Adapter for JDBC on the same machine. For
details, see “Overview of Installing, Upgrading, and Uninstalling Adapter for JDBC” on
page 48.
2. Install a compatible JDBC driver. For instructions, see “Installing a JDBC Driver on Integration
Server” on page 65. For a list of supported drivers, see IBM webMethods Adapters System
Requirements.
3. Make sure you have Integration Server administrator privileges so that you can access Adapter
for JDBC's administrative screens. For information about setting user privileges, see the IBM
webMethods Integration Server Administrator’s Guide for your release.
4. Be sure to check for a list of known driver limitations because it may affect how you configure
your connections.
5. Start your Integration Server and Integration Server Administrator, if they are not already
running.
6. Using Integration Server Administrator, make sure the WmJDBCAdapter package is enabled.
For instructions, see “Enabling Packages” on page 55.
7. Using Designer, create a user-defined package to contain the connection, if you have not already
done so. For more information about managing packages for the adapter, see “Adapter for
JDBC Package Management” on page 54.
8. If you use Oracle JDBC OCI drivers, you must set an environment variable before you can
configure the connection. For details, see “Setting the Environment Variable for Oracle JDBC
OCI Drivers” on page 285.
If you use Oracle JDBC OCI drivers with Oracle OCI Instant Client, then copy the following
client library files before you set the environment variable:
ojdbc5.jar and ojdbc6.jar files to the two locations, Integration Server_directory\lib\jars and
Integration Server_directory\instances\instance_name\lib\jars.
64 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
4 Adapter for JDBC Connections
All the other client library files to the two locations, Integration Server_directory\lib and
Integration Server_directory\instances\instance_name\lib.
Multiple Version
Warning:
The Default or Single Version and Multiple Version modes are mutually exclusive. At any
given point of time, you can use the JDBC driver(s) in one mode only.
1. Place the JDBC driver JAR file(s) in the classpath of Integration Server, typically in
Integration Server_directory/instances/instance_name/packages/WmJDBCAdapter/code/jars
folder.
Integration Server uses the JAR file(s) added to its classpath after the restart.
1. If you want to use multiple versions of JDBC drivers, then perform the following steps for
each version:
Note:
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 65
4 Adapter for JDBC Connections
Ensure that none of the related driver JAR file(s) of other versions are placed inside any
of the classpaths of Integration Server:
Default driver group classpath: Integration Server_directory/
instances/instance_name/packages/WmJDBCAdapter/code/jars
Static folder classpath: Integration Server_directory/instances/instance_name/
packages/WmJDBCAdapter/code/jars/static
Integration Server common library classpath: Integration Server_directory/common/lib
For example, if you want to use multiple Oracle specific JAR file(s) such as ojdbc8.jar and
ojdbc6.jar, you must perform the following:
mssqlV11
mssqlV10
mssqlV8
mysqlV8
mysqlV5.1.40
2. Place the respective JDBC driver JAR file(s) in this folder. For example:
You can see oracleV8 and oracleV6 in the Driver Group dropdown in the JDBC Connection
page.
3. In the JDBC Connection page, select the Driver Group based on your requirements.
Note:
Ensure that none of the related driver JAR file(s) of other versions are placed inside any of
the classpaths of Integration Server: Default driver group classpath, Static folder classpath or
Integration Server common library classpath.
Note:
66 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
4 Adapter for JDBC Connections
If you use Oracle JDBC OCI drivers with Adapter for JDBC, you must add an environment
variable setting before you configure adapter connections. For details, see “Setting the
Environment Variable for Oracle JDBC OCI Drivers” on page 285.
1. In the Adapters menu in Integration Server Administrator's navigation area, click IBM
webMethods Adapter for JDBC.
4. In the Configure Connection Type > IBM webMethods Adapter for JDBC section, configure
the following fields:
Field Description/Action
Package Package in which to create the connection. Use Designer to create the package
before specifying the value in this field. For general information about
creating packages, see the IBM webMethods Service Development Help for your
release.
Note:
Configure the connection in a user-defined package rather than in the
adapter's package. For other important considerations when creating
packages for Adapter for JDBC, see “Adapter for JDBC Package
Management” on page 54.
Connection Name you want to give to the connection. Connection names cannot have
Name spaces or use special characters reserved by Integration Server and Designer.
For more information about the use of special characters in package, folder,
and element names, see the IBM webMethods Service Development Help for
your release.
Note:
The following table shows suggested values for these parameters as guidance only. For
more information about what values to assign to these parameters, see your JDBC driver
documentation.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 67
4 Adapter for JDBC Connections
a. Specify the Transaction Type, Driver Group, and DataSource Class fields as follows:
Field Description/Action
Transaction Type of transaction support that the connection provides. Select one of the
Type following transaction types:
Note:
If you are configuring a Basic Notification and using the Exactly
Once Notification and Delete selected records options, you must
configure the notification to use a LOCAL_TRANSACTION
connection. For information about these specific configuration options,
see “Configuring BasicNotifications” on page 153.
Driver Enables you to use multiple versions of the JDBC driver JAR file(s) which
Group are used to connect to different versions of the database.
The Driver Group field lists the Default and the user created folders
located at Integration Server_directory/instances/instance_name/
packages/WmJDBCAdapter/code/jars.
Note:
Ensure that none of the related driver JAR file(s) of other versions are
placed inside any of the classpaths of Integration Server:
68 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
4 Adapter for JDBC Connections
Field Description/Action
Default driver group classpath: Integration Server_directory/
instances/instance_name/packages/WmJDBCAdapter/code/jars
Static folder classpath: Integration Server_directory/
instances/instance_name/packages/WmJDBCAdapter/code/jars/
static
Integration Server common library classpath:
Integration Server_directory/common/lib
For more information, see “Installing a JDBC Driver on Integration
Server” on page 65.
Warning:
The Default or Single Version and Multiple Version modes are mutually
exclusive. At any given point of time, you can use the JDBC driver(s)
in one mode only.
DataSource Name of the JDBC driver's DataSource or XADataSource class. Type the
Class DataSource or XADataSource class names, depending on the JDBC driver
and transaction type that the connection will use. For more information
about the datasource for different databases, see “JDBC Driver Specific
Properties” on page 257.
b. Depending on the driver type, some or all of the following fields are required.
Note:
If you use a DataDirect Connect for JDBC driver you must create the package and port
information you enter from this tab. For details, see DataDirect Connect documentation.
Field Description/Action
User* Username that the connection will use to connect to the database.
Note:
You can also update the password programmatically using the
pub.jdbcAdapter:updateConnectionPassword service.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 69
4 Adapter for JDBC Connections
Field Description/Action
Port Port number that the connection must use to connect to the database.
Number
Network A standard JDBC DataSource property to indicate the name of the network protocol
Protocol that the connection will use when connecting to the database.
Other Property specific to the database. You can specify database specific property settings,
Properties table filter property settings, transaction isolation level settings, and driver-dependent
property settings in this field.
Use { } to delimit a combination of multiple key value pairs that use ; (semi-colons)
as delimiters.
TableFilter='<current catalog>'.'Accounting';driverType=oci;
connectionProperties={oracle.jdbc.V8Compatible=true,includeSynonymns=true};
transactionIsolation=2
Note:
Do not enter spaces after the semi-colon.
c. Complete the following fields that appear only if you select IBM webMethods Adapter
for JDBC SSL Connection as the Connection Type.
Field Description/Action
TrustStore Alias/File Path Alias for the truststore file or the fully qualified file name
of the SSL truststore.
KeyStore Alias/File Path Alias for the keystore file or the fully qualified file name
of the SSL keystore.
Note:
For two-way SSL configuration, provide the TrustStore Alias/File Path and KeyStore
Alias/File Path.
70 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
4 Adapter for JDBC Connections
For more information about configuring keystore aliases and truststore aliases for securing
communication with Integration Server, see IBM webMethods Integration Server Administrator’s
Guide.
For more information about JDBC driver specific connection properties, see “JDBC Driver
Specific Properties” on page 257.
Field Description/Action
Enable Enables the connection to use connection pooling. For more information
Connection about connection pooling, see “Adapter Connections” on page 13.
Pooling
Note:
If you plan to enable connection pooling in a clustered environment,
consider the connection pool size. For details, see “Considerations When
Configuring Connections with Connection Pooling Enabled” on page 61.
Minimum Pool If connection pooling is enabled, this field specifies the number of connections
Size to create when the connection is enabled. The adapter will keep open the
number of connections you configure here regardless of whether these
connections become idle.
Maximum Pool If connection pooling is enabled, this field specifies the maximum number
Size of connections that can exist at one time in the connection pool.
Pool Increment If connection pooling is enabled, this field specifies the number of connections
Size by which the pool will be incremented if connections are needed, up to the
maximum pool size.
Block Timeout If connection pooling is enabled, this field specifies the number of
milliseconds that Integration Server will wait to obtain a connection with
the database before it times out and returns an error. For example, you have
a pool with Maximum Pool Size of 20. If you receive 30 simultaneous
requests for a connection, 10 requests will be waiting for a connection from
the pool. If you set the Block Timeout to 5000, the 10 requests will wait for
a connection for 5 seconds before they time out and return an error. If the
services using the connections require 10 seconds to complete and return
connections to the pool, the pending requests will fail and return an error
message stating that no connections are available. If you set the Block
Timeout value too high, you may encounter problems during error
conditions. If a request contains errors that delay the response, other requests
will not be sent. This setting must be tuned in conjunction with the Maximum
Pool Size to accommodate such bursts in processing.
Expire Timeout If connection pooling is enabled, this field specifies the number of
milliseconds that an inactive connection can remain in the pool before it is
closed and removed from the pool. The connection pool will remove inactive
connections until the number of connections in the pool is equal to the
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 71
4 Adapter for JDBC Connections
Field Description/Action
Minimum Pool Size. The inactivity timer for a connection is reset when the
connection is used by the adapter.
If you set the Expire Timeout value too high, you may have a number of
unused inactive connections in the pool. This consumes local memory and
a connection on your backend resource. This could have an adverse effect if
your resource has a limited number of connections.
If you set the Expire Timeout value too low, performance could degrade
because of the increased activity of creating and closing connections. This
setting must be tuned in conjunction with the Minimum Pool Size to avoid
excessive opening/closing of connections during normal processing.
Startup Retry Number of times that the system must attempt to initialize the connection
Count pool at startup if the initial attempt fails. The default is 0.
Startup Number of seconds that the system must wait between attempts to initialize
Backoff the connection pool.
Timeout
Heart Beat If the connection pooling is enabled and the minimum pool size is more than
Interval zero, the Heart Beat Interval is applicable. The connection pool checks the
connectivity of the connections that are idle for the value of Heart Beat
Interval. The default value for Heart Beat Interval is zero and it is mentioned
in seconds. For example, if the value of Heart Beat Interval is 25 seconds,
connection pool looks for connection that are idle for 25 seconds. If the
connection is broken then the connection pool is reset.
The feature is applicable for Integration Server 10.5 and all subsequent
versions.
The connection you created appears on the adapter's Connections screen and in Designer.
You can enable a connection only if the parameters for the connection are valid.
Note:
72 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
4 Adapter for JDBC Connections
Use a ; (semi-colon) to delimit table filter, transaction isolation level, and driver-dependent
property settings. Do not enter spaces after the semi-colon. For example: TableFilter=‘<current
catalog>'.‘Accounting';driverType=oci
Use the following format to enter table filter property settings in the Other Properties field:
TableFilter=‘catalog1'.‘schema1'.‘table1',
‘catalog2'.‘schema2'.‘table2',‘catalogN'.‘schemaN'
For example:
TableFilter=‘Payables'.‘Accounting'.‘Finance'
Note:
The TableFilter setting is case-sensitive. Be sure that the names you enter match the names in
the database table. If you use ‘<current catalog>' or ‘<current schema>' described below, be
sure that you use all lowercase letters.
When configuring the TableFilter property, you can use the following rules:
Use Purpose
<current catalog> Use the catalog for the default login catalog.
Note:
Informix databases automatically access the current catalog only.
table Table name pattern. The table is an optional field. If you do not specify a table
value, Adapter for JDBC loads all of the tables for the schema. The following
example lists all the tables under the Accounting schema:
TableFilter=‘<current catalog>'.‘Accounting'
% (percent) Use the % to match any substring of zero or more characters. The following
example lists all the tables under the Accounting schema named Finance,
Finance1, FinanceDept, and so forth:
TableFilter=‘<current catalog>'.
‘Accounting'.‘Finance%'
, (commas) Use the , to list multiple TableFilter settings. Do not enter spaces after the comma.
For example:
TableFilter=‘<current catalog>'.‘Accounting'.
‘Finance_',‘<current catalog>'.‘Employee%'
_ (underscore) Use the _ to match any one character. The following example lists all the tables
under the Accounting schema named Finance1, Finance2, Finance3, and so forth:
TableFilter=‘<current catalog>'.‘Accounting'.‘Finance_'
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 73
4 Adapter for JDBC Connections
Use Purpose
; (semi-colons) Use the ; to delimit multiple property settings: TableFilter settings, transaction
isolation level settings, and driver-dependent settings. Do not enter spaces after
the semi-colon. For example:
TableFilter=‘<current catalog>'.‘Accounting'.
‘Finance_',‘<current catalog>'.‘Accounting';
transactionIsolation=2;driverType=thin
Note:
Use a ; (semi-colon) to delimit table filter, transaction isolation level, and driver-dependent
property settings. Do not enter spaces after the semi-colon. For example: TableFilter=‘<current
catalog>'.‘Accounting';driverType=oci
Use the following format to specify the transaction isolation levels of the database:
transactionIsolation=value
You can specify only one transaction isolation level for a connection. The commonly used transaction
isolation levels and their values are:
TRANSACTION_READ_UNCOMMITTED 1
TRANSACTION_READ_COMMITTED 2
TRANSACTION_REPEATABLE_READ 4
TRANSACTION_SERIALIZABLE 8
For information about the transaction isolation levels supported by your database, refer to your
database documentation.
If you do not specify the isolation level in the Other Properties field, the default isolation level
of the database is considered. If you specify an isolation level that is not supported by the database,
an error is thrown while enabling the connection.
74 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
4 Adapter for JDBC Connections
In the Other Properties field, type the driver-dependent parameters based on the JDBC driver
and the transaction type the connection is using.
For more information about the database specific properties, see “JDBC Driver Specific
Properties” on page 257.
Kerberos Authentication
Kerberos is an authentication protocol that uses symmetric encryption and a trusted third-party
system to validate the identity of clients. The Kerberos protocol provides authentication over open
and insecure networks in which communication between the hosts can be intercepted. You can
use Integration Server to enable and configure Kerberos authentication for service requests.
Field Description
Key Distribution Center Optional. Host name of the machine on which the KDC resides.
Host
Kerberos Configuration Location of the Kerberos configuration file that contains the
File Kerberos configuration information, including the locations of
KDCs, defaults for the realm and for Kerberos applications, and
the host names and Kerberos realms mappings
Use Subject Credentials Specifies whether Integration Server requires a Kerberos V5 Generic
Only Security Services (GSS) mechanism to obtain the necessary
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 75
4 Adapter for JDBC Connections
Field Description
For more information about configuring Integration Server to use Kerberos, see IBM
webMethods Integration Server Administrator’s Guide.
If you decide to create a login module configuration file, the file must follow this format:
<name> {
<LoginModule> <flag> <LoginModule options>;
<optional_additional_LoginModules, flags_and_options>;
};
Example of a login module configuration file for Microsoft SQL Server JDBC driver:
SQLJDBCDriver {
com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true;
};
Note:
The name of the login module configuration file can be fixed or variable, depending on the
driver, and can be optionally passed as a connection property. For Microsoft SQL Server
JDBC driver, the name of the login module configuration file can optionally be passed using
connection property jaasConfigurationName, thereby allowing each connection to have its
own login configuration.
Example of Kerberos ticket cache authentication for Microsoft SQL Server JDBC driver:
SQLJDBCDriver {
com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true;
};
The keytab file specifies the service principal. Example of Kerberos keytab file authentication
for Microsoft SQL Server JDBC driver:
SQLJDBCDriver {
com.sun.security.auth.module.Krb5LoginModule
required useKeyTab=true
keyTab="c:\ibm\joe_analyst.keytab"
principal="joe_analyst/[email protected]";
76 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
4 Adapter for JDBC Connections
};
Note:
Key pair authentication is currently supported in Adapter for JDBC for Snowflake database
only.
Follow the steps given below to setup the key pair authentication between the Adapter for JDBC
and the Snowflake database. To set up key pair authentication:
2. Open a terminal or command prompt to use OpenSSL commands to generate the key pair.
For example:
openssl req -x509 -newkey rsa:2048 -keyout privatekey.pem -out my_cert.pem
-sha256 -days 730 -nodes -subj
"/C=US/ST=Ohio/L=Columbus/O=Software Co/OU=Adapters/CN=soco"
This command will generate a 2048-bit RSA private key in PEM format, for example:
—–BEGIN PRIVATE KEY—–
MIIE6TjjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu/3pg9veETm
—–END PRIVATE KEY—–
4. Using the private key, you can generate the corresponding public key using the following
command:
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 77
4 Adapter for JDBC Connections
For example:
openssl rsa -in privatekey.pem -pubout -out pubkey.pub
This command will extract the public key from the private key in PEM format. For example:
—–BEGIN PUBLIC KEY—
MIIBIjjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu/3pg9veETm
—–END PUBLIC KEY—–
Securely store both the private and public keys in a local directory and record the path to the
files. Encrypt the private key using the passphrase.
5. Using the private key generated in step 3, generate a keystore file in either PKCS#12 or JKS
format using the following command:
openssl pkcs12 -export -name {alias} -in {cert.pem} -inkey {privatekey.pem}
-out {key.p12}
For example:
openssl pkcs12 -export -name privatekey -in my_cert.pem -inkey privatekey.pem
-out mykeystore.p12
Note:
Use the keystore file generated in this step to create a keystore alias and use it for key pair
authentication. For more information on keystore and creating keystore alias, see the IBM
webMethods Integration Server Administrator’s Guide.
2. Assign the public key derived from the private key to your Snowflake user to enable key pair
authentication.
Alter the user to use key pair authentication using the following command in Snowflake and
replace rsa_public_key with the content from your public key file.
ALTER USER <your_username> SET RSA_PUBLIC_KEY='<your_public_key>'
For example:
ALTER USER JOHN SET
RSA_PUBLIC_KEY='MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtD7m97G2h9sNdkWeDBey
FhgUPLu2wbccYXT3vXwDudL2qFm7W6PxVaEj/k1bFeKcOHDI2jVVeHzU1awg1wxBJ3Jd2GJ9dYNmjGho
vLSrthbKbGMavlwU +QIDAQAB'
Note:
You must have the ACCOUNTADMIN role to make edits to a user.
78 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
4 Adapter for JDBC Connections
3. Use the altered user in Snowflake Worksheets to verify key pair authentication.
1. Select the IBM webMethods Adapter for JDBC SSL Connection as the Connection Type.
2. Specify Key Store Alias/File path in the Key Store Alias/File path field in the Connection
Properties.
General Constraints
When you reload the adapter values after modifying an existing StoredProcedureWithSignature
service at the backend, the service parameters are updated, but the input fields are not updated.
To work around this limitation:
Add new arguments to the end of the argument list in the stored procedure definition. Do
not add new arguments in-between existing arguments in the list.
When you change the order of the service parameters, you must re-edit the input fields
for the parameters manually.
Important:
At run time, you can change either the credentials (user name and password) or the connection
name associated with a specific service, but not both at the same time. If you override both the
credentials and the connection name, Adapter for JDBC takes into account only the connection
name override.
To override the default connection, you must code your flow to pass a value through the pipeline
into a service's $connectionName field.
For example, you have a flow whose primary purpose is to update a production database. However,
you want the flow to have the capability to update a test database, with the decision of which
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 79
4 Adapter for JDBC Connections
database to update to be made programmatically at runtime. The output signature of the flow's
first service contains a field called Target. The flow could branch based on the value in Target. If
Target contains the value Production, the second service in the flow would ignore $connectionName,
thus using its default connection to connect to (and then update) the production database. However,
if Target contains the value Test, the second service in the flow would use the value in the
$connectionName from the pipeline and connect to (and then update) the test database.
Both connections, the default and override, must use the same database schema.
The connection with which you override the default (that is, the value provided for
$connectionName) must be configured to use the same transaction type as the default
connection.
For more information, see “Changing the Connection Associated with an Adapter Service at Run
Time” on page 21.
For more information, see “Changing the User Credentials of a Service's Associated Connection
at Run Time” on page 21.
1. In the Adapters menu in Integration Server Administrator's navigation area, click IBM
webMethods Adapter for JDBC.
80 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
4 Adapter for JDBC Connections
When using the adapter with Integration Server 8.0 and later, you can sort and filter the list
of connections that appears on the Connections screen.
To sort information on the Connections screen, click the Up and Down arrows at the top
of the column you want to sort.
2. Type the criterion by which you want to filter into the Filter criteria box. Filtering is
based on the node name, not the connection alias. To locate all connections containing
specific alphanumeric characters, use asterisks (*) as wildcards. For example, if you
want to display all connections containing the string "abc", type *abc* in the Filter
criteria box.
3. Click Submit. The Connections screen displays the connections that match the filter
criteria.
The Connections screen appears, listing all the current connections. You can control
the number of connections that are displayed on this screen. For more information, see
“Controlling Pagination” on page 46.
2. On the Connections screen, click the icon for the connection you want to see.
The View Connection screen displays the parameters for the connection. For descriptions of
the connection parameters, see “Configuring Adapter for JDBC Connections” on page 66.
3. Click Return to IBM webMethods Adapter for JDBC Connectionsto return to the main
connections screen.
1. From the Designer navigation area, open the package and folder in which the connection is
located.
The parameters for the connection appear on the Connection Information tab. For descriptions
of the connection parameters, see “Configuring Adapter for JDBC Connections” on page 66.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 81
4 Adapter for JDBC Connections
To edit a connection
1. In the Adapters menu in Integration Server Administrator's navigation area, click IBM
webMethods Adapter for JDBC.
2. Make sure that the connection is disabled before editing it. For instructions, see “Disabling
Adapter Connections” on page 84.
3. On the Connections screen, click the icon for the connection you want to edit.
The Edit Connection screen displays the current parameters for the connection. Update the
connection's parameters by typing or selecting the values you want to specify.
For descriptions of the connection parameters, see “Configuring Adapter for JDBC
Connections” on page 66.
4. Click Save Changes to save the connection and return to the Connections screen.
To copy a connection
1. In the Adapters menu in Integration Server Administrator's navigation area, click Adapter
for JDBC.
2. On the Connections screen, click the icon for the connection you want to copy.
The Copy Connection screen displays the current parameters for the connection you want to
copy. Name the new connection, specify a package name and folder name, and edit any
connection parameters as needed by typing or selecting the values you want to specify.
Note:
When you copy a connection, the new connection does not save the password of the original
connection. You must enter and then retype the password before you can save the new
connection.
82 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
4 Adapter for JDBC Connections
For descriptions of the connection parameters, see “Configuring Adapter for JDBC
Connections” on page 66.
3. Click Save Connection Copy to save the connection and return to the Connections screen.
If you delete a Adapter for JDBC connection, the adapter services or notifications that are defined
to use the connection will no longer work. However, you can assign a different connection to an
adapter service and re-use the service. To do this, use the setAdapterServiceNodeConnection built-in
service. For more information, see “Changing the Connection Associated with an Adapter Service
or Notification at Design Time” on page 20.
To delete a connection
1. In the Adapters menu in the Integration Server Administrator navigation area, click Adapter
for JDBC.
2. Make sure that the connection is disabled before deleting. To disable the connection, click Yes
in the Enabled column and click OK to confirm. The Enabled column now shows No (Disabled)
for the connection.
3. On the Connections screen, click for the connection you want to delete.
Note:
When you reload a package that contains enabled connections, the connections will automatically
be enabled when the package reloads. If the package contains connections that are disabled,
they will remain disabled when the package reloads.
To enable a connection
1. In the Adapters menu in the Integration Server Administrator navigation area, click Adapter
for JDBC.
2. On the Connections screen, click No in the Enabled column for the connection you want to
enable.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 83
4 Adapter for JDBC Connections
Integration Server Administrator enables the adapter connection and displays a and Yes in
the Enabled column.
To disable a connection
1. In the Adapters menu in the Integration Server Administrator navigation area, click Adapter
for JDBC.
2. On the Connections screen, click Yes in the Enabled column for the connection you want to
disable.
The adapter connection becomes disabled and you see a No in the Enabled column.
84 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
5 Using Command Central to Manage Adapter for
JDBC
■ Adapter for JDBC Configuration Types ........................................................................... 86
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 85
5 Using Command Central to Manage Adapter for JDBC
webMethods Adapter for JDBC Connections The connection for Adapter for
JDBC.
To create, edit, view, or delete an item for an Adapter for JDBC configuration type
1. Select the Integration Server environment from the Environment pane, then click the IBM
webMethods Adapter for JDBC from the Instances tab.
3. Command Central displays the Connections screen for Adapter for JDBC configuration type.
4. To create a connection for Adapter for JDBC connection configuration type, click . Enter
the required values in the displayed fields and click Save.
Note:
For more information about the usage and field descriptions of the Adapter for JDBC
configuration types, see “Configuring Adapter for JDBC Connections” on page 66
5. To edit a connection, click the corresponding connection configuration type that you want to
update and click Edit. Make the necessary changes and click one of the following:
To enable the connection, select the Yes radio button in the Enabled field of the Connection
State section. By default, No radio button is selected.
6. To view the connection details, click on the connection name of the newly created connection.
86 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
5 Using Command Central to Manage Adapter for JDBC
7. To delete a connection, click the connection configuration type that you want to delete and
click .
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 87
5 Using Command Central to Manage Adapter for JDBC
88 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
6 Adapter Services
■ Overview of Adapter Services ........................................................................................ 90
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 89
6 Adapter Services
1. Start your Integration Server and Integration Server Administrator, if they are not already
running.
2. Make sure you have Integration Server Administrator privileges so that you can access Adapter
for JDBC's administrative screens. For information about setting user privileges, see the IBM
webMethods Integration Server Administrator’s Guide for your release.
3. Be sure to check “JDBC Driver Specific Properties” on page 257 for a list of known limitations
for your database driver since it may affect how you configure your connections and adapter
services.
4. If you have made changes to the table schema for a given adapter service, be sure to update
the adapter service accordingly.
5. Using Integration Server Administrator, make sure the WmJDBCAdapter package is enabled.
For instructions, see “Enabling Packages” on page 55.
6. Using Integration Server Administrator, configure an adapter connection to use with the
adapter service. For instructions, see “Configuring Adapter for JDBC Connections” on page 66.
Note:
Integration Server provides a built-in service you can use at design time to change the
connection associated with an adapter service. For more information, see “Changing the
Connection Associated with an Adapter Service or Notification at Design Time” on page 20.
8. Using Designer, create a user-defined package to contain the service, if you have not already
done so. When you configure adapter services, you should always define them in user-defined
packages rather than in the WmJDBCAdapter package. For more information about managing
packages for the adapter, see “Overview of Package Management” on page 54.
90 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
6 Adapter Services
Be sure to review the section “Before Configuring or Managing Adapter Services” on page 90
before you configure adapter services.
1. In Designer, right-click the package in which the service should be contained and select New
> Adapter Service.
2. Select the parent namespace, type a name for the adapter service, and click Next.
3. Select Adapter for JDBC as the adapter type and click Next.
5. From the list of available templates, select the SelectSQL template and click Finish.
The adapter service editor for the adapter service appears. You can select the Adapter Settings
tab at any time to confirm adapter service properties such as the Adapter Name, Adapter
Connection Name, and Adapter Service Template, as necessary.
6. Select the Tables tab to configure the database table (or tables) the operation accesses, using
the following fields:
Field Description/Action
Table Alias The table alias is assigned automatically when you select more than one table
in the Table Name field. The default is t1.
Table Name Select a table name. The default for the associated catalog name is current
catalog. The default for the associated schema name is current schema. The
table name must not contain a period. If the table name does contain a period,
Designer will throw an error.
Note:
Informix databases do not allow you to specify a catalog and database name
because you can only access the current catalog.
Type The type displays automatically based on the table you select.
7. If you are not joining tables, skip this step. Select the Joins tab to specify the columns for
joining the tables you just configured.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 91
6 Adapter Services
b. Select Left Column and select the first table's joining column.
d. Select Right Column and select the next table's joining column.
e. Repeat this procedure until you have defined all the joins.
8. Use the SELECT tab to define the columns and fields to be selected as follows:
a. In the ALL/DISTINCT field, select ALL to include duplicate rows or DISTINCT to suppress
duplicate rows. Selecting ALL corresponds to the SQL statement SELECT ALL name from
tablename. The default value is blank, which corresponds to the SQL statement SELECT
name from tablename.
b. Use the icon to create new rows as needed. You can use the icon to fill in all rows to
the table.
c. As you insert additional rows, the corresponding Column Type, JDBC Type, Output
Field Type, and Output Field display for each column you select in the Expression field.
Field Description/Action
Column Type The column data type defined in the database table.
Output Field Type The data type of the output field. Adapter for JDBC automatically
converts database-specific types to Java data types. For a list of JDBC
type to Java type mappings, see “JDBC Data Type to Java Data Type
Mappings” on page 216.
Output Field The name of the field containing the output from the SELECT
operation. An output field name displays when you select an
expression. You can also modify the output field names as required.
Sort Order Specifies how rows are returned as follows: Select either Ascend or
Descend. Leave the field blank if there is no sort order.
Maximum Row Use this field only to specify the maximum number of records to
retrieve from the database. The default value of 0 (no limit) retrieves
all records.
92 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
6 Adapter Services
Field Description/Action
This value is the amount of time Adapter for JDBC waits for the service
to execute before stopping the SQL operation.
The time out specified in the Query Time Out field is not guaranteed
but depends on the implementation specific to the driver vendor. The
JDBC standard Statement.SetQueryTimeout() method relies on the
Statement.cancel() method. When execution takes longer than the
specified time-out interval, the monitor thread calls Statement.cancel().
In some cases, because of a limitation in the Statement.cancel() method,
the time out does not free the thread that invoked the
Statement.execute() method and this may lead to higher waiting times.
The default value is -1. Use the default value to have the service use
the value indicated on the watt.adapter.JDBC.QueryTimeout property
as the time out. If you specify a value equal to 0, or if the
watt.adapter.JDBC.QueryTimeout property is not set, the service
executes without a time out.
If you specify a value greater than 0, the service executes with the
specified value as the time out.
Note:
-1 is the only permissible negative value for this field.
Result Field Specify a name for the output field that must contain the total number
of rows affected by the SQL statement. Do not use results as the value
of the Result Field.
9. Use the WHERE tab to specify the conditions for selecting information:
b. Select a logical operator from the AND/OR field, an Operator, and separators (the left and
right parentheses) as needed, and specify values for the following fields:
Field Description/Action
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 93
6 Adapter Services
Field Description/Action
Column The name of the column you want to use in the WHERE
clause.
Operator The operator used with the Column and Input Field.
Input Field The default value is ?, which acts as a placeholder for the
variable so that you can set the input variable for that column
at run time, or get input external to this adapter service. You
can also type a fixed value in this field now or at run time.
If you type a fixed value, be sure that it is valid, or an
exception will be generated at run time.
Field Description
Column (second occurrence The name of the column you want to use in the WHERE
of this field) clause.
Input Field Type The corresponding input field's Java type. For a list of JDBC
type to Java type mappings, see “JDBC Data Type to Java
Data Type Mappings” on page 216.
Input Field (second The name of the input field. By default the name combines
occurrence of this field) the values of the Parameter and Column fields. However,
you can also choose to specify any custom value.
Note:
For Oracle users, if you use a CHAR(n) data type and enter a value in the Input Field,
Adapter for JDBC automatically sets the ORACLEFIXED_CHAR data type as the JDBC
data type.
Note:
The WHERE clause does not support the java.sql.Array data type.
c. If necessary, use the or icons to change the order of the WHERE clause to ensure the
parameters are parsed in the correct order.
d. Repeat this procedure until you have specified all WHERE parameters.
94 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
6 Adapter Services
Be sure to review the section “Before Configuring or Managing Adapter Services” on page 90
before you configure adapter services.
1. In Designer, right-click the package in which the service should be contained and select New
> Adapter Service.
2. Select the parent namespace, type a name for the adapter service, and click Next.
3. Select Adapter for JDBC as the adapter type and click Next.
5. From the list of available templates, select the InsertSQL template and click Finish.
The adapter service editor for the adapter service appears. You can select the Adapter Settings
tab at any time to confirm adapter service properties such as the Adapter Name, Adapter
Connection Name, and Adapter Service Template, as necessary.
6. Select the Table tab to configure the database table to be updated and set the fields as follows:
Field Description/Action
Table Name Select a table name. The default for the associated catalog name is current
catalog. The default for the associated schema name is current schema. The
table name must not contain a period. If the table name does contain a period,
Designer will throw an error.
Note:
Informix databases do not allow you to specify a catalog and database name
because you can only access the current catalog.
Type The table type displays automatically based on the table you select.
7. Select the INSERT tab and use the Column, Column Type, JDBC Type and Expression fields
on the top row of the tab to define the columns and fields to be inserted as described in the
following table.
a. Use the icon to create new rows as needed. You can use the icon to fill in all rows to
the table.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 95
6 Adapter Services
Field Description/Action
Column Type The INSERT column data type in the database table.
Expression The default value is ?, which acts as a placeholder for the variable so that
you can set the input variable for that column at run time, or get input
external to this adapter service. It adds one row with the same column
name to the table. You can also type a fixed value in this field now or at
run time. If you type a fixed value, be sure that it is valid, or an exception
will be generated at run time.
b. For each inserted row that uses the default Expression value of ?, the corresponding JDBC
Type, Input Field, and Input Field Type display on the second row of the INSERT tab.
Field Description/Action
Column Type The INSERT column data type in the database table.
Input Field* The input field name. You can change this name if needed.
Input Field Type The data type of the input field. You can change this type if needed.
Note:
For Oracle users, if you use a CHAR(n) data type and enter a value in the Input Field,
Adapter for JDBC automatically sets the ORACLEFIXED_CHAR data type as the JDBC
data type.
c. Specify the query time out value of the InsertSQL service you are configuring in the
following field:
Field Description/Action
This value is the amount of time Adapter for JDBC waits for the service
to execute before stopping the SQL operation.
The time out specified in the Query Time Out field is not guaranteed
but depends on the implementation specific to the driver vendor. The
JDBC standard Statement.SetQueryTimeout() method relies on the
96 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
6 Adapter Services
Field Description/Action
The default value is -1. Use the default value to have the service use
the value indicated on the watt.adapter.JDBC.QueryTimeout property
as the time out. If you specify a value equal to 0, or if the
watt.adapter.JDBC.QueryTimeout property is not set, the service
executes without a time out. If you specify a value greater than 0, the
service executes with the specified value as the time out.
Note:
-1 is the only permissible negative value for this field.
8. Use the Result tab's Result Field and Result Field Type to specify the output field name and
corresponding field types for the resulting number of rows that have been inserted.
Be sure to review the section “Before Configuring or Managing Adapter Services” on page 90
before you configure adapter services.
1. In Designer, right-click the package in which the service should be contained and select New
> Adapter Service.
2. Select the parent namespace, type a name for the adapter service, and click Next.
3. Select Adapter for JDBC as the adapter type and click Next.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 97
6 Adapter Services
5. From the list of available templates, select the UpdateSQL template and click Finish.
The adapter service editor for the adapter service appears. You can select the Adapter Settings
tab at any time to confirm adapter service properties such as the Adapter Name, Adapter
Connection Name, and Adapter Service Template, as necessary.
6. Select the Table tab to configure the database table to be updated and set fields as follows:
Field Description/Action
Table Name Select a table name. The default for the associated catalog name is current
catalog. The default for the associated schema name is current schema. The
table name must not contain a period. If the table name does contain a period,
Designer will throw an error.
Note:
Informix databases do not allow you to specify a catalog and database name
because you can only access the current catalog.
Type The table type displays automatically based on the table you select.
7. Select the UPDATE tab and use the Column, Column Type, JDBC Type and Expression
fields on the top row of the tab to define the columns and fields, as follows:
a. Use the icon to create new rows as needed. You can use the icon to fill in all rows to
the table.
Field Description/Action
Column Type The UPDATE column data type in the database table.
Expression The default value is ?, which acts as a placeholder for the variable so that
you can set the input variable for that column at run time, or get input
external to this adapter service. It adds one row with the same column
name to the table. You can also type a fixed value in this field now or at
run time. If you type a fixed value, be sure that it is valid, or an exception
will be generated at run time.
b. If you insert additional rows using the default Expression value of ?, the corresponding
JDBC Type, Input Field and Input Field Type display on the second row of the UPDATE
tab:
98 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
6 Adapter Services
Field Description/Action
Column Type The column data type defined in the database table.
Input Field The input field name. You can change this name if needed.
Input Field The data type of the input field. You can change this type if needed.
Type
Note:
For Oracle users, if you use a CHAR(n) data type and enter a value in the Input Field,
Adapter for JDBC automatically sets the ORACLEFIXED_CHAR data type as the JDBC
data type.
c. Specify the query time out value of the UpdateSQL service you are configuring in the
following field:
Field Description/Action
The time out specified in the Query Time Out field is not guaranteed
but depends on the implementation specific to the driver vendor. The
JDBC standard Statement.SetQueryTimeout() method relies on the
Statement.cancel() method. When execution takes longer than the
specified time-out interval, the monitor thread calls Statement.cancel().
In some cases, because of a limitation in the Statement.cancel() method,
the time out does not free the thread that invoked the
Statement.execute() method and this may lead to higher waiting times.
The default value is -1. Use the default value to have the service use
the value indicated on the watt.adapter.JDBC.QueryTimeout property
as the time out. If you specify a value equal to 0, or if the
watt.adapter.JDBC.QueryTimeout property is not set, the service
executes without a time out. If you specify a value greater than 0, the
service executes with the specified value as the time out.
Note:
-1 is the only permissible negative value for this field.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 99
6 Adapter Services
8. Use the WHERE tab to specify the conditions for selecting information:
b. Select a logical operator from the AND/OR field, an Operator, and separators (the left and
right parentheses) as needed.
Field Description/Action
Column The name of the column you want to use in the WHERE clause.
Operator The operator used with the Column and Input Field.
Input Field* The default value is ?, which acts as a placeholder for the variable so that
you can set the input variable for that column at run time, or get input
external to this adapter service. You can also type a fixed value in this field
now or at run time. If you type a fixed value, be sure that it is valid, or an
exception will be generated at run time.
Field Description
Column (second occurrence The name of the column you want to use in the WHERE
of this field) clause.
Input Field Type The corresponding input field's Java type. For a list of JDBC
type to Java type mappings, see “JDBC Data Type to Java
Data Type Mappings” on page 216.
Input Field (second The name of the input field. By default the name combines
occurrence of this field) the values of the Parameter and Column fields. However,
you can also choose to specify any custom value.
Note:
For Oracle users, if you use a CHAR(n) data type and enter a value in the Input Field,
Adapter for JDBC automatically sets the ORACLEFIXED_CHAR data type as the JDBC
data type.
Note:
The WHERE clause does not support the java.sql.Array data type.
100 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
6 Adapter Services
9. Use the Result tab's Result Field and Result Field Type to specify the output field name and
corresponding field types for the resulting number of rows that have been inserted.
Be sure to review the section “Before Configuring or Managing Adapter Services” on page 90
before you configure adapter services.
Note:
BatchInsertSQL services cannot be used with a Teradata database (any version).
1. In Designer, right-click the package in which the service should be contained and select New
> Adapter Service.
2. Select the parent namespace, type a name for the adapter service, and click Next.
3. Select Adapter for JDBC as the adapter type and click Next.
Note:
For BatchInsertSQL services, you must use a LOCAL_TRANSACTION connection. If you
do not use LOCAL_TRANSACTION, you will not see a list of tables in the Tables tab. Also,
you may not see an error message until you reload metadata values or check the error log.
For instructions for creating a LOCAL_TRANSACTION connection, see “Configuring
Adapter for JDBC Connections” on page 66. For information about reloading metadata
values, see “Reloading Adapter Values” on page 179.
5. From the list of available templates, select the BatchInsertSQL template and click Finish.
The adapter service editor for the adapter service appears. You can select the Adapter Settings
tab at any time to confirm adapter service properties such as the Adapter Name, Adapter
Connection Name, and Adapter Service Template, as necessary.
6. Select the Table tab to configure the database table to be updated and set the fields as follows:
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 101
6 Adapter Services
Field Description/Action
Table Name Select a table name. The default for the associated catalog name is current
catalog. The default for the associated schema name is current schema. The
table name must not contain a period. If the table name does contain a period,
Designer will throw an error.
Note:
Informix databases do not allow you to specify a catalog and database name
because you can only access the current catalog.
Type The table type displays automatically based on the table you select.
7. Select the INSERT tab and use the Column, Column Type, JDBC Type, and Expression
fields on the top row of the tab to define the columns and fields to be inserted as described in
the following table.
a. Use the icon to create new rows as needed. You can use the icon to fill in all rows to
the table.
Field Description/Action
Column Type The INSERT column data type in the database table.
Expression The default value is ?, which acts as a placeholder for the variable so that
you can set the input variable for that column at run time, or get input
external to this adapter service. It adds one row with the same column
name to the table. You can also type a fixed value in this field now or at
run time. If you type a fixed value, be sure that it is valid, or an exception
will be generated at run time.
b. For each inserted row that uses the default Expression value of ?, the corresponding Input
Field, and Input Field Type display on the second row of the INSERT tab. Use the following
fields:
Field Description/Action
Column Type The INSERT column data type in the database table.
Input Field The input field name. You can change this name if needed.
Input Field Type The data type of the input field. You can change this type if needed.
102 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
6 Adapter Services
Field Description/Action
Note:
If you use WmFlatFile services to generate the document list as
input, the input field type must be java.lang.String. This is because
fields from WmFlatFile services generate documents that have
String fields.
Note:
For Oracle users, if you use a CHAR(n) data type and enter a value in the Input Field,
Adapter for JDBC automatically sets the ORACLEFIXED_CHAR data type as the JDBC
data type.
c. Specify the query time out value of the BatchInsertSQL service you are configuring in the
following field:
Field Description/Action
The time out specified in the Query Time Out field is not guaranteed
but depends on the implementation specific to the driver vendor. The
JDBC standard Statement.SetQueryTimeout() method relies on the
Statement.cancel() method. When execution takes longer than the
specified time-out interval, the monitor thread calls Statement.cancel().
In some cases, because of a limitation in the Statement.cancel() method,
the time out does not free the thread that invoked the Statement.execute()
method and this may lead to higher waiting times.
The default value is -1. Use the default value to have the service use
the value indicated on the watt.adapter.JDBC.QueryTimeout property
as the time out. If you specify a value equal to 0, or if the
watt.adapter.JDBC.QueryTimeout property is not set, the service
executes without a time out. If you specify a value greater than 0, the
service executes with the specified value as the time out.
Note:
-1 is the only permissible negative value for this field.
8. Use the Batch Result tab's Batch Result Output Name to specify the output field name for
the batch operation. The output of the batch operation is a string list. The elements of the string
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 103
6 Adapter Services
list are ordered according to the order in which commands were added to the batch. Depending
on the JDBC driver you use, the elements in the string list may be one of the following:
A number greater than or equal to zero. This indicates that the command was successfully
executed and the number of rows in the database affected.
Note:
BatchUpdateSQL services cannot be used with a Teradata database (any version).
Be sure to review the section “Before Configuring or Managing Adapter Services” on page 90
before you configure adapter services.
1. In Designer, right-click the package in which the service should be contained and select New
> Adapter Service.
2. Select the parent namespace, type a name for the adapter service, and click Next.
3. Select Adapter for JDBC as the adapter type and click Next.
Note:
For BatchUpdateSQL services, you must use a LOCAL_TRANSACTION connection. If you
do not use LOCAL_TRANSACTION, you will not see a list of tables in the Tables tab. Also,
you may not see an error message until you reload metadata values or check the error log.
For instructions for creating a LOCAL_TRANSACTION connection, see “Before Configuring
or Managing Adapter Connections” on page 64. For information about reloading metadata
values, see “Reloading Adapter Values” on page 179.
5. From the list of available templates, select the BatchUpdateSQL template and click Finish.
104 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
6 Adapter Services
The adapter service editor for the adapter service appears. You can select the Adapter Settings
tab at any time to confirm adapter service properties such as the Adapter Name, Adapter
Connection Name, and Adapter Service Template, as necessary.
6. Select the Table tab to configure the database table to be updated and set the fields as follows:
Field Description/Action
Table Name Select a table name. The default for the associated catalog name is current
catalog. The default for the associated schema name is current schema. The
table name must not contain a period. If the table name does contain a period,
Designer will throw an error.
Note:
Informix databases do not allow you to specify a catalog and database name
because you can only access the current catalog.
Type The table type displays automatically based on the table you select.
7. Select the UPDATE tab and use the Column, Column Type, JDBC Type, and Expression
fields on the top row of the tab to define the columns and fields, as follows:
a. Use the icon to create new rows as needed. You can use the icon to fill in all rows to
the table.
Field Description/Action
Column Type The UPDATE column data type in the database table.
Expression The default value is ?, which acts as a placeholder for the variable so that
you can set the input variable for that column at run time, or get input
external to this adapter service. It adds one row with the same column
name to the table. You can also type a fixed value in this field now or at
run time. If you type a fixed value, be sure that it is valid, or an exception
will be generated at run time.
b. If you insert additional rows using the default Expression value of ?, the corresponding
Input Field and Input Field Type display on the second row of the UPDATE tab:
Field Description/Action
Column Type The column data type defined in the database table.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 105
6 Adapter Services
Field Description/Action
Input Field The input field name. You can change this name if needed.
Input Field Type The data type of the input field. You can change this type if needed.
Note:
If you use WmFlatFile services to generate the document list as input,
the input field type must be java.lang.String. This is because fields
from WmFlatFile services generate documents are have String fields.
Note:
For Oracle users, if you use a CHAR(n) data type and enter a value in the Input Field,
Adapter for JDBC automatically sets the ORACLEFIXED_CHAR data type as the JDBC
data type.
c. Specify the query time out value of the BatchUpdateSQL service you are configuring in
the following field:
Field Description/Action
The time out specified in the Query Time Out field is not guaranteed
but depends on the implementation specific to the driver vendor. The
JDBC standard Statement.SetQueryTimeout() method relies on the
Statement.cancel() method. When execution takes longer than the
specified time-out interval, the monitor thread calls Statement.cancel().
In some cases, because of a limitation in the Statement.cancel() method,
the time out does not free the thread that invoked the
Statement.execute() method and this may lead to higher waiting times.
The default value is -1. Use the default value to have the service use
the value indicated on the watt.adapter.JDBC.QueryTimeout property
as the time out. If you specify a value equal to 0, or if the
watt.adapter.JDBC.QueryTimeout property is not set, the service
executes without a time out. If you specify a value greater than 0, the
service executes with the specified value as the time out.
Note:
-1 is the only permissible negative value for this field.
106 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
6 Adapter Services
8. Use the WHERE tab to specify the conditions for selecting information:
b. Select a logical operator from the AND/OR field, an Operator, and separators (the left and
right parentheses) as needed. Use the following fields:
Field Description/Action
Column The name of the column you want to use in the WHERE
clause.
Operator The operator used with the Column and Input Field.
Input Field The default value is ?, which acts as a placeholder for the
variable so that you can set the input variable for that column
at run time, or get input external to this adapter service. You
can also type a fixed value in this field now or at run time. If
you type a fixed value, be sure that it is valid, or an exception
will be generated at run time.
Input Field Type The corresponding input field's Java type. For a list of JDBC
type to Java type mappings, see “JDBC Data Type to Java
Data Type Mappings” on page 216.
Input Field (second Type the name of the input field. If you use the default ?
occurrence of this field) variable placeholder as the Input Field value in the where
clause, be sure to enter the corresponding Input Field and
its JDBC Field Type in the same order as they appear on the
top portion of the WHERE tab.
Note:
The WHERE clause does not support the java.sql.Array data type.
9. Use the Batch Result tab's Batch Result Output Name to specify the output field name for
the batch operation. The output of the batch operation is a string list. The elements of the string
list are ordered according to the order in which commands were added to the batch. Depending
on the JDBC driver you use, the elements in the string list may be one of the following:
A number greater than or equal to zero. This indicates that the command was successfully
executed and the number of rows in the database affected.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 107
6 Adapter Services
Be sure to review the section “Before Configuring or Managing Adapter Services” on page 90
before you configure adapter services.
1. In Designer, right-click the package in which the service should be contained and select New
> Adapter Service.
2. Select the parent namespace, type a name for the adapter service, and click Next.
3. Select Adapter for JDBC as the adapter type and click Next.
5. From the list of available templates, select the DeleteSQL template and click Finish.
The adapter service editor for the adapter service appears. You can select the Adapter Settings
tab at any time to confirm adapter service properties such as the Adapter Name, Adapter
Connection Name, and Adapter Service Template, as necessary.
6. Select the Table tab to configure the database table to be updated and set the fields as follows:
Field Description/Action
Table Name Select a table name. The default for the associated catalog name is current
catalog. The default for the associated schema name is current schema. The
table name must not contain a period. If the table name does contain a period,
Designer will throw an error.
Note:
Informix databases do not allow you to specify a catalog and database name
because you can only access the current catalog.
Type The table type displays automatically based on the table you select.
7. Use the WHERE tab to specify the conditions for selecting information:
b. Select a logical operator from the AND/OR field, an Operator, and separators (the left and
right parentheses) as needed.
108 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
6 Adapter Services
Field Description/Action
Column The name of the column you want to use in the WHERE clause.
Operator The operator used with the Column and Input Field.
Input Field The default value is ?, which acts as a placeholder for the variable so
that you can set the input variable for that column at run time, or get
input external to this adapter service. You can also type a fixed value
in this field now or at run time. If you type a fixed value, be sure that
it is valid, or an exception will be generated at run time.
Field Description
Column (second occurrence The name of the column you want to use in the WHERE
of this field) clause.
Input Field Type The corresponding input field's Java type. For a list of JDBC
type to Java type mappings, see “JDBC Data Type to Java
Data Type Mappings” on page 216.
Input Field (second The name of the input field. By default the name combines
occurrence of this field) the values of the Parameter and Column fields. However,
you can also choose to specify any custom value.
Note:
For Oracle users, if you use a CHAR(n) data type and enter a value in the Input Field,
Adapter for JDBC automatically sets the ORACLEFIXED_CHAR data type as the JDBC
data type.
Note:
The WHERE clause does not support the java.sql.Array data type.
8. Use the Result tab's Result Field and Result Field Type to specify the output field name and
corresponding field types for the resulting number of rows that have been inserted.
9. To verify input or output information for this service, use the Input/Output tab as needed.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 109
6 Adapter Services
If you need to write custom SQL, you can create a service that uses customized SQL statements.
This allows you the flexibility to execute almost any SQL statements required, such as data
management statements and data definition statements, including insert, select, update, and delete.
Because an adapter service that uses custom SQL provides no error checking, be sure that your
SQL statement works correctly. You can verify SQL statement accuracy using your vendor's SQL
utility. For details, see your vendor documentation.
Be sure to review the section “Before Configuring or Managing Adapter Services” on page 90
before you configure adapter services.
Note:
You can use a CustomSQL service to call a stored procedure only when the stored procedure
does not have any OUT/INOUT or return parameters. If you need to use these parameters, use
the StoredProcedure service. For instructions, see “Configuring StoredProcedure Services” on
page 118.
Specify the table select deptno, empno from select d.deptno, e.empno
dept,emp deptno from dept d,emp e where
alias along with the d.deptno = ?
table name if the
SQL query contains
more than one table.
110 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
6 Adapter Services
Column names in select partno as 'partno' from select partno as partno from
emp where partno = 1 emp where partno=1
the SQL query
should not be
enclosed in quotes.
Use the “as” select city dummy from emp select city as dummy from emp
keyword when you
specify an alias for a
column.
Note:
If your SQL query has errors or does not follow the considerations specified in the above table,
the Fill in all rows to the table icon does not populate the input and output parameters. Then
the input and output parameters must be configured manually. You can view the error message
by clicking the Reload values from adapter icon.
1. In Designer, right-click the package in which the service should be contained and select New
> Adapter Service.
2. Select the parent namespace, type a name for the adapter service, and click Next.
3. Select Adapter for JDBC as the adapter type and click Next.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 111
6 Adapter Services
5. From the list of available templates, select the CustomSQL template and click Finish.
The adapter service editor for the adapter service appears. You can select the Adapter Settings
tab at any time to confirm adapter service properties such as the Adapter Name, Adapter
Connection Name, and Adapter Service Template, as necessary.
6. Select the SQL tab to specify a SQL statement and the associated input and output parameters.
Use the icon and to create new rows as needed. You can use the icon to fill in all rows to
the table.
Be sure to review the section “Considerations before using Fill in all rows to the table feature in CustomSQL
Adapter Service” on page 110 before you use the Fill in all rows to the table icon.
Note:
When using the CustomSQL service for a Select SQL, it is not mandatory to configure the
output fields Output JDBC Type, Output Field Type, and Output Field. Adapter for JDBC
uses the fields provided in the Select SQL statement as the output parameter fields.
Field Description/Action
SQL* A SQL statement. If you need more space to type your statement, use
the launch icon to the right to open a text editor window. You can type
the statement directly in this field, for example:
select short_col, int_col, float_col, double_col,
date_col, date_time_col, varchar_col from -ADAPTER-TEST
For variable names, use the ? variable placeholder for each variable. For
example:
select employee_name where StaffID = ? and Dept = ?
Note:
If you use the ? variable placeholders in your SQL statement, be sure
to enter the corresponding Input Field and field type information in
the same order as they appear in your SQL statement. For example,
using the SQL statement above, StaffID would be the first entry in
the Input Field and Dept would be the second entry.
Note:
Do not end your SQL statement with a semi-colon (;) or an exception
will be generated at run time.
Note:
112 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
6 Adapter Services
Field Description/Action
You may paste text into this field from the system clipboard. However,
you may not cut or copy text from this field to the clipboard for pasting
into another application.
Input JDBC Type The JDBC type of the corresponding Input Field.
Input Field Type The Java type that corresponds to the input JDBC type. For a list of JDBC
type to Java type mappings, see “JDBC Data Type to Java Data Type
Mappings” on page 216.
Output JDBC Type The JDBC type of the corresponding Output Field.
Output Field Type The Java type that corresponds to the output JDBC type. For a list of
JDBC type to Java type mappings, see “JDBC Data Type to Java Data
Type Mappings” on page 216.
Maximum Row The maximum number of records to retrieve from the database. The
default value of 0 (no limit) retrieves all records. Use this field only with
SQL statements that return a result set.
Query Time Out Specify the query time out value in seconds.
This value is the amount of time Adapter for JDBC waits for the service
to execute before stopping the SQL operation.
The time out specified in the Query Time Out field is not guaranteed
but depends on the implementation specific to the driver vendor. The
JDBC standard Statement.SetQueryTimeout() method relies on the
Statement.cancel() method. When execution takes longer than the
specified time-out interval, the monitor thread calls Statement.cancel().
In some cases, because of a limitation in the Statement.cancel() method,
the time out does not free the thread that invoked the Statement.execute()
method and this may lead to higher waiting times.
The default value is -1. Use the default value to have the service use the
value indicated on the watt.adapter.JDBC.QueryTimeout property as
the time out.If you specify a value equal to 0, or if the
watt.adapter.JDBC.QueryTimeout property is not set, the service executes
without a time out.If you specify a value greater than 0, the service
executes with the specified value as the time out.
Note:
-1 is the only permissible negative value for this field.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 113
6 Adapter Services
Field Description/Action
Result Field Name of the output field that contains the total number of rows affected
by the SQL statement.
Important:
Adapter for JDBC does not validate the input parameters of a DynamicSQL service for any
malicious SQL injections. When you use a variable input parameter such as the text
${INPUT_FIELD_NAME} in a DynamicSQL service, you must take extra measures to avoid
potential security risks by, for example, using a wrapper service for your DynamicSQL service
that will validate the variable input parameters.
Note:
When using the DynamicSQL service for a Select SQL, it is not mandatory to configure the
output fields Output JDBC Type, Output Field Type, and Output Field. Adapter for JDBC
uses the fields provided in the Select SQL statement as the output parameter fields.
114 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
6 Adapter Services
In this example, the service template will generate an input field for the {where} portion of the
statement. Note that you do not type a semicolon (;) at the end of the SQL statement. Doing so
will generate an exception at run time.
The generated SQL statement will be Select * from table1 where col1>100.
A more extreme example would be to set the SQL field to "${sql}"; in this case, the entire SQL
statement will be set through the input field sql.
Be sure to review the section “Before Configuring or Managing Adapter Services” on page 90
before you configure adapter services.
Note:
You can use a DynamicSQL service to call a stored procedure only when the stored procedure
does not have any OUT/INOUT or return parameters. If you need these parameters, use the
StoredProcedure service. For instructions, see “Configuring StoredProcedure Services” on
page 118.
1. In Designer, right-click the package in which the service should be contained and select New
> Adapter Service.
2. Select the parent namespace, type a name for the adapter service, and click Next.
3. Select Adapter for JDBC as the adapter type and click Next.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 115
6 Adapter Services
5. From the list of available templates, select the DynamicSQL template and click Finish.
The adapter service editor for the adapter service appears. You can select the Adapter Settings
tab at any time to confirm adapter service properties such as the Adapter Name, Adapter
Connection Name, and Adapter Service Template, as necessary.
6. Select the Dynamic SQL tab to specify a SQL statement and the associated input and output
parameters.
Use the icon and set the SQL parameters as described in the table below.
Field Description/Action
SQL A SQL statement. If you need more space to type your statement, use
the launch icon to the right to open a text editor window. You can type
the statement directly in this field, for example:
select short_col, int_col, float_col, double_col,
date_col, date_time_col, varchar_col from ADAPTER-TEST
For variable names, use the ? variable placeholder for each variable.
For example:
select employee_name where StaffID = ? and Dept = ?
Note:
If you use the ? variable placeholders in your SQL statement, be sure
to enter the corresponding Input Field and field type information in
the same order as they appear in your SQL statement. In the above
example, StaffID would be the first entry in the Input Field and Dept
would be the second entry.
Note:
Do not end your SQL statement with a semi-colon (;) or you will
generate an exception.
Note:
You may paste text into this field from the system clipboard.
However, you may not cut or copy text from this field to the clipboard
for pasting into another application.
Input JDBC Type The JDBC type of the corresponding Input Field.
Input Field Type The Java type that corresponds to the input JDBC type. For a list of
JDBC type to Java type mappings, see “JDBC Data Type to Java Data
Type Mappings” on page 216.
116 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
6 Adapter Services
Field Description/Action
Output JDBC Type The JDBC type of the corresponding Output Field.
Output Field Type The Java type that corresponds to the output JDBC type. For a list of
JDBC type to Java type mappings, see “JDBC Data Type to Java Data
Type Mappings” on page 216.
Maximum Row The maximum number of records to retrieve from the database. The
default value of 0(no limit) retrieves all records.Use this field only
with SQL statements that return a result set.
Query Time Out Specify the query time out value in seconds.
This value is the amount of time Adapter for JDBC waits for the service
to execute before stopping the SQL operation.
The time out specified in the Query Time Out field is not guaranteed
but depends on the implementation specific to the driver vendor. The
JDBC standard Statement.SetQueryTimeout() method relies on the
Statement.cancel() method. When execution takes longer than the
specified time-out interval, the monitor thread calls Statement.cancel().
In some cases, because of a limitation in the Statement.cancel() method,
the time out does not free the thread that invoked the
Statement.execute() method and this may lead to higher waiting times.
The default value is -1. Use the default value to have the service use
the value indicated on the watt.adapter.JDBC.QueryTimeout property
as the time out. If you specify a value equal to 0, or if the
watt.adapter.JDBC.QueryTimeout property is not set, the service
executes without a time out. If you specify a value greater than 0, the
service executes with the specified value as the time out.
Note:
-1 is the only permissible negative value for this field.
Result Field Name of the output field that contains the total number of rows affected
by the SQL statement.Do not use results as the value of the Result
Field.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 117
6 Adapter Services
The adapter StoredProcedure service does not support stored procedures that have Array or
Struct as OUT parameters. You can use the StoredProcedureWithSignature service instead.
For information on configuring StoredProcedureWithSignature service, see “Configuring
StoredProcedureWithSignature Services” on page 122.
When operating on a MySQL database, the adapter StoredProcedure service supports stored
procedures, but does not support functions. To call functions, use the
StoredProcedureWithSignature service template instead. For more information about
configuring StoredProcedureWithSignature services, see “Configuring
StoredProcedureWithSignature Services” on page 122.
MySQL 5.0.x does not support stored procedure and function names containing spaces.
When using SAP HANA database, ResultSet tab cannot be configured because the cursor
cannot be returned as output in SAP HANA stored procedures.
Be sure to review the sections “Before Configuring or Managing Adapter Services” on page 90
and “Considerations when Configuring StoredProcedure Adapter Services” on page 118 before
you configure StoredProcedure services.
1. In Designer, right-click the package in which the service should be contained and select New
> Adapter Service.
2. Select the parent namespace, type a name for the adapter service and click Next.
3. Select Adapter for JDBC as the adapter type and click Next.
118 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
6 Adapter Services
5. From the list of available templates, select the StoredProcedure template and click Finish.
The adapter service editor for the adapter service appears. You can select the Adapter Settings
tab at any time to confirm adapter service properties such as the Adapter Name, Adapter
Connection Name, and Adapter Service Template, as necessary.
6. Select the Call tab to specify the stored procedure to call. Use the following fields to set the
Call parameters:
Field Description/Action
Catalog Name The name of the catalog. The default for the catalog name is current
catalog.
Schema Name The name of the schema. The default for the schema name is current
schema.
Enable Procedure To type in the Procedure Name, set this field to False. To select the
Name Lookup Procedure Name from a list, set this field to True. The default is
(Optional) False. To save you time, use the default value (typing the name) if
you know the name of the procedure and you are working with a
large database which may have a long list of procedures.
Procedure Name Type or select the stored procedure name, depending on how you
set the Enable Procedure Name Lookup field.
JDBC Type Specify the JDBC type of the corresponding return field for the stored
procedure.Use the icon to create new rows as needed. You can
use the icon to fill in all rows to the table.
Return Field Name Add return field names for the stored procedure.Use the icon to
create new rows as needed. You can use the icon to fill in all rows
to the table.
Query Time Out Specify the query time out value in seconds.
This value is the amount of time Adapter for JDBC waits for the
service to execute before stopping the SQL operation.
The time out specified in the Query Time Out field is not guaranteed
but depends on the implementation specific to the driver vendor.
The JDBC standard Statement.SetQueryTimeout() method relies on
the Statement.cancel() method. When execution takes longer than
the specified time-out interval, the monitor thread calls
Statement.cancel(). In some cases, because of a limitation in the
Statement.cancel() method, the time out does not free the thread
that invoked the Statement.execute() method and this may lead to
higher waiting times.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 119
6 Adapter Services
Field Description/Action
The default value is -1. Use the default value to have the service use
the value indicated on the watt.adapter.JDBC.QueryTimeout
property as the time out. If you specify a value equal to 0, or if the
watt.adapter.JDBC.QueryTimeout property is not set, the service
executes without a time out. If you specify a value greater than 0,
the service executes with the specified value as the time out.
Note:
-1 is the only permissible negative value for this field.
8. Use the icon to create new stored procedure parameters as needed. You can use the icon
to fill in all rows to the table.
Field Description/Action
Param JDBC Type The JDBC type of the stored procedure parameter.
Expression The default value is ?, which acts as a placeholder for the variable so that
you can set the input variable for that column at run time, or get input
external to this adapter service. It adds one row with the same column
name to the table. You can also type a fixed value as input now or at run
time. If you choose to type a fixed value, you type a stored procedure
call statement with values you set using this field.
Input Type The input parameter Java type. For a list of JDBC type to Java type
mappings, see “JDBC Data Type to Java Data Type Mappings” on
page 216.
Output Type The output parameter Java type. For a list of JDBC type to Java type
mappings, see “JDBC Data Type to Java Data Type Mappings” on
page 216.
9. If the procedure returns a result set, select the ResultSet tab to specify result set parameters
using the fields in the following table.
120 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
6 Adapter Services
Note:
StoredProcedure services can support multiple results sets. The result set can contain nested
cursors.When using the result set that contains nested cursors, the performance of Adapter
for JDBC could degrade. Since the nested cursors are recursively processed, Adapter for
JDBC may also return data that may not be required.
Use the icon to create additional result sets as needed. Use the following fields:
Field Description/Action
Result Set Index An index is automatically assigned to each result set. The first row
default value is 1.
Result Set Name The name of the result set you want to create.
Output Type The Java type of the result column. For a list of JDBC type to Java
type mappings, see “JDBC Data Type to Java Data Type Mappings” on
page 216.
To set this property, use Integration Server Administrator and select Settings > Extended > Edit
Extended Settings. Enter this property in the Extended Settings box:
watt.adapter.JDBC.StoredProcedureMaxCursorIndex=value
where value is the required maximum number of result sets. For example, to return a maximum
number of 30 result sets from the StoredProcedure service, set the property as:
watt.adapter.JDBC.StoredProcedureMaxCursorIndex=30
The value should be greater than zero with no upper limits. However, it is recommended to provide
a value within the practical limits. A large value can lead to an unpredictable behavior of the
system. Instead, you can configure another StoredProcedure adapter service for the next set of
result sets.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 121
6 Adapter Services
For more information about setting the watt properties, see the IBM webMethods Integration Server
Administrator’s Guide for your release.
When using Array as IN or OUT parameter in an Oracle database, the input to the IN parameter
must be a Java array. The OUT parameter returns a Java array as Java data type, java.lang.Object.
MySQL 5.0.x does not support stored procedure and function names containing spaces.
When using SAP HANA database, ResultSet tab cannot be configured because the cursor
cannot be returned as output in SAP HANA stored procedures.
Be sure to review the sections “Before Configuring or Managing Adapter Services” on page 90
and “Considerations when Configuring StoredProcedure Adapter Services” on page 118 before
you configure StoredProcedureWithSignature services.
1. In Designer, right-click the package in which the service should be contained and select New
> Adapter Service.
2. Select the parent namespace, type a name for the adapter service, and click Next.
122 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
6 Adapter Services
3. Select Adapter for JDBC as the adapter type and click Next.
5. From the list of available templates, select the StoredProcedureWithSignature template and
click Finish.
The adapter service editor for the adapter service appears. You can select the Adapter Settings
tab at any time to confirm adapter service properties such as the Adapter Name, Adapter
Connection Name, and Adapter Service Template, as necessary.
6. Select the Call tab to specify the stored procedure to call. Use the following fields to set the
call parameters:
Field Description/Action
Catalog Name Name of the catalog. The default for the catalog name is current
catalog.
Schema Name Name of the schema. The default for the schema name is current schema.
Note:
You can disable the schema lookup performed on the database by
configuring the Schema Name parameter in the Configuration tab.
Procedure Name To save time, you can type all or part of the procedure name in this field
Pattern to narrow your search. This is helpful when dealing with a large
database that has a long list of procedures. Use % as a multi-character
wildcard and _ (underscore) as a single character wildcard.
Note:
With DB2 databases, functions do not appear in the list of procedure
names. Only procedures appear in the list.
Note:
The Procedure Name Pattern field value is not considered if you
disable the store procedure lookup performed on the database.
Procedure Name Select the stored procedure name, depending on the how you set the
Procedure Name Pattern field. If you select <All Procedures>, this
field lists all of the procedures in the selected catalog and schema.
Note:
You can disable the store procedure lookup performed on the
database by configuring the Procedure Name parameter in the
Configuration tab.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 123
6 Adapter Services
Field Description/Action
Specific Name Select the specific name for a stored procedure in a DB2 or DB2 AS/400
(Only for DB2 and database after specifying the Procedure Name.
DB2AS400)
a. The top table on the Call tab lists the following fields and values based on the signature
for the stored procedure:
Field Description/Action
Parameter Type Defines the parameter type as IN, INOUT, or OUT. If you select IN or
INOUT, you may also set the input expression in the Expression field.
Expression* Sets the input for the IN or INOUT parameter types only. The RETURN
or OUT parameters will appear automatically on the Call tab's bottom
table. For a list of the allowable expression settings by parameter type, and
how each parameter will map to the input or output fields, see the following
table.
b. The middle table on the Call tab lists the following input parameters and values for the
stored procedure that will map to the input fields of the service:
Field Description/Action
124 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
6 Adapter Services
Field Description/Action
Input Field Type Input parameter Java data type. For a list of JDBC type to Java data
type mappings, see “JDBC Data Type to Java Data Type
Mappings” on page 216.
c. The bottom table on the Call tab lists the following output parameters and values for the
stored procedure that will map to the output of the service, including the OUT or INOUT
parameters:
Field Description/Action
Output Field Type Output parameter Java data type. For a list of JDBC to Java data
type mappings, see “JDBC Data Type to Java Data Type
Mappings” on page 216.
d. Specify the query time out value of the StoredProcedureWithSignature service you are
configuring in the following field:
Field Description/Action
The time out specified in the Query Time Out field is not guaranteed but depends
on the implementation specific to the driver vendor. The JDBC standard
Statement.SetQueryTimeout() method relies on the Statement.cancel() method. When
execution takes longer than the specified time-out interval, the monitor thread calls
Statement.cancel(). In some cases, because of a limitation in the Statement.cancel()
method, the time out does not free the thread that invoked the Statement.execute()
method and this may lead to higher waiting times.
The default value is -1. Use the default value to have the service use the value
indicated on the watt.adapter.JDBC.QueryTimeout property as the time out. If you
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 125
6 Adapter Services
Field Description/Action
Note:
-1 is the only permissible negative value for this field.
7. Select the Configuration tab to configure the lookup parameters for stored procedure. Use
the following fields to set the parameters and values:
Schema Name Performs a lookup on the database for schema name. Possible values are:
false. Skips the lookup on the database for schema name. The Schema
Name field is now editable and you can enter the value.
Procedure Name Performs a lookup on the database for procedure name. Possible values
are:
false.
Skips the lookup on the database for procedure name. The
Procedure Name field is now editable and you can enter the value.
Note:
The value in the Procedure Name Pattern field is not considered.
8. If the procedure returns a result set, select the ResultSet tab to specify result set parameters
using the fields in the following table.
StoredProcedureWithSignature services can support multiple results sets. The result set can
contain nested cursors.
Note:
When using the result set that contains nested cursors, the performance of Adapter for JDBC
could degrade. Since the nested cursors are recursively processed, Adapter for JDBC may
also return data that may not be required.
Note:
126 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
6 Adapter Services
While all the tables in the Call tab will be updated automatically if the selected stored
procedure changes, the ResultSet tab information is not updated automatically. To update
this information, you must manually update the fields in the ResultSet tab.
Field Description/Action
Result Set Index An index is automatically assigned to each result set. The first
row default value is 1.
Note:
When using for Oracle database, this field is not required.
Result Set Name Name of the result set you want to create.
Note:
When using for Oracle database, this field is not required.
Output Type Java data type of the result column. For a list of JDBC to Java
data type mappings, see “JDBC Data Type to Java Data Type
Mappings” on page 216.
The Input Field Type and Output Field Type supported for
User-defined data types are java.lang.Object and IDATA, an
object of com.wm.data.IData.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 127
6 Adapter Services
The Input Field Type and Output Field Type supported for
User-defined data types are java.lang.Object and
IDATA_ARRAY, an array object of com.wm.data.IData.
128 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
6 Adapter Services
1. In Designer, right-click the package in which the service should be contained and select New
> Adapter Service.
2. Select the parent namespace, type a name for the adapter service, and click Next.
3. Select Adapter for JDBC as the adapter type and click Next.
5. From the list of available templates, select the ExecuteService template and click Finish.
The adapter service editor for the adapter service appears. You can select the Adapter Settings
tab at any time to confirm the adapter service properties such as the Adapter Name, Adapter
Connection Name, and Adapter Service Template, as necessary.
6. Select the Service to Invoke tab to specify the Java or the flow service name that needs the
connection:
Field Description/Action
Service Name The Java or the flow service name that requires a connection from the
connection pool. If you specify an incorrect service name, an exception is
thrown at run time.
For information about setting the package dependencies, see the IBM webMethods Service
Development Help for your release.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 129
6 Adapter Services
Do not use the forbidden methods like close(), setAutoCommit(), and commit() in the service
code. Doing so causes the adapter to throw an exception at run time.
When using the ExecuteService in transactions, it is important for the WmART package to be
aware about any exceptions generated in the service within the transaction SEQUENCE block.
Only then will a roll back of the transaction happen. You can do this by throwing a
ServiceException from the service. You can use the following sample code in the service code
to do so.
java.sql.Connection conn =
(java.sql.Connection)IDataUtil.get(pipeline.getCursor(),
com.wm.adapter.wmjdbc.services.ExecuteService.PIPELINE_CONNECTION);
try
{
java.sql.PreparedStatement pstmt=conn.prepareStatement("insert into Person
values(1,'Chris')");
pstmt.execute();
}
catch(Throwable e)
{
e.printStackTrace();
throw new ServiceException(e);
}
Note:
If an error occurs when using the ExecuteService in a transaction for a Teradata database,
the roll back of transactions does not happen.
For more information about testing and debugging services, see the IBM webMethods Service
Development Help for your release.
1. In Designer, expand the package and folder that contain the service you want to test.
Designer displays the configured service in the service template's Adapter Service Editor.
4. Specify how you want to connect to the database, using either of the following ways:
To connect to a database using a connection that is different than the connection specified
during design time, specify the connection name here:
130 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
6 Adapter Services
Parameter Description
Note:
The database schema of the overridden connection must be the same as that of the default
connection. For more information, see “Dynamically Changing a Service's Connection
at Run Time” on page 79.
To connect to a database using user credentials of a connection that are different than the
user credentials provided when configuring the connection, specify the user name and
password here.
Parameter Description
Note:
If you do not provide the user credentials here, the user credentials specified when the
connection was configured are used. For more information, see “Dynamically Changing
the User Credentials of a Service's Connection at Run Time” on page 80.
Note:
You can override either the connection or the user credentials at run time. If you provide
both, the connection name and the user credentials, the connection name takes precedence
and the service is invoked using the overridden connection.
5. If you defined any other input fields, you will be prompted to type their input values. Type
the values for each input field and then click OK.
6. Click the Service Result tab to view the output from the service.
To view a service
1. In Designer, expand the package and folder that contain the service you want to view.
Designer displays the configured service in the service template's Adapter Service Editor.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 131
6 Adapter Services
1. In Designer, browse to and open the adapter service that you want to edit.
Designer displays the adapter service in the service template's Adapter Service Editor.
If you have the VCS Integration feature enabled, right-click the service and select Check
Out.
If you do not have the VCS Integration feature enabled, right-click the service and select
Lock for Edit.
If you are using the local service development feature, from the Team menu in Designer,
select the appropriate option to check out the service. The options available in the Team
menu depend on the VCS client that you use.
4. Modify the values for the adapter service's parameters as needed. For detailed descriptions of
the service's parameters, see the section on configuring a service for the specific type of service
you want to edit.
5. After you complete your modifications, save the service and do one of the following:
If you have the VCS Integration feature enabled, right-click the service and select Check
In. Enter a check-in comment and click OK.
If you do not have the VCS Integration feature enabled, right-click the service and select
Unlock.
If you are using the local service development feature, from the Team menu in Designer,
select the appropriate option to check in the service. The options available in the Team
menu depend on the VCS client that you use.
To delete a service
132 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
6 Adapter Services
1. In Designer, expand the package and folder that contain the service you want to delete.
If you select the option to always validate values for adapter services, it will do so for all
webMethods WmART-based adapters installed on Integration Server.
For more information about the Adapter Service/Notification Editor and other Designer menu
options and toolbar icons, see the IBM webMethods Service Development Help for your release.
1. In Designer, expand the package and folder that contain the service for which you want to
enable automatic validation.
2. Double-click the service for which you want to validate the data.
Designer displays the configured adapter service in the service template's Adapter Service
Editor.
1. In Designer, select the Window > Preferences >IBM> Service Development > Adapter
Service/Notification Editor item.
3. Click OK.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 133
6 Adapter Services
When you reload adapter values for a single adapter service, Designer compares the service values
against the resource data that has already been fetched from the selected adapter.
If you select the option to always reload values for adapter services, it will do so for all webMethods
WmART-based adapters installed on Integration Server.
For more information about the Adapter Service/Notification Editor, other menu options, and
toolbar icons, see the IBM webMethods Service Development Help for your release.
1. In Designer, expand the package and folder that contain the service for which you want to
enable automatic validation.
2. Double-click the service for which you want to validate the data.
Designer displays the configured adapter service in the service template's Adapter Service
Editor.
1. In Designer, select the Window > Preferences >IBM> Service Development > Adapter
Service/Notification Editor item.
3. Click OK.
134 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
7 Adapter Notifications
■ Overview of Adapter Notifications ................................................................................ 136
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 135
7 Adapter Notifications
1. Start your Integration Server and Integration Server Administrator, if they are not already
running.
2. Make sure you have Integration Server Administrator privileges so that you can access Adapter
for JDBC's administrative screens. For information about setting user privileges, see the IBM
webMethods Integration Server Administrator’s Guide for your release.
3. Be sure to check for a list of known limitations for your database driver since it may affect how
you configure your connections and notifications.
4. If you have made changes to the table schema for a given adapter notification, be sure to update
the adapter notification accordingly.
5. If you plan to use the Only Once notification feature, for details, see “Using the Exactly Once
Notification Feature” on page 175.
6. Using Integration Server Administrator, make sure the WmJDBCAdapter package is enabled.
For instructions, see “Enabling Packages” on page 55.
7. Using Integration Server Administrator, configure an adapter connection to use with the
notification. For instructions, see “Configuring Adapter for JDBC Connections” on page 66.
Note:
Integration Server provides a built-in service you can use at design time to change the
connection associated with a polling notification. For more information, see “Changing the
Connection Associated with an Adapter Service or Notification at Design Time” on page 20.
9. Using Designer, create a user-defined package to contain the notification, if you have not
already done so. When you configure notifications, you should always define them in
user-defined packages rather than in the WmJDBCAdapter package. For more information
about managing packages for the adapter, see “Overview of Package Management” on page 54.
136 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
7 Adapter Notifications
10. You must schedule a notification and then enable it before you can use the notification. For
instructions, see “Managing Polling Notifications” on page 173.
11. If you want to enable the same polling notification on multiple Integration Server instances
connecting to the same source database to achieve automated failover, you have to use the
polling notification within an Integration Server cluster. For information how to configure
clustered polling notifications, see “Polling Notification Support in Integration Server
Clusters” on page 58.
Configuring InsertNotifications
An InsertNotification publishes notification of insert operations on a database table. For more
information about notifications, see “Adapter Notifications” on page 23.
MySQL version 5.0.x does not support multiple triggers with the same event (insert, delete,
or update) for one table. Hence, with a MySQL database, when using an InsertNotification to
monitor a table, you must disable the notification before you can enable another
InsertNotification or an OrderedNotification with an insert operation for the same table.
Creating an InsertNotification
You configure notifications using Designer.
Be sure to review the sections “Before Configuring or Managing Notifications” on page 136 and
“Considerations when Configuring InsertNotifications” on page 137 before you configure
InsertNotifications.
To create an InsertNotification
1. In Designer, right-click the package in which the notification should be contained and select
New > Adapter Notification.
2. Select the parent namespace, type a name for the adapter notification, and click Next.
3. Select Adapter for JDBC as the adapter type and click Next.
The name of the publishable document associated with this notification is displayed.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 137
7 Adapter Notifications
6. Click Finish.
For more information about adapter notifications and publishable documents, see “Adapter
Notifications” on page 23. For more details about the Integration Server publishable documents,
see the Publish-Subscribe Developer’s Guide for your release.
7. Designer creates the notification, and the editor for the adapter notification appears.
a. You can select the Adapter Settings tab at any time to confirm adapter notification
properties such as the Adapter Name, Adapter Connection Name, and Adapter
Notification Template, as necessary.
b. In the Publish Document section, you can specify how you want the notification document
to be published:
To publish documents to a JMS provider, select JMS Provider, and provide values for
the following input fields:
Field Description/Action
Connection alias name The name of the JMS connection alias configured on Integration
Server.
Note:
Adapter Runtime does not support LOCAL_TRANSACTION
and XA_TRANSACTION type JMS connection alias.
Destination name The name of the destination from which you want the JMS
trigger to receive messages.
The information from the Permissions tab appears in the Properties panel.
8. Select the Notification Configure tab and use the following fields:
Field Description/Action
Base Name The base name used to generate the Resource Name created by Adapter
for JDBC.
Note:
138 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
7 Adapter Notifications
Field Description/Action
For OS/390 DB2 7.2, the Base Name you create below must be no
more than five characters because triggers on OS/390 name cannot be
more than eight characters.
Resource Type Types are buffer table, trigger, and sequence. The base name and resource
type determine the following Resource Name.
Resource Name To ensure uniqueness, the resource name combines the following
elements. You cannot edit this name.
Resource prefix (WMB, WMT, and WMS for buffer table, trigger,
and sequence respectively)
File Record Format The format of the file record. Optional field used by DB2 for AS/400
V4R5 only.
Database Name The name of the database where the buffer tables will be created.
Optional field used by DB2 for OS/390 only.
Table Space Name The table space where the buffer tables will be created. Optional field
used by DB2 for OS/390 only.
Note:
For AS/400 DB2 V4R5 using a jt400.jar file, the table name for the notification cannot exceed
10 characters; otherwise, an exception will be generated when you try to enable the
notification.
Field Description/Action
Table Alias The table alias is automatically assigned when you select more than one table
in the Table Name field. The default is t1.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 139
7 Adapter Notifications
Field Description/Action
Table Name Select a table name. The default for the associated catalog name is current
catalog. The default for the associated schema name is current schema. The
table name must not contain a period. If the table name does contain a period,
Designer will throw an error.
Note:
Informix databases do not allow you to specify a catalog and database name
because you can only access the current catalog.
Type The table type displays automatically based on the table you select.
10. If you are not joining tables, skip this step. Select the Joins tab to specify the columns for
joining the tables you just configured.
b. Select Left Column and select the first table's joining column.
d. Select Right Column and select the next table's joining column.
11. Use the SELECT tab to define the columns and fields to be selected using the following fields:
Note:
When using the Join clause, select only the fields of the monitor table in the Select tab.
a. In the ALL/DISTINCT field, select ALL to include duplicate rows or DISTINCT to suppress
duplicate rows. Selecting ALL corresponds to the SQL statement SELECT ALL name from
tablename. The default value is blank, which corresponds to the SQL statement SELECT
name from tablename.
b. Select the icon (or the icon to fill in all rows of the table) to create new fields as needed.
c. In the Expression field, select a column or type any valid SQL expression. The
corresponding Column Type, JDBC Type, Output Field Type, and Output Field display
for each column you select in the Expression field. Use the following fields:
Field Description/Action
Column Type The column data type defined in the database table.
140 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
7 Adapter Notifications
Field Description/Action
Output Field Type The data type of the output field. Adapter for JDBC automatically
converts database-specific types to Java data types. For a list of JDBC
type to Java type mappings, see “JDBC Data Type to Java Data Type
Mappings” on page 216.
Output Field The name of the field containing the output from the SELECT
operation. An output field name displays when you select an
expression. You can also modify the output field names as required.
Maximum Row Specifies the number of rows to be retrieved from the buffer table.
This field is useful when you are working with a large number of
records and you want to limit the number of documents sent each
time the notification polls. Use a value of 0 to indicate no limit on the
number of rows retrieved.
Query Time Out Specify the query time out value in seconds. This value is the amount
of time Adapter for JDBC waits for the notification to execute before
stopping the SQL operation. The default value is -1. Use the default
value to have the notification use the value indicated on the
watt.adapter.JDBC.QueryTimeout property as the time out. If you
specify a value equal to 0, or if the watt.adapter.JDBC.QueryTimeout
property is not set, the notification executes without a time out. If you
specify a value greater than 0, the notification executes with the
specified value as the time out.
Note:
-1 is the only permissible negative value for this field.
12. Use the WHEN tab to specify the conditions for selecting information using the following fields.
Note:
If you use Microsoft SQL Server, Sybase, or V4 AS/400 DB2, do not use the WHEN tab because
this feature is not supported. An exception will be generated if you try to use this tab.
b. Select the Column field and choose a column from the list.
c. Select a logical operator from the AND/OR field, an Operator, and separators (the left and
right parentheses) as needed.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 141
7 Adapter Notifications
d. Type a fixed value in the Value field. Be sure that it is a valid value, or an exception will
be generated at run time.
e. If necessary, use the or icons to change the order of the WHEN clause to ensure the
parameters are parsed in the correct order.
13. The information about using the Permissions tab to assign an access control list (ACL) to an
element appears in the Properties panel.
15. You must schedule and enable the notification using Integration Server Administrator before
you can use it. For details, see “Managing Polling Notifications” on page 173.
Configuring UpdateNotifications
An UpdateNotification publishes notification of update operations on a database table. For more
information about notifications, see “Adapter Notifications” on page 23.
MySQL version 5.0.x does not support multiple triggers with the same event (insert, delete,
or update) for one table. Hence, with a MySQL database, when using an UpdateNotification
to monitor a table, you must disable the notification before you can enable another
UpdateNotification or an OrderedNotification with an update operation for the same table.
When using an UpdateNotification with a MySQL database, updating any database field with
the same value will not invoke a trigger.
Creating an UpdateNotification
You configure notifications using Designer.
Be sure to review the sections “Before Configuring or Managing Notifications” on page 136 and
“Considerations when Configuring UpdateNotifications” on page 142 before you configure an
UpdateNotification.
To create an UpdateNotification
1. In Designer, right-click the package in which the notification should be contained and select
New > Adapter Notification.
142 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
7 Adapter Notifications
2. Select the parent namespace, type a name for the adapter notification, and click Next.
3. Select Adapter for JDBC as the adapter type and click Next.
The name of the publishable document associated with this notification is displayed.
6. Click Finish.
For more information about adapter notifications and publishable documents, see “Adapter
Notifications” on page 23. For more details about the Integration Server publishable documents,
see the Publish-Subscribe Developer’s Guide for your release.
7. Designer creates the notification, and the editor for the adapter notification appears.
a. You can select the Adapter Settings tab at any time to confirm adapter notification
properties such as the Adapter Name, Adapter Connection Name, and Adapter
Notification Template, as necessary.
b. In the Publish Document section, you can specify how you want the notification document
to be published:
To publish documents to a JMS provider, select JMS Provider, and provide values for
the following input fields:
Field Description/Action
Connection alias name The name of the JMS connection alias configured on Integration
Server.
Note:
Adapter Runtime does not support LOCAL_TRANSACTION
and XA_TRANSACTION type JMS connection alias.
Destination name The name of the destination from which you want the JMS
trigger to receive messages.
8. Select the Notification Configure tab and use the following fields:
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 143
7 Adapter Notifications
Field Description/Action
Base Name The base name used to generate the Resource Name created by Adapter
for JDBC.
Note:
For OS/390 DB2V7.2, the Base Name you create below must be no
more than five characters because triggers on OS/390 name cannot be
more than eight characters.
Resource Type Types are buffer table, trigger, and sequence. The base name and resource
type determine the following Resource Name.
Resource Name To ensure uniqueness, the resource name combines the following
elements. You do not edit this name.
Resource prefix (WMB, WMT, and WMS for buffer table, trigger,
and sequence respectively)
File Record Format The format of the file record. Optional field used by DB2 for AS/400
V4R5 only.
Database Name The name of the database where the buffer tables will be created.
Optional field used by DB2 for OS/390 only.
Table Space Name The table space where the buffer tables will be created. Optional field
used by DB2 for OS/390 only.
Note:
For AS/400 DB2 V4R5 using a jt400.jar file, the table name for the notification cannot exceed
10 characters; otherwise, an exception will be generated when you try to enable the
notification.
144 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
7 Adapter Notifications
Field Description/Action
Table Alias The table alias is automatically assigned when you select more than one table
in the Table Name field. The default is t1.
Table Name Select a table. The default for the associated catalog name is current catalog.
The default for the associated schema name is current schema. The table name
must not contain a period. If the table name does contain a period, Designer
will throw an error.
Note:
Informix databases do not allow you to specify a catalog and database name
because you can only access the current catalog.
Type The table type displays automatically based on the table you select.
10. If you are not joining tables, skip this step. Select the Joins tab to specify the columns for
joining the tables you just configured.
b. Select Left Column and select the first table's joining column.
d. Select Right Column and select the next table's joining column.
11. Use the SELECT tab to define the columns and fields to be selected as follows:
Note:
When using the Join clause, select only the fields of the monitor table in the Select tab.
a. In the ALL/DISTINCT field, select ALL to include duplicate rows or DISTINCT to suppress
duplicate rows. Selecting ALL corresponds to the SQL statement SELECT
ALLnamefromtablename. The default value is blank, which corresponds to the SQL statement
SELECTnamefromtablename.
b. Select the icon (or the icon to fill in all rows of the table) to create new fields as needed.
c. In the Expression field, select a column or type any valid SQL expression. The
corresponding Column Type, JDBC Type, Output Field Type, and Output Field display
for each column you select in the Expression field. Use the following fields:
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 145
7 Adapter Notifications
Field Description/Action
Column Type The column data type defined in the database table.
Output Field Type The data type of the output field. Adapter for JDBC automatically
converts database-specific types to Java data types. For a list of JDBC
type to Java type mappings, see “JDBC Data Type to Java Data Type
Mappings” on page 216.
Output Field The name of the field containing the output from the SELECT
operation. An output field name displays when you select an
expression. You can also modify the output field names as required.
Notify On Update Enable this option to indicate for which of the columns specified in
the SELECT tab you want a notification, if the column is updated.
Select:
Output Value Specifies which output value to retrieve from the database table. By
Type default, the UpdateNotification retrieves the new value from the
database table. Select either of the following output value types:
To retrieve both the old and the new values, create two rows and then
select an Output Value Type as Old in one row and an Output Value
Type as New in the other row. While doing so, ensure that the Output
Field is unique for both the old and the new values.
Note:
For Sybase and Microsoft 2000/2005, you cannot retrieve both the
old and the new values in the same notification. The notification
must retrieve either the old or the new value.
Maximum Row Specifies the number of rows to be retrieved from the buffer table.
This field is useful when you are working with a large number of
146 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
7 Adapter Notifications
Field Description/Action
records and you want to limit the number of documents sent each
time the notification polls. Use a value of 0 to indicate no limit on the
number of rows retrieved.
Query Time Out Specify the query time out value in seconds. This value is the amount
of time Adapter for JDBC waits for the notification to execute before
stopping the SQL operation. The default value is -1. Use the default
value to have the notification use the value indicated on the
watt.adapter.JDBC.QueryTimeout property as the time out. If you
specify a value equal to 0, or if the watt.adapter.JDBC.QueryTimeout
property is not set, the notification executes without a time out. If you
specify a value greater than 0, the notification executes with the
specified value as the time out.
Note:
-1 is the only permissible negative value for this field.
12. Use the WHEN tab to specify the conditions for selecting information:
Note:
If you use Microsoft SQL Server, Sybase, or V4 AS/400 DB2, do not use the WHEN tab because
this feature is not supported. An exception will be generated if you try to use this tab.
b. Select the Column field and choose a column from the list.
c. Select a logical operator from the AND/OR field, an Operator, and separators (the left and
right parentheses) as needed.
d. Type a fixed value in the Value field. Be sure that it is a valid value, or an exception will
be generated at run time.
e. If necessary, use the or icons to change the order of the WHEN clause to ensure the
parameters are parsed in the correct order.
13. The information about using the Permissions tab to assign an access control list (ACL) to an
element appears in the Properties panel.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 147
7 Adapter Notifications
15. You must schedule and enable the notification using Integration Server Administrator before
you can use it. For details, see “Managing Polling Notifications” on page 173.
Configuring DeleteNotifications
A DeleteNotification publishes notification of delete operations on a database table. For more
information about notifications, see “Adapter Notifications” on page 23.
MySQL version 5.0.x does not support multiple triggers with the same event (insert, delete,
or update) for one table. Hence, with a MySQL database, when using a DeleteNotification to
monitor a table, you must disable the notification before you can enable another
DeleteNotification or an OrderedNotification with a delete operation for the same table.
Creating a DeleteNotification
You configure notifications using Designer.
Be sure to review the sections “Before Configuring or Managing Notifications” on page 136 and
“Considerations when Configuring DeleteNotifications” on page 148 before you configure
DeleteNotifications.
To create a DeleteNotification
1. In Designer, right-click the package in which the notification should be contained and select
New > Adapter Notification.
2. Select the parent namespace, type a name for the adapter notification, and click Next.
3. Select Adapter for JDBC as the adapter type and click Next.
The name of the publishable document associated with this notification is displayed.
6. Click Finish.
148 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
7 Adapter Notifications
For more information about adapter notifications and publishable documents, see “Adapter
Notifications” on page 23. For more details about the Integration Server publishable documents,
see the Publish-Subscribe Developer’s Guide for your release.
7. Designer creates the notification, and the editor for the adapter notification appears.
a. You can select the Adapter Settings tab at any time to confirm adapter notification
properties such as the Adapter Name, Adapter Connection Name, and Adapter
Notification Template, as necessary.
b. In the Publish Document section, you can specify how you want the notification document
to be published:
To publish documents to a JMS provider, select JMS Provider, and provide values for
the following input fields:
Field Description/Action
Connection alias name The name of the JMS connection alias configured on Integration
Server.
Note:
Adapter Runtime does not support
LOCAL_TRANSACTION and XA_TRANSACTION type
JMS connection alias.
Destination name The name of the destination from which you want the JMS
trigger to receive messages.
The information from the Permissions tab appears in the Properties panel.
8. Select the Notification Configure tab and use the following fields:
Field Description/Action
Base Name The base name used to generate the Resource Name created by Adapter
for JDBC.
Note:
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 149
7 Adapter Notifications
Field Description/Action
For OS/390 DB2V7.2, the Base Name you create below must be no more
than 5 characters because triggers on OS/390 name cannot be more than
8 characters.
Publish Locally Specifies whether to publish the notification's publishable document to the
local Integration Server. By default, this option is not selected, that is, if the
Broker is configured to Integration Server, the publishable document is
published to the Broker; otherwise the publishable document is published
to the local Integration Server. Selecting the Publish Locally option reduces
performance problems, if Integration Server is connecting to a remotely
located Broker that is in turn triggering a service on the local Integration
Server.
Resource Type Types are buffer table, trigger, and sequence. The base name and resource
type determine the following Resource Name.
Resource Name To ensure uniqueness, the resource name combines the following elements.
You do not edit this name.
Resource type prefix (WMB, WMT, and WMS for buffer table, trigger,
and sequence respectively)
File Record The format of the file record. Optional field used by DB2 for AS/400 V4R5
Format only.
Database Name The name of the database where the buffer tables will be created. Optional
field used by DB2 for OS/390 only.
Table Space The table space where the buffer tables will be created. Optional field used
Name by DB2 for OS/390 only.
Note:
For AS/400 DB2 V4R5 using a jt400.jar file, the table name for the notification cannot exceed
10 characters; otherwise, an exception will be generated when you try to enable the
notification.
Field Description/Action
Table Alias The table alias is automatically assigned when you select more than one table
in the Table Name field. The default is t1.
150 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
7 Adapter Notifications
Field Description/Action
Table Name Select a table name. The default for the associated catalog name is current
catalog. The default for the associated schema name is current schema. The
table name cannot contain a period. If the table name does contain a period,
Designer will throw an error.
Note:
Informix databases do not allow you to specify a catalog and database name
because you can only access the current catalog.
Type The table type displays automatically based on the table you select.
10. If you are not joining tables, skip this step. Select the Joins tab to specify the columns for
joining the tables you just configured.
b. Select Left Column and select the first table's joining column.
d. Select Right Column and select the next table's joining column.
11. Use the SELECT tab to define the columns and fields to be selected.
Note:
When using the Join clause, select only the fields of the monitor table in the Select tab.
a. In the ALL/DISTINCT field, select ALL to include duplicate rows or DISTINCT to suppress
duplicate rows. Selecting ALL corresponds to the SQL statement SELECT ALL name from
tablename. The default value is blank, which corresponds to the SQL statement SELECT
name from tablename.
b. Select the icon (or the icon to fill in all rows of the table) to create new fields as needed.
c. In the Expression field, select a column or type any valid SQL expression. The
corresponding Column Type, JDBC Type, Output Field Type, and Output Field display
for each column you select in the Expression field. Use the following fields:
Field Description/Action
Column Type The column data type defined in the database table.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 151
7 Adapter Notifications
Field Description/Action
Output Field Type The data type of the output field. Adapter for JDBC automatically
converts database-specific types to Java data types. For a list of JDBC
type to Java type mappings, see “JDBC Data Type to Java Data Type
Mappings” on page 216.
Output Field The name of the field containing the output from the select operation.
An output field name displays when you select an expression. You
can also modify the output field names as required.
Maximum Row Specifies the number of rows to be retrieved from the buffer table.
This field is useful when you are working with a large number of
records and you want to limit the number of documents sent each
time the notification polls. Use a value of 0 to indicate no limit on
the number of rows retrieved.
Query Time Out Specify the query time out value in seconds. This value is the amount
of time Adapter for JDBC waits for the notification to execute before
stopping the SQL operation. The default value is -1. Use the default
value to have the notification use the value indicated on the
watt.adapter.JDBC.QueryTimeout property as the time out. If you
specify a value equal to 0, or if the watt.adapter.JDBC.QueryTimeout
property is not set, the notification executes without a time out. If
you specify a value greater than 0, the notification executes with the
specified value as the time out.
Note:
-1 is the only permissible negative value for this field.
12. Use the WHEN tab to specify the conditions for selecting information:
Note:
If you use Microsoft SQL Server, Sybase, or V4 AS/400 DB2, do not use the WHEN tab because
this feature is not supported. An exception will be generated if you try to use this tab.
a. Select the Insert Row icon to define new WHEN clause fields.
b. Select the Column field and choose a column from the list.
c. Select a logical operator from the AND/OR field, an Operator, and separators (the left and
right parentheses) as needed.
152 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
7 Adapter Notifications
d. Type a fixed value in the Value field. Be sure that it is a valid value, or an exception will
be generated at run time.
e. If necessary, use the or icons to change the order of the WHEN clause to ensure the
parameters are parsed in the correct order.
13. The information about using the Permissions tab to assign an access control list (ACL) to an
element appears in the Properties panel.
15. You must schedule and enable the notification using Integration Server Administrator before
you can use it. For details, see “Managing Polling Notifications” on page 173.
Configuring BasicNotifications
A BasicNotification polls a database table for data using a SQL Select operation. For more
information about notifications, see “Adapter Notifications” on page 23.
Creating a BasicNotifications
You configure notifications using Designer.
Be sure to review the section “Before Configuring or Managing Notifications” on page 136 before
you configure notifications.
To configure a BasicNotification
1. In Designer, right-click the package in which the notification should be contained and select
New > Adapter Notification.
2. Select the parent namespace, type a name for the adapter notification, and click Next.
3. Select Adapter for JDBC as the adapter type and click Next.
The name of the publishable document associated with this notification is displayed.
6. Click Finish.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 153
7 Adapter Notifications
For more information about adapter notifications and publishable documents, see “Adapter
Notifications” on page 23. For more details about the Integration Server publishable documents,
see the Publish-Subscribe Developer’s Guide for your release.
7. Designer creates the notification, and the editor for the adapter notification appears.
a. You can select the Adapter Settings tab at any time to confirm adapter notification
properties such as the Adapter Name, Adapter Connection Name, and Adapter
Notification Template, as necessary.
b. In the Publish Document section, you can specify how you want the notification document
to be published:
To publish documents to a JMS provider, select JMS Provider, and provide values for
the following input fields:
Field Description/Action
Connection alias name The name of the JMS connection alias configured on Integration
Server.
Note:
Adapter Runtime does not support LOCAL_TRANSACTION
and XA_TRANSACTION type JMS connection alias.
Destination name The name of the destination from which you want the JMS
trigger to receive messages.
The information from the Permissions tab appears in the Properties panel.
Note:
For AS/400 DB2 V4R5 using a jt400.jar file, the table name for the notification cannot exceed
10 characters; otherwise, an exception will be generated when you try to enable the
notification.
Field Description/Action
Table Alias The table alias is automatically assigned when you select more than one table
in the Table Name field. The default is t1.
154 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
7 Adapter Notifications
Field Description/Action
Table Name Select a table name. The default for the associated catalog name is current
catalog. The default for the associated schema name is current schema. The
table name must not contain a period. If the table name does contain a period,
Designer will throw an error.
Note:
Informix databases do not allow you to specify a catalog and database name
because you can only access the current catalog.
Type The table type displays automatically based on the table you select.
9. If you are not joining tables, skip this step. Select the Joins tab to specify the columns for
joining the tables you just configured.
a. Select the icon (or the icon to fill in all rows of the table) to create new left and right
columns.
b. Select Left Column and select the first table's joining column.
d. Select Right Column and select the next table's joining column.
10. Use the SELECT tab to define the columns and fields to be selected.
a. In the ALL/DISTINCT field, select ALL to include duplicate rows or DISTINCT to suppress
duplicate rows. Selecting ALL corresponds to the SQL statement SELECT ALL name from
tablename. The default value is blank, which corresponds to the SQL statement SELECT
name from tablename.
b. Select the icon (or the icon to fill in all rows of the table) to create new fields as needed.
c. In the Expression field, select a column or type any valid SQL expression. The
corresponding Column Type, JDBC Type, Output Field Type, and Output Field display
for each column you select in the Expression field. Use the following fields:
Field Description/Action
Column Type The column data type defined in the database table.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 155
7 Adapter Notifications
Field Description/Action
Output Field Type The data type of the output field. Adapter for JDBC automatically
converts database-specific types to Java data types. For a list of JDBC
type to Java type mappings, see “JDBC Data Type to Java Data Type
Mappings” on page 216.
Output Field The name of the field containing the output from the SELECT
operation. An output field name displays when you select an
expression. You can also modify the output field names as required.
Sort Order Specifies ordering of publishable documents per each polling. Use
this field to ensure that the notification's publishable documents,
for each polling, are in the correct ascending or descending order
based on one or more table columns. Select either Ascend or
Descend. Leave the field blank if there is no sort order.
d. If you want the notification's publishable document to be published to the local Integration
Server, select the Publish Locally option.
By default, this option is not selected, that is, if the Broker is configured to Integration
Server, the publishable document is published to the Broker; otherwise the publishable
document is published to the local Integration Server.
Selecting the Publish Locally option reduces performance problems, if Integration Server
is connecting to a remotely located Broker that is in turn triggering a service on the local
Integration Server.
e. If you want to use the Exactly Once notification feature, you must enable the Exactly Once
Notification option. For more information, see “Using the Exactly Once Notification
Feature” on page 175.
f. Set the Delete selected records flag to automatically delete the selected records from the
buffer table (based on their Record ID Column value) after the notification. Use this option
to prevent publishing the same documents to Integration Server each time polling occurs.
Note:
Running a BasicNotification may generate a duplicate message error. Integration Server
will ignore the duplicate notification document. In this case, you should check the Delete
selected records option and choose a column with sequentially unique values as the
Record ID Column value next in the procedure.
g. You must use the Record ID Column field to use the Exactly Once notification feature.
Select the column from the buffer table that you want to use as the unique ID for the
publishable document for this notification. For more information, see “Using the Exactly
Once Notification Feature” on page 175.
To ensure that all values will be unique, choose a table column in the Record ID Column
field whose values are sequential numbers.
156 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
7 Adapter Notifications
h. Use the Mark ID Column field to mark the records as processed. Select the column that
you created in the database table to hold the status of the record. Use this option when
you do not want to set the Delete selected records flag, and also want to avoid the
publishing of duplicate records. For information about creating the column that holds the
status of the records and marking the records as published, see “Basic Notifications” on
page 29.
i. Use the Maximum Row field to specify the maximum number of records to retrieve from
the database. This field is useful when you are working with a large number of records
and you want to limit the number of documents sent each time the notification polls.
j. Use the Query Time Out field to specify the query time out value of the BasicNotification
you are configuring. This value is the amount of time Adapter for JDBC waits for the
notification to execute before stopping the SQL operation.
The default value is -1. Use the default value to have the notification use the value indicated
on the watt.adapter.JDBC.QueryTimeout property as the time out.
If you specify a value greater than 0, the notification executes with the specified value as
the time out.
Note:
-1 is the only permissible negative value for this field.
11. Use the WHERE tab to specify the WHERE conditions on the SQL query statement for selecting
information:
b. Select a logical operator from the AND/OR field, an Operator, and separators (the left and
right parentheses) as needed, and use the following fields:
Field Description/Action
Column The name of the column you want to use in the WHERE clause.
Operator The operator used with the Column and Input Field.
Input Field Type a fixed value in this field. Be sure that it is a valid value, or an exception
will be generated at run time.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 157
7 Adapter Notifications
Note:
For Oracle users, if you use a CHAR(n) data type and enter a value in the Input Field,
Adapter for JDBC automatically sets the ORACLEFIXED_CHAR data type as the JDBC
data type.
c. If necessary, use the or icons to change the order of the WHERE clause to ensure the
parameters are parsed in the correct order.
d. Repeat this procedure until you have specified all the WHERE parameters.
12. The information about using the Permissions tab to assign an access control list (ACL) to an
element appears in the Properties panel.
14. You must schedule and enable the notification using Integration Server Administrator before
you can use it. For details, see “Managing Polling Notifications” on page 173.
Configuring StoredProcedureNotifications
A StoredProcedureNotification publishes notification data by calling a stored procedure inside of
a database. For more information about notifications, see “Adapter Notifications” on page 23.
Creating a StoredProcedureNotifications
You configure notifications using Designer.
Be sure to review the section “Before Configuring or Managing Notifications” on page 136 before
you configure notifications.
For details and important considerations when using a StoredProcedureNotification, see “Stored
Procedure Notifications” on page 32.
To configure a StoredProcedureNotification
1. In Designer, right-click the package in which the notification should be contained and select
New > Adapter Notification.
2. Select the parent namespace, type a name for the adapter notification, and click Next.
3. Select Adapter for JDBC as the adapter type and click Next.
The name of the publishable document associated with this notification is displayed.
158 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
7 Adapter Notifications
6. Click Finish.
For more information about adapter notifications and publishable documents, see “Adapter
Notifications” on page 23. For more details about the Integration Server publishable documents,
see the Publish-Subscribe Developer’s Guide for your release.
7. Designer creates the notification, and the editor for the adapter notification appears.
a. You can select the Adapter Settings tab at any time to confirm adapter notification
properties such as the Adapter Name, Adapter Connection Name, and Adapter
Notification Template, as necessary.
b. In the Publish Document section, you can specify how you want the notification document
to be published:
To publish documents to a JMS provider, select JMS Provider, and provide values for
the following input fields:
Field Description/Action
Connection alias name The name of the JMS connection alias configured on Integration
Server.
Note:
Adapter Runtime does not support LOCAL_TRANSACTION
and XA_TRANSACTION type JMS connection alias.
Destination name The name of the destination from which you want the JMS
trigger to receive messages.
The information from the Permissions tab appears in the Properties panel.
8. Select the Call tab to specify which stored procedure to use with the notification. Use the
icon and set the Call parameters as follows:
Field Description/Action
Catalog Name The name of the catalog. The default for the catalog name is current
catalog.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 159
7 Adapter Notifications
Field Description/Action
Schema Name The name of the schema. The default for the schema name is current
schema.
Enable Procedure To type in the Procedure Name, set this field to False.To select the
Lookup (Optional) Procedure Name from a list, set this field to True. The default is False.
Set this value to False if you know the name of the procedure and you
are working with a large database that has a long list of procedures.
Procedure Name Type or select the stored procedure name, depending on how you set the
Enable Procedure Lookup field.
JDBC Type The JDBC type of the corresponding Return Field Name.
Return Field Name Name of the return field of the stored procedure.
Query Time Out Specify the query time out value in seconds. This value is the amount of
time Adapter for JDBC waits for the notification to execute before stopping
the SQL operation. The default value is -1. Use the default value to have
the notification use the value indicated on the
watt.adapter.JDBC.QueryTimeout property as the time out. If you specify
a value equal to 0, or if the watt.adapter.JDBC.QueryTimeout property
is not set, the notification executes without a time out. If you specify a
value greater than 0, the notification executes with the specified value as
the time out.
Note:
-1 is the only permissible negative value for this field.
9. Use the Parameter tab to specify stored procedure parameters. Use the icon (or the icon
to fill in all rows of the table) to create new parameters for the stored procedure.
160 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
7 Adapter Notifications
Field Description/Action
ParamJDBCType The JDBC type of the stored procedure parameter. For a list of JDBC type
to Java type mappings, see “JDBC Data Type to Java Data Type
Mappings” on page 216.
Output Name Name of any output parameters of the stored procedure, if any. For
information about output fields for stored procedures, see “Stored
Procedure Notifications” on page 32.
Output Type Output parameter Java type. For a list of JDBC type to Java type mappings,
see “JDBC Data Type to Java Data Type Mappings” on page 216.
10. StoredProcedure notifications can support one result set (or one Oracle REF CURSOR). The
result set can contain nested cursors.
Note:
When using the result set that contains nested cursors, the performance of Adapter for JDBC
could degrade. Since the nested cursors are recursively processed, Adapter for JDBC may
also return data that may not be required.
If the procedure returns a result set, select the ResultSet tab to specify result set parameters
using the fields in the following table:
Field Description/Action
Result Set Index An index is automatically assigned to each result set. The first row default
value is 1.
Note:
When using for Oracle database, this field is not required.
Result Set Name Type the name of the result set you want to create. For information about
result sets, see “Stored Procedure Notifications” on page 32.
Note:
When using for Oracle database, this field is not required.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 161
7 Adapter Notifications
Field Description/Action
Output Type The Java type of the result column. For a list of JDBC type to Java type
mappings, see “JDBC Data Type to Java Data Type Mappings” on
page 216.
11. The information about using the Permissions tab to assign an access control list (ACL) to an
element appears in the Properties panel.
13. You must schedule and enable the notification using Integration Server Administrator before
you can use it. For details, see “Managing Polling Notifications” on page 173.
Configuring StoredProcedureNotificationWithSignature
A StoredProcedureNotificationWithSignature publishes notification data by calling a stored
procedure inside of a database. Unlike a StoredProcedureNotification, the
StoredProcedureNotificationWithSignature enables you to automatically obtain a stored procedure's
parameters by introspecting and listing the signature of the stored procedure at the time you
configure this notification. This means that you do not need to look up and retype these parameters
manually.
Creating a StoredProcedureNotificationWithSignature
You configure Adapter for JDBC notifications using Designer. For more information about adapter
notifications, including what you need to know before you configure and manage them, see “Before
Configuring or Managing Notifications” on page 136.
To configure a StoredProcedureNotificationWithSignature
1. In Designer, right-click the package in which the notification should be contained and select
New > Adapter Notification.
2. Select the parent namespace, type a name for the adapter notification, and click Next.
3. Select Adapter for JDBC as the adapter type and click Next.
The name of the publishable document associated with this notification is displayed.
162 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
7 Adapter Notifications
6. Click Finish.
For more information about adapter notifications and publishable documents, see “Adapter
Notifications” on page 23. For more details about the Integration Server publishable documents,
see the Publish-Subscribe Developer’s Guide for your release.
7. Designer creates the notification, and the editor for the adapter notification appears.
a. You can select the Adapter Settings tab at any time to confirm adapter notification
properties such as the Adapter Name, Adapter Connection Name, and Adapter
Notification Template, as necessary.
b. In the Publish Document section, you can specify how you want the notification document
to be published:
To publish documents to a JMS provider, select JMS Provider, and provide values for
the following input fields:
Field Description/Action
Connection alias Name of the JMS connection alias configured on Integration Server.
name
If the connection alias is a Broker Cluster configured with Multisend
Guaranteed policy, you must add the watt property
watt.art.notification.jmsSend.usePublicService and set it to true.
Note:
Adapter Runtime does not support LOCAL_TRANSACTION
and XA_TRANSACTION type JMS connection alias.
Destination name Name of the destination from which you want the JMS trigger to
receive messages.
The information from the Permissions tab appears in the Properties panel.
8. Select the Call tab to specify the stored procedure to call. Provide values for the following call
parameters:
Field Description/Action
Catalog Name Name of the catalog. The default for the catalog name is current catalog.
Schema Name Name of the schema. The default for the schema name is current schema.
Note:
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 163
7 Adapter Notifications
Field Description/Action
You can disable the lookup performed on the database for schema name
by configuring the Schema Name parameter in the Configuration tab.
Procedure To save time, you can type all or part of the procedure name in this field to
Name Pattern narrow your search. This is helpful when dealing with a large database that
has a long list of procedures. Use % as a multi-character wildcard and _
(underscore) as a single character wildcard.
Note:
With DB2 databases, functions do not appear in the list of procedure
names. Only procedures appear in the list.
Note:
If you disable the lookup performed on the database for stored procedure
name by configuring the Procedure Name parameter in the Configuration
tab, the value in the Procedure Name Pattern field is not taken into
consideration OR is ignored.
Procedure Type or select the stored procedure name, depending on how you set the
Name Procedure Name Pattern field. If you select <All Procedures>, this field
lists all of the procedures in the selected catalog and schema.
Note:
You can disable the lookup performed on the database for stored procedure
name by configuring the Procedure Name parameter in the Configuration
tab.
Publish Locally Specifies whether to publish the notification's publishable document to the
local Integration Server. By default, this option is not selected, that is, if the
Broker is configured to Integration Server, the publishable document is
published to the Broker; otherwise the publishable document is published
to the local Integration Server. Selecting the Publish Locally option reduces
performance problems, if Integration Server is connecting to a remotely
located Broker that is in turn triggering a service on the local Integration
Server.
a. The top table on the Call tab based on the signature for the stored procedure you specified:
Field Description/Action
164 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
7 Adapter Notifications
Field Description/Action
Parameter Type Defines the parameter type as IN, INOUT, or OUT. If you select IN or
INOUT, you may also set the input expression in the Expression field.
Expression* Sets the input for the IN or INOUT parameter types only. The RETURN
or OUT parameters will appear automatically on the Call tab's bottom
table. For a list of the allowable expression settings by parameter type, and
how each parameter will map to the input or output fields, see the following
table.
b. The bottom table on the Call tab lists the following output parameters and values for the
stored procedure that will map to the output of the notification's publishable document
and returns the value of OUT or INOUT parameters:
Field Description/Action
Output Field Type Output parameter Java data type. For a list of JDBC to Java data
type mappings, see “JDBC Data Type to Java Data Type
Mappings” on page 216.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 165
7 Adapter Notifications
Field Description/Action
Query Time Query time out value in seconds. This value is the amount of time Adapter for
Out JDBC waits for the notification to execute before stopping the SQL operation.
The default value is -1. Use the default value to have the notification use the
value indicated on the watt.adapter.JDBC.QueryTimeout property as the time
out. If you specify a value equal to 0, or if the watt.adapter.JDBC.QueryTimeout
property is not set, the notification executes without a time out. If you specify a
value greater than 0, the notification executes with the specified value as the
time out.
Note:
-1 is the only permissible negative value for this field.
9. Select the Configuration tab to configure the lookup parameters for stored procedure. Use
the following fields to set the parameters and values:
Schema Name Performs a lookup on the database for schema name. Possible values are:
false. Skips the lookup on the database for schema name. The Schema
Name field is now editable and you can enter the value.
Procedure Name Performs a lookup on the database for procedure name. Possible values
are:
false.
Skips the lookup on the database for procedure name. The
Procedure Name field is now editable and you can enter the value.
Note:
The value in the Procedure Name Pattern field is not taken into
consideration/ignored.
10. If the procedure returns a result set, select the ResultSet tab to specify result set parameters
using the fields in the following table.
This type of notification can support multiple results sets. Use the icon to create additional
result sets as needed.
Note:
166 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
7 Adapter Notifications
While all the tables in the Call tab are updated automatically if the selected stored procedure
changes, the ResultSet tab information is not updated automatically. To update this
information, you must manually update the fields in the ResultSet tab.
Field Description/Action
Result Set Index An index is automatically assigned to each result set. The first
row default value is 1.
Result Set Name The name of the result set you want to create.
Output Type The Java data type of the result column. For a list of JDBC to
Java data type mappings, see “JDBC Data Type to Java Data
Type Mappings” on page 216.
11. The information about using the Permissions tab to assign an access control list (ACL) to an
element appears in the Properties panel.
13. You must schedule and enable the notification using Integration Server Administrator before
you can use it. For details, see “Managing Polling Notifications” on page 173.
Configuring OrderedNotifications
An OrderedNotification publishes notification data for multiple insert, update, or delete operations
on multiple tables. For more information about notifications, see “Adapter Notifications” on
page 23.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 167
7 Adapter Notifications
When using an OrderedNotification with a MySQL database, updating any database field
with the same value will not invoke a trigger.
MySQL version 5.0.x does not support multiple triggers with the same event (insert, delete,
or update) for one table. Hence, with a MySQL database, before you can enable an
OrderedNotification for a table, you must disable any OrderedNotification or other adapter
notifications of the same operation type monitoring the table.
Creating an OrderedNotification
You configure notifications using Designer.
Be sure to review the sections “Before Configuring or Managing Notifications” on page 136 and
“Considerations when Configuring OrderedNotifications” on page 167 before you configure an
OrderedNotification.
To create an OrderedNotification
1. In Designer, right-click the package in which the notification should be contained and select
New > Adapter Notification.
2. Select the parent namespace, type a name for the adapter notification, and click Next.
3. Select Adapter for JDBC as the adapter type and click Next.
6. The name of the publishable document associated with this notification displays. Click Finish.
For more information about adapter notifications and publishable documents, see “Adapter
Notifications” on page 23. For more details about the Integration Server publishable documents,
see the Publish-Subscribe Developer’s Guide for your release.
7. Designer creates the notification, and the editor for the adapter notification appears.
a. You can select the Adapter Settings tab at any time to confirm adapter notification
properties such as the Adapter Name, Adapter Connection Name, and Adapter
Notification Template, as necessary.
b. In the Publish Document section, you can specify how you want the notification document
to be published:
168 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
7 Adapter Notifications
To publish documents to a JMS provider, select JMS Provider, and provide values for
the following input fields:
Field Description/Action
Connection alias name The name of the JMS connection alias configured on Integration
Server.
Note:
Adapter Runtime does not support LOCAL_TRANSACTION
and XA_TRANSACTION type JMS connection alias.
Destination name The name of the destination from which you want the JMS
trigger to receive messages.
The information from the Permissions tab appears in the Properties panel.
8. Select the Notification Configure tab and use the following fields:
Field Description/Action
Base Name The base name used to generate the Resource Name created by Adapter
for JDBC.
Note:
For OS/390 DB2V7.2, the Base Name you create below must be no
more than five characters because triggers on OS/390 name cannot be
more than eight characters.
Resource Type Types are buffer table, trigger, and sequence. The base name and resource
type determine the following Resource Name.
Resource Name To ensure uniqueness, the resource name combines the following
elements. You do not edit this name.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 169
7 Adapter Notifications
Field Description/Action
Resource prefix (WMB, WMT, and WMS for buffer table, trigger,
and sequence respectively)
File Record Format The format of the file record. Optional field used by DB2 for AS/400
V4R5 only.
Database Name The name of the database where the buffer tables will be created.
Optional field used by DB2 for OS/390 only.
Table Space Name The table space where the buffer tables will be created. Optional field
used by DB2 for OS/390 only.
9. Select the Source Tables tab and use the following fields:
Note:
For AS/400 DB2 V4R5 using a jt400.jar file, the table name for the notification cannot exceed
10 characters; otherwise, an exception will be generated when you try to enable the
notification.
Field Description/Action
Table Alias The table alias is automatically assigned when you select more than one
table in the Table Name field. The default is t1.
Table Name Select a table name. The default for the associated catalog name is current
catalog. The default for the associated schema name is current schema.
The table name must not contain a period. If the table name does contain
a period, Designer will throw an error.
Note:
Informix databases do not allow you to specify a catalog and database
name because you can only access the current catalog.
Type The table type displays automatically based on the table you select.
Operation ID Assign an ID to uniquely identify the given operation for the notification.
10. Use the SELECT tab to define the columns and fields to be selected using the following fields:
a. In the ALL/DISTINCT field, select ALL to include duplicate rows or DISTINCT to suppress
duplicate rows. Selecting ALL corresponds to the SQL statement SELECT ALL name from
170 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
7 Adapter Notifications
tablename. The default value is blank, which corresponds to the SQL statement SELECT
name from tablename.
b. Select the icon (or the icon to fill in all rows of the table) to create new fields as needed.
For each Expression column you select, the corresponding Operation ID, Column Type,
JDBC Type, Output Field Type, and Output Field display.
Field Description/Action
Column Type The column data type defined in the database table.
Output Field The data type of the output field. Adapter for JDBC automatically converts
Type database-specific types to Java data types. For a list of JDBC type to Java
type mappings, see “JDBC Data Type to Java Data Type Mappings” on
page 216.
Output Field The name of the field containing the output from the SELECT operation.
An output field name displays when you select an expression. You can
also modify the output field names as required.
Notify On Used for Update operations only. Enable this option to indicate which of
Update the columns specified in the SELECT tab you want notification if updated.
Select:
Yes if you want notification if this column of data has been updated.
Yes is the default value.
Output Value Used for Update operations only. Specifies which output value to retrieve
Type from the database table. By default, the notification retrieves the new value
from the database table. Select either of the following output value types:
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 171
7 Adapter Notifications
Field Description/Action
To retrieve both the old and the new values, you need to create two rows
and then select an Output Value Type as Old in one row and an Output
Value Type as New in the other row. While doing so, ensure that the
Output Field is unique for both the old and the new values.
Note:
For Sybase and Microsoft 2000/2005, you cannot retrieve both the old
and the new values in the same notification. The notification must
retrieve either the old or the new value.
Maximum Specifies the number of rows to be retrieved from the buffer table. This
Row field is useful when you are working with a large number of records and
you want to limit the number of documents sent each time the notification
polls. Use a value of 0 to indicate no limit on the number of rows retrieved.
Query Time Specify the query time out value in seconds. This value is the amount of
Out time Adapter for JDBC waits for the notification to execute before stopping
the SQL operation. The default value is -1. Use the default value to have
the notification use the value indicated on the
watt.adapter.JDBC.QueryTimeout property as the time out. If you specify
a value equal to 0, or if the watt.adapter.JDBC.QueryTimeout property is
not set, the notification executes without a time out. If you specify a value
greater than 0, the notification executes with the specified value as the time
out.
Note:
-1 is the only permissible negative value for this field.
11. Use the WHEN tab to specify the conditions for selecting information using the following table.
Note:
If you use Microsoft SQL Server or Sybase, do not use the WHEN tab because this feature
is not supported. An exception will be generated if you try to use this tab.
b. Select the column in the Expression field. The corresponding Operation ID is displayed.
c. Select a logical operator from the AND/OR field, an Operator, and separators (the left and
right parentheses) as needed.
172 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
7 Adapter Notifications
d. Type a fixed value in the Value field. Be sure that it is a valid value, or an exception will
be generated at run time.
e. If necessary, use the or icons to change the order of the WHEN clause to ensure the
parameters are parsed in the correct order.
12. The information about using the Permissions tab to assign an access control list (ACL) to an
element appears in the Properties panel.
14. You must schedule and enable the notification using Integration Server Administrator before
you can use it. For details, see “Managing Polling Notifications” on page 173.
Note:
While enabling the Ordered Notification that monitors a Sybase database, if you encounter
an error that indicates data definition commands are not allowed in transactions, then you
need to run the following command in your Sybase database: sp_dboption
database_name,"ddl in tran", true.
Note:
You must have Integration Server Administrator privileges to access Adapter for JDBC's
administrative screens. For information about setting user privileges, see the IBM webMethods
Integration Server Administrator’s Guide for your release.
2. From the Adapters menu in the navigation area of Integration Server Administrator, select
Adapter for JDBC.
4. From the Adapter for JDBCPolling Notifications table, use the fields in the following table
to manage each adapter notification:
Note:
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 173
7 Adapter Notifications
For AS/400 DB2 V4R5 using a jt400.jar file, the table name for the notification cannot exceed
10 characters. If the table name exceeds 10 characters, an exception will be generated when
you try to enable the notification.
Note:
If you use an XA-Transaction connection, you cannot enable a notification.
Field Description/Action
State After you schedule a polling notification, you can use this option's
dropdown list to set the polling notification's state:
Note:
You must schedule a polling notification before you can enable it.
To schedule a polling notification, use the icon described in these
procedures.
The Suspend all enabled and Enable all suspended links help you
change states quickly for multiple polling notifications. Enabling,
suspending, and disabling a notification affects how its trigger and
buffer tables are created and dropped. For details, see “Polling
Notifications and States” on page 43. If there is no polling notification
scheduled for a given adapter notification, control for this field is
disabled. Use the icon to schedule a polling notification.
Edit Schedule Click the icon to create or modify polling notification parameters.
Note:
You must disable a polling notification before you can edit it.
View Schedule Click on the View Schedule icon to review the parameters for the
selected polling notification. Click Return toAdapter for
JDBCNotifications to go back to the main polling notification page.
174 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
7 Adapter Notifications
5. To create or modify schedule parameters for the selected adapter notification, click on the
icon and use the following fields:
Field Description/Action
Overlap Note:
Do not use this option; otherwise, when you enable this notification,
it may lock up tables and cause Integration Server to fail.
7. After you create a polling notification, you can enable it. Use the State field to enable a polling
notification.
Because this feature ensures that the rows of the data in the buffer table will not be duplicated
even after a processing failure, you should not re-create a notification in the event of a processing
failure. The Exactly Once feature will automatically make the appropriate corrections as needed.
Note:
Stored Procedure Notifications do not support the Exactly Once notification feature because
they do not use publishable document unique IDs.
Note:
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 175
7 Adapter Notifications
After you export or deploy an adapter notification, IBM recommends reloading the adapter values
in the notification template in Designer if all of the following conditions are met:
1. The connection for the notification in the source and target Integration Server connects to the
same database.
2. The connection for the notifications is configured with different schemas on the source and
target Integration Server.
With Insert Notifications, Update Notifications, Delete Notifications, and Ordered Notifications
the buffer table and trigger remain in the database. When the Integration Server with the exported
notifications starts, each configured notification starts to poll the data from the buffer table.
If you want to export configured notifications in a Disabled state, you need to disable the
notifications before you export the package containing them. With Insert Notifications, Update
Notifications, Delete Notifications, and Ordered Notifications the buffer table and trigger will be
dropped when you disable the notification. When you enable the exported notification, the buffer
table and trigger will be created.
For more details, see “Insert Notifications, Update Notifications, and Delete Notifications” on
page 25.
When exporting the configured notifications, IBM recommends that you export them in a Suspended
state. The trigger and buffer table are not dropped in the Suspended state.
After exporting the configured notifications, the following scenarios can occur in Adapter for JDBC
if the notifications are not exported in a Suspended state:
While reloading the package containing exported enabled notifications, or while restarting
Integration Server, if some or all of the database objects of a notification are missing, the adapter
throws a warning indicating that the database objects are missing, and then disables that
notification.
When enabling an exported disabled notification, if some or all of the database objects for that
notification exist, the adapter throws an error indicating that the database objects exist.
When disabling an exported notification, if some of the database objects are missing, the adapter
disables the notification but does not delete the existing database objects. The next time you
enable the same notification, the adapter throws an error indicating that incomplete database
objects exist.
To help you recover from these scenarios, Adapter for JDBC provides the following services:
176 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
7 Adapter Notifications
For information about polling notifications and their states, see “Polling Notifications and States” on
page 43.
For more information about exporting packages, see the IBM webMethods Integration Server
Administrator’s Guide for your release.
Viewing Notifications
You use Designer to view notifications.
To view a notification
1. In Designer, expand the package and folder that contain the notification you want to view.
Designer displays the notification in the notification template's Adapter Notification Editor.
Editing Notifications
You use Designer to edit notifications. You may be able to change the connection associated with
an adapter using the built-in service pub.art.notification:setPollingNotificationNodeConnection. For more
information, see “Changing the Connection Associated with an Adapter Service or Notification
at Design Time” on page 20.
To edit a notification
1. In Designer, expand the package and folder that contain the notification you want to edit.
Designer displays the notification in the notification template's Adapter Notification Editor.
If you have the VCS Integration feature enabled, right-click the notification and select
Check Out.
If you do not have the VCS Integration feature enabled, right-click the notification and
select Lock for Edit.
If you are using the local service development feature, from the Team menu in Designer,
select the appropriate option to check out the notification. The options available in the
Team menu depend on the VCS client that you use.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 177
7 Adapter Notifications
4. Modify the values for the notification's parameters as needed. For detailed descriptions of the
notification's parameters, see the section on configuring a notification for the specific type of
notification you want to edit.
5. After you have completed your modifications, save the notification and do one of the following:
If you have the VCS Integration feature enabled, right-click the notification and select
Check In. Enter a check-in comment and click OK.
If you do not have the VCS Integration feature enabled, right-click the notification and
select Unlock.
If you are using the local service development feature, from the Team menu in Designer,
select the appropriate option to check in the notification. The options available in the Team
menu depend on the VCS client that you use.
Note:
Because adapter notifications inherently depend on connections, you cannot edit or change
the adapter connection for a notification after you configure it.
Deleting Notifications
You use Designer to delete adapter notifications.
Note:
Before you delete the notification, be sure that you first disable it. Otherwise, the trigger and
buffer table created by the notification will remain in the database. To disable a notification, see
“Managing Polling Notifications” on page 173.
To delete a notification
1. In Designer, expand the package and folder that contain the notification you want to delete.
When you enable data validation for a single adapter notification, Designer compares the
notification values against the resource data that has already been fetched from the selected adapter.
If you select the option to always validate values for adapter notifications, it will do so for all
webMethods WmART-based adapters installed on Integration Server.
178 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
7 Adapter Notifications
For more information about the Adapter Service/Notification Editor, other Designer menu options,
and toolbar icons, see the IBM webMethods Service Development Help for your release.
1. In Designer, expand the package and folder that contain the notification for which you want
to enable automatic validation.
2. Double-click the notification for which you want to validate the data.
Designer displays the configured adapter notification in the service template's Adapter
Notification Editor.
1. In Designer, select the Window > Preferences >IBM> Service Development > Adapter
Service/Notification Editor item.
3. Click OK.
When you reload adapter values for a single adapter notification, Designer compares the notification
values against the resource data that has already been fetched from the selected adapter.
If you select the option to always reload values for adapter notifications, it will do so for all
webMethods WmART-based adapters installed on Integration Server.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 179
7 Adapter Notifications
For more information about the Adapter Service/Notification Editor, other menu options, and
toolbar icons, see the IBM webMethods Service Development Help for your release.
1. In Designer, expand the package and folder that contain the service for which you want to
enable automatic validation.
2. Double-click the service for which you want to validate the data.
Designer displays the configured adapter service in the service template's Adapter Notification
Editor.
180 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
8 Data Type Configuration
■ Overview of Data Type Configuration ........................................................................... 182
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 181
8 Data Type Configuration
a database-specific data type mapping configuration file for each supported backend, for
example OracleTypeMapping.xml
Each column in a database table is assigned an SQL type. The JDBC driver then maps each SQL
data type to a JDBC data type. The adapter in turn maps each JDBC data type to one or more Java
data types that are used as the input or output of adapter services and notifications.
For more information on JDBC data type to Java data type mappings, see “JDBC Data Type to
Java Data Type Mappings” on page 216.
Based on the XML configuration, Adapter for JDBC selects the exact JDBC type applicable for a
particular table column in the database. The adapter service or notification template shows the
corresponding Java data types that are mapped to the JDBC data type in the XML configuration
file.
In rare cases, you might need to modify the database-specific configuration file, if you need custom
processing of a data type. For more information on custom processing of a data type, see “Customize
data type configuration” on page 186. If the modified file fails validation, Adapter for JDBC ignores
the file, and the adapter connections to the database do not work.
The native SQL data types returned by the JDBC driver that are not part of the predefined JDBC
data types must be configured as extended data types in the database-specific configuration file.
javaType
Contains:
the fully qualified class name that is used while accessing the Java object corresponding to a
database column.
the setter and getter methods in the prepared statement and result set while accessing a specific
column in the database.
182 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
8 Data Type Configuration
typeMapping
Contains the Java type mappings for the default JDBC types supported in the java.sql.Types class.
A single JDBC type can be mapped to one or more Java types. Those Java types appear as
drop-down lists in the Adapter for JDBC service and notification templates in IBM webMethods
Designer.
If a database requires special handling for a JDBC type and needs to have different javaType
mapping from the one provided in the default TypeMapping.xml file, you can modify the
database-specific configuration file accordingly overriding the default configuration. For more
information on custom processing of a data type, see “Customize data type configuration” on
page 186.
extTypeMapping
Includes additional JDBC types that are not supported in the java.sql.Types class, as well as the
corresponding code of the JDBC type.
typeClassName
Contains the fully qualified class name that extends the com.wm.adapter.wmjdbc.config.JDBCType
class when a JDBC type requires special handling.
For example, the new class names for the Oracle BLOB and CLOB data types are included in the
typeClassName attribute of the BLOB and CLOB JDBC types in the Oracle database configuration
file because the Oracle BLOB and CLOB data types require special handling.
columnTypeMapping
Contains the mapping between the native SQL type of a column in a particular database (in the
columnType element) and the corresponding JDBC type.
In addition, the following attributes provide special handling of a particular column type.
alternativeName
Specifies the value returned by the JDBC driver when a native SQL column type in a database has
a different name from the name returned by the driver.
For example, a column of double precision type in a Sybase database is returned as double precis
by the driver. In this case, the alternativeName attribute is set to double precis in the Sybase type
mapping configuration file so that the adapter can recognize it as the double precision type.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 183
8 Data Type Configuration
includeColumnSize
Specifies whether a column type name is suffixed with the column size when creating an adapter
service or notification. When the attribute is set to false, the column size is not included. The
default value is true.
resizeFactor
Indicates that the size of a column is different from the size returned by the JDBC driver. The
default value is 1, that is, the column size is the same as the size returned by the JDBC driver.
includePrecision
Specifies whether to include column precision for a Decimal or Numeric JDBC type. If the attribute
is set to true, precision is included. The default value is false.
1. Open the database-specific data type mapping configuration file from the location-
Integration Server_directory\instances\instance_name\packages\WmJDBCAdapter\config directory.
For example, to configure the SDO_GEOMETRY data type in an Oracle database, open the
OracleTypeMapping.xml file.
2. Add the jdbcType, typeClassName , and javaType attributes for the new data type in the
extTypeMapping section of the configuration file.
For example,
<extTypeMapping>
....
...
<jdbcType name="SDO_GEOMETRY" code="2002"
typeClassName="com.test.OracleSDOGeometryType">
<javaType name="STRING"/>
<javaType name="STRUCT"/>
<javaType name="OBJECT"/>
</jdbcType>
</extTypeMapping>
3. In the columnTypeMapping section of the file, specify the new data type for the jdbcTypeName
and nativeSqlType attributes in the columnType. This allows you to map the column in the
database with the jdbcType attribute.
For example,
<columnType jdbcTypeName="SDO_GEOMETRY"
nativeSqlType="SDO_GEOMETRY" includeColumnSize="false"/>
184 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
8 Data Type Configuration
4. Create a new custom java class. Use the following attributes in the table to create the custom
java class:
Class Name You can specify any name for the attribute.
Base Class The new custom java class must be derived from the base class which is
com.wm.adapter.wmjdbc.config.JDBCType.
Example,
The template to create a new java class for SDO_GEOMETRY data type in an Oracle database
is as follows:
import com.wm.adapter.wmjdbc.config.JDBCType;
public class OracleSDOGeometryType extends JDBCType {
public OracleSDOGeometryType(String name, int code, JAVAType javaType) {
super(name, code, javaType);
}
@Override
public Object getOutput(ResultSet results, int index) throws
SQLException,DataMappingException {
/* Enter your code */
}
@Override
protected void setInput(PreparedStatement statement, int index, Object value) throws
6. Copy the .jar files for the typeClassName attribute to the location:
Integration Server_directory\instances\instances_name\pacakges\WmJDBCAdapter\code\jars
directory.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 185
8 Data Type Configuration
2. Copy the database-specific data type mapping configuration file from the
Integration Server_directory\instances\instance_name\packages\WmJDBCAdapter\config directory
to the custom directory. For example, copy OracleTypeMapping.xml file from source location
to target location.
3. Open the database-specific type mapping configuration file from the custom directory and
modify it as required. For example, to configure the SDO_GEOMETRY data type in an Oracle
database, open the OracleTypeMapping.xml file in custom directory, customize the file as per
your specification, adhering to the TypeMapping.xsd schema located in the
Integration Server_directory\instances\instance_name\packages\WmJDBCAdapter\config directory.
Note:
If the modified file fails validation, Adapter for JDBC ignores the file and the adapter
connections will work with the default configuration files.
Oracle
To enable SQLXML data type support for Oracle, you must download the xdb6.jar and
xmlparserv2.jar files from the Oracle website and copy them to the
Integration Server_directory\instances\instance_name\packages\WmJDBCAdapter\code\jars\static
directory.
Note:
After installing a new fix, reapply the changes made to the configuration files manually.
186 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
9 Predefined Health Indicator
■ Predefined Health Indicator .......................................................................................... 188
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 187
9 Predefined Health Indicator
188 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
10 Administrator APIs
■ Administrator APIs ........................................................................................................ 190
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 189
10 Administrator APIs
Administrator APIs
The Administrator APIs are available for Adapter for JDBC. For more information about
Administrator APIs and samples, see IBM webMethods Adapter Runtime User's Guide.
190 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
11 Configuration Variables Templates for Adapter
Assets in Microservices
■ Configuration Variables Templates for Adapter Assets in Microservices Runtime ........ 192
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 191
11 Configuration Variables Templates for Adapter Assets in Microservices
192 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
12 Parallel Asset Initialization
■ Parallel Asset Initialization ............................................................................................ 194
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 193
12 Parallel Asset Initialization
194 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
13 Logging and Exception Handling
■ Overview of Logging and Exception Handling .............................................................. 196
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 195
13 Logging and Exception Handling
For a list of known database driver limitations, see “JDBC Driver Specific Properties” on page 257.
1. From the Integration Server Administrator screen, select Settings > Logging.
The Logging Settings screen appears. The Loggers section has Adapters included in the
Facility section.
2. Expand the Adapters tree to see a list of all installed adapters with their code number and
adapter description, along with the logging level.
1. Click Edit Logging Settings. Select the required Level of Logging for Adapter for JDBC.
3. For complete information about specifying the amount and type of information to include in
the log, see the IBM webMethods Audit Logging Guide for your release.
196 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
13 Logging and Exception Handling
The logging levels for Adapter for JDBC are given in the following table.
Integration Server 10.3 Audit Log You can monitor individual adapter services
using the audit log as you would audit any
service in Integration Server. The audit
properties for an adapter service are available in
each Adapter for JDBC service template on the
Audit tab.
Adapter for JDBC's log messages appear in either of the following formats:
ADA.1.nnnnc
ADA.0001.nnnnc
where the facility code ADA indicates that the message is from an adapter, 0001 or 1 indicate that
it is Adapter for JDBC, nnnn represents the error's minor code, and (optionally) c represents the
message's severity level. For detailed descriptions of Adapter for JDBC's minor codes, see “Adapter
for JDBC Error Codes ” on page 202.
To monitor Adapter for JDBC's log messages in the server log, ensure that your server log's logging
settings are configured to monitor the following facilities:
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 197
13 Logging and Exception Handling
1. To report an error related to the adapter's logic, such as a configuration error or a connection
creation error.
2. To wrap an SQLException if the adapter does not consider the SQLException's SQLCODE to
be a fatal error. In this case, WmART wraps the AdapterException in a
com.wm.pkg.art.error.DetailedServiceException and throws it to . AdapterExceptions containing
an error code of 316 are SQLExceptions.
AdapterException
Adapter for JDBC throws an AdapterException for two reasons:
1. To report an error related to the adapter's logic, such as a configuration error or a connection
creation error.
2. To wrap an SQLException if the adapter does not consider the SQLException's SQLCODE to
be a fatal error. In this case, WmART wraps the AdapterException in a
com.wm.pkg.art.error.DetailedServiceException and throws it to Integration Server.
AdapterExceptions containing an error code of 316 are SQLExceptions.
To manage the AdapterException, you can catch the DetailedServiceException in a flow or Java
service and then navigate through the nested exceptions to the AdapterException, which will
contain the error code identifying the error.
AdapterConnectionException
Adapter for JDBC throws an AdapterConnectionException to wrap an SQLException if the adapter
interprets the SQLCODE as a fatal error.
In this case, WmART resets the entire connection pool. WmART then wraps the exception in
com.wm.pkg.art.error.DetailedSystemException and throws it to Integration Server.
198 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
13 Logging and Exception Handling
SQLException
When an adapter connection's associated JDBC driver fails to execute a SQL command against a
database, the driver throws a SQLException. SQLExceptions include a SQL STATE, a SQLCODE,
and an error message.
Adapter for JDBC catches the SQLException from the JDBC driver and, depending on the
SQLCODE, wraps the SQLException in either an AdapterException or an
AdapterConnectionException. If a SQL CODE is in the adapter's list of fatal errors for the database,
the adapter wraps the exception in an AdapterConnectionException; otherwise, it wraps it in an
AdapterException. Each AdapterException and AdapterConnectionException contains an adapter
error code. If the error code is 316, then the exception wraps an SQLException.
3. Select Edit Extended Settings. In the edit box, type either of the following watt parameters:
This watt property is database driver specific. Note that there is no space after the , (comma).
Example: To allow Adapter for JDBC to refresh connections when encountering Oracle
error codes 17002 and 17003 using an Oracle JDBC driver, type:
watt.adapter.JDBC.Oracle.fatalErrors=+17002,17003
Note:
If the error code of a database starts with a zero, then remove the zero from the error
code and append the remaining code to the list. For example, for Oracle database, if you
want to add the error code, 01401, then type the watt parameter as follows:
watt.adapter.JDBC.Oracle.fatalErrors=+1401
Driver Setting
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 199
13 Logging and Exception Handling
Driver Setting
JTOpen watt.adapter.JDBC.DB2JTOPEN.fatalErrors
watt.adapter.JDBC.database.fatalErrors=+ErrorCode_1,ErrorCode_2, ErrorCode_n
This watt property is not database driver specific, instead applies to all drivers. Note that
there is no space after the , (comma).
Example: To allow Adapter for JDBC to refresh connections when encountering error codes
12535, type:
watt.adapter.JDBC.database.fatalErrors=+12535
It is recommended that you use this watt property to add error codes to the adapter's list
of error codes, instead of watt.adapter.JDBC.database driver.fatalErrors.
To override the existing fatal error list with a new fatal error list
200 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
13 Logging and Exception Handling
For example, to override the list of fatal error codes for Adapter for JDBC with a list of error
codes 17002, 17003, and 16702 for Oracle driver, type the following:
watt.adapter.JDBC.Oracle.fatalErrors=17002,17003,16702
Note that there is no space after the , (comma). For a list of other supported driver settings,
see “Customizing the Adapter's List of Fatal Error Codes” on page 199.
Note:
If the error code of a database starts with a zero, then remove the zero from the error code
and append the remaining code to the list. For example, for Oracle database, if you want to
override the error code, 01401, then type the watt parameter as follows:
watt.adapter.JDBC.Oracle.fatalErrors=1401
By default, Adapter for JDBC's fatal error codes are 17001, 17002, 17416, 1092, 28, 1012, 17410,
12571, 3114, 1089, 1033, 08S01, 40003, -30081, -99999, HY000, -601, JZ0C0, -79716. This list is a
combination of common fatal error codes from different databases.
where ErrorCode_1, ErrorCode_2, and ErrorCode_n are the error codes of the errors that you
want to suppress, and Error_Description is the description of the error that you want to suppress.
For databases that do not have error codes, you can provide the error description.
Example: To allow Adapter for JDBC to suppress the error codes ORA-12500, ORA- 01033,
17002, and the error with description User account is locked, type the following:
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 201
13 Logging and Exception Handling
watt.adapter.JDBC.SuppressErrorCodes=ORA-12500,ORA-01033,17002,User account
is locked
Action: Check the spelling and make sure the JDBC driver file is in the
CLASSPATH or in the packages_directory/WmJDBCAdapter/code/jars directory.
Explanation: Properties cannot be set through the DataSource class because the
driver does not support the specified property.
Action: For supported drivers and their settings, see “Using JDBC Drivers to
Connect to Databases” on page 13.
203 The JDBC DataSource class ClassName does not have some of the configured
property settings.
Action: For supported drivers and their settings, see “Using JDBC Drivers to
Connect to Databases” on page 13.
Explanation: Check the SQL exception in the Integration Server error log, and
check the database error messages.
202 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
13 Logging and Exception Handling
Action: The connection between the adapter and the database failed.
Action: Check the SQL exception in the Integration Server error log, and check
the database error messages.
Action: For supported drivers and DataSource class names, see your Adapter
for JDBC documentation.
208 Cannot disconnect from the database DataBaseName. The connection between
the adapter and database cannot be closed.
Explanation: The connection between the adapter and database cannot be closed.
Action: Check the SQL exception in the Integration Server error logs and database
error messages for details.
209 Cannot create writer with file path FilePathName or JDBC Log.
Action: Check that the log file path has the correct
watt.adapter.JDBC.JDBCLogFile setting.
Explanation: The OEM version of the DataDirect Connect for JDBC driver cannot
be unlocked with the key "webMethods".
Action: Check that the driver is the OEM version and that the key is
"webMethods".
306 The adapter does not support Ordered Notification for this database
DataBaseName. Please select another service or notification template.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 203
13 Logging and Exception Handling
307 The adapter does not support Automatic Notification for this DataBaseName.
Please select another operation template.
308 There must be at least one expression for the SELECT statement.
Explanation: You did not specify any rows using the SELECT tab for the
configured service.
Action: Add at least one column of the main table under the SELECT tab.
310 The database vendor VendorName does not support the database trigger
condition.
Explanation: The WHEN trigger condition does not apply to this database.
Action: Check the adapter connection and contact your administrator to increase
the number of connections.
Action: Check the SQL exception in the Integration Server error logs and database
error messages for details.
204 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
13 Logging and Exception Handling
316 Cannot execute the SQL statement SQLStatement. SQL statements failed to
execute.
Action: Check the SQL exception in the Integration Server error logs and database
error messages for details.
Action: Check the SQL exception in the Integration Server error logs and database
error messages for details.
Action: Check the SQL exception in the Integration Server error logs and database
error messages for details.
Action: Check the SQL exception in the Integration Server error logs and database
error messages for details.
Action: Check the SQL exception in the Integration Server error logs and database
error messages for details.
Action: Check the SQL exception in the Integration Server error logs and database
error messages for details.
326 This database does not support stored procedure calls using JDBC stored
procedure escape syntax.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 205
13 Logging and Exception Handling
331 The String for the input field InputFieldName does not contain a parsable
number.
333 You must have the Record ID column listed under the SELECT tab.
Action: Add the Record ID column using the SELECT tab for the Basic
Notification.
Explanation: You configured more than one result set for the Stored Procedure
Notification.
Action: Rewrite the stored procedure and configure only one result set.
335 A notification procedure can only have a single Oracle REF Cursor.
Explanation: You configured more than one Oracle REF Cursor for the Stored
Procedure Notification.
Action: Rewrite the stored procedure and configure only one Oracle REF Cursor.
336 If you choose Only Once Notification, you must also check the Delete Selected
Records box to avoid duplicate document warning messages.
Action: For a list of supported data type mappings, see “JDBC Data Type to Java
Data Type Mappings” on page 216.
206 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
13 Logging and Exception Handling
339 The number of Base Name characters used in Notification Configure tab must
not exceed MaximumCharacterLength.
Action: Refer to the message itself and shorten the Base Name using the
Notification Configure tab.
Action: Check the command and error message. For more details see the error
logs.
Explanation: An error occurs when the adapter creates the file on the AS/400
system.
Explanation: An error occurs when the adapter creates a trigger on the AS/400
system.
Action: Check whether there is already a trigger with this name. Also check
whether the user has rights to create the trigger.
Explanation: Errors occur when the adapter drops a trigger from the AS/400
system.
501 BaseName is not a valid name. For the notification on AS/400, the name of the
source table, buffer table and trigger should not exceed 10 characters.
Action: Change the base name so that the names of buffer table and trigger are
10 characters or less.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 207
13 Logging and Exception Handling
208 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
14 Support for OData Service
■ Understanding OData Service Terminology in Adapter ................................................ 210
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 209
14 Support for OData Service
External Entity Type. External entity types are the representation of database tables. For more
details on OData specific terminology, see the IBM webMethods Service Development Help.
System query options such as $select, $filter, $orderby, $top, $skip, $inlinecount,
and $count.
Referential constraints
Important:
Not all of Integration Server’s OData features are supported when using an OData service
with IBM webMethods Adapter for JDBC.
For instruction on how to create an OData service using Designer, refer to "Working with OData
Services" chapter in the IBM webMethods Service Development Help.
Once you select a connection from the list of configured Connection Alias, Adapter for JDBC
retrieves the list of database tables in the current catalog. You can add the database tables associated
with the connection as external entity type to the OData service. These entity types are displayed
in schema_TableName format in Designer.
In Designer, when you select an external entity type, Adapter for JDBC retrieves the properties
for that entity type. You can configure the Java Data Type for the respective property. Each Java
Data Type is mapped to a corresponding EDM Type. The mapping between Java Data type to
EDM Type is shown below:
210 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
14 Support for OData Service
Note:
You can make a property as key for the tables that do not have the primary key defined in
the database. This can be done using the OData Sync feature.
For MSSQL server, do not make entity property as a key which has SQL datatype nchar,
as it may append extra character space in OData response link tag.
To modify the external entity type, see the "Working with OData Services" chapter in the IBM
webMethods Service Development Help.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 211
14 Support for OData Service
Adapter for JDBC also supports filter expressions in OData requests to filter and return only those
results that match the expression specified. You can add the $filter system query option at the
end of the OData request.
212 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
14 Support for OData Service
Note:
The functions such as ceiling and round are applicable only for Oracle database.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 213
14 Support for OData Service
214 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
A Data Type Mapping
■ JDBC Data Type to Java Data Type Mappings ............................................................. 216
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 215
A Data Type Mapping
The following table shows the JDBC data type to Java data type mappings. You can map each
JDBC data type to a set of Java data types by choosing one from the set. The JDBC data type you
select during configuration will then map to the input or output of the adapter service or
notification.
For a list of data types for which Integration Server has some constraints, see “JDBC Data Type to
Java Data Type Mapping Constraints” on page 221.
Note:
Adapter for JDBC does not support the DATALINK DB2 data type when using the adapter
with DB2 for AS/400 or DB2 for OS/390.
Note:
Adapter for JDBC does not support the TIMESTAMP WITH TIME ZONE and TIMESTAMP
WITH LOCAL TIME ZONE data types in Oracle 10g.
Note:
Adapter for JDBC does not support user-defined data types, Oracle PL/SQL collections, or
Oracle PL/SQL records.
ARRAY java.sql.Array
java.lang.Object
BIT java.lang.Boolean
java.lang.String
java.lang.Object
TINYINT java.lang.Byte
java.lang.Integer
java.lang.String
java.lang.Object
SetAsString
SMALLINT java.lang.Short
java.lang.Integer
216 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
A Data Type Mapping
java.lang.String
java.lang.Object
INTEGER java.lang.Integer
java.lang.String
java.lang.Object
BIGINT java.lang.Long
java.lang.String
java.lang.Object
FLOAT java.lang.Double
java.lang.String
java.lang.Object
java.math.BigDecimal
SetAsString
REAL java.lang.Float
java.lang.String
java.lang.Object
java.math.BigDecimal
BOOLEAN java.lang.Boolean
java.lang.String
java.lang.Object
DOUBLE java.lang.Double
java.lang.String
java.lang.Object
java.math.BigDecimal
SetAsString
NUMERIC java.math.BigDecimal
java.lang.String
java.lang.Object
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 217
A Data Type Mapping
DECIMAL java.math.BigDecimal
java.lang.String
java.lang.Object
CHAR java.lang.String
java.lang.Character
java.lang.Object
VARCHAR java.lang.String
java.lang.Object
LONGVARCHAR java.lang.String
java.lang.Object
DATE java.sql.Date
java.util.Date
java.lang.String
java.lang.Object
SetAsString
TIME java.sql.Time
java.util.Date
java.lang.String
java.lang.Object
SetAsString
TIMESTAMP java.sql.Timestamp
java.util.Date
java.lang.String
java.lang.Object
SetAsString
218 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
A Data Type Mapping
java.lang.Object
java.lang.Object
java.lang.Object
LONGNVARCHAR java.lang.String
java.lang.Object
NCHAR java.lang.String
java.lang.Object
NULL java.lang.String
java.lang.Object
NVARCHAR java.lang.String
java.lang.Object
CLOB java.sql.Clob
java.lang.String
java.io.Reader
java.lang.Object
BLOB java.sql.Blob
byte array
java.io.InputStream
java.lang.Object
ORACLECURSOR java.lang.Object
ORACLEFIXED_CHAR java.lang.String
STRUCT java.sql.Struct
java.lang.Object
OTHER java.lang.Object
java.lang.String
java.sql.Struct
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 219
A Data Type Mapping
java.sql.Array
When using the CLOB data with java.io.Reader as input data type, it is recommended that
you use the InputStreamReader implementation of java.io.Reader with the correct encoding
parameter.
When Designer executes a Adapter for JDBC SELECT service that has its output type set to
java.sql.Blob for a BLOB data type, Designer issues a java.io.NotSerializableException error.
To work around this issue, perform one of the following:
When using the java.sql.Array or java.sql.Struct as the output field type for a database column
of type array or struct, Adapter for JDBC returns the java.sql.Array and the java.sql.Struct
objects, respectively, as returned by the driver. However, when serializing the data across the
JVMs, this returned data may not be serializable and may result into a
java.io.NotSerializableException. Therefore, before serializing the data across the JVMs, it is
important that you use a Java or a flow service to process the java.sql.Struct and java.sql.Array
objects as required, and then drop them from the pipeline.
Note:
The java.sql.Struct and java.sql.Array data types are available only for Adapter for JDBC
services.
220 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
A Data Type Mapping
For example, you can specify the format for date, time, or timestamp using the to_date function
or a similar database function for Oracle database. Adapter for JDBC treats the input data as a
string data type and does not convert it to the equivalent JDBC data type. The to_date function
then uses the string data to provide the required format of the date, time or timestamp.
If your database has native database specific functions that can convert string data type to any
other data type, you may use the SetAsString data type.
Note:
The SetAsString data type is available only for Adapter for JDBC services.
If you select one of the following Java data types, the data type will map exactly to the Input/Output
tab in Designer:
java.lang.String
java.lang.Byte
java.lang.Boolean
java.lang.Character
java.lang.Double
java.lang.Float
java.lang.Integer
java.lang.Long
java.lang.Short
java.util.Date
java.math.BigDecimal
java.math.BigInteger
java.lang.Object
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 221
A Data Type Mapping
Those data types not included in this list will map to java.lang.Object. In these cases, if the JDBC
data type you specify is for input, you will need to pass in the object with the selected Java data
type. If the JDBC type is for output, you can cast the object to the selected Java data type.
INTEGER INT4
BIGINT INT8
DOUBLE FLOAT8
CHAR BPCHAR
DATE DATE
TIME TIME
TIMESTAMP TIMESTAMP
BINARY BYTEA
BIT BOOL
222 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
B Built-In Services
■ Overview ...................................................................................................................... 224
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 223
B Built-In Services
Overview
This appendix provides information on the built-in services provided by IBM webMethods Adapter
for JDBC. These services are located in the WmJDBCAdapter package.
pub.jdbcAdapter:updateNotificationSchema
The pub.jdbcAdapter:updateNotificationSchema Java service changes the schema names configured in the
following types of notifications: InsertNotification, DeleteNotification, UpdateNotification,
OrderedNotification, and BasicNotification.
This service always validates the new schemas against the notification settings, and sets the state
of the notification to the state it is in before it is updated, regardless of whether the update is
successful.
Step Description
2 If the notification is enabled, the service checks the forceDisable parameter. If forceDisable
is false, the service reports the error. If forceDisable is true, the service disables the
notification.
3 The service validates the schema against the notification's settings. The validation requires
that the schema be in the same catalog that is configured with the notification and that
the table, synonym, view, or alias, configured in the notification be in the schema. If the
schema is not valid, the service throws an exception.
4 The service updates the notification property with the new schemas, and throws an
exception if the input fields for the new schemas are not valid.
5 If the original notification state is enabled, the service enables the notification.
Note:
If an exception is thrown when the service attempts to re-enable a polling notification, you will
receive the message "The schema is updated but the notification could not be enabled." This is
because, by design, the metadata has already been updated. You might need to roll back to the
previous state, as needed.
Input Parameters
224 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
B Built-In Services
Output Parameters
None.
The allSchemaChange and schemaChanges fields are mutually exclusive. This means that if
allSchemaChange is set, then schemaChanges will be ignored.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 225
B Built-In Services
The useCurrentSchema and schemaName fields are mutually exclusive everywhere they occur
in the input. This means that if useCurrentSchema is set to true, then the value in schemaName
will be ignored.
The service does not generate output. It throws an AdapterServiceException and wraps
exceptions from ART and Adapter for JDBC.
Note:
Fields that do not list an input value in the tables below should be left empty.
nodeName folder1:notification1
forceDisable true
allSchemaChange
allSchemaChange.useCurrentSchema true
nodeName folder1:notification1
forceDisable true
allSchemaChange
allSchemaChange.schemaName A
226 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
B Built-In Services
nodeName folder1:notification1
forceDisable true
schemaChanges
schemaChanges[0]
schemaChanges[0].existingSchema
schemaChanges[0].existingSchema.useCurrentSchema true
schemaChanges[0].newSchema
schemaChanges[0].newSchema.schemaName A
nodeName folder1:notification1
forceDisable true
schemaChanges
schemaChanges.schemaChanges[0]
schemaChanges.schemaChanges[0].existingSchema
schemaChanges.schemaChanges[0].existingSchema.schemaName A
schemaChanges.schemaChanges[0].newSchema
schemaChanges.schemaChanges[0].newSchema.useCurrentSchema true
nodeName folder1:notification1
forceDisable true
schemaChanges
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 227
B Built-In Services
schemaChanges.schemaChanges[0]
schemaChanges.schemaChanges[0].existingSchema
schemaChanges.schemaChanges[0].existingSchema.schemaName A
schemaChanges.schemaChanges[0].newSchema
schemaChanges.schemaChanges[0].newSchema.schemaName A1
schemaChanges.schemaChanges[1]
schemaChanges.schemaChanges[1].existingSchema
schemaChanges.schemaChanges[1].existingSchema.schemaName B
schemaChanges.schemaChanges[1].newSchema
schemaChanges.schemaChanges[1].newSchema.useCurrentSchema true
pub.jdbcAdapter:updateServiceSchema
The pub.jdbcAdapter:updateServiceSchema Java service enables you to change the schema settings
associated with an adapter service without having to manually update the service from the Designer
Adapter Service Editor.
This service supports the following types of services: InsertSQL, DeleteSQL, UpdateSQL, SelectSQL,
StoredProcedure, and StoredProcedureWithSignature.
Input Parameters
228 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
B Built-In Services
Output Parameters
None.
The allSchemaChange and schemaChanges fields are mutually exclusive. This means that if
allSchemaChange is set, then schemaChanges will be ignored.
The useCurrentSchema and schemaName fields are mutually exclusive everywhere they occur
in the input. This means that if useCurrentSchema is set to true, then the value in schemaName
will be ignored.
The service does not generate output. It throws an AdapterServiceException and wraps
exceptions from ART and Adapter for JDBC.
Note:
Fields that do not list an input value in the tables below should be left empty.
nodeName folder1:notification1
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 229
B Built-In Services
allSchemaChange
allSchemaChange.useCurrentSchema true
nodeName folder1:notification1
allSchemaChange
allSchemaChange.schemaName A
nodeName folder1:notification1
schemaChanges
schemaChanges[0]
schemaChanges[0].existingSchema
schemaChanges[0].existingSchema.useCurrentSchema true
schemaChanges[0].newSchema
schemaChanges[0].newSchema.schemaName A
nodeName folder1:notification1
schemaChanges
schemaChanges.schemaChanges[0]
230 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
B Built-In Services
schemaChanges.schemaChanges[0].existingSchema
schemaChanges.schemaChanges[0].existingSchema.schemaName A
schemaChanges.schemaChanges[0].newSchema
schemaChanges.schemaChanges[0].newSchema.useCurrentSchema true
nodeName folder1:notification1
schemaChanges
schemaChanges.schemaChanges[0]
schemaChanges.schemaChanges[0].existingSchema
schemaChanges.schemaChanges[0].existingSchema.schemaName A
schemaChanges.schemaChanges[0].newSchema
schemaChanges.schemaChanges[0].newSchema.schemaName A1
schemaChanges.schemaChanges[1]
schemaChanges.schemaChanges[1].existingSchema
schemaChanges.schemaChanges[1].existingSchema.schemaName B
schemaChanges.schemaChanges[1].newSchema
schemaChanges.schemaChanges[1].newSchema.useCurrentSchema true
pub.jdbcAdapter:updateConnectionPassword
The pub.jdbcAdapter:updateConnectionPassword service updates the existing password of an existing
connection with a new password without requiring you to manually change the connection's
password in the Connection Properties screen.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 231
B Built-In Services
Input Parameters
connectionAlias String. Required. The name of the connection for which the password
has to be updated.
confirmNewPassword String. Required. The new password for the connection. This is required
to confirm the new password.
Output Parameters
None.
pub.jdbcAdapter:createConnectionNodes
The pub.jdbcAdapter:createConnectionNodes service automatically configures the JDBC connections
without requiring you to use the Administrative screens.
The pub.jdbcAdapter:createConnectionNodes service is useful when you need to configure a large number
of connections. The input for this service is an XML file that contains the connection configuration
properties that are required to configure the connections.
Note:
When using the encoding attribute in the XML file, ensure that it matches the encoding used
when the XML file is saved, and also supports the characters specified in the file. This ensures
the correct interpretation of any foreign characters in the XML file.
In the XML file, provide the Connection properties and the Connection Manager properties as
name-value pairs. Based on the number of connections that need to be configured, provide the
same number of connection configuration property sets in the XML file. For example, in the XML
file, if you provide two connection configuration property sets, the pub.jdbcAdapter:createConnectionNodes
service configures only two connections.
Note:
If the Connection Manager properties for the connection are not provided in the XML file, the
connection is configured using the default Connection Manager properties.
Note:
232 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
B Built-In Services
After executing the service, the Results panel displays the status (success or failure) for each
connection. The Results panel also displays an error message for the connection that has failed to
configure.
Input Parameters
fileName String. Required. The path of the XML file that contains the connection
configuration properties.
Output Parameters
None.
Usage Notes
Using the pub.jdbcAdapter:createConnectionNodes service, you can configure a deleted connection that
was configured using this service, but you cannot configure a connection that already exists. An
error will be displayed in the Results panel indicating that there was a failure in configuring the
connection. For example, consider the following scenario:
2. In the fileName field, type the path of the XML file containing the connection properties. The
input XML file has properties for configuring connections conn_local1 and conn_local2.
6. The deleted connection conn_local1 is configured again, but the existing connection conn_local2
is not configured. No error message is thrown, but the Results panel shows a message indicating
that there was a failure in configuring connection conn_local2.
<serverName>localhost</serverName>
<user>user1</user>
<password>abc123</password>
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 233
B Built-In Services
<databaseName>ORCL1</databaseName>
<portNumber>1521</portNumber>
<otherProperties>driverType=thin</otherProperties>
<networkProtocol>TCP</networkProtocol>
</connectionSettings>
<connectionManagerSettings>
<poolable>true</poolable>
<minimumPoolSize>1</minimumPoolSize>
<maximumPoolSize>10</maximumPoolSize>
<poolIncrementSize>1</poolIncrementSize>
<blockingTimeout>1000</blockingTimeout>
<expireTimeout>1000</expireTimeout>
<startupRetryCount>1</startupRetryCount>
<startupBackoffSecs>20</startupBackoffSecs>
<heartBeatInterval>15</heartBeatInterval>
</connectionManagerSettings>
</Connection>
<Connection>
<packageName>MyJDBC</packageName>
<connectionAlias>Connections:con_local2</connectionAlias>
<connectionSettings>
<transactionType>NO_TRANSACTION</transactionType>
<datasourceClass>oracle.jdbc.pool.OracleConnectionPoolDataSource</datasourceClass>
<serverName>localhost</serverName>
<user>user2</user>
<password>xyz321</password>
<databaseName>ORCL1</databaseName>
<portNumber>1521</portNumber>
<otherProperties>driverType=thin</otherProperties>
<networkProtocol>TCP</networkProtocol>
</connectionSettings>
<connectionManagerSettings>
<poolable>true</poolable>
<minimumPoolSize>5</minimumPoolSize>
<maximumPoolSize>10</maximumPoolSize>
<poolIncrementSize>1</poolIncrementSize>
<blockingTimeout>1000</blockingTimeout>
<expireTimeout>1000</expireTimeout>
<startupRetryCount>1</startupRetryCount>
<startupBackoffSecs>20</startupBackoffSecs>
<heartBeatInterval>15</heartBeatInterval>
</connectionManagerSettings>
</Connection>
</Connections>
pub.pollingNotificationUtils:dropDatabaseObjects
The servicepub.pollingNoificationUtils:dropDatabaseObjects allows you to automatically clean up the
existing database objects of a notification.
Input Parameters
notificationName String. Required. The name of the notification from which the database
objects need to be deleted.
234 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
B Built-In Services
Output Parameters
None.
Usage Notes
Disable the target notification before invoking this service. Invoking this service for an enabled
or a suspended notification, throws an error.
pub.pollingNotificationUtils:getDatabaseObjectsForNotification
The service pub.pollingNotificationUtils:getDatabaseObjectsForNotification allows you to list the existing
database objects associated with a notification.
The service returns null against the database objects that do not exist.
Input Parameters
notificationName String. Required. The name of the notification from which to list the
database objects.
jdbcConnectionSchemaName String The name of the schema in the connection for the notification.
Output Parameters
wm.adapter.wmjdbc.utils:docListToObject
The wm.adapter.wmjdbc.utils:docListToObject utility service maps an input parameter of type Document
List to a parameter of type Object.
Input Parameters
docList Document List. Represents the Document List value to be mapped to the
type Object.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 235
B Built-In Services
Output Parameters
obj Object. Represents the Object value mapped to the type Document List.
wm.adapter.wmjdbc.utils:objectToDocList
The wm.adapter.wmjdbc.utils: objectToDocList utility service maps an input parameter of type Object to
a parameter of type Document List.
Input Parameters
obj Object. Represents the Object value to be mapped to the type Document
List.
Output Parameters
docList Document List. Represents the Document List value mapped to the type
Object.
wm.adapter.wmjdbc.admin.service:update
The wm.adapter.wmjdbc.admin.service:update service updates the table name in the configured adapter
services.
By default, the wm.adapter.wmjdbc.admin.service:update service runs under simulation mode, that is, no
actual changes are made to the corresponding JDBC service nodes, and only a check is performed
if the service nodes can be updated successfully.
Input Parameters
236 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
B Built-In Services
glob.
regex. Default.
connectionAlias String. Required. Name of the connection alias. All JDBC service
nodes matched by the namespace filter and having this
connection alias are picked for an update.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 237
B Built-In Services
true.
false. Default.
Output Parameters
238 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
B Built-In Services
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 239
B Built-In Services
240 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
C Built-In Transaction Management Services
■ Transaction Management Overview ............................................................................. 242
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 241
C Built-In Transaction Management Services
For information about other built-in services available with Adapter for JDBC, see the IBM
webMethods Integration Server Built-In Services Reference for your release.
Transactions
Integration Server considers a transaction to be one or more interactions with one or more resources
that are treated as a single logical unit of work. The interactions within a transaction are either all
committed or all rolled back. For example, if a transaction includes multiple database inserts, and
one or more inserts fail, all inserts are rolled back.
Transaction Types
Integration Server supports the following kinds of transactions:
Integration Server can automatically manage both kinds of transactions, without requiring the
adapter user to do anything. Integration Server uses a container-managed (implicit) transaction
management approach based on the Connector Architecture standard, and also performs some
additional connection management. This is because adapter services use connections to create
transactions. For more information about implicit transactions, see “Implicit and Explicit
Transactions” on page 243.
However, there are cases where adapter users need to explicitly control the transactional units of
work. Examples of these cases are provided in “Implicit and Explicit Transaction Examples” on
page 245.
To support transactions, Integration Server relies on an Oracle transaction manager. The transaction
manager is responsible for beginning and ending transactions, maintaining a transaction context,
enlisting newly connected resources into existing transactions, and ensuring that local and
XAResource transactions are not combined in illegal ways.
The transaction manager only manages operations performed by adapter services, a transacted
JMS trigger, or a built-in JMS service that uses a transacted JMS connection alias.
Important:
You cannot step or trace a flow that contains a transacted adapter service or a transacted JMS
service.
242 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
C Built-In Transaction Management Services
XA Transactions
If an XA transactional connection throws an exception during a service transaction and the exception
results in an inconsistent state, you may need to resolve the transaction using the tools provided
with the database.
For information about using Integration Server to manage XA transactions, see the IBM webMethods
Integration Server Administrator’s Guide for your release.
The following sections describe implicit and explicit transactions and how to manage them.
Implicit Transactions
With implicit transactions, Integration Server automatically manages both local and XAResource
transactions without requiring you to explicitly do anything. That is, Integration Server starts and
completes an implicit transaction with no additional service calls required by the adapter user.
A transaction context, which the transaction manager uses to define a unit of work, starts when
an adapter service is encountered in a flow execution. The connection required by the adapter
service is registered with the newly created context and used by the adapter service. If another
adapter service is encountered, the transaction context is searched to see if the connection is already
registered. If the connection is already registered, the adapter service uses this connection. If the
connection is not registered, a new connection instance is retrieved and registered with the
transaction.
Note that if the top level flow invokes another flow, adapter services in the child flow use the same
transaction context.
When the top level flow completes, the transaction is completed and is either committed or rolled
back, depending on the status (success or failure) of the top level flow.
A single transaction context can contain any number of XA_TRANSACTION connections but no
more than one LOCAL_TRANSACTIxON connection. If you choose to provide dynamic user
credentials at run time, then all the adapter services using the LOCAL_TRANSACTION connection
within a single transaction must use the same user credentials. For example, if you have two
adapter services s1 and s2 configured using the LOCAL_TRANSACTION connection c1 in a single
transaction context, then both s1 and s2 must either use the same dynamic credentials at run time
or the default configured credentials provided at design time. For more information on dynamic
user credentials for a service's associated connection, see“Changing the User Credentials of a
Service's Associated Connection at Run Time” on page 21.
For implicit transaction examples, see “Implicit and Explicit Transaction Examples” on page 245.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 243
C Built-In Transaction Management Services
For more information about designing and using flows, see the IBM webMethods Service Development
Help for your release.
For more information about transaction types, see “Transaction Management of Adapter
Connections” on page 14.
Explicit Transactions
You use explicit transactions when you need to explicitly control the transactional units of work.
To do this, you use additional services, known as built-in services, in your flow.
For more information on dynamic user credentials for a service's associated connection, see
“Changing the User Credentials of a Service's Associated Connection at Run Time” on page 21.
Note:
With explicit transactions, you must be sure to call either a commitTransaction or
rollbackTransaction for each startTransaction; otherwise you will have dangling transactions
that will require you to reboot Integration Server. You must also ensure that the startTransaction
is outside the SEQUENCE.
A new explicit transaction context can be started within a transaction context, provided that you
ensure that the transactions within the transaction context are completed in the reverse order they
were started-that is, the last transaction to start should be the first transaction to complete, and so
forth.
For explicit transaction examples, see “Implicit and Explicit Transaction Examples” on page 245.
244 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
C Built-In Transaction Management Services
Note:
You can use the pub.flow:getLastError service in the SEQUENCE, to retrieve the error information
when a sequence fails. For more information on using the pub.flow:getLastError service, see the
IBM webMethods Service Development Help for your release.
For more information about designing and using flows, see the IBM webMethods Service Development
Help for your release.
For more information about transaction types, see “Transaction Management of Adapter
Connections” on page 14.
Step Description
2 You configured the following adapter services which use the LOCAL_TRANSACTION
connections listed in step 1 above.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 245
C Built-In Transaction Management Services
Step Description
3 You configured the following adapter services which use the XA_TRANSACTION
connection listed in step 1 above.
4 You create the following flow examples (described in this section) using
LOCAL_TRANSACTIONs:
5 You create the following flow examples (described in this section) using both
XA_TRANSACTIONs and LOCAL_TRANSACTIONs:
246 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
C Built-In Transaction Management Services
This flow calls one adapter service (InsertLocal1) using a LOCAL_TRANSACTION connection.
This example demonstrates the correct way to set up your flow to use an explicit transaction. You
use the following construct of three SEQUENCEs, which is required to insure that the explicit
transaction is either committed (on success) or rolled back (on failure).
Step Description
1 The top-level SEQUENCE will exit on success. Note that the start transaction is outside
the SEQUENCE.
2 The transaction will be committed if successful, and the top-level SEQUENCE will
complete.
Note that with this construct, you will not get trigger retries or a retryable exception. The EXIT
statement will result in generating a Flow exception which is not retryable. To get retries, you will
need to use a REPEAT step statement in your flow. For information about using the REPEAT
statement, see the IBM webMethods Service Development Help for your release.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 247
C Built-In Transaction Management Services
In this example, InsertXA1 and SelectLocal2 are registered as part of the implicit transaction.
SingleLocalInsert is part of its own explicit transaction. The explicit transaction is required since
you are using two different local transaction connections (localConn1 and localConn2).
This flow shows an explicit transaction residing within another explicit transaction. The flow calls
a flow and an adapter service which use different LOCAL_TRANSACTION connections. Recall
that you must use an explicit transaction if you have more than one LOCAL_TRANSACTION
connection.
Notice that the flow is similar to the SingleLocalInsert flow example shown in “Flow Example:
SingleLocalInsert” on page 246, which uses a flow construct involving three SEQUENCEs to insure
that the explicit transaction is either committed (on success) or rolled back (on failure).
248 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
C Built-In Transaction Management Services
Step Description
1 The top-level SEQUENCE will exit on success. Note that the start transaction is outside
the SEQUENCE.
2 The transaction will be committed if successful, and the top-level SEQUENCE will
complete.
pub.art.transaction:commitTransaction
This service commits an explicit transaction. It must be used in conjunction with the
pub.art.transaction:startTransaction service.
If it does not have a corresponding pub.art.transaction:startTransaction service, your flow service will
receive a run time error. For more information about implicit and explicit transactions, see “Implicit
and Explicit Transactions” on page 243.
Input Parameters
Output Parameters
None.
pub.art.transaction:rollbackTransaction
This service rolls back an explicit transaction. It must be used in conjunction with the
pub.art.transaction:startTransaction service.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 249
C Built-In Transaction Management Services
If it does not have a corresponding pub.art.transaction:startTransaction service, your flow service will
receive a run time error. For more information about implicit and explicit transactions, see “Implicit
and Explicit Transactions” on page 243.
Input Parameters
Output Parameters
None.
pub.art.transaction:setTransactionTimeout
This service enables you to manually set a transaction timeout interval for implicit and explicit
transactions.
When you use this service, you are temporarily overriding the Integration Server transaction
timeout interval. For information on changing the server's default transaction timeout, see
“Changing the Integration Server Transaction Timeout Interval” on page 251.
You must call this service within a flow before the start of any implicit or explicit transactions.
Implicit transactions start when you call an adapter service in a flow. Explicit transactions start
when you call the pub.art.transaction:startTransaction service.
If the execution of a transaction takes longer than the transaction timeout interval, all transacted
operations are rolled back.
This service only overrides the transaction timeout interval for the flow service in which you call
it.
Input Parameters
timeoutSeconds Integer The number of seconds that the implicit or explicit transaction
stays open before the transaction manager marks it for rollback.
250 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
C Built-In Transaction Management Services
Output Parameters
None.
pub.art.transaction:startTransaction
This service starts an explicit transaction.
For more information about implicit and explicit transactions, see “Implicit and Explicit
Transactions” on page 243.
Input Parameters
Output Parameters
transactionName String. The name of the transaction the service just started.
Be sure to shut down Integration Server before you edit this file. After you make changes, restart
the server.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 251
C Built-In Transaction Management Services
This transaction timeout parameter does not halt the execution of a flow; it is the maximum number
of seconds that a transaction can remain open and still be considered valid. For example, if your
current transaction has a timeout value of 60 seconds and your flow takes 120 seconds to complete,
the transaction manager will rollback all registered operations regardless of the execution status.
For more information about adding parameters to the server.cnf file, see the IBM webMethods
Integration Server Administrator’s Guide for your release.
252 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
D Adapter Configuration Parameters
■ Overview ...................................................................................................................... 254
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 253
D Adapter Configuration Parameters
Overview
This appendix contains a description of Adapter for JDBC parameters you can specify in the server
configuration file (server.cnf), which is located in the Integration Server_directory\config directory.
Typically you use the Settings > Extended screen in Integration Server Administrator to update
this file, but there might be times when you need to edit the file directly using a text editor. If you
edit the file directly, you should first shut down Integration Server before updating the file. After
you make the changes, restart the server. If you are using the Settings > Extended screen to update
the server configuration file (server.cnf), a server restart is not required unless otherwise specified.
The server uses default values for the parameters. If a parameter has a default, it is listed with the
description of the parameter.
watt.adapter.JDBC.AutomaticNotification.Joincolumn.BufferTable
Specifies whether Adapter for JDBC displays the columns of the buffer table on the Joins tab for
an Insert, Delete, or Update polling notification, when the notification has an Output Field name
different from the column name in the source table, and the same column is selected on the Joins
tab. If the parameter is set to true, the adapter displays the columns of the buffer table on the
Joins tab for the notification. If the parameter is set the false, the adapter displays the columns
of the source table on the Joins tab for the notification.
watt.adapter.JDBC.DateWithTimestamp
Appends the timestamp to the output of an Adapter for JDBC service when the adapter service
retrieves data from a database table with a Date column, the JDBC type is set to DATE, and the
Output Field Type parameter is set to java.lang.String. When the parameter is set to true, the
adapter services append the timestamp to the output. When the parameter is set to false, the
default, the adapter services do not append the timestamp to the output.
watt.adapter.JDBC.DateWithTimestampAndMilliseconds
Appends the timestamp with milliseconds to the output of an Adapter for JDBC service when the
adapter service retrieves data from a database table with a Date column, the JDBC type is set to
DATE, and the Output Field Type parameter is set to java.lang.String or SetAsString. When the
parameter is set to true, the adapter services append the timestamp with milliseconds to the
output. When the parameter is set to false, the default, the adapter services append the timestamp
to the output without milliseconds.
watt.adapter.JDBC.DisableEmptyResult
Specifies whether Adapter for JDBC Custom SQL services and Dynamic SQL services return a
document when the result set returned by the database is empty. When the parameter is set to
true, the adapter services do not return an empty results document. When the parameter is set to
false, the default, the adapter services return an empty results document.
254 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
D Adapter Configuration Parameters
watt.adapter.JDBC.StoredProcedure.customRSColNames
Specifies whether Adapter for JDBC supports the mapping of custom column names in the Column
Name field to the result set in the Output signature of StoredProcedure and
StoredProcedureWithSignature services. When the parameter is set to true, the default, the adapter
supports the mapping of custom column names in the Column Name field. If the parameter is
set to false, the adapter uses the standard values that match the result set in the Output signature
of the StoredProcedure and StoredProcedureWithSignature service.
watt.adapter.JDBC.UsePlainString
Specifies whether Adapter for JDBC services return an exponential form of the column value
retrieved from a database when using Java version 1.5 and higher. When the adapter services
retrieve a column value of Decimal or Numeric JDBC Data Type and the Output Field Type is
defined as java.lang.String, the output returned may sometimes be in exponential form. The output
returned is the String obtained by invoking the BigDecimal.toString() method. Due to changes in
the behavior of BigDecimal.toString in Java 5, BigDecimal.toString() now returns exponential
values in some cases. When the watt.adapter.JDBC.UsePlainString parameter is set to true, Adapter
for JDBC invokes the toPlainString() method and returns the non-exponential form in all cases.
When the parameter is set to false, the default, the adapter invokes the toString() method, and
returns the exponential form if needed.
watt.adapter.JDBC.notification.useBaseNameAsPrefix
Enables users to customize the names of notification resources. Set the parameter to true to use
the Base Name provided in the notification as a prefix to notification resources like buffer table,
sequence, and trigger. The default values if false. The parameter is applicable to the SAP HANA
database only.
watt.adapter.JDBC.timezone.useGMT
Specifies whether Adapter for JDBC OData services retrieve, insert, and update time values in
GMT or local timezone. If the parameter is set to true, then the time values are retrieved, inserted,
and updated in GMT. The default value is false.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 255
D Adapter Configuration Parameters
256 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
E JDBC Driver Specific Properties
■ Apache Cassandra ....................................................................................................... 258
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 257
E JDBC Driver Specific Properties
Apache Cassandra
DataSource
NO_TRANSACTION wm.jdbcx.cassandra.CassandraDataSource40
Other Properties
Specify the parameters in the Other Properties field:
Parameter Description
Note:
LOCAL_TRANSACTION connections are not supported.
REFRESH SCHEMA Use REFRESH SCHEMA in SQL statement to add newly discovered objects to your
relational view of native data type.
webMethods BigData No No No No No No
Driver for Apache
Cassandra
258 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
E JDBC Driver Specific Properties
Limitations
Driver Database/ Limitation Description
Adapter IS Operating
System/
Platform Affected
2. Notifications: InsertNotifications,
UpdateNotifications, DeleteNotifications,
StoredProcedureNotifications,
StoredProcedureNotificationsWithSignature, and
OrderedNotifications
3. LOCAL_TRANSACTION and
XA_TRANSACTION connections
Apache Hive
DataSource
Other Properties
Specify the parameters in the Other Properties field:
Parameter Description
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 259
E JDBC Driver Specific Properties
Parameter Description
Note:
LOCAL_TRANSACTION connections are not supported.
Kerberos Authentication
Add the login module in Integration Server_directory\instances\<instance_name>\config\is_
jaas.cnf file. The is_jaas.cnf file is provided by Integration Server and located in
Integration Server_directory\instances\<instance_name>\config directory.
Configure the krb5.conf file in Integration Server Administrator. For more information, see
“Kerberos Authentication” on page 75.
Specify the Kerberos authentication parameters in the Other Properties field in the following
format:
authenticationMethod=kerberos;servicePrincipalName=<Service_Principal_Name>
For example:
authenticationMethod=kerberos;servicePrincipalName=hive/[email protected]
webMethods BigData No No No No No No
Driver for Apache Hive
DataSource
260 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
E JDBC Driver Specific Properties
Kerberos Authentication
Add the login module in Integration Server_directory\instances\<instance_name>\config\is_
jaas.cnf file. The is_jaas.cnf file is provided by Integration Server and located in
Integration Server_directory\instances\<instance_name>\config directory.
Configure the krb5.conf file in Integration Server Administrator. For more information, see
“Kerberos Authentication” on page 75.
Specify the Kerberos authentication parameters in the Other Properties field in the following
format:
url={jdbc:hive2://<hostname>:portnumber/databasename;
AuthMech=1;
KrbRealm=<Kerberos_Realm_Name>;
KrbHostFQDN=<Kerberos_FQDN>;
KrbServiceName=<Kerberos_Service_Name>;
KrbAuthType=1}
Driver Name Server Name User Password Database Port Number Network
Name Protocol
Limitations
Driver Database/ Limitation Description
Adapter IS Operating
System/
Platform Affected
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 261
E JDBC Driver Specific Properties
Adapter IS Operating
System/
Platform Affected
2. Notifications
3. XA_TRANSACTION connection
Apache Impala
DataSource
Other Properties
Specify the parameters in the Other Properties field:
Parameter Description
url Other database related properties are provided as part of the url values.
url={jdbc:impala://<hostname>:portnumber/databasename;
AuthMech=1;SSL=SSL_value;UseSasl=UseSasl_value}
Note:
The properties such as AuthMech, SSL, and UseSasl are required only for secured
connections.
Kerberos Authentication
Specify the Kerberos authentication parameters in the Other Properties field in the following
format:
url={jdbc:impala://<hostname>:portnumber/databasename;
AuthMech=1;
KrbRealm=<Kerberos_Realm_Name>;
KrbHostFQDN=<Kerberos_FQDN>;
KrbServiceName=<Kerberos_Service_Name>;
262 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
E JDBC Driver Specific Properties
KrbAuthType=1}
For example:
url={jdbc:impala://gbs1.windmill.local:8443/default;
AuthMech=1;
KrbRealm=gbs_Realm.windmill.local;
KrbHostFQDN=gbs_FQDN.windmill.local;
KrbServiceName=impala;
KrbAuthType=1}
Limitations
Driver Database/ Limitation Description
Adapter IS
Operating System/
Platform Affected
Cloudera JDBC Apache Impala Inserting and retrieving data works only on Current
Driver for catalog and Current schema.
Apache Impala
This driver does not support:
2. Notifications: InsertNotifications,
UpdateNotifications, DeleteNotifications,
StoredProcedureNotifications,
StoredProcedureNotificationsWithSignature, and
OrderedNotifications
3. LOCAL_TRANSACTION and
XA_TRANSACTION connections
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 263
E JDBC Driver Specific Properties
Apache SparkSQL
DataSource
Other Properties
Specify the parameters in the Other Properties field:
Parameter Description
webMethods BigData No No No No No No
Driver for Apache
SparkSQL
Limitations
Driver Database/ Limitation Description
Adapter IS Operating
System/
Platform Affected
264 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
E JDBC Driver Specific Properties
Adapter IS Operating
System/
Platform Affected
2. Notifications: InsertNotifications,
UpdateNotifications, DeleteNotifications,
StoredProcedureNotifications,
StoredProcedureNotificationsWithSignature, and
OrderedNotifications
3. XA_TRANSACTION connections
Databricks
DataSource
Other Properties
Specify the server URL and the user credentials in the Other Properties field:
Parameter Description
url URL for Simba Apache Spark JDBC Connector. For format:
url={
jdbc:spark://hostname:portnumber/databasename;
TransportMode=TransportMode_value;
SSL=SSL_value;AuthMech=AuthMech_value;
httpPath=httpPath_value};
userId=userId_value
Note:
The properties such as AuthMech, and SSL are required only for secured connections.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 265
E JDBC Driver Specific Properties
Limitations
Driver Database/ Limitation Description
Adapter IS Operating
System/
Platform Affected
Simba Apache Spark All platforms This driver does not support:
JDBC Connector
1. Services: BatchInsertSQL, BatchUpdateSQL,
StoredProcedure,
StoredProcedureWithSignature
2. Notifications
3. LOCAL_TRANSACTION and
XA_TRANSACTION connections
DB2
DataSource
XA_TRANSACTION com.ibm.as400.access.AS400JDBCXADataSource
266 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
E JDBC Driver Specific Properties
Parameter Description
TransactionIsolation If you are accessing a table with the <current catalog>.<current schema>
qualifier, set the transaction isolation level and also specify the Libraries
property.
TransactionIsolation=none;
Libraries If you are specifying the transaction isolation level, you must specify the
Libraries property as shown:
Libraries=QGPL;
Other Properties
Specify the parameters in the Other Properties field:
Parameter Description
clischema Use the clischema property to enable or disable adapter polling notifications
when the systriggers view is not in the default schema. For example:
clischema=schema_name
metadatasource Use the metadatasource property if the StoredProcedure adapter service calls a
stored procedure with a procedure name that is different from its specific name.
For example:
metadatasource=1
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 267
E JDBC Driver Specific Properties
Parameter Description
TransactionIsolation Non-repeatable read does not function when you set the transaction
isolation level to 2.
TransactionIsolation=2;
Other Properties
Specify the parameters in the Other Properties field:
Parameter Description
clischema Use the clischema property to enable an adapter polling notification if the triggers for
the notification already exist.
Specify the schema in which the view was created against the clischema property.
Thus the adapter redirects the query for triggers to the appropriate schema. For
example:
clischema=schema_name
DB2 Net Type 3 for UDB Yes Yes Yes Yes Yes No
V7.2 and V8.1
Note:
The DB2 net type 3 driver property portNumber is the same as the DB2 JDBC Applet server's
port number. The default is 6789.
268 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
E JDBC Driver Specific Properties
DataSource
XA_TRANSACTION com.ibm.db2.jcc.DB2XADataSource
Other Properties
Specify the parameters in the Other Properties field:
Parameter Description
driverType Required.
driverType=2
currentSchema Specifies the default schema name used to qualify unqualified database objects
in dynamically prepared SQL statements.
currentSchema=YourSchemaName
loginTimeout Maximum time in seconds to wait for the DataSource object to connect to a data
source.
loginTimeout=number
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 269
E JDBC Driver Specific Properties
DataSource
XA_TRANSACTION com.ibm.db2.jcc.DB2XADataSource
Other Properties
Specify the parameters in the Other Properties field:
Parameter Description
driverType Required. If the driverType is not set to 4, then Type 2 connectivity is selected
by default.
driverType=4
currentSchema Specifies the default schema name used to qualify unqualified database objects
in dynamically prepared SQL statements.
currentSchema=YourSchemaName
loginTimeout Maximum time in seconds to wait for the DataSource object to connect to a data
source.
loginTimeout=number
traceFile Specifies the name of a file into which this driver writes the trace information.
traceFile=fileName
traceFileAppend Appends, instead of overwriting, the file that is specified by the traceFile
property.
traceFileAppend=true
-1 to TRACE_ALL.
270 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
E JDBC Driver Specific Properties
Parameter Description
2 to TRACE_STATEMENT_CALLS.
DataDirect Connect
DataSource
Other Properties
Specify the parameters in the Other Properties field:
Parameter Description
For information about creating packages, see your DataDirect Connect for JDBC
documentation.
Note:
Applicable to all DataDirect Connect for JDBC 3.2 for DB2 UDB 7.2, 8.1, 9.1, and
9.5
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 271
E JDBC Driver Specific Properties
Limitations
Driver Database/ Limitation Description
Adapter IS
Operating
System/
Platform
Affected
DB2 Net Type 3 DB2 7 on If you attempt to insert 20k or more records, either the
Driver OS/390 system stops responding or you will receive a timeout
error.
272 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
E JDBC Driver Specific Properties
Adapter IS
Operating
System/
Platform
Affected
DB2 Net Type 3 DB2 7.2 on When configuring a Adapter for JDBC notification in IBM
Driver OS/390 webMethods Designer (File > New > Adapter Notification),
the Base Name you specify on the Notification Configure
tab must be no more than 5 characters because triggers on
OS/390 name cannot be more than 8 characters.
DB2 Net Type 3 DB2 on OS/390 Using a SelectSQL service, you cannot select a large volume
Driver of data (20k) using the CLOB data type.
DB2 Net Type 3 UDB 7.2 The driver does not write to the JDBC log, even when the
Driver log option is enabled. The workaround is to create an
empty log file. To do this, use Integration Server
Administrator and select Settings > Extended > Edit
Extended Settings and type:
watt.adapter.JDBC.JDBCLogFile= c:\log.txt
DB2 Net Type 3 UDB 8.1 No error message is issued when inserting a string that is
Driver larger than the size of the column defined for CHAR(N) or
VARCHAR(N).
DB2 Net Type 3 UDB 7.2 and StoredProcedure and StoredProcedureWithSignature adapter
Driver UDB 8.1 services, and StoredProcedure and
StoredProcdeureNotificationWithSignature adapter
notifications do not display functions in the Procedure Name
field. The workaround is to use the StoredProcedure service
or the StoredProcedureNotification and type the function
name in the Procedure Name field.
DB2 Net Type 3 UDB 9.1 The DB2 database system does not support the type 3 driver.
Driver
DB2 Universal UDB 8.x Does not support XA transactions for versions earlier than
Type 4 UDB 8.2. Instead, use the Universal type 2 driver if you
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 273
E JDBC Driver Specific Properties
Adapter IS
Operating
System/
Platform
Affected
DB2 Universal DB2 6 and DB2 Insert, Delete, Update, Basic, and Ordered Notifications cannot
Type 4 7 on OS/390 be enabled if the source table contains CHAR, VARCHAR,
or LONG VARCHAR columns.
DataDirect DB2 UDB 7.2 Does not support the BLOB data types. If you try to select
Connect for JDBC data from a table that has BLOB data types, you receive
3.2 the following message:
Note:
This driver supports BLOB data types using OS/390 or
DB2 iSeries V5R2.
DataDirect DB2 UDB 7.2 Cannot use the CLOB data type in the OUT parameter in
Connect for JDBC and UDB 8.1 StoredProcedure services. You receive the following
3.2 message: [DataDirect][DB2 JDBC Driver][DB2]DATA
TYPE/LENGTH/VALUE OF ARGUMENT 1 OF
CLOBSP1 IS INVALID.
274 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
E JDBC Driver Specific Properties
Adapter IS
Operating
System/
Platform
Affected
DB2 JDBC App UDB DB2 Cannot run a SelectSQL adapter service with table names that
Type 2 8.1/Oracle use special characters. Note that you can do so if you use a
Solaris Microsoft Windows NT operating system and a JDBC app
(type 2) driver.
DB2 JDBC App UDB DB2 7.2 If a Stored Procedure Notification has been enabled for long
Type 2 periods of time, the following message is posted:
DB2 JDBC App UDB DB2 8.1 No error message is issued when inserting a string that is
Type 2 larger than the size of the column defined for CHAR(N) or
VARCHAR(N).
DB2 JDBC App UDB DB2 8.1 on Integration Server crashes if the database is shut down while
Type 2 AIX5.1 executing an InsertSQL adapter service using an
XA_TRANSACTION connection.
DB2 JDBC App UDB DB2 7.2 StoredProcedure and StoredProcedureWithSignature adapter
Type 2 and UDB 8.1 services, and StoredProcedure and
StoredProcdeureNotificationWithSignature adapter
notifications do not display functions in the Procedure Name
field. The workaround is to use the StoredProcedure service
or the StoredProcedureNotification and type the function
name in the Procedure Name field.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 275
E JDBC Driver Specific Properties
Adapter IS
Operating
System/
Platform
Affected
DB2 JDBC App UDB DB2 9.1 The support for DB2 JDBC App Type 2 driver is deprecated.
Type 2
DataSource
NO_TRANSACTION, com.google.cloud.spanner.jdbc.JdbcDataSource
LOCAL_TRANSACTION
Other Properties
Specify the server URL and the user credentials in the Other Properties field:
Parameter Description
url URL for Google Cloud Spanner database. Format for user credentials:
Relative path to the credentials=<path
to service account credential json file>
For example:
url=jdbc:cloudspanner:/projects/<project id>/
instances/<instance id>/databases/<database name>;
For more information on Google Cloud Spanner connection properties, see Google
Cloud Spanner open-source JDBC driver documentation.
276 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
E JDBC Driver Specific Properties
Limitations
Driver Database/ Limitation Description
Adapter IS Operating
System/
Platform Affected
Google Cloud Google Cloud Spanner This driver does not support:
Spanner
Open-Source JDBC Services: StoredProcedure,
Driver StoredProcedureWithSignature.
Notifications: InsertNotifications,
UpdateNotifications, DeleteNotifications,
StoredProcedureNotifications,
StoredProcedureNotificationsWithSignature,
OrderedNotifications.
XA_TRANSACTION connections.
Informix
DataSource
NO_TRANSACTION, com.informix.jdbcx.IfxDataSource
LOCAL_TRANSACTION
Note:
If you use the com.informix.jdbcx.IfxDataSource DataSource class with
Integration Server, you must disable the WmTomcat package. Be
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 277
E JDBC Driver Specific Properties
XA_TRANSACTION com.informix.jdbcx.IfxXADataSource
Parameter Description
TransactionIsolation Phantom read does not function when you set the transaction isolation
level to 4. For example:
TransactionIsolation=4;
Other Properties
Specify the parameters in the Other Properties field:
Parameter Description
IfxIFXHOST Machine name of the database server. Applicable for all transaction types.
IfxIFXHOST=hostname
278 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
E JDBC Driver Specific Properties
Limitations
Driver Database/ Limitation Description
Adapter IS Operating
System/
Platform Affected
Informix Driver Informix 7.31 and 9.x This driver does not support multiple results sets. If
for JDBC Version you configure the adapter to use multiple result sets,
2.21 type 4 all the rows in the result will be stored in the first
Result Set you specified when you configured the
adapter.
MariaDB
DataSource
MariaDB Connector/J No No No No No No
Type 4 JDBC Driver
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 279
E JDBC Driver Specific Properties
MongoDB
DataSource
Other Properties
Specify the parameters in the Other Properties field:
Parameter Description
REFRESH SCHEMA Use REFRESH SCHEMA in SQL statement to add newly discovered objects to your
relational view of native data type.
webMethods BigData No No No No No No
Driver for MongoDB
Limitations
Driver Database/ Limitation Description
Platform Affected
webMethods BigData MongoDB for all supported This driver does not support:
Driver for MongoDB databases
1. Services: StoredProcedure
280 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
E JDBC Driver Specific Properties
Platform Affected
2. Notifications
3. XA_TRANSACTION connections
Note:
MongoDB database supports WiredTiger
storage engine.
Microsoft SQL
DataSource
NO_TRANSACTION, com.microsoft.sqlserver.jdbc.SQLServerDataSource
LOCAL_TRANSACTION
XA_TRANSACTION com.microsoft.sqlserver.jdbc.SQLServerXADataSource
SSL Settings
Specify the SSL parameters in the Other Properties field in the following format:
encrypt=value;
trustStore=Truststore path;
trustStorePassword=Truststore password
encrypt value is true or false depending on the encryption settings in the Microsoft SQL
server.
Note:
If you have configured SSL connections between Adapter for JDBC and Microsoft SQL Server,
enter the TCPS port number of the Microsoft SQL Server.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 281
E JDBC Driver Specific Properties
Kerberos Authentication
Specify the Kerberos authentication parameters in the Other Properties field in the following
format:
integratedSecurity=true;
authenticationScheme=NativeAuthentication
NativeAuthentication is specific to the Windows platform and uses the following files:
For Windows 32 or Windows 64, copy the appropriate library (sqljdbc_auth.dll or mssql-
jdbc_auth-x.x.x.xxx.dll) to Integration Server_directory\instances\instance_name\lib directory.
Authentication
The user name and password you configure for a connection must be the same as those used to
create the tables you use with a specific notification. Otherwise, an exception is generated at
runtime.
Other Properties
Specify the parameters in the Other Properties field:
Parameter Description
282 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
E JDBC Driver Specific Properties
DataDirect Connect
DataSource
NO_TRANSACTION , com.wm.dd.jdbcx.sqlserver.SQLServerDataSource
LOCAL_TRANSACTION and
XA_TRANSACTION
JDBC Jars
Based on your Microsoft SQL Server architecture, use the required DLL and stored procedure
folder found in dd-cjdbc.jar file. For details, see DataDirect Connect documentation.
Limitations
Driver Database/ Limitation Description
Adapter IS
Operating System/
Platform Affected
Microsoft JDBC Microsoft SQL When running the SelectSQL adapter service using
Driver Version Server 2000 the "not null real" type, the following error appears:
2.2.0019 for Microsoft
SQL Server 2000 Value cannot be converted to requested type.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 283
E JDBC Driver Specific Properties
Adapter IS
Operating System/
Platform Affected
Microsoft JDBC Microsoft SQL This driver returns incorrect data type TEXT,
Driver Version Server 2005 IMAGE, and NTEXT for MS SQL data types
1.0.809.102 for VARCHAR(max), VARBINARY(max) and
Microsoft SQL Server NVARCHAR(max) respectively.
2005
This driver returns invalid JDBC data type for MS
SQL UNIQUEIDENTIFIER data type.
DataDirect Connect Microsoft SQL When running the SelectSQL adapter service using
Server 2000 the "not null real" type, the following error appears:
MySQL
DataSource
NO_TRANSACTION, com.mysql.jdbc.jdbc2.optional.MysqlDataSource
LOCAL_TRANSACTION
For driver version 8.0.15 and later, use the following:
com.mysql.cj.jdbc.MysqlDataSource
XA_TRANSACTION com.mysql.jdbc.jdbc2.optional.MysqlXADataSource
284 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
E JDBC Driver Specific Properties
Driver Name Server Name User Password Database Port Number Network
Name Protocol
Oracle
Set the following environment variable before you configure the connection.
Solaris* LD_LIBRARY_PATH=/ORACLE_HOME/lib
HP* SHLIB_PATH=/ORACLE_HOME/lib
AIX* LIBPATH=/ORACLE_HOME/lib
Linux LD_LIBRARY_PATH=/ORACLE_HOME/lib
Check that the OCI client is configured correctly before you proceed.
Note:
*If you are using Oracle 920 JDBC driver files with an Oracle 920 client to connect to different
Oracle database versions, set the environment variable for your platform to /ORACLE_HOME/lib32.
DataSource
XA_TRANSACTION oracle.jdbc.xa.client.OracleXADataSource
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 285
E JDBC Driver Specific Properties
Parameter Description
Driver Name Server Name User Password Database Port Number Network
Name Protocol
DataSource
XA_TRANSACTION oracle.jdbc.xa.client.OracleXADataSource
Parameter Description
286 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
E JDBC Driver Specific Properties
Kerberos Authentication
Specify the Kerberos authentication parameters in the Other Properties field in the following
format:
connectionProperties={
oracle.net.authentication_services=(KERBEROS5),
oracle.net.kerberos5_mutual_authentication=true,
oracle.net.kerberos5_cc_name=<kerberoscache_file_path>}
where <kerberoscache_file_path> is the path to the file that has the stored ticket.
Synonym Support
Specify the following property to enable synonym support in the Other Properties field:
connectionproperties={includeSynonyms=true}
SSL Setting
If you have configured SSL connections between Adapter for JDBC and Oracle server, enter
the TCPS port number of the Oracle server.
If you have configured SSL connections between Adapter for JDBC and Oracle server, enter
tcp or tcps in the Network Protocol field.
If you have configured SSL connections between Adapter for JDBC and Oracle server, set the
truststore alias name in the watt.server.ssl.trustStoreAlias property.
For information on creating truststore aliases, refer to the IBM webMethods Integration Server
Administrator’s Guide.
Driver Name Server Name User Password Database Port Number Network
Name Protocol
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 287
E JDBC Driver Specific Properties
DataDirect Connect
DataSource
Driver Name Server Name User Password Database Port Number Network
Name Protocol
DataDirect Connect No No No No No No
DataSource
XA_TRANSACTION oracle.jdbc.xa.client.OracleXADataSource
Parameter Description
Other Properties
Specify the following properties in the Other Properties field:
288 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
E JDBC Driver Specific Properties
Parameter Description
retry_count Number of times to retry after the initial attempt fails. For example:
(retry_count=20)
ssl_server_dn_match Flag to indicate if the SSL Server DN is a match. Possible values are:
yes
no. Default.
For example:
(ssl_server_dn_match=yes)
For example:
url=jdbc:oracle:thin:@(description=(retry_count=20)(retry_delay=3)
(address=(protocol=tcps)(port=1522)(host=adb.aaa-xxx.oraclecloud.com))
(connect_data=(service_name=sss.adb.oraclecloud.com))
(security=(ssl_server_dn_match=yes)))?TNS_ADMIN="C:\\XXX\\Wallet_XXXX"
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 289
E JDBC Driver Specific Properties
Limitations
Driver Database/ Limitation Description
Adapter IS
Operating
System/
Platform
Affected
Oracle JDBC OCI All supported The NUMBER and NUMBER(n,m) Oracle data
Driver Oracle types map to java.math.BigDecimal in all the
databases adapter services by default.
Oracle JDBC Thin
Driver BLOB and CLOB data types cannot be used in a
table definition when configuring the adapter
notifications.
Oracle JDBC OCI Oracle 8.0.5 When mapping a date data type to java.util.Date
Driver using the InsertSQL adapter service, you receive
the following error:
Oracle JDBC OCI HP-UX 11i Be sure to apply the HP-UX 11i Quality Pack (June
Driver 2002) and the PHSS_26138 on HP-UX 11i before
configuring the adapter connection using an OCI
Oracle JDBC Thin driver; otherwise, you receive the following error:
Driver
Unresolved symbol :gethrtime (code).
Oracle JDBC OCI HP-UX If all the adapter notifications are enabled for more
Driver than 18 hours, you receive the following error:
290 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
E JDBC Driver Specific Properties
Adapter IS
Operating
System/
Platform
Affected
Oracle JDBC Thin Oracle 10g With Oracle Database 10g, you cannot configure
Driver 9.0.1 (Mac OS adapter services or notifications with
) BINARY_DOUBLE or BINARY_FLOAT databases
using the Adapter Service Editor. In these cases, if you
Oracle JDBC OCI try to insert a row, the corresponding JDBC data type
Driver does not appear in the Adapter Service Editor. As an
Oracle JDBC Thin alternative, use the CustomSQL adapter service when
Driver (all other OSs) configuring services involving these data types.
DataDirect driver
shipped with Host
Integration Server
PostgreSQL
DataSource
XA_TRANSACTION com.edb.xa.PGXADataSource
Driver JAR
For information about the specific version of the client driver JARs to use, see IBM webMethods
Adapters System Requirements.
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 291
E JDBC Driver Specific Properties
DataSource
XA_TRANSACTION org.postgresql.xa.PGXADataSource
Driver JAR
For information about the specific version of the client driver JARs to use, see IBM webMethods
Adapters System Requirements.
Other Properties
Specify the parameters in the Other Properties field:
Parameter Description
postgresql.casesensitive Enclose the table names, column names, and procedure names in
quotes if the values are in upper case or camel case. Possible values
are:
false. The table names, column names, and procedure names are
not enclosed in quotes if the values are in upper case or camel
case.
For example:
postgresql.casesensitive=true
292 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
E JDBC Driver Specific Properties
Driver Name Server Name User Password Database Port Number Network
Name Protocol
PostgreSQL JDBC No No No No No No
Driver
Limitations
Driver Database/ Limitation Description
Adapter IS Operating
System/
Platform Affected
Advanced Server Postgres Plus Advanced This driver does not support Query timeout.
JDBC Connector Server 9.0/
Driver
Any supported operating
system
2. Notifications: InsertNotifications,
UpdateNotifications, DeleteNotifications,
StoredProcedureNotifications,
StoredProcedureNotificationsWithSignature,
and OrderedNotifications
SAP HANA
DataSource
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 293
E JDBC Driver Specific Properties
XA_TRANSACTION com.sap.db.jdbcext.XADataSourceSAP
Driver Name Server Name User Password Database Port Number Network
Name Protocol
Limitations
Driver Database/ Limitation Description
Adapter IS
Operating System/
Platform Affected
StoredProcedure, StoredProcedureWithSignature,
StoredProcedureNotification and
StoredProcedureNotificationWithSignature do not support
ResultSet.
294 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
E JDBC Driver Specific Properties
Snowflake
DataSource
NO_TRANSACTION, net.snowflake.client.jdbc.SnowflakeBasicDataSource
LOCAL_TRANSACTION
Other Properties
Specify the parameters in the Other Properties field:
Parameter Description
Driver Name Server Name User Password Database Port Number Network
Name Protocol
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 295
E JDBC Driver Specific Properties
Limitations
Driver Database/ Limitation Description
Adapter IS
Operating System/
Platform Affected
JDBC Driver for Snowflake 3.55.4, This driver does not support:
Snowflake Snowflake 9.1.0
(snowflake-jdbc-3.9.1) , 1. Services: StoredProcedure,
JDBC Driver for StoredProcedureWithSignature
Snowflake 2. Notifications: InsertNotifications,
(snowflake-jdbc-3.20.0) UpdateNotifications, DeleteNotifications,
StoredProcedureNotifications,
StoredProcedureNotificationsWithSignature,
OrderedNotifications
3. XA_TRANSACTION connections
4. Batch services
Note:
Run the following query on the Snowflake
backend to change the format if the SELECT
operation fails.
ALTER SESSION SET
JDBC_QUERY_RESULT_FORMAT=JSONALTER USER
<DATABASE_USER> SET
JDBC_QUERY_RESULT_FORMAT=JSON
Sybase
DataSource
XA_TRANSACTION com.sybase.jdbc2.jdbc.SybXADataSource
296 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
E JDBC Driver Specific Properties
DataSource
XA_TRANSACTION com.sybase.jdbc3.jdbc.SybXADataSource
DataSource
XA_TRANSACTION com.sybase.jdbc4.jdbc.SybXADataSource
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 297
E JDBC Driver Specific Properties
Limitations
Driver Database/ Limitation Description
Adapter IS Operating
System/
Platform Affected
jCONNECT 5.5 and Sybase 11.x, 12.x, and A Sybase column using a BIT data type does not allow
6.05 Type 4 15.x NULL values due to driver behavior. This means that
if you insert a NULL or ? (variable) value when you run
an InsertSQL service, the driver converts this column
value to false and inserts the NULL value for the
column into the database.
jConnect for 7.0 Sybase 15.7 This driver does not support XA_TRANSACTION
Type 4 connections.
jConnect for 7.0 Sybase 16.x This driver does not support:
Type 4
1. Services: StoredProcedure,
StoredProcedureWithSignature.
2. Notifications: InsertNotifications,
UpdateNotifications, DeleteNotifications,
StoredProcedureNotifications,
StoredProcedureNotificationsWithSignature, and
OrderedNotifications
All driver types All Sybase versions The TEXT, IMAGE, and UNITEXT data types are not
supported for all types of adapter notifications in
Sybase.
298 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
E JDBC Driver Specific Properties
Teradata
DataSource
Parameter Description
TransactionIsolation Dirty read does not function if you set the transaction isolation level
to 1.
For example:
TransactionIsolation=Transaction_Isolation_Level;
Other Properties
Specify the driver-dependent parameters based on the JDBC driver and the transaction type that
the connection is using in the Other Properties field:
Parameter Description
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 299
E JDBC Driver Specific Properties
Limitations
Driver Database/ Limitation Description
Adapter IS
Operating System/
Platform Affected
Teradata V2R5 All supported If you use the @ character in a table or column name,
(Type 4) databases you will receive the following syntax error:
2. Notifications: InsertNotifications,
UpdateNotifications, DeleteNotifications, and
OrderedNotifications
3. XA_TRANSACTION connections
3. XA_TRANSACTION connections
300 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3
E JDBC Driver Specific Properties
Tibero
DataSource
NO_TRANSACTION, com.tmax.tibero.jdbc.ext.TbConnectionPoolDataSource
LOCAL_TRANSACTION
XA_TRANSACTION com.tmax.tibero.jdbc.ext.TbXADataSource
Driver Name Server Name User Password Database Port Number Network
Name Protocol
Limitations
Driver Database/ Limitation Description
Adapter IS Operating
System/
Platform Affected
JDBC Driver for Tibero 5.1 This driver does not support the following:
Tibero 5 SP1
1. Services: StoredProcedure,
StoredProcedureWithSignature
2. Notifications: InsertNotifications,
UpdateNotifications, DeleteNotifications,
StoredProcedureNotifications,
StoredProcedureNotificationsWithSignature,
OrderedNotifications
IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3 301
E JDBC Driver Specific Properties
302 IBM webMethods Adapter for JDBC Installation and User’s Guide 10.3