Entering content frameProcedure documentation Configuring the Outbound JDBC Adapter Locate the document in its SAP Library structure

Use

You need to configure the outbound JDBC adapter so that you can convert XML messages from the Integration Engine into the contents of database tables.

To configure the adapter you must specify the following:

This driver is not supplied with the adapter but must be supplied by the database provider or third-parties.

Prerequisites

You have:

  1. Installed a JDBC driver (Version 2.0) for the database.
  2. Installed the corresponding adapter.
  3. Selected the adapter on the configuration screen.
  4. Chosen Configure to call the configuration of the adapter module.

Procedure

The configuration of the outbound JDBC adapter comprises five functional subareas:

  1. Java class name for the outbound JDBC adapter

    2. Specify the class name as follows:

    classname=com.sap.aii.messaging.adapter.ModuleXMB2DB

    This specification is mandatory.

  2. JDBC adapter mode

    3. Specify the mode of the outbound JDBC adapter. The following is the only permitted value:

    mode=XMB2DB

    Subsequent versions may permit additional values.

  3. Specifications for addressing by the Integration Engine

<port_no> specifies the HTTP server port that receives the messages from the Integration Engine.

<service> describes the service part of the URL where the Integration Engine must send its messages.

These specifications are mandatory.

Note

For example, if you have specified XMB.httpPort=1234 and XMB.httpService=/db/Receiver, a URL must be specified as the end point address of the JDBC adapter in the Integration Engine, as follows:

http://<Datenbankadapterhost>:1234/db/Receiver

This graphic is explained in the accompanying text

The endpoint address must be extended as follows for the Integration Engine in Release 1.0:

http://<databaseadapterhost>:1234/db/Receiver?action=execute&pipelineid=Receiver

If the Integration Engine message is sent to a non-specified adapter service, the system displays the following error message:

No registered listener for <Service> found

The system displays the same message if the adapter is initialized, but has not been started (status STOPPED or INITIALIZED).
  1. Specifications for database access

These specifications are mandatory and have no default values.

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 material from the respective provider for exact details.

Specify the URL with which you can establish a database connection using the JDBC driver. The exact URL format can vary; see material from the respective provider for more details.

Specify the database table where the incoming data is to be written to. In the current version of the JDBC adapter it is not possible to distribute the contents of an incoming document to different database tables.

An operating system command specified here is executed following successful database operations. The default value is an empty character string (no command).
  1. Additional specifications to handle messages with Quality of Service = Exactly Once (In Order)

As in the other adapters, Exactly Once messages are handled by default using status information in the file system. All adapter error statutes and program terminations initialized externally (shutdown of the adapter operating system process) are also handled in this mode.

However, this does not include external program terminations during a database commit. In this case, the status of message processing is unclear since it can only be changed in the management file once the database commit has been completed.

However, this kind of situation is identified when the application is started and editing of the message terminated during processing can be controlled using db.exactlyOnceErrorInPendingState.

This specification is only effective for handling errors that occur when a message is being processed for a second time after initial processing remained in the unclear status described above.

If an error now occurs during this second processing attempt, this is returned by default to the sender system as an error (or if the value ERROR is set explicitly).

However, if the error occurs because the message was saved in the database when it was first processed and it is still located there, processing can be completed for the sender system using the value IGNORE (note that the database interface normally triggers the error duplicate insert if at least one of the table fields was defined as a primary key). Otherwise the sender system will continue to send the message and the error will continue to occur.

Nevertheless, it is possible that a message can become duplicated during Exactly Once handling. For example, if there is no primary key field in the database table or if the data is already being processed by another application and it is then deleted, when the first attempt at message processing is interrupted by an external termination of the adapter process immediately after the database commit, a message can be duplicated. This problem can only be solved if message processing and status information management take place in the same database so that the processing steps have the same commit cycle.

In the database where the write-to tables are located you must create an additional table with two columns for this purpose. Column 1 must be type character with length 36 (or more) and have the name XIMessage_ID. Column 2 must be of type integer and have the name XIMessage_Ts. This table is made known to the adapter as follows:

Set this value to use the specified database table instead of file-based Exactly-Once processing. If the table does not exist or the columns cannot be found or are of the wrong type, then a corresponding error is triggered and the adapter will not be started.

If you use a different column name to XIMessage_Id (for example, because you want to use a table that already exists), you can specify this value for the type char(36) column. If a greater field length is specified the table can nevertheless be used. However, the minimum field length is 36. This value is only evaluated if you set db.tableForExactlyOnceHandling.

If you use a different column name to XIMessage_Is (for example, because you want to use a table that already exists), you can specify this value for the type integer) column. This value is only evaluated if you set db.tableForExactlyOnceHandling.

Specify the number of days that the management information for received messages with the service attribute Exactly Once (In Order) should be kept. This information is required to avoid messages being duplicated, if when handling an error the Integration Engine sends the same message to an adapter more than once. The default value is 60 days. This value applies to both file-based and database-based status management.

This graphic is explained in the accompanying text

If the value is set to 0 or to a negative value, all management information is deleted each time the adapter is initialized. This can be useful for test purposes but must not be used for production operation.
  1. Required XML document format

The incoming message must represent a table in XML format; its contents are written to the database table specified in db.table. The same document format is required as is generated by the inbound file and JDBC adapters. This means that 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 is an example for 3 columns and 2 lines. The number of lines and columns is, of course, unlimited.

The column names of the database tables are taken from the element names in the XML document (for example, column-name1, column-name2, column-name3), and the corresponding values are inserted for each line.

The document does not have to contain all columns of a database table as long as the database definition accepts a null value in place of the missing columns. Element names of the XML document that do not exist as table column names are ignored.

 

 

 Leaving content frame