Configuring the Sender JDBC Adapter

Use

You need to configure the sender JDBC adapter to send database contents to the Integration Engine.

To configure the adapter you must specify the following:

A JDBC database driver to access the database
This driver is not supplied with the adapter but must be supplied by the database provider or third-parties.
Logon data for the database to be read from
An SQL statement to determine the table contents you want to read
An SQL statement to process successfully sent table contents
A dispatcher class (optional) with the corresponding settings and the user exits and their settings that are to be called by the dispatcher
Sender and receiver data required by the Integration Engine for routing and mapping

Prerequisites

You have:

Installed a JDBC driver (Version 2.0) for the database.
Installed the corresponding adapter.
Selected the adapter on the configuration screen.
Called the adapter configuration by choosing Configure.

Procedure

The configuration of the sender JDBC adapter comprises four functional subareas:

Java class name for the sender JDBC adapter
Specify the class name as follows:
classname=
```
com.sap.aii.messaging.adapter.ModuleDB2XMB
```
This specification is mandatory.
The version specification for the configuration
version=
```
30
```
This specification is mandatory. If no specification is entered, the configuration is interpreted as an XI 2.0 adapter configuration. Other values are not permitted and trigger an error.
JDBC adapter mode
Specify the mode of the sender JDBC adapter. The following is the only permitted value:
mode=
```
DB2XMB
```
Subsequent versions may permit additional values.
The dispatcher class and the user exits to be called by the dispatcher (optional)
The sender JDBC adapter provides you with a dispatcher that you can use to convert messages before they are sent. The settings required for the dispatcher are explained in the example .
Specifications for the Integration Engine
Enter the complete address (URL) of the Integration Engine that you want to send the message to:
XI.TargetURL=
```
http://IntegrationEngineHost:port/pipeline-arguments
```
This specification is mandatory.
Note

The Integration Engine address can also be accessed dynamically from the SAP System Landscape Directory (SLD). The following entry is added to the configuration for this purpose:
```
XI.SLDConfiguration=SLDaccessor
```
In this case the URL of the corresponding Integration Server for the system specified with XI.SenderService is read from the SLD and used instead of the value specified under XI.TargetURL. Therefore, specify the following:
```
XI.TargetURL=<fromSLD>
```
To be able to access the SLD, the SLDaccessor service must be configured correspondingly and the respective entries must be maintained in the SLD.
Note

If the Integration Server is accessed by means of an HTTP proxy server rather than directly, the following parameters must be set:

XI.proxyHost=<proxyHostname>

XI.proxyPort=<proxyPortnumber>
<proxyHostname> is the host name of the proxy and <proxyPortnumber> is the port where the proxy receives HTTP requests (for example,
```
8080
```
).
If an authentication was specified for the specified URL (HTTP service) in the Integration Engine, the following specifications are mandatory:
- XI.User=<user-name>
- XI.Password=<password>
  
  Note
  
  The specifications must match those that you made in transaction SICF in the Integration Engine. If you do not specify a user and password combination, or the combination is invalid, the system will terminate each attempt to access the Integration Engine with the message Transport Exception: http-Error 401 - Unauthorized.
  
  The user must have the authorizations of group SAP_XI_APPL_SERV_USER on the Integration Server.
For more information on configuring SSL authentication with a certificate, see: Certificate Administration , then Setting Up the Adapter Engine as SSL Client.

If you want to use a different client or language to the default setting in the Integration Engine when logging on, you can also set the following parameters:
- XI.Client=<client-no>
- XI.Language=<language-id>
The following address arguments for the sender system (the JDBC adapter) are mandatory: They are used to identify the adapter configuration in routing and in mapping in the Integration Engine pipeline. You can also find an explanation about each argument there.
- ```
XI.SenderParty=<sender party name>
```
- XI.SenderService=<sender service
```
name>
```
- XI.InterfaceNamespace=<
```
namespace URI>
```
- XI.Interface=<
```
name>
```
- ```
XI.ReceiverParty=<receiver party name>
```
- XI.ReceiverService=<receiver service
```
name>
```
  Note
  
  You must set at least XI.SenderService, XI.Interface, and XI.InterfaceNamespace. Specification of the receiver is only mandatory if no receiver is determined during routing.
- XI.QualityOfService=<
```
QualityOfService>
```
  Specifies how the Integration Engine should process a message. The following values are permitted:
  - XI.qualityOfService=
```
BE
```
    (Best Effort, means synchronous processing)
  - XI.qualityOfService=
```
EO
```
    (Exactly Once, means asynchronous processing with guaranteed execution exactly once)
  - XI.qualityOfService=
```
EOIO
```
    (Exactly Once in Order, means asynchronous processing using queues, in other words guaranteed execution exactly once and maintaining the sequence of successive messages)
  You must also define a queue name for
```
EOIO
```
  :
- XI.QueueId=<
```
QueueName>
```
  This queue name is used in the Integration Engine to process messages in the same sequence that they arrived in.
Specifications for database access
- db.jdbcDriver=<java_class_of_jdbcdriver
```
>
```
  Specify the Java class of the JDBC driver that the JDBC adapter must load to be able to access the driver. The exact specification varies according to the JDBC driver; see documentation from the respective provider for exact details. This specification is mandatory.
- db.connectionURL=<jdbc_driver_connection_url
```
>
```
  Specify the address with which you can establish a database connection using the JDBC driver. The exact format of the address can vary; see documentation from the respective provider for more details. This specification is mandatory.
- db.user=<username>
- db.password=<password>
  Instead of using the database logon in the string specified by the parameter db.connectionURL, specify the database logon explicitly with user and password. This means that instead of the JDBC call getConnection(url), the call (url,user,password)is executed in the JDBC adapter, and this call is expected or handled differently by some database systems.
- db.reconnect=YES|NO
  When a database connection error occurs, this parameter enables you to specify whether you want reconnect to the database via the JDBC driver each time the database is accessed. The default setting is
```
YESNO
```
  . If you specify , when an error occurs the JDBC adapter terminates the connection to the database and it must then be restarted from the administration screen.
- db.processDBSQLStatement=<SQL-Select-Statement>
  Either specify a valid SQL SELECT statement to select the data to be sent from the specified database, or specify an SQL EXECUTE statement to execute a stored procedure that contains exactly one SELECT statement. The expression only needs to correspond to the SQL variant supported by the respective JDBC driver; so it can also contain table JOINs, for example. This specification is mandatory.
- db.confirmDBSQLStatement=<SQL-Update-Statement>
  Specify a valid SQL statement that can be applied to the database once the data (determined with db.processDBSQLStatement) has been successfully sent to the Integration Engine. This must be an INSERT, UPDATE, or DELETE statement. Examples of typical scenarios would be deleting the sent data from the database with a DELETE statement or selecting the data with an UPDATE statement. Instead of the SQL statement, you could also specify <
```
TEST
```
  > (including the pointed parentheses). In this case, once the data has been successfully sent, the system does not execute a database operation and the data remains unaltered in the database.
  The default value is
```
<TEST>
```
  . This may be useful (besides for test purposes) when, for example, the data has not only been read by a stored procedure defined in the statement db.processDBSQLStatement, but has already been changed.
  Caution
  This means that data is sent again as a new message if the adapter is restarted or if the time period specified in
```
db.pollInterval
```
  is exceeded. This mode is exclusively of use when testing the configuration of the adapter or the Integration Engine, and is not for production operation.
  Note
  
  In Exactly Once mode, the statements specified under db.processDBSQLStatement and db.confirmDBSQLStatement, as well as the formatting of the message are all performed within one database transaction. The message is then sent afterwards. Until the message has been sent successfully to the Integration Server, it is temporarily persisted as a file in the Adapter Engine directory /Data.
- db.execute=<operating system command>
  If you specify an operation system command here, the system executes it following successful database operations (PROCESS and CONFIRM statements). The default value is an empty character string (no command).
- db.pollInterval=
  Specify the number of seconds that the adapter must wait before it calls the db.processDBSQLStatement again.
  
  This specification is mandatory. You can also specify the following parameters so as to specify an additional waiting time in milliseconds:
  
  db.pollIntervalMsecs=
  
  If db.pollIntervalis set to 0, then very short, almost real time processing times can be achieved.
  
  The default value for this parameter is 0.
  
  If the call is not to be repeated then you must set both parameters to 0 (or just the parameter db.pollInterval if you have not specified a value for parameter db.pollIntervalMsecs).
  You can set the value to
```
0
```
  , if you do not want to repeat the call. In this case the adapter status remains as STOPPED. To initiate a new call, choose Stop/Start or Restart to restart the adapter.
- db.retryInterval=
  Specify the number of seconds that the adapter is to wait before a SQL statement processed with errors is processed again.
  
  The value from db.pollIntervalis taken as the default value. If this value is 0 (processing is not repeated), then SQL statements processed with errors are not processed again.
  
  If db.retryIntervalis also 0, then the adapter is terminated if an error occurs, even when a value greater than 0 was specified for db.pollInterval. In this case the adapter status remains as STARTED. To process the file again, choose Stop/Start or Restart to restart the adapter.
- db.logPollInterval=NO|YES
  All entries to loops that last longer than 5 seconds are shown in the adapter log by default. As a result, this can lead to a lot of entries in the log. In such instances, the log output (but not the loop itself) can be deactivated by using db.logPollInterval=NO.
  
  For loops that last 5 seconds or less, the output can be activated with db.logPollInterval=YES.
- db.disconnect=NO|YES
  The database connection is released and then reestablished before each poll interval.
  
  The default value is NO.
- db.autoCommit=NO|YES
  Use this parameter to deactivate the logical unit of work required by the JDBC adapter to guarantee that the data in the database is consistent. This option is required for JDBC drivers that do not support transactions. To avoid data inconsistencies in the database when the logical unit of work is deactivated, ensure that multiple database transactions cannot access the database simultaneously.
  
  The default value is NO.
  
  Caution
  
  Do not set this parameter to YES if the JDBC driver supports transactions, that is, if the system does not display a corresponding error message during normal operation.
- db.transactionIsolation=0|1|2|4|8
  There are different levels of database transactions known as isolation levels. The JDBC adapter uses the highest isolation level by default to avoid database inconsistencies arising from parallel database transactions. Some JDBC drivers or database products do not support this isolation level and it may therefore be necessary to lower it accordingly. Note, however, that lowering the isolation level can have an adverse effect on transaction security. Therefore, only do this when necessary. The values listed above correspond to the following JDBC constants:
  - 0 - TRANSACTION_NONE
  - 1 - TRANSACTION_READ_UNCOMMITED
  - 2 - TRANSACTION_READ_COMMITED
  - 4 - TRANSACTION_REPEATABLE_READ
  - 8 - TRANSACTION_SERIALIZABLE
  If the parameter is not set, then the default value of the connected database takes effect.
  
  Caution
  
  You must only lower the isolation level where necessary and as far as necessary. To avoid data inconsistencies in the database when the isolation level is lowered, ensure that multiple database transactions cannot access the database simultaneously.
- db.documentName=<name>
  If you specify a document name, it is inserted in the message as the main XML tag. The default setting is
```
resultset
```
  (see below).
- db.documentNamespace=<namespace>
  If specified, the namespace is added to the name of the document.
How the adapter responds when it is stopped.
db.stopMode=0|1
- 0 Processing is terminated immediately if the adapter is stopped.
- 1 The message that is currently being processing is processed fully before the adapter is stopped.
The default value is 0.

Result

The system converts the table resulting from the db.processDBSQLStatement into a valid XML document and sends it to the Integration Engine. The document looks as follows:

<resultset>

<row>

<column-name1>column-value</column-name1>

<column-name2>column-value</column-name2>

<column-name3>column-value</column-name3>

</row>

<row>

<column-name1>column-value</column-name1>

<column-name2>column-value</column-name2>

<column-name3>column-value</column-name3>

</row>

</resultset>

This document can then be processed further by the Integration Engine.