Referencing databases in a

message flow

© Copyright IBM Corporation 2013

Course materials may not be reproduced in whole or in part without the prior written permission of IBM. 3.3.1 8.0
Unit objectives
After completing this unit, you should be able to:
• Use database message processing nodes to modify messages and
control message processing
• Configure database nodes to access user databases
• Describe the differences between ESQL and SQL SELECT
• Define a database service

© Copyright IBM Corporation 2013

Using databases in message flows
• Connection to application databases on DB2, MS SQLServer, Oracle,
Sybase, Informix, or SolidDB
• IBM Integration Bus ODBC automatically manages transactions
– ESQL, maps, and JavaCompute (MbSQLStatement)
– Integration node managed JDBC type 4: JavaCompute, DatabaseRoute, and
DatabaseRetrieve nodes
• Transactions must be handled manually in code
– Standard JDBC API type 2 and 4: JavaCompute
– SQLJ: JavaCompute node
• Use mapping or compute nodes to SELECT, INSERT, UPDATE, or
DELETE
• Database definitions can be imported or discovered
– Created by the Relational Database Definition wizard in IBM Integration Toolkit
– Used for maps and ESQL content assist

© Copyright IBM Corporation 2013

Configure database access for the integration node
• On Windows, configure an existing database as a System ODBC data
source
• ODBC on UNIX: Customize files odbc.ini and odbc64.ini
• Integration node managed JDBC Type 4
– Create a JDBCProvider configurable service for each (existing) database that is
connected to Java applications

mqsicreateconfigurableservice IB9NODE -c JDBCProviders -o DSN1

-n databaseName -v SAMPLE
mqsichangeproperties IB9NODE -c JDBCProviders -o DSN1 -n databaseType
-v DB2
mqsichangeproperties IB9NODE -c JDBCProviders -o DSN1 -n serverName
-v localhost
....
mqsireportproperties IB9NODE -c JDBCProviders -o DSN1 -r
mqsistop IB9NODE
mqsistart IB9NODE Configuring local Windows
DB2 database SAMPLE as
JDBCProvider DSN1
© Copyright IBM Corporation 2013
Compute node

InputRoot
OutputRoot
InputBody

Database Database

• Retrieve the data from an application database and include it in an output

message
• Set DSN in node properties and write or generate ESQL
Example: SET OutputRoot.XML.Message.Price =
THE (SELECT ITEM A.PRICE
FROM Database.PRICEDATA AS A
WHERE A.PRODUCT = 'Widget');

• A Compute node can also UPDATE, INSERT, or DELETE a database

© Copyright IBM Corporation 2013

Database node

Root
OutputRoot
Body

Database Database

• Allows a transaction in the form of an ESQL expression

• An input message is sent unchanged to the output terminal
• UPDATE, INSERT, DELETE, and SELECT
• SELECT cannot directly update a message

Example:
INSERT INTO Database.DSN2.Schema2.PRICEDATA
(PRODUCT_NAME, ITEM_PRICE, STATUS)
VALUES (Body.Message.ProductID,
Body.Message.UnitPrice,'OPEN');

© Copyright IBM Corporation 2013

Node properties for database access
• Set the data source to use as a default DSN (ODBC)
• When Transaction = Automatic, database updates are either committed or
rolled back with the entire message flow
• When Transaction = Commit:
– Updates to the default DSN immediately, even if the message flow fails later
– All noncommitted updates are made in this message flow to the default DSN
• To handle SQL errors in ESQL code by using SQLNATIVEERROR
functions, clear the Throw exception on database error check box

© Copyright IBM Corporation 2013

Transaction support
• By default, a message flow is a logical unit of work
– Commit or rollback resources
– Transaction property of input node; the default is YES
• Some processing nodes can be explicitly excluded from a logical unit of
work
– It is a partially coordinated transaction, if TransactionMode of node = Commit
• If multiple resource managers in a flow (WebSphere MQ and DBMS),
choose the transaction coordinator for a deployed message flow in
BAR

© Copyright IBM Corporation 2013

Transaction coordinator options
• Uncoordinated transaction (default)
– The application (integration node) handles the transaction
– A database commit, then MQCMIT
– It is a problem if MQCMIT fails after a successful database commit
• XA-coordinated transaction
– The integration node queue manager acts as an XA transaction manager
– A two-phase commit includes database and WebSphere MQ resources
(MQBEGIN)
– A special setup is necessary

• To enable XA:
1. Set up XA for the integration node queue manager
2. In the BAR file, display the properties of the .cmf and select Coordinated
transaction
3. Change the transaction to Automatic on the database nodes
4. Enable XA in the application database, if necessary
© Copyright IBM Corporation 2013
ESQL SELECT compared with SQL SELECT
• ESQL limitations on SQL SELECT
• SELECT DISTINCT
– SELECT ALL
– GROUP BY or HAVING
– AVG is a column function

• Use PASSTHRU to bypass the IBM Integration Bus parser

– For special SELECTs
– For special database syntax
– Call stored procedures
– Run a coded statement

• ESQL additions to SQL SELECT

– Produces a tree-structured result
– Accepts arrays in SELECT clauses
– THE(SELECT)
– SELECT ITEM
© Copyright IBM Corporation 2013
PASSTHRU example
• PASSTHRU function issues complex SELECTS
Example:
SET OutputRoot.XMLNSC.Msg.Results[]= PASSTHRU(
'SELECT WORKDEPT, MAX(SALARY) AS MaxSalary
FROM schema1.EMPLOYEE
GROUP BY WORKDEPT
HAVING MAX(SALARY) > ?'
TO Database.SAMPLE
VALUES(InputBody.Msg.Salary));

• PASSTHRU statement issues administrative commands to a database

• Use parameter markers for performance

© Copyright IBM Corporation 2013

THE (SELECT …)
• SELECT returns a list Msg

SET OutputRoot.XML.Msg.Name[]= Name Name

(SELECT E.LASTNAME
from Database.EMPLOYEE as E); LASTNAME LASTNAME

Haas Thompson

• THE (SELECT …) returns the first Msg

element of a list
Name
SET OutputRoot.XML.Msg.Name =
THE(SELECT E.LASTNAME LASTNAME
from Database.EMPLOYEE as E);
Haas

© Copyright IBM Corporation 2013

SELECT (ITEM …)
• SELECT (ITEM..) gets the value only
– Without the ITEM keyword, the database table column name or XML tag is used
as a message tag
– Can be overridden with an AS keyword in a SELECT statement

Msg
SET
OutputRoot.XML.Msg.Name[]= Name Name
(SELECT E.LASTNAME from
Database.EMPLOYEE as E);
LASTNAME LASTNAME

Haas Thompson

SET
Msg
OutputRoot.XML.Msg.Name[]=
(SELECT ITEM E.LASTNAME from Name Name
Database.EMPLOYEE as E);
Haas Thompson

© Copyright IBM Corporation 2013

JavaCompute node database access example
JDBCType4Connection
// Add user code below
Connection conn = getJDBCType4Connection("MSGSTORE",
JDBC_TransactionType.MB_TRANSACTION_AUTO);
MbElement mqmd = message.getRootElement().get FirstElementByPath("MQMD");
try (
PreparedStatement insertStmt = conn
.preparedStatement("INSERT INTO MQSIUSER.COMPLAIN" +
" (MSDID, RECEIVED, MESSAGE) VALUE(?,?,?)");
insertStmt.setBytes(1, (byte[] mqmd.getFirstElementByPath("MsgId";)
.getValue());
Timestamp ts = new Timestamp(System.currentTimeMillis());
insertStmt.setTimestamp(2,ts);
insertStmt.setBytes(3, (byte[]) message.getBuffer());
insertStmt.execute();
) catch (SQLException e) (
e.printStackTrace();
)
// End of user code

© Copyright IBM Corporation 2013

DatabaseRoute node
• Directs messages that meet certain criteria down different parts of a flow
– Matches on contents of a database (JDBC connection)
– Uses XPath or ESQL(*) expressions to identify match criteria
• Define the custom output terminals to specify multiple expressions
• Default terminal if no matches are found
• KeyNotFound terminal if the query is unsuccessful or the outgoing message
is unsuccessfully routed
If Customer
STATUS is
“Bronze”

If Customer
STATUS is
“Silver”
Look up
CUSTOMER If Customer
STATUS is
“Gold”

If Customer
STATUS is
“Platinum”
© Copyright IBM Corporation 2013
Configuring the DatabaseRoute node
1. The workspace must have:
– A database definition
– A message model
2. Add custom output terminals to the DatabaseRoute node
3. Add query elements
4. Add filter expressions
5. Set the Distribution mode to propagate messages to the FIRST
terminal that matches, or to ALL that match
6. Wire the node terminals
7. Configure JDBC for the integration node
8. Deploy

© Copyright IBM Corporation 2013

DatabaseRoute node query elements

© Copyright IBM Corporation 2013

DatabaseRoute node filter expressions

• Filter order is important

– Expressions are applied in the order that they are given in the filter
table
– If the result is true, a copy of the message is routed to its
associated output terminal
Use these icons to
reorder the filters

© Copyright IBM Corporation 2013

DatabaseRetrieve node

• Populates fields by using data in a database record

• Similar to the graphical Compute node with database
SELECT
• Output terminals
– Out
Outgoing message is routed here when it is modified successfully
– KeyNotFound
Terminal to which the original message is routed, unchanged, when the result
set is empty
– Failure
Terminal to which the message is routed if a failure is detected during processing
• The Database Retrieve and Route nodes provide similar functions to
the DatabaseRoute node
© Copyright IBM Corporation 2013
Database service discovery
• DBMS represents a system of
record for key business entities Accounts Products Partners
such as customers, accounts,
partners, and products
• IBM Integration Bus tools
discover and represent these
key data
• Integration services extend WSDL WSDL WSDL
access to user applications
Accounts Products Partners
• Many uses for a database .WSDL .WSDL .WSDL
service definition
– WSDL contains both logical and
physical database information
– Drag WSDL to automatically
create SQL access methods
– Create an integration service to
use customized database
access © Copyright IBM Corporation 2013
Discovering database assets
1. Connect to DBMS
2. Discover source artifacts such as
tables and views
3. Map operations to the service
interface
4. Save in a canonical WSDL
document with custom bindings for
SQL access
5. Reuse the database WSDL in
multiple scenarios

© Copyright IBM Corporation 2013

Unit summary
Having completed this unit, you should be able to:
• Use database message processing nodes to modify messages and
control message processing
• Configure database nodes to access user databases
• Describe the differences between ESQL and SQL SELECT
• Define a database service

© Copyright IBM Corporation 2013

Checkpoint questions
1. True or False: Database updates are only rolled back in case of an
error, if you configured flow, DBMS, and queue manager for a
coordinated transaction.

2. Identify the two nodes that can transform the message and update a
database:
a. Route node
b. Database node
c. Compute node
d. JavaCompute

© Copyright IBM Corporation 2013

Checkpoint answers
1. True or False: Database updates are only rolled back in case of an
error, if you configured flow, DBMS and queue manager for a
coordinated transaction.

Answer: False. The default is a transactional flow with a one-phase

commit, that is, an uncoordinated (integration node coordinated)
transaction.

2. Identify the two nodes that can transform the message and update a
database:
a. Route node
b. Database node
c. Compute node
d. JavaCompute
Answer: c and d.
© Copyright IBM Corporation 2013
 Exercise 9

Referencing a database in a map

© Copyright IBM Corporation 2013

Course materials may not be reproduced in whole or in part without the prior written permission of IBM. 8.0
Exercise objectives
After completing this exercise, you should be able to:
• Discover database definitions
• Add a database node to a message flow
• Create the logic to store a message in a database
• Use the Graphical Data Mapping editor to map message elements
• Reference an external database when mapping message elements

© Copyright IBM Corporation 2013