Database node

Purpose

Use the Database node to interact with a database in the specified ODBC data source. You define the nature of the interaction by coding ESQL statements that specify the data from the input message, and perhaps transform it in some way (for example, to perform a calculation), and assign the result to a database table.

You can set a property to control whether the update to the database is committed immediately, or deferred until the message flow completes, at which time the update is committed or rolled back according to the overall completion status of the message flow.

Although you can use this node to update the database, you cannot make any updates to the message.

You can use specialized forms of this node to:
  • Update values within a database table (the DataUpdate node)
  • Insert rows into a database table (the DataInsert node)
  • Delete rows from a database table (the DataDelete node)
  • Store the message, or parts of the message, in a warehouse (the Warehouse node)

The Database node is represented in the workbench by the following icon:

Database node icon

Using this node in a message flow

Look at the following samples to see how you can use this node:

Consider a situation in which you receive an order for 20 monitors. If you have sufficient numbers of monitors in your warehouse, you want to decrement the stock level on your stock database. You can use the Database node to check that you have sufficient monitors available, and decrement the value of the quantity field in your database.

Configuring the Database node

When you have put an instance of the Database node into a message flow, you can configure it. Right-click the node in the editor view and click Properties. The node's basic properties are displayed.

All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk on the properties dialog.

Configure the Database node as follows:

  1. Specify in Data Source the name by which the appropriate database is known on the system on which this message flow is to execute. The broker connects to this database with user ID and password information that you have specified on the mqsicreatebroker, mqsichangebroker, or mqsisetdbparms command.

    On z/OS systems, the broker uses the broker started task ID, or the user ID and password that were specified on the mqsisetdbparms command JCL, BIPSDBP in the customization data set <hlq>.SBIPPROC.

  2. In Statement, identify the module within an ESQL file that contains the ESQL statements that are to be executed in this node. If you want the module name to include one or more spaces, enclose the name in double quotes in the Statement property.

    When you code ESQL statements that interact with tables, those tables are assumed to exist within this database. If they do not, a database error is generated by the broker at runtime.

    Code ESQL statements to customize the behavior of the Database node in an ESQL file that is associated with the message flow in which you have included this instance of the Database node. The ESQL file, which by default has the name <message_flow_name>.esql, contains ESQL for every node in the message flow that requires it. Each portion of code that is related to a specific node is known as a module.

    If an ESQL file does not already exist for this message flow, right-click the Database node and click Open ESQL. This creates and opens a new ESQL file in the ESQL editor view.

    If an ESQL file already exists, click the Browse button beside the Statement property. This displays the Module Selection dialog, which lists the available Database node modules defined in the ESQL files that are accessible by this message flow (ESQL files can be defined in other, dependent, projects). Select the appropriate module and click OK. If no suitable modules are available, the list is empty.

    If the module that you have specified doesn't exist, it is created for you and the editor positions the file to display it. If the file and the module already exist, the editor positions the file and displays and highlights the correct module.

    If you prefer, you can open the appropriate ESQL file in the Resource Navigator and select this node in the Outline view.

    If a module skeleton is created for this node in a new or existing ESQL file, it consists of the following ESQL. The default module name is shown in this example:

    CREATE DATABASE MODULE <flow_name>_Database
           CREATE FUNCTION Main() RETURNS BOOLEAN
           BEGIN
                   RETURN TRUE; 
           END;
    END MODULE;

    If you create your own ESQL module, create exactly this skeleton. You can update the default name, but ensure that the name that you specify matches the name of the corresponding node property Statement.

    Add your own ESQL to customize this node after the BEGIN statement and before RETURN TRUE.

    You can also create an ESQL file by clicking File > New > Message Flow ESQL File.

    You can use all the ESQL statements including SET, WHILE, DECLARE, and IF in this module, but (unlike the Compute node) the Database node propagates unchanged the message that it receives at its input terminal to its output terminal. This means that, like the Filter node, you have only one message to refer to in a Database node.

    Because you can't modify any part of any message, the assignment statement (the SET statement, not the SET clause of the INSERT statement) can assign values only to temporary variables. The scope of actions that you can take with an assignment statement is therefore limited.

    If you prefer, you can open the appropriate ESQL file in the Resource Navigator and select this node in the Outline view.

  3. Select the Transaction setting from the drop-down menu. The values are:
    • Automatic (the default). The message flow, of which the Database node is a part, is committed if it is successful. That is, the actions that you define in the ESQL module are performed and the message continues through the message flow. If the message flow fails, it is rolled back. If you choose Automatic, the ability to commit or roll back the action of the Database node on the database depends on the success or failure of the entire message flow.
    • Commit. If you want to commit any uncommitted actions performed in this message flow on the database connected to this node, irrespective of the success or failure of the message flow as a whole, select Commit. The changes to the database are committed even if the message flow itself fails.
  4. Select Basic in the properties dialog navigator and set or clear the two check boxes:
    • If you want database warning messages to be treated as errors and the node to propagate the output message to the failure terminal, select the Treat Warnings as Errors check box. The box is initially cleared.

      When you select the box, the node handles all positive return codes from the database as errors and generates exceptions in the same way as it does for the negative, or more serious, errors.

      If you do not select the box, the node treats warnings as normal return codes, and does not raise any exceptions. The most significant warning raised is not found, which can be handled as a normal return code safely in most circumstances.

    • If you want the broker to generate an exception when a database error is detected, select the Throw Exception on Database Error check box. The box is initially selected.

      If you clear the box, include ESQL to check for any database error that might be returned after each database call that you make (you can use SQLCODE and SQLSTATE to do this). If an error has occurred, you must handle the error in the message flow to ensure the integrity of the broker and the database: the error is ignored if you do not handle it through your own processing, because you have chosen not to invoke the default error handling by the broker. For example, you can include the ESQL THROW statement to throw an exception in this node, or you can use the Throw node to generate your own exception at a later point.

  5. Select Description in the properties dialog navigator to enter a short description, a long description, or both.
  6. Click Apply to make the changes to the Database node without closing the properties dialog. Click OK to apply the changes and close the properties dialog.

    Click Cancel to close the dialog and discard all the changes that you have made to the properties.

Terminals and properties

The terminals of the Database node are described in the following table.

Terminal Description
In The input terminal that accepts a message for processing by the node.
Failure The output terminal to which the input message is propagated if a failure is detected during the computation. If you have selected Treat warnings as errors, the node propagates the message to this terminal even if the processing completes successfully.
Out The output terminal to which the transformed message is routed when processing in the node is completed. The transformed message might also be routed to this terminal by a PROPAGATE statement.
Out1 The first alternate output terminal to which the transformed message might be routed by a PROPAGATE statement.
Out2 The second alternate output terminal to which the transformed message might be routed by a PROPAGATE statement.
Out3 The third alternate output terminal to which the transformed message might be routed by a PROPAGATE statement.
Out4 The fourth alternate output terminal to which the transformed message might be routed by a PROPAGATE statement.
Note: See PROPAGATE statement for the syntax of the PROPAGATE statement.

The following tables describe the node properties; the column headed M indicates whether the property is mandatory (marked with an asterisk on the properties dialog if you must enter a value when no default is defined), the column headed C indicates whether the property is configurable (you can change the value when you add the message flow to the bar file to deploy it).

The Database node Basic properties are described in the following table.

Property M C Default Description
Data Source No Yes   The ODBC data source name of the database in which reside the tables to which you refer in the ESQL associated with this node (identified by the Statement property).
Statement Yes No Database The name of the module within the ESQL file that contains the statements to execute against the database.
Transaction Yes No Automatic The transaction mode for the node. This can be Automatic or Commit.
Treat Warnings as Errors Yes No Cleared Treat database SQL warnings as errors. If you select the check box, this action is performed.
Throw Exception on Database Error Yes No Selected Database errors cause the broker to throw an exception. If you select the check box, this action is performed.

The Description properties of the Database node are described in the following table.

Property M C Default Description
Short Description No No   A brief description of the node.
Long Description No No   Text that describes the purpose of the node in the message flow.