TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Parameterized Destination Name Information

Publishing on parameterized subjects or destinations allows a subject or destination to be created from the contents of one or more table columns. See

Parameterized Subject or

Destination Names on page 168

— Publish data by creating a copy (by value). See

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Preface | xvii

TIBCO ActiveMatrix Adapter for Database Documentation

The following documents form the TIBCO ActiveMatrix Adapter for Database documentation set:

• TIBCO ActiveMatrix Adapter for Database Concepts Read this manual to gain an understanding of adapters in general that you can apply to the various tasks you may undertake.

• TIBCO ActiveMatrix Adapter for Database Installation Read this manual to learn how to install TIBCO ActiveMatrix Adapter for Database.

• TIBCO ActiveMatrix Adapter for Database Configuration and Deployment This manual explains how to create and configure adapter projects. Information on deploying adapter projects is also included.

• TIBCO ActiveMatrix Adapter for Database Examples Read this manual to work through the examples provided with the adapter.

• TIBCO ActiveMatrix Adapter for Database Release Notes Read the release notes for a list of new and changed features. This document also contains lists of known issues and closed issues for this release.

Typographical Conventions

The following typographical conventions are used in this manual.

Table 1 General Typographical Conventions

Convention

TIBCO_HOME

TIB_ADADB_HOME

ENV_NAME

CONFIG_HOME

Use

Many TIBCO products must be installed within the same home directory. This directory is referenced in documentation as

TIBCO_HOME

. The default value of

TIBCO_HOME

depends on the operating system. For example, on Windows systems, the default value is

C:\tibco

Other TIBCO products are installed into an installation environment. Products installed into different installation environments do not share components.

Incompatible products and multiple instances of the same product must be installed into different installation environments. An installation environment consists of the following properties:

•

Name

Identifies the installation environment. The name is appended to the name of Windows services created by the installer and is a component of the path to the product in the Windows Start > All Programs menu. This directory is referenced in documentation as

ENV_HOME

•

Path

The directory into which the product is installed. This directory is referenced in documentation as

TIBCO_HOME

. TIBCO ActiveMatrix Adapter for Database installs into a directory within

TIBCO_HOME

. This directory is referenced in documentation as

TIB_ADADB_HOME

. The default value of

TIB_ADADB_HOME

depends on the operating system. For example, on Unix systems, the default value is

TIBCO_HOME

/adapter/adadb/ version

A TIBCO configuration folder stores configuration data generated by TIBCO products. Configuration data can include sample scripts, session data, configured binaries, logs, and so on. This folder is referenced in documentation as

CONFIG_HOME

. The default location of the folder is

USER_HOME

ENV_NAME

/tibco/cfgmgmt/ product_name

. For example, on Windows, the default location is

C:\Documents and Settings\ user_name

\Application

Data\

ENV_NAME\ tibco\cfgmgmt\ product_name

code font

Code font identifies commands, code examples, filenames, pathnames, and output displayed in a command window. For example:

Use

MyCommand

to start the foo process.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Preface | xix

Table 1 General Typographical Conventions (Cont’d)

Convention bold code font

Use

Bold code font is used in the following ways:

• In procedures, to indicate what a user types. For example: Type admin

• In large code samples, to indicate the parts of the sample that are of particular interest.

• In command syntax, to indicate the default parameter for a command. For example, if no parameter is specified,

MyCommand

is enabled:

MyCommand [enable | disable] italic font

Key combinations

Italic font is used in the following ways:

• To indicate a document title. For example: See TIBCO ActiveMatrix

BusinessWorks Concepts.

• To introduce new terms For example: A portal page may contain several portlets. Portlets are mini-applications that run in a portal.

• To indicate a variable in a command or code syntax that you must replace. For example:

MyCommand

PathName

Key name separated by a plus sign indicate keys pressed simultaneously. For example: Ctrl+C.

Key names separated by a comma and space indicate keys pressed one after the other. For example: Esc, Ctrl+Q.

The note icon indicates information that is of special interest or importance, for example, an additional action required only in certain circumstances.

The tip icon indicates an idea that could be useful, for example, a way to apply the information provided in the current section to achieve a specific result.

The warning icon indicates the potential for a damaging situation, for example, data loss or corruption if certain steps are taken or not taken.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

xx | Typographical Conventions

Table 2 Syntax Typographical Conventions

Convention

[ ]

Use

An optional item in a command or code syntax.

For example:

MyCommand [optional_parameter] required_parameter

{ }

A logical

that separates multiple items of which only one may be chosen.

For example, you can select only one of the following parameters:

MyCommand para1 | param2 | param3

A logical group of items in a command. Other syntax notations may appear within each logical group.

For example, the following command requires two parameters, which can be either the pair param1

and param2

, or the pair param3

and param4

MyCommand {param1 param2} | {param3 param4}

In the next example, the command requires two parameters. The first parameter can be either param1

or param2

and the second can be either param3

or param4

MyCommand {param1 | param2} {param3 | param4}

In the next example, the command can accept either two or three parameters. The first parameter must be param1

. You can optionally include param2

as the second parameter. And the last parameter is either param3

or param4

MyCommand param1 [param2] {param3 | param4}

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Preface | xxi

Connecting with TIBCO Resources

How to Join TIBCOmmunity

TIBCOmmunity is an online destination for TIBCO customers, partners, and resident experts. It is a place to share and access the collective experience of the TIBCO community. TIBCOmmunity offers forums, blogs, and access to a variety of resources. To register, go to

http://www.tibcommunity.com

How to Access TIBCO Documentation

You can access TIBCO documentation here:

http://docs.tibco.com

How to Contact TIBCO Support

For comments or problems with this manual or the software it addresses, contact TIBCO

Support as follows.

• For an overview of TIBCO Support, and information about getting started with

TIBCO Support, visit this site:

http://www.tibco.com/services/support

• If you already have a valid maintenance or support contract, visit this site:

https://support.tibco.com

Entry to this site requires a user name and password. If you do not have a user name, you can request one.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

xxii | Connecting with TIBCO Resources

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Chapter 1

271

Introduction

This book provides information on configuring an adapter instance, using adapter features, and deploying the adapter to the runtime environment.

| 1

Topics

•

Overview, page 2

•

Configuration, page 4

•

Deployment, page 9

•

Adapter Project Lifecycle, page 11

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

2 | Chapter 1 Introduction

Overview

TIBCO ActiveMatrix Adapter for Database software (the adapter) allows data changes in a database to be sent as they occur to other databases and applications. It extends publish-subscribe and request-response technology to databases, making multiple levels of delivery services available to applications that need access to these databases. ODBC and JDBC compliant databases such as Oracle, Sybase, Microsoft SQL Server, MySQL, and Teradata are supported. While the adapter does not run on z/OS and iSeries systems, it can remotely connect to a DB2 database running on these systems.

Features

The following capabilities are described in detail in this manual.

• Automatically publish data when rows in pre-specified database tables are inserted, updated or deleted:

Publish by Value on page 73

— Publish by reference (publish data directly from the source database table without first copying the data from the source table to a publishing table). See

Publish by

Reference on page 74

— Publish on parameterized subjects or destinations, which allows a subject or destination to be created from the contents of one or more table columns. See

Parameterized Subject or Destination Names on page 164

The subject names mentioned in this document are referred to as subject names when using the TIBCO Rendezvous transport type, but are referred to as destination names when using the JMS (Java Messaging Service) transport type.

— Preregister certified subscribers with a certified publisher. See

Preregistering a

Certified Subscriber on page 167

— Update both parent and child tables within a publication. Both the parent row and all related child rows will be published if the user has set up to publish child data.

See

Adding Child Tables on page 65

— Specify that a group of rows fetched from the publishing table is sent in a single message.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Overview | 3

• Automatically subscribe to data and insert, update or delete the data in pre-specified tables in a database:

— Subscribe using wildcard subject names. See

Preregistering a Certified Subscriber on page 167

— Perform batch commits based on message count or time out value. See

Adapter

Instance Tabs on page 34

— Subscribe a group of rows set in a single message. You can configure the adapter to update all rows in a single database transaction by turning on the Enable Group

Message Transaction Support option. See

Subscriber Options Tab on page 82

• Use request-response semantics to publish SQL statements, stored procedures, or both on a specified subject:

— Execute stored procedures with IN parameters, OUT parameters, or both. (Binary

OUT parameters are not supported. This is a limitation of the Oracle ODBC driver.)

See

Oracle REF Data Type Support on page 139

• Support RPC (Remote Procedure Calls). The adapter can act as an operation server providing a simple means for a client to execute a single or batch of SQL statements.

See

Request-response Mode on page 114

the supplied callout library. See

RPC Mode on page 122

• Change published messages for a publication or subscription service by customizing

User Callout Library on page 179

• Customize adapter behavior to suit your needs:

— Specify relationships between tables, then publish related tables together. See

Tables Tab on page 62

— Monitor for database changes using periodic polling or notification by an alerting mechanism. See

Adapter Services Tab on page 43

• Rely on standards:

— Connect to multiple database vendors using ODBC or JDBC drivers. See

Design-time Connection Tab on page 37

— Monitor your adapter service using TIBCO Hawk software. See

Table 8, Runtime Connection Tab, on page 41

— Interoperate with other TIBCO products through the use of TIBCO Adapter SDK

software. See

Sending Messages to an Adapter Instance on page 170

Monitoring Tab on page 55

Configure the adapter easily using TIBCO Designer. See

Chapter 11, Monitoring the Adapter, on page 233

— Choose message transports: TIBCO Rendezvous or JMS (Java Messaging

Service).

•

Chapter 3 on page 25

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

4 | Chapter 1 Introduction

Configuration

TIBCO Designer, the design-time component, is an easy-to-use graphic user interface.

The TIBCO ActiveMatrix Adapter for Database palette in TIBCO Designer is used to create adapter instances, configure adapter services, download schemas, and save the resulting configuration in a project.

Before using TIBCO Designer, make sure you read the TIBCO Designer product documentation.

The following figure shows the TIBCO Designer interface.

Figure 1 TIBCO Designer Main Window

Menu bar

Tool bar

Project panel

Design panel

Palette panel

Configuration panel

Project Panel

Each TIBCO Designer window contains one and only one project, which is represented as the root folder in the panel.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Configuration | 5

Projects are the key organizational principle for the configuration information you specify.

A project is a collection of all configured resources. Resources are the components of a project. For example, an adapter publication service is a resource. Resources can be complex and contain other resources, much like a folder can contain other folders on your computer file system. Together, these resources make up your integration project. The top-level (root) folder in the project tree panel represents a project. The top-level folder is initially named

Untitled

and is renamed to the name of the project when you save the project for the first time.

Most adapter resources have context-sensitive help available for the configuration of that resource. Right-click on the resource and choose What Is This? from the popup menu for more information on configuring the resource.

An adapter project contains the following folders:

• AESchemas Folder

The AESchemas folder is the default location for all TIBCO ActiveEnterprise schema files. Each schema file contains a collection of classes, scalars, associations, unions, and sequences.

• Adapter Services Folder

The Adapter Services folder contains services available to the adapter. Most adapters include publication, subscription, request-response, and request-response invocation services.

• Advanced Folder

The Advanced folder contains resources created by TIBCO Designer while the adapter is configured. For example, each time you add a service to an adapter, a session and endpoint are created and stored in the Advanced folder. Other resources such as advanced logging resources are accessed directly from the folder. Adapter developers typically do not access resources in this folder. Most of the adapter configuration is done by changing resources that are available from the Adapter Services folder.

Palette Panel

Palettes organize resources and allow you to add them into your project. Palettes are available from the palette panel in TIBCO Designer. Resources are visible components in a palette. You select resources in the palette panel and drag-and-drop them into the design panel to add them to your project.

Each adapter you install adds one or more palettes during installation. Which palette is displayed depends on the resource selected in the project tree and on your preferences. In the default view, the current selection in the project tree determines which palettes are displayed in the palette panel.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

6 | Chapter 1 Introduction

Design Panel

The design panel displays the current resource selected in the project tree panel. For resources that contain other resources, the contents of the selected resource are shown in the design panel. For example, if you select a folder, its contents are displayed.

Configuration Panel

The configuration panel allows you to specify configuration options for the selected resource. The type and the purpose of the resource determine the contents of the configuration panel. There are usually one or more tabs in the configuration panel that allow you to access the various configuration options. The tabs provide an organization to the options for the resource.

You can click the question mark icon (?) in the top right corner of the configuration panel for online help on the current selection.

For each tab, you must click the Apply button after you have specified configuration information before you can select another tab. If you decide you do not want to add the configuration information, click the Reset button before you apply any changes to return to the previous values for each field in the tab.

Projects

A project is a named collection of data, usually schema data, and configuration data that is persistently stored. Each project is opened and saved in multi-file format, which allows the project to be used with a version control system. It allows different developers to collaborate on a project and merge changes as needed.

When a project is ready to be deployed, it can be created or exported in the following formats:

• Enterprise Archive File

• Local Repository

• Server Repository

• ZIP Archive

Enterprise Archive File

An Enterprise Archive file contains information about the adapter instances and processes you wish to deploy. The format is used by TIBCO Administrator. The EAR file is imported into Administrator where you can deploy, start, and manage the adapter instance on the machines of your choice.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Configuration | 7

Local Repository

A project exported to a local repository is saved in

.dat

format. Projects saved in

.dat

format should only be used for development and testing. The format can be used where data is not shared by more than one adapter. It is possible to have a few local adapters accessing a local project in read-only mode. It is, however, not possible to have more than one local adapter accessing a local project in read and write mode.

Data are loaded at startup for local projects, so a local project has higher memory requirements.

Server Repository

A project exported to a server repository is managed by a TIBCO Administration Server running in a separate process, typically elsewhere on the network. One or more adapters can communicate with a project managed by an Administration Server. Each can support multiple projects.

An Administration Server is identified by a name that must be unique among all administration servers on a network. The server-based mode of operation is scalable and generally recommended for production situations. Server repositories allow multiple simultaneous write operations with locking, automatic updates of clients, and notification.

Data are loaded on demand for server-based projects.

ZIP Archive

A project exported to a ZIP archive is written to the location you specify as a read-only

ZIP file. A project exported as a ZIP archive can be imported into TIBCO Designer.

Version Control

TIBCO Designer allows multiple developers to work on the same project and to use file sharing (locking) or a version control system so that the same resource is not changed by two developers at the same time. Different users can then add resources to the project and lock the parts of the project they are working on.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

8 | Chapter 1 Introduction

TIBCO Designer creates a file that can be shared and locked for each top-level resource, such as an adapter configuration. It does not create a file for each resource. As a result, for example, you can lock an adapter configuration but cannot lock individual adapter services.

When an adapter service is configured, the adapter creates a corresponding set of schema files. A warning is displayed when the files are created advising you to add the files to your version control system. You must add the files to your version control system and ensure they are checked-in, otherwise your project will not be managed correctly by the version control system.

TIBCO Designer also creates folders for folders you create in your project. You can lock each folder as needed.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Deployment | 9

Deployment

After an integration project has been developed and tested, it is necessary to deploy the runtime components to the machines on which they will ultimately run in a production environment. An adapter instance can be deployed, started and managed using TIBCO

Administrator from the Administrator web browser.

Using TIBCO Administrator, you can upload the EAR, deploy the adapter on the machine(s) of your choice, and set runtime options before deployment. Additionally you can start and stop the adapter using TIBCO Administrator.

TIBCO Administrator also provides built-in tools to monitor and manage the adapter.

TIBCO Administrator provides user, resource, and application management modules for adapters.

• User Management. This module allows you to set permissions for adapter users. You define authentication, users and groups, and assign access control lists to users. This includes security for server-based projects at design time and for deployed applications at runtime.

• Resource Management. This module allows you to monitor machines and all running applications in a TIBCO administration domain. Alerts can be created, for example, to notify an administrator if the number of processes or disk usage exceed a certain number.

• Application Management. This module allows you to upload Enterprise Archive

(EAR) files, and create, configure, and deploy adapters. This console is also used to start and stop adapters.

TIBCO Administration Domain

A TIBCO administration domain is installed only if you have also installed the User

Management module.

A TIBCO administration domain is a collection of users, machines, and components that an administration server manages. There is only one Administration Server for each administration domain. Components within an administration domain can communicate with systems outside of the domain, but the domain is the administrative boundary of your enterprise integration project.

.See the TIBCO Administrator product documentation for more information.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

10 | Chapter 1 Introduction

TIBCO Administration Server

The TIBCO Administrator Server provides a central storage and distribution point for configuration data and schema data needed by an adapter. The server is included in both

Administrator editions.

Each administration domain has one and only one TIBCO Administration Server. The

TIBCO Administration Server is the machine process that handles the stored project and requests to manage the TIBCO administration domain.

The TIBCO Administrator Server contains its own web server (Apache Tomcat) that can be accessed via the TIBCO Administrator GUI for configuration and monitoring information.

TIBCO Administrator GUI

You can access the TIBCO Administration Server using the web-based TIBCO

Administrator GUI. The GUI allows you to create users and assign access to projects managed by the Administration Server. You can invoke the GUI from any machine in a

TIBCO administration domain. The next diagram shows the GUI.

Figure 2 TIBCO Administrator GUI

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Adapter Project Lifecycle | 11

Adapter Project Lifecycle

This section describes the high-level steps required to configure and deploy an adapter.

Each of these steps are described in details in subsequent chapters. Adapter projects are configured using TIBCO Designer.

Configuration

Task A Configure the Vendor Application to work with the Adapter

This task is completed as part of installing the adapter and before configuring an adapter instance for the first time.

Task B Define an Adapter Project

When starting TIBCO Designer, you create or select a project. A project contains adapter configuration information, such as the service and messaging transport to use, logging options, and other specific settings. A project is opened and saved in multi-file format, which allows a version control system to manage the files associated with the project.

Adapter Instance Tabs on page 34

Task C Set Global Variables

By default each project you create in TIBCO Designer includes several global variables.

Global variables provide an easy way to set defaults for use throughout your project.

Default values are predefined for some of the variables. You can define additional variables and, optionally, set their values when configuring your adapter.

When the project is deployed and the configured adapters are run, all occurrences of the global variable name are replaced with the global variable value.

A global variable value set in TIBCO Designer can be overridden at runtime by redefining the value in TIBCO Administrator.

Using Global Variables on page 30

Task D Configure an Adapter Service

The adapter supports the following services: publication, subscription, request-response, and request-response invocation.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

12 | Chapter 1 Introduction

Task E Test the Adapter Configuration

The adapter tester can be used to verify an adapter service after it has been configured.

When invoked, all adapter services configured in the project are displayed. You select the adapter service to test, and start and stop the adapter from the tester. The tester window displays adapter output within the tool so you can easily view results.

Deployment

During development, you save your design to a project. When you are ready to deploy your project to a machine, you generate an Enterprise archive file (EAR file) from TIBCO

Designer. The EAR file contains information on what you wish to deploy

Task F Generate and Import an Enterprise Archive File

An Enterprise Archive file contains adapter instance configuration information, which is used by a runtime adapter. An Enterprise Archive file is generated using TIBCO Designer and imported into TIBCO Administrator.

Create an EAR File in TIBCO Designer on page 92

Task G Specify Deployment Information

After importing an Enterprise Archive file, the adapter can be deployed. This involves:

• Assigning adapter services to the machines in the administration domain.

• Specifying startup options for each process engine and adapter service.

Deploy the Project on page 93

for more information.

Task H Specify Monitoring Options

Before starting the adapter you can optionally specify monitoring options, including:

• Specifying alerts or TIBCO Hawk rulebases for each machine.

• Specifying alerts and TIBCO Hawk rulebases for an adapter service.

• Setting log file properties for an adapter service instance.

Task I Start the Adapter

The adapter is started and stopped using the TIBCO Administrator GUI.

configuration (as listed in

Start or Stop the Adapter on page 94

for more information.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Chapter 2

Getting Started

This chapter helps you get familiar with the adapter by walking you through a basic exercise. Work through the exercise to get a hands-on understanding on how the adapter works.

| 13

Topics

•

Overview, page 14

•

Create the Database Tables, page 17

•

Configure the Properties File, page 18

•

Start the Adapter Services, page 20

•

Change the Table Values and Receive Notification, page 21

•

Exit the Query Tool and Adapters, page 23

•

Clean Up, page 24

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

14 | Chapter 2 Getting Started

Overview

In this exercise, you create tables in your database and configure a publisher adapter and a subscriber adapter. Then you modify a table and observe how the publisher adapter and subscriber adapter handle the change and update the subscription table.

Required Platform and Software

This exercise can be performed on any supported operating system, using adapters provided with TIBCO ActiveMatrix Adapter for Database. The exercise can be run using the TIBCO Rendezvous transport method or the JMS transport method.

The exercise can be performed with an Oracle, Microsoft SQL or Sybase database.

A sample DAT file that can be used with an Oracle database,

ADBDemo2-ora.dat

, is included in the

TIB_ADADB_HOME

\ demo\demo2

directory.

Before Starting

Before performing this exercise, make sure that TIBCO ActiveMatrix Adapter for

Database is installed according to the procedures in the TIBCO ActiveMatrix Adapter for

Database Installation.

You should be familiar with using TIBCO Designer to open and close projects and drag and drop resources; see the TIBCO Designer User’s Guide for more information. That document also describes the multi-file format used by TIBCO Designer, and converting to and from the

.dat

file format used by the runtime adapter. The TIBCO Designer User’s

Guide is available from TIBCO Designer by selecting Help > Designer Help.

Tables

The tables are created by running a script specific to your database vendor. The script creates the following tables, all with a common set of columns:

•

Source table

to which you will add new data.

•

Publishing table

to which the new data from the source table is copied using the trigger set on the source table. This table has additional columns (prefixed by

ADB_

) that are used by the adapter.

•

Destination table

that TIBCO ActiveMatrix Adapter for Database will update with the new data.

•

Exception table

to which TIBCO ActiveMatrix Adapter for Database will write any errors that occur during subscription.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Actions

Overview | 15

When you add data to the source table, the following occurs:

1. The insert action fires a trigger and the inserted row is copied to the publishing table.

2. The publisher adapter polls the publishing table to check if any new rows have been inserted. Newly inserted rows are fetched using ODBC, packed into a message, and published.

3. The subscriber adapter listens for messages. When a message arrives, the subscriber adapter inserts it into the destination table using ODBC.

The following diagram illustrates the activity.

Figure 3 Diagram of Publish-Subscribe Steps

Destination

Table

Insert Trigger

Source

Table

Publishing

Table

Adapter

Publisher

Adapter

Subscriber

Exception

Table

Tasks

TIBCO Messaging

This exercise consists of the following tasks:

•

Create the Database Tables, page 17

•

Configure the Properties File, page 18

•

Start the Adapter Services, page 20

•

Change the Table Values and Receive Notification, page 21

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

16 | Chapter 2 Getting Started

•

Exit the Query Tool and Adapters, page 23

•

Clean Up, page 24

Exercise

This exercise uses the Oracle database. You can use the TIBCO Rendezvous or JMS transport. When performing this exercise, use the appropriate transport values for your

Table 3 on page 16

) and follow the instructions that pertain to your particular database vendor.

You will need the following information, specific to your user environment:

• Database user ID

• Database password

• Database service7

The values you will enter for the tables and the publisher and subscriber adapter instances are different, depending on which transport type you are using. (The kind of database you are using does not affect these names.)

Table 3 Values to Use for TIBCO Rendezvous and JMS Transport Types

Item

Source Table

TIBCO Rendezvous

Transport Value

ORDER_TABLE

JMS Transport

Value

ITEM_TABLE

Publishing Table

Destination Table

PUB_ORDER

SUB_ORDER

PUB_ITEM

SUB_ITEM

Exception Table

Publisher Adapter

SUB_ORDER_EXCEP rvpub

Subscriber Adapter rvsub

SUB_ITEM_EXCEP jmspub jmssub

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Create the Database Tables | 17

Create the Database Tables

The first task is to create the database tables.

1. Open a command window and change directory to the demo1

subdirectory. For example:

> cd

TIB_ADADB_HOME

\demo\demo1

2. Execute the demo1_ databaseVendor

.sql

script in the subdirectory to create the tables for your database. Use your environment-specific user ID, password, and database service. For example:

> sqlplus userid

/ password

@ dbService

@demo1_ora.sql

The script creates the items and displays the status. For example:

TIB_ADADB_HOME

\demo\demo1>sqlplus karlh/karlh@ORCL @demo1_ora.sql

SQL*Plus: Release 8.1.7.0.0 - Production on Tue Aug 10 13:10:48 2004

Connected to:

Personal Oracle8i Release 8.1.7.0.0 - Production

With the Partitioning option

JServer Release 8.1.7.0.0 - Production

Table created.

Index created.

Sequence created.

Trigger created.

Table created.

Index created.

Sequence created.

Trigger created.

Table created.

Commit complete.

SQL>

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

18 | Chapter 2 Getting Started

Configure the Properties File

After creating the database tables, configure the adapter’s properties file.

1. In the demo1

subdirectory, locate the correct publisher adapter properties file for the transport type you are using. See

Table 3 on page 16

2. Open the publisher adapter file and set the following values for your environment.

Property adb.user

username adb.password

adb.dsn

pwd data source

Value

Use the database account name used by the adapter instance.

This is the same username entered during TIBCO

ActiveMatrix Adapter for Database post installation procedure when creating a database account for the adapter.

Use the database account password used by the adapter instance. This is the same password entered during TIBCO

ActiveMatrix Adapter for Database post installation procedure when creating a database account for the adapter.

This password is not saved in the project. The global variable

%%adb.password%%

is saved instead.

Use the name of the ODBC system data source for the adapter.

The data source is configured as a post installation procedure.

See the TIBCO ActiveMatrix Adapter for Database

Installation for more information.

For example:

TIB_ADADB_HOME

\demo\demo1>write rvpub.tra

# Sample ADB properties file

# Optional properties file you can use in place of command line parameters

# Usage: adbagent --propFile propFilename

# Change these settings for your login and dsn for Demo1 adb.user karlh adb.password karlh adb.dsn Oracle001

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Configure the Properties File | 19

3. Save and close the publisher adapter file.

4. In the same subdirectory, locate the correct subscriber adapter file for the transport type you are using.

5. Open the subscriber adapter file and repeat the changes you made in

step 2

6. Save and close the subscriber adapter file.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

20 | Chapter 2 Getting Started

Start the Adapter Services

You can use TIBCO Rendezvous or TIBCO Enterprise Message Service as the message transport.

1. If you are using TIBCO Rendezvous transport, skip this step and proceed to

step 2

If you are using JMS transport, open a command window and change directory to the

TIBCO Enterprise Message Service bin

directory and start the server. Note that this step is not required if the server is running as a service on Microsoft Windows. For example: cd

TIBCO_HOME

\ems\bin

> tibemsd

2. Open a new command window and change directory to the adapter bin

directory. For example:

> cd

TIB_ADADB_HOME

\bin

3. In separate command windows, start the publisher and subscriber adapters for your database.

If using TIBCO Rendezvous:

> adbagent --propFile

TIB_ADADB_HOME

\demo\demo1\rvpub.tra

> adbagent --propFile

TIB_ADADB_HOME

\demo\demo1\rvsub.tra

If using TIBCO Enterprise Message Service:

> adbagent --propFile

TIB_ADADB_HOME

\demo\demo1\jmspub.tra

> adbagent --propFile

TIB_ADADB_HOME

\demo\demo1\jmssub.tra

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Change the Table Values and Receive Notification | 21

Change the Table Values and Receive Notification

You must change table setting in your database to trigger a notification.

1. Open a new command window and change directory to the demo1

subdirectory. For example:

> cd

TIB_ADADB_HOME

\demo\demo1

2. Invoke the query tool using the environment-specific user ID, password, and database service specified in

Create the Database Tables, page 17

> sqlplus userid

/ password

@ dbService

3. Insert three values into the source table, then commit the change.

If using TIBCO Rendezvous:

SQL> insert into ORDER_TABLE values(111,'Oak Table',499.95);

SQL> commit;

If using TIBCO Enterprise Message Service:

SQL> insert into ITEM_TABLE values(111,'Oak Table',499.95);

SQL> commit;

You will see the message being sent in the publisher adapter window and, after a short delay, received in the subscriber adapter window.

4. Verify that the row in the source table has been inserted into the destination table.

If using TIBCO Rendezvous:

SQL> select * from ORDER_TABLE;

The following example result confirms that the data has been inserted:

ORDER_ID

----------

ORDER_DESCRIPTION

---------------------------------------------------

ORDER_PRICE

-----------

111

Oak Table

499.95

If using TIBCO Enterprise Message Service:

SQL> select * from ITEM_TABLE;

The following example result confirms that the data has been inserted:

ITEM_ID

----------

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

22 | Chapter 2 Getting Started

ITEM_DESCRIPTION

---------------------------------------------------

ITEM_PRICE

-----------

111

Oak Table

499.95

5. Insert additional rows of data, if you wish. If you do, be aware that the first column

(containing the value

111

in the example) is a primary key and must contain a value that is unique within the table.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Exit the Query Tool and Adapters | 23

Exit the Query Tool and Adapters

After running the example, exit the query tool and adapters.

1. Exit the SQL query tool. For example:

SQL> exit

2. In a command window, use the tibrvsend

application to send a message on the terminate subject to stop each adapter instance:

If using TIBCO Rendezvous: tibrvsend _ADB.rvpub.TERMINATE now tibrvsend _ADB.rvsub.TERMINATE now

If using TIBCO Enterprise Message Service: tibrvsend _ADB.jmspub.TERMINATE now tibrvsend _ADB.jmssub.TERMINATE now

Note that the tibrvsend

program is typically not used to terminate the adapter. Instead, a

JMS program typically sends a JMS message to the JMS termination destination configured for the adapter.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

24 | Chapter 2 Getting Started

Clean Up

This cleanup script removes the example tables that were created by the demo1_cleanup_ databasevendor

.sql

script.

1. In a command window, change directory to the demo1

directory. For example:

> cd

TIB_ADADB_HOME

\demo\demo1\

2. Execute the appropriate demo_cleanup.sql

script in the subdirectory.

> sqlplus userid

/ password

@ dbService

@demo1_cleanup_ databasevendor

.sql

For example:

> sqlplus karlh/karlh@ORCL @demo1_cleanup_ora.sql

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Chapter 3

Adapter Instance Options

This chapter explains how to create an adapter instance by configuring standard settings.

All configuration tasks are performed in TIBCO Designer and the information is stored in a project that is later used by the runtime adapter.

| 25

Topics

•

Overview, page 26

•

Adapter Instance Tabs, page 34

•

Configuration Tab, page 35

•

Design-time Connection Tab, page 37

•

Runtime Connection Tab, page 41

•

Adapter Services Tab, page 43

•

General Tab, page 47

•

Logging Tab, page 49

•

Startup Tab, page 54

•

Monitoring Tab, page 55

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

26 | Chapter 3 Adapter Instance Options

Overview

The adapter instance tabs in TIBCO Designer allow you to create, design, and run an

adapter. Adding services to an adapter is described in

Chapter 4, Adapter Service Options

Please read the following sections before starting to configure an adapter.

•

Configuration Task Sequence, page 26

•

Saving the Project, page 27

•

Testing the Adapter, page 27

•

Notes on Configuring an Adapter, page 27

•

Configuration Recommendations, page 28

•

Changing an Existing Configuration, page 29

Configuration Task Sequence

Use the following sequence to create and configure an adapter service.

1. Start TIBCO Designer and open a multi-file project. See the TIBCO Designer documentation for details.

2. Drag the ActiveDatabase Adapter Configuration icon from the palettes panel to the design panel. This creates an adapter instance named, by default,

ActiveDatabaseAdapterConfiguration

3. Define the adapter instance by assigning a new name. See

Configuration Tab on page 35

4. Define and test the design-time connection options for the instance. See

Design-time

Connection Tab on page 37

5. Either now or when the instance is ready to deploy, define and test the runtime

connection options for the instance. See

Runtime Connection Tab on page 41

6. As necessary, modify the following default values for the instance:

— Default startup state and session, metadata search URL: see

General Tab on page 47

— Threads, polling, publishing child data, bulk insert size, TIBCO Rendezvous queue

size, exception table: see

Adapter Services Tab on page 43

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Overview | 27

7. Add one or more services to the adapter instance by dragging a service icon from the

palettes panel and dropping it in the design panel: see

Chapter 4, Adapter Service

Options

8. Under the service’s Configuration tab, set the combination of options for each service.

This is required.

9. As necessary, define tables, mappings, message and reply subjects, endpoints, and other service options.

10. Save the project as a server repository project.

After configuring the adapter, create the runtime adapter property file and add the project name and adapter instance name.

Also define and test the runtime connection options for the instance if you did not do it

earlier. See

Runtime Connection Tab on page 41

Saving the Project

Configuration information for an adapter and all other parameter settings related to the adapter are saved as a project. At any time while configuring the adapter, you can save the associated project. Each time you save a project, any configuration information you have entered is saved as a project.

For detailed steps and more information about exporting or importing projects to different formats (such as

.dat

), see the TIBCO Designer User’s Guide.

Testing the Adapter

You can use the Adapter Tester to verify that an adapter instance is configured correctly.

The tester is invoked from the TIBCO Designer Tools menu and is documented in TIBCO

Designer Palette Reference.

Notes on Configuring an Adapter

Required and Optional Settings

•

You must set the options in the

Configuration Tab

for all adapters.

•

The

Design-time Connection Tab

options are required before you can start designing the adapter and adding services.

• The remaining tabs are optional, and are customized for your adapter or services only as needed.

You should be aware of the following before starting or configuring an adapter.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

28 | Chapter 3 Adapter Instance Options

• A database account must have been created for running the adapter. For details, see the TIBCO ActiveMatrix Adapter for Database Installation.

• The database server process, and the repository server process if you are using a remote repository, must be running to start an adapter instance.

• Each adapter must have configuration information defined in a project using TIBCO

Designer. For instructions, see

Chapter 3, Adapter Instance Options

• Data source connection parameters for an adapter instance can be specified in the adapter properties file and in TIBCO Designer. Values given in the properties file override the same values specified in TIBCO Designer.

• An adapter instance name is defined in TIBCO Designer. Names must be alphanumeric, can contain underscores (_) and hyphens(-), and must be less then 80 characters.

• Multiple subscribers of the same instance should not be configured to listen on the same subject.

• Multiple subscribers in different instances can be configured to listen on the same subject but should not write to the same destination table.

• An adapter instance can be configured as a publisher, subscriber, or both. It can handle request-response operations if it is configured to do so.

• An adapter instance can publish or subscribe to a maximum of 1024 database columns per table. The maximum size of each record is restricted by the number of bytes per row supported by the database server, and the amount of contiguous space in memory available to build the message.

• If an adapter instance cannot access the database at startup, the adapter will not start.

If the connection fails after startup, you can configure the adapter to attempt automatic

reconnections (see the

Runtime Connection Tab on page 41

). You can also build a

TIBCO Hawk rule to restart the adapter instance after the database is restarted.

• To start or stop an adapter instance see

Start or Stop the Adapter on page 94

• An adapter instance logs error, warning, debug and information messages to the console window by default. Some of the output can be directed to a log file that can be located anywhere on your file system.

• Do not use

ADB_

to prefix columns in the database. The prefix is reserved for this product.

Configuration Recommendations

The following recommendations and limitations apply when using TIBCO ActiveMatrix

Adapter for Database:

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Overview | 29

• The wire format for both the publishing and destination tables must be the same, otherwise an error will occur.

• Publisher and subscriber information should be defined in the same project for all cases. When using parent-child tables or the XML wire format, define the publisher and subscriber in the same repository.

• For the limitations that apply to parameterized subject names and destination names,

see

Parameterized Subject and Destination Name Restrictions on page 164

Changing an Existing Configuration

You can change an existing adapter instance before or after it is deployed, but doing so may have unintended consequences to the database, the schema, and to other adapter instances associated with the same schema. When making changes, be aware of the following:

• It is recommended to back up your project before making major configuration changes. To back up a project, use TIBCO Designer to export the project. The export file can be imported into TIBCO Designer, if necessary. For more information, see

TIBCO Designer Palette Reference.

• Legitimate changes to the database as a result of adapter instance changes may not be immediately successful, for example, if the database was not available at the time the change was made.

• If you want adapter instance changes to be reflected in the database, make sure the

Deploy On Save checkbox is selected; otherwise, make sure this checkbox is cleared.

This checkbox is on the Configuration tab of the configured adapter resource.

• If you delete an adapter instance or service that is already deployed, the related database will be cleaned up as soon as you confirm the deletion, and the changes will be irreversible.

• If you change an adapter instance or service that is already deployed, the related database will be cleaned up as soon as you re-save the project.

• Deleting an adapter instance deletes all the services included in that configuration.

• When deleting an adapter service, you have the opportunity to save the service’s schema. This is important when another adapter instance is also associated with the same schema.

• If an adapter instance is renamed, the schema associated with that configuration is also renamed, and if another configuration is associated with that same schema, the association will become invalid once the schema is renamed.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

30 | Chapter 3 Adapter Instance Options

If legitimate changes to the database result in error messages while you are trying to save the changes, you may need to run the cleanup script that the adapter creates during the save operation. For more information about these error messages and using the script, see

Using Database Deployment and Cleanup Scripts on page 194

Using Global Variables

The variable substitution mechanism can override global variables predefined in the project in a restricted manner. Predefined variables can be viewed and set in TIBCO

Designer. Variables are specified as

%%VARNAME%%

and cannot contain any white space.

Variable substitution allows you to accomplish the following.

• Substitute string variables specified in the project at startup time.

• Locally define the value for a variable for a specific project. The local value takes precedence over any global value.

• Specify the value for a variable in a properties file. This overrides the project repository and values set in code, but not variables set on the command line.

• Enforce the pre-defined variables listed in

Predefined Global Variables on page 32

Variables can be used anywhere in the configuration and will be replaced by the locally-defined adapter instance.

Variable Specification

The adapter can specify variables:

• In the project during configuration using TIBCO Designer.

• In a properties file.

• In TIBCO Administrator Enterprise Edition when deploying the project.

The values in the properties file or Enterprise Edition take precedence over the values set in the project through TIBCO Designer.

Specifying Variables Using TIBCO Designer

Global variables provide an easy way to set defaults for use throughout your project.

For example, you could assign the value 7474 to the predefined global variable

RvDaemon

You can then use the variable in different sessions in your adapter. If you wish to change the TIBCO Rendezvous daemon for your adapter, you can globally set it to a different value or override it from the command line.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

To Specify Global Variables:

1. In the project panel, select the

Global Variables

tab.

Overview | 31

The project panel displays all currently defined global variables. You have these choices for modifying global variables:

— To assign or change a variable value, triple-click the variable. The variable expands so you can change either the variable name or the variable value. Press Enter when done.

— To add a new global variable group, click the group icon (on the left below the project panel). Specify the name of the group, then press Enter.

— To add a global variable to the list, click the abc

icon below the project panel. A new global variable item is added to the bottom of the list. Type the variable name and, optionally, the value. Press Enter when done.

— To add a global variable to a group, select the desired group icon and click the abc icon below the project panel.

— Click the pencil icon to open the advanced editor where you can add more information to a global variable.

The global variable is now displayed in the global variables list.

2. When you want to use the global variable in the fields of a resource, enter the variable name surrounded by

on both sides.

When the project is deployed and the configured components are run, all occurrences of the global variable name are replaced with the global variable value (unless it was

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

32 | Chapter 3 Adapter Instance Options overridden in a way that had higher precedence). For example,

RvServiceTest

would be replaced with

7800

A number of global variables are predefined. See

Predefined Global Variables

in the next

section for information. You may add definitions of any variables you need to the predefined variables.

Predefined Global Variables

The following table lists and explains the predefined global variables. Some global variables are automatically used within the system when an adapter instance is configured.

Table 4 Predefined Global Variables (Sheet 1 of 2)

Variable

Deployment

Description

Defaults to the TIBCO Designer project name. This value can be any string value. This global variable is used by the system to partially define the subject name defined for a service.

DirLedger

DirTrace

Domain

JmsProviderUrl

JmsSslProviderUrl

RemoteRvDaemon

RvDaemon

RvNetwork

Specifies the path name of the TIBCO Rendezvous certified messaging ledger file. The default is the root installation directory.

Specifies the path name for log file used by the adapter. The default is the root installation directory.

The default value for file-based local projects is

Domain

. The value for server-based projects is the domain to which the project was saved.

Tells applications where the JMS daemon is located. Setting this value mostly makes sense in early stages of a project, when only one JMS daemon is used.

Tells applications where the JMS SSL daemon is located.

TIBCO Rendezvous routing daemon ( rvrd

) to be used. See TIBCO

Administrator Server Configuration Guide for details about setting up a domain using rvrd

TIBCO Rendezvous daemon. Sessions use this daemon to establish communication. The default value is

7500

TIBCO Rendezvous network. This variable need only be set on computers with more than one network interface. If specified, the

TIBCO Rendezvous daemon uses that network for all outbound messages.

In most cases, you can leave the default.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Overview | 33

Table 4 Predefined Global Variables (Sheet 2 of 2)

Variable

RvService

Description

TIBCO Rendezvous service. The TIBCO Rendezvous daemon divides the network into logical partitions. Each transport communicates on a single service. A transport can communicate only on the same service with other transports.

Unless you are using a non-default TIBCO Rendezvous configuration, you should leave the default (7500).

RvaHost

RvaPort

TIBHawkDaemon

TIBHawkNetwork

TIBHawkService

Computer on which the TIBCO Rendezvous agent runs. This variable is only relevant if you are using the TIBCO Rendezvous

Agent ( rva

) instead of the TIBCO Rendezvous daemon, and if you have configured a non-default setup. See TIBCO Rendezvous

Administration for details about specifying the rva parameters.

TCP port where the TIBCO Rendezvous agent (rva) listens for client connection requests. See TIBCO Rendezvous Administration for details about specifying the rva parameters. Defaults to 7501.

TIBCO Rendezvous daemon used in the TIBCO Hawk session.

Specifies which Hawk daemon handles communication for the session. A local daemon is specified by the communications type

(always tcp

) and a socket number. The default configuration uses the local daemon with the TCP socket number 7474.

Specify a remote daemon by inserting its host name or IP address between the tcp

entry and the port number of the daemon parameter, such as tcp:remote_computer:7800.

See the TIBCO Hawk Installation and Configuration manual for details about this parameter.

TIBCO Rendezvous network used by the TIBCO Hawk session.

Specifies which network to use for outbound session communications when a computer is connected to more than one network, and also specifies the multicast groups to use for communication.

See the TIBCO Hawk Installation and Configuration manual for details about this parameter.

TIBCO Rendezvous service used by the TIBCO Hawk session. The

Service parameter specifies which User Datagram Protocol (UDP) service group the TIBCO Rendezvous daemon should use for session communications. The default service port is 7474.

See the TIBCO Hawk Installation and Configuration manual for details about this parameter.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

34 | Chapter 3 Adapter Instance Options

Adapter Instance Tabs

The following tabs are available when configuring an adapter instance.

•

Configuration Tab

•

Design-time Connection Tab

•

Runtime Connection Tab

•

Adapter Services Tab

•

General Tab

•

Logging Tab

•

Startup Tab

•

Monitoring Tab

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Configuration Tab | 35

Configuration Tab

Table 5 Adapter Instance Configuration

Field

Instance Name

Description

This is the name that was specified when creating the adapter configuration.

See

Guidelines for Choosing an Instance Name on page 36 for more information.

Description A short description of the adapter configuration.

Version

You must define the options on the Configuration tab before other options can be

configured. Click Apply to apply the changes before leaving the Configuration tab.

Table

5, Adapter Instance Configuration, on page 35

Message Filter

Show All Tabs

Vendor

The version string indicates the TIBCO ActiveEnterprise (AE) configuration format in which the adapter instance is saved. An adapter instance can be saved in AE 4.0, AE 5.0 or AE fro1 format.

When a new adapter instance is created in TIBCO Designer 5.x, the version string is set to

AE Version 5.1

. When a 4.x adapter instance is opened in Designer

5.x, the

Version

field is set to

AE Version 4.0

• If a 4.x adapter instance is to be run with a 4.x runtime adapter, the instance must be saved with the

Version

field set to

AE Version 4.0

• If you are using TIBCO Designer 5.x to modify 4.x adapter instances, change only features supported by the 4.x. runtime adapter and use the validation utility to verify the instance before deploying the project. Invoke the utility by selecting Project > Validate Project For Deployment in

Designer.

To change versions, click the Change Version button.

Specify a message filter, if you have configured a message filter resource for use with the adapter. The plugin allows you to manipulate incoming and outgoing data before sending it on the network or handing it to the target application. Plugins can be written using the TIBCO Adapter SDK. See the TIBCO Adapter SDK Programmer’s Guide for information about writing a message filter.

Select this box to display additional tabs for configuring advanced options.

Select the database vendor to which the adapter connects. This populates the JDBC

Driver and JDBC URL fields in the Design-time Connection Tab with the appropriate

dat.

In the drop-down list, vendor names enclosed in parenthesis are not supported.

For example Informix and INGRES.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

36 | Chapter 3 Adapter Instance Options

Table 5 Adapter Instance Configuration (Cont’d)

Field

DB2 AS400 Library

Description

(Appears when DB2 AS400 is selected in the Vendor field.) When this option is selected, the adapter automatically creates an asynchronous queue named

TIBADB

on the AS400 machine. Your programs will be created in

TIBCOSRC

in the library specified in the DB2 AS400 Library field.

You must also set the trigger option under the publication service DB2/AS400

Options tab.

Convert Number Data Type to String

Write to Database on Save

(Appears when Oracle is selected in the Vendor field.) When this option is selected, the adapter will use string operation for number data type at runtime.

Select this box if you want to write configuration settings to the database when this project is saved. This is the default mode.

Guidelines for Choosing an Instance Name

• An instance name must use alphanumeric characters. An underscore (_) character can be used. The entire instance name must be less than 80 characters. The space character cannot be used in an instance name.

• An instance name cannot use global variables.

• An instance name must be unique with respect to other adapter instances for the same adapter in the project. The same instance name can be used to name an adapter instance for a different adapter in the same project. For example, an ADB adapter instance named

TEST

and a Siebel adapter instance named

TEST

can coexist in the same project.

• Each instance name must be unique per adapter within a project even if each instance is defined in a different folder. That is, configuring same-named adapter instances in different folders will not make their names unique.

When you create an adapter instance, the palette automatically creates several resources for it. The names of these resources derive from the name of the instance they belong to.

Changing the adapter instance name results in an automatic regeneration of the resources names. If you manually modify any resource name, that particular name will not be automatically regenerated next time your rename the adapter instance.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Design-time Connection Tab | 37

Design-time Connection Tab

You must define the JDBC information and database account options in the Design-time

Connection tab before you can design the adapter instance.

After completing these fields, click the Apply button, then click the Test Connection button to establish a connection to the database. When the connection is successful

message appears, click the OK button. You can now begin design-time configuration of the adapter.

Many of the following fields can use global variables. Click the Global Variables tab in the project panel to add or modify a global variable.

Table 6 Design-time Configuration Parameters

Field

JDBC Driver

JDBC URL

Description

The name and URL of the JDBC driver used during design-time configuration. The following table lists all the supported JDBC drivers and their URLs. For detailed parameter descriptions, see your JDBC driver documentation.

See

Table 7, JDBC Drivers and URLs, on page 38 for the supported JDBC Drivers and

the associated URLs

User Name

Password

Remember Password

The database user that the design-time adapter uses to connect to the database.

The password for the database user.

The next time you open this project, the Password field displays the masked password and the adapter will connect to the database without the user needing to know or enter the password.

If this field is not checked, the password must be entered here each time the project is opened. The password is saved in the project file as the global variable

%%adb.password%%

This field is not used.

Use Design-time Connection

For Runtime

Test Connection Click this button to test the connection using the specified parameters.

Instead of manually entering the following driver and URL values, you can populate these fields using a connection template or previously-stored connection parameters. For more

information, see

Using Connection Settings Templates on page 39

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

38 | Chapter 3 Adapter Instance Options

Table 7 JDBC Drivers and URLs

Database

Oracle

Driver and URL

JDBC Driver: tibcosoftwareinc.jdbc.oracle.OracleDriver

JDBC URL: jdbc:tibcosoftwareinc:oracle:// server_name

: 1521;SID=ORCL

Microsoft SQL

Server

JDBC Driver: tibcosoftwareinc.jdbc.sqlserver.

SQLServerDriver

JDBC URL: jdbc:tibcosoftwareinc:sqlserver:// server_name

:1433;databaseName= database_name

Note: Default port number is 1433.

Sybase

Adaptive

Server

Anywhere

MySQL

JDBC Driver: tibcosoftwareinc.jdbc.sybase.SybaseDriver

JDBC URL: jdbc:tibcosoftwareinc:sybase:// server_name

5000

Note: Specify a database_name

parameter (as shown in the SQL Server description above) if connecting to a database that is not the default database.

JDBC Driver: com.sybase.jdbc2.jdbc.SybDriver

JDBC URL: jdbc:sybase:Tds:localhost:2638/asademo

JDBC Driver: com.mysql.jdbc.Driver

JDBC URL:

jdbc:mysql:// server_name

:3306/ database_name

Teradata

DB2 OS390

DB2 AS400

JDBC Driver: com.teradata.jdbc.TeraDriver

JDBC URL: jdbc:teradata:// server_name

JDBC Driver: tibcosoftwareinc.jdbc.db2.DB2Driver

JDBC URL: jdbc:tibcosoftwareinc:db2:// server_name

: port

; locationName=

DB2_location_name

;packageName= package_name_prefix

JDBC Driver: com.ibm.as400.access.AS400JDBCDriver

JDBC URL: jdbc:as400:// server_IP

;libraries= lib

DB2 UDB

JDBC Driver: tibcosoftwareinc.jdbc.db2.DB2Driver

JDBC URL: jdbc:tibcosoftwareinc:db2:// server_name

50000;databaseName= database_name

;packageName=DEF00

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Design-time Connection Tab | 39

Using Connection Settings Templates

TIBCO ActiveMatrix Adapter for Database provides connection settings templates with

JDBC driver information for each supported database vendor. The templates populate the

JDBC Driver and JDBC URL fields with the default settings as shown above. You then replace the variables with values appropriate for your configuration.

To populate the fields with default values, select ActiveDatabase > Connection templates, then select your database type from the submenu. The following screen sample shows Oracle being selected.

Saving Connection Settings for Reuse

After you have customized the connection settings on this tab for your configuration, you can save them for use in another adapter. You can save as many sets of customized connection parameters as you need. The parameter sets can include the user name and password.

To save a set of connection parameters:

1. Fill in the connection parameters for the adapter.

2. Select ActiveDatabase > Save Connection Settings. The following dialog displays:

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

40 | Chapter 3 Adapter Instance Options

3. Type a name, then click the OK button. The following dialog displays:

4. Click either Yes or No button:

— Yes saves the password in the parameter set. (If the Password field is empty, no password is saved.) When the user selects the parameter set, the Password field will be populated with the current password in clear text, even if the password is not saved in the project file or if it has been obfuscated in the project file.

— No does not save the current password in the parameter set. The user will have to enter it manually.

The connection parameters are saved.

Using Saved Connection Parameters

To use a saved set of connection parameters, select ActiveDatabase > User connections, then select a parameter set from the submenu.

The fields on the

Configuration

and

Connection

tabs are populated with the values stored in the parameter set.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Runtime Connection Tab | 41

Runtime Connection Tab

Table 8 Runtime Connection Tab

Field

ODBC DSN

Description

The name of an ODBC system data source for the database where the source or destination database table resides. The adapter uses this data source to send and receive information. If not specified, the data source name must be given in the adapter’s properties file or on the command line.

User Name

The settings available in the Runtime Connection tab must be configured before you start the runtime adapter.

After configuring these settings, click the Apply button, then click the Test Connection button to establish a connection to the database. When the connection is successful

message appears, click the OK button. The runtime adapter is now configured.

Password

Default Schema

Database Disconnection

Codes

This is the database user that the runtime adapter uses to connect to the database. This field is automatically populated when you select a template as described in

Using

Connection Settings Templates on page 39

. It cannot be changed here.

This is the password for the database user. This field is automatically populated when

you select a template as described in Using Connection Settings Templates on page 39

It cannot be changed here.

This is the schema name of the current user. Usually it is the same as the username, but can be different, for example, when using Microsoft SQL Server. For Teradata database, the Default Schema must be the name of the database you want to connect to.

Specify the database disconnection codes provided by your database. Multiple codes can be entered if each is separated by a semi-colon (;). No spaces are allowed between codes.

To populate this field with the default disconnection codes for your database, click

ActiveDatabase > Connection Templates > database_name.

If disconnection codes are not provided and a database operation fails, the adapter issues a test query to verify whether the database connection is valid. If the connection is not valid, the adapter attempts to reconnect and will shutdown if it cannot reconnect. This approach is database independent, but affects performance because the adapter has to send the query and wait for results.

If database disconnection codes are provided in this field, they are stored in a fatal error code dictionary. When a database operation fails, most database systems return an error code to the adapter. The adapter can look up the returned error code in the fatal error code dictionary and determine if the database connection is lost and respond accordingly. This is more efficient then sending the test query.

When using ODBC native driver to reconnect on DB2/UDB, add the database disconnection code

-30081

manually. For Oracle database, the disconnection code is

30046

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

42 | Chapter 3 Adapter Instance Options

Table 8 Runtime Connection Tab (Cont’d)

Field

Maximum Number of

Reconnect Attempts

Description

The total number of reconnection attempts to make after the service has been suspended.

When this number is reached, the runtime adapter or adapter service will be stopped.

A value of -1 means reconnection attempts will continue indefinitely.

Number of Reconnect

Attempts Before Suspending

Impacted Service(s)

Specify the number of reconnection attempts to make before suspending the service.

This value is 1 and cannot be changed.

Specify the time interval (in milliseconds) to elapse between each reconnection attempt. Interval between Reconnect

Attempts (milliseconds)

Adapter Termination Criteria

(after max number of reconnect attempts)

Test Connection

The adapter and all of its services is stopped if any one of its services has been unable to re-establish connection after the Maximum Number of Reconnect Attempts has been made. This option cannot be changed.

This option is not used.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Adapter Services Tab | 43

Adapter Services Tab

You are not required to change any settings in the Adapter Services tab. The settings available in this tab affect all publishers, subscribers, and request-response services defined for the adapter, unless overridden by the individual service configurations as described in

Chapter 4, Adapter Service Options

Click the Apply button to apply the changes before leaving this tab.

All Publication Services

The settings available in the All Publication Services panel apply to all Publication services in the adapter.

Table 9 Publication Service Configuration Options

Field

Number of Publication

Service Threads

Description

This field is currently disabled. Threads are allocated on demand. For example, if the adapter instance has only a publication service configured, a publication thread and database connection will be created automatically.

Use Polling Batch Size

Polling Interval

Check this box to activate Polling Batch Size (Maximum Rows). If Polling Batch Size is not active, the adapter picks up all new rows and then tries to send all of them before returning to the event loop. This could affect adapter performance in a high volume environment.

Type a specific polling interval in milliseconds. This is how often an adapter with a publication service checks the publishing table for new rows. The default is 5000, or once every five seconds. Note that if you specify a polling interval of 0, it is assumed that you are using an alerter to manage polling.

Polling Batch Size

(Maximum Rows)

(Only active when Use Polling Batch Size is checked) The maximum number of messages that are picked up per polling interval. The adapter returns to the event loop when it is finished sending those messages. Using this option helps process TIBCO

Rendezvous events in an efficient manner. For example, when polling a large number of rows, the adapter works best if a fixed number of rows is specified in this field.

Batch Publish Status Updates (Only active when Use Polling Batch Size is checked. Do not use this option when messages are published using a parameterized subject name.)

Check this box to optimize publishing performance by batching message status updates to the publishing table.

If an adapter stops before a batch update is performed, the status column is not updated.

As a result, duplicate messages may be published when the adapter is restarted.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

44 | Chapter 3 Adapter Instance Options

Table 9 Publication Service Configuration Options (Cont’d)

Field Description

Publisher Batch Confirm Size (Applies only to adapters with a publication service that uses certified message delivery.

Do not use this option when messages are published using a parameterized subject name.)

The number of message status updates to include in a single batch.

Entering a value in this field optimizes performance. However, if an adapter stops before a batch update is performed, the status column is not updated. As a result, messages that were successfully published might still have a status of P (pending) in the publishing table when the adapter is restarted. In this case, the ledger file contains the correct status information. Smaller values in this field decrease this risk.

Publisher Batch Confirm

Timeout

Publish Child Data

Polling Commit for DB2

(Applies only to publisher adapters with publications that use certified message delivery.

Do not use this option when messages are published using a parameterized subject name.)

The number of milliseconds to wait before updating the status column. After this interval, an update is performed even if the batch size value is not reached. The default value is 10000 (10 seconds). A value of 0 means that no timeout interval is used.

If an adapter instance stops before a batch update is performed, the status column is not updated. As a result, messages that were successfully published might still have a status of P (pending) in the publishing table when the adapter is restarted. In this case, the ledger file contains the correct status information. Smaller interval values decrease this risk.

This is selected by default. When selected, the parent row and all related child rows is published when a parent row is updated. Upon receipt of such a message, a subscriber adapter updates the parent row and then updates all the child rows with the data that was received in the message.

Any changes to the child tables without a change in the parent table will not be processed. The adapter monitors only the parent table for publishing.

The adapter updates the child rows by deleting all the related child rows, then inserting child rows again based on the data in the received message. For information on adding related tables for a publisher adapter, see

Adding Child Tables on page 65 . For

information on adding related tables for a subscriber adapter, see

Child Table Mappings

Tab on page 80 .

Select to enable the adapter publisher to do a commit after selecting query for DB2.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Adapter Services Tab | 45

All Subscription Services

The settings available in the All Subscription Services panel apply to all subscription services in the adapter.

Table 10 Subscription Service Configuration Options

Field

Number of Subscription

Service Threads

Description

This field is currently disabled. Threads are allocated on demand. For example, if the adapter instance has only a subscription service configured, a subscription thread and database connection will be created automatically.

Subscriber Batch Commit

Size

Subscriber Batch Commit

Timeout (milliseconds)

The number of messages to batch before invoking a commit operation. The default value is 0.

Subscriber Batch Commit option is not supported with RVCMQ Quality of Service. The

RVCMQ scheduler requires a message to be confirmed before dispatching the next message, which prevents the adapter from operating in batch mode.

Specify an interval (in milliseconds) that can expire before confirmation messages regarding successful insertion into the exception table are sent back to the publisher. The default is 1.

The batch commit feature does not commit all received messages if the adapter instance terminates before the batch commit value or time-out value is met.

When using RVCMQ, subscriber batch commit will timeout after each operation

(insert/update/delete) when batch commit size>1.

Subscriber Bulk Insert Size

Rendezvous Maximum

Queue Size

Use Exception Table

All incoming messages to insert are stored until this size is reached. Then, a bulk insert operation is performed on the destination table. This number must be less than or equal to the value in Subscriber Batch Commit Size. The default value is 1.

Maximum number of messages to allow in the TIBCO Rendezvous event queue. The default value is 0, which means no limit is placed on event queue size. Use this option to prevent a subscriber’s memory from overflowing if the publisher is too fast.

Select this box to use an exception table. The exception table is defined when you create a subscription service.

Considerations when using the

Subscriber Bulk Insert Size parameter:

Note the following considerations:

• If any individual messages greater than 32K are published, bulk insert is automatically turned off.

• If an update statement is published while messages are being batched, the bulk insert is performed regardless of whether the size value has been reached. After records have been inserted, the update operation is performed.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

46 | Chapter 3 Adapter Instance Options

• Do not use this option if LONG, LONG RAW, image, or variable-length BINARY type records are published. These records cannot be bulk inserted into a destination table.

All Request-response Services

The settings available in the All Request-response Services panel apply to all request-response services in the adapter, unless the individual service is configured differently.

Table 11 Request-response Service Configuration Options

Field

Number of Request-Response

Service Threads

Description

Indicate the number of database request-response threads to use. Valid values are from 1 through n. Each thread has a separate connection to the database. Specifying multiple threads allows you to load balance incoming RPC requests.

Request Response max Rows Specify the maximum number of rows to fetch. This can be used limit the memory usage of the adapter. The unfetched rows will be ignored by the adapter.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

General Tab | 47

General Tab

Table 12 General Configuration Options

Field Description

Termination Subject or Topic A message sent on this subject (if TIBCO Rendezvous is the transport) or topic (if JMS is the transport) stops the adapter.

The default termination subject or topic for a project is:

%%Domain%%.%%Deployment%%.adb.%%InstanceId%%.exit

The termination subject for a 4.0 project is shown below. Do not change it.

_ADB.%%InstanceId%%.TERMINATE

See TIBCO Rendezvous Concepts for information about specifying subject names. See the TIBCO Enterprise Message Service User’s Guide for information about publishing on a topic.

JMS Destination Prefix

The General tab allows you to set a termination subject or topic and specify the encoding type, debug level, and verbose mode. Note that the adapter should communicate only with other applications that support the same code pages or Unicode.

Click the Apply button to apply the changes before leaving the General tab.

Adapter Encoding

Specify this prefix if you are using the JMS transport and have selected the

Use Separate

Service Thread

option for a subscription service. The destination prefix is the subject used by the single-threaded subscription service.

By default, the adapter uses a dynamic destination that is generated using the Domain and Deployment global variables, and the adapter instance name. If you use this default dynamic destination, make sure the values for Domain and Deployment are not empty.

You can override the default dynamic destination by specifying the static destination in this field. The static destination must be defined with write permissions on the TIBCO

Enterprise Message Service server before it can be used by the runtime adapter.

Select the encoding from the drop down menu. The adapter may support other encodings

not shown. See Chapter 10, Setting Encoding Options

, for a list of additional encodings that can be typed into this field.

The palette does not validate encoding values that you type into the field. The runtime adapter will throw an error if the encoding value you type is not supported.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

48 | Chapter 3 Adapter Instance Options

Table 12 General Configuration Options (Cont’d)

Field

Debug Level

Description

This field is valid only when the Debug logging option is selected, as described in

Logging Tab on page 49 .

Select how much debugging output to provide at the console window or log file location specified in the

Log File field. The options are:

No debug information

Only SQL commands executed with the database

Only the ODBC data source for each SQL command

All debug information

Generate Verbose Output

Generate Payload on Error

Script File

Alerter Name

This field is valid only when the Information logging option is selected, as described in

Logging Tab on page 49 .

Check this box to include verbose output (all available information) at the console window or log file location specified in the

Log File

field.

Allows the adapter to log the payload information under Error role when an error occurs.

Allows you to change the location where the SQL script file is written.

The name of the alerter service register in the database.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Logging Tab | 49

Logging Tab

Table 13 Logging Configuration Options

Field

Use Advanced Logging

Description

When this box is clear, the standard log file is used. This is the default. Fill out the remaining fields on this tab. You do not need to read the rest of this field description.

When this box is selected, you can set two standard output destinations (sinks) for trace messages and set the tracing level for the roles selected. The following sink types are available:

• File

• STDIO

• Hawk

• Network

See

Creating Log Sinks on page 51

for more information.

Log to Standard I/O

Use the settings available in the Logging tab to configure a log file or log sinks, including which types of trace messages you want logged and where they are sent. Click the Apply button to apply the changes before leaving the Logging tab.

Log File

Log Info/ Debug/ Warning/

Error Messages

When selected, trace messages are displayed in the command prompt window where the adapter is started. This is the same as creating a STDIO sink. When not selected, trace messages do not display in the window.

Specify the name of the log file to which trace messages are written. This is the same as creating a file sink. Global variables can be used to specify the location of the log file.

See

Using Global Variables on page 30 for more information.

Type the name and file system path, or click the Browse button and select an existing log file. If no file name is specified, trace information is not written to a file.

Select the types of trace messages you want logged.

By default all error, warning, debug and information messages are printed in the console window in which the adapter was started. Alternatively, you can specify a log file and path to redirect trace output to a log file located anywhere on your file system. The default log file name is

%%DirTrace%%/%%Deployment%%.%%InstanceId%%.log

, and is saved in the same directory where your project (repository instance) is stored.

Most errors received by the adapter are logged. The only errors that might not be logged are any TIBCO Rendezvous or TIBCO Adapter SDK errors that appear at startup time before tracing can be initialized.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

50 | Chapter 3 Adapter Instance Options

Logging trace messages is helpful for troubleshooting. There are four levels of trace messages that you can log: Information, Warning, Debug, and Error. Trace messages are

described and listed in

Appendix B, Trace Messages

Logging affects system performance. It is recommended that you use logging only as needed.

Debug messages should not be logged unless requested by the TIBCO Product Support

Group. This option writes a lot of information to the log file and significantly reduces the speed of the adapter.

By default, the Use Advanced Logging checkbox is not checked. In this mode, you configure a standard log file using the fields on this tab, as shown in the example below.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Logging Tab | 51

When you check the Use Advanced Logging checkbox, you configure log sinks using icons in the TIBCO Designer project panel. This gives you complete control on selecting the destinations and associating desired roles with each of the destinations.

Creating Log Sinks

1. Check the Use Advanced Logging checkbox.

2. Click the Apply button.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

52 | Chapter 3 Adapter Instance Options

3. In the TIBCO Designer project panel, expand the Log Sinks folder under the

Advanced folder.

4. Select an existing log sink or create a new one:

— Select either the fileSink or stdioSink icon.

— Create a new log sink by dragging and dropping the

Generic log sink

icon from the palette panel into the design panel, then assign a type to it from the drop down menu in the configuration panel. Click the Apply button.

5. With the desired log sink icon selected in the design panel, fill in the fields in the configuration panel. You can also change the name and enter a description for each sink by right-clicking on the sink icon in the project panel.

— File sink logs the trace messages to a file. Specify the file limit, file count, and the option to append or overwrite. By default, the file limit is 30000 bytes, the file count is 3, and the mode is append.

— STDIO sink sends trace messages to stdout

or stderr

. By default, stdout

is selected.

— Hawk sink sends each trace message to TIBCO Hawk Monitor or TIBCO Hawk

Display using the Hawk session, which is created by the adapter for monitoring

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Logging Tab | 53 purposes. Specify the

MicroAgent Name

. (For details on Hawk sessions, see

Using

Global Variables on page 30

— Network sink publishes each trace message on TIBCO Rendezvous. Specify the session and the subject on which the trace messages needs to be published.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

54 | Chapter 3 Adapter Instance Options

Startup Tab

Metadata Search URL

Do not change the settings in the Startup tab. This tab displays the default startup behavior.

Table 14 Startup Options

Field

Show Startup Banner

Description

The startup banner displays the runtime adapter version, the infrastructure version on which the adapter is built, and copyright information in the console window when the adapter is started.

This field is predefined and cannot be changed. It specifies the location where the adapter searches for base schemas. All schemas that have been defined and saved at this location are loaded at startup.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Monitoring Tab | 55

Monitoring Tab

The settings available in the Monitoring tab do not need to be configured unless TIBCO

Hawk is installed.

You can use microagents to supplement the monitoring information provided by the standard logging capability. Examples of supplemental information that you can obtain with microagents include the repository URL and the command line arguments used to start the adapter.

Click the Apply button to apply the changes before leaving the Monitoring tab.

service that determines how messages are sent. See Quality of Service on page 58 for a description

Chapter 11, Monitoring the Adapter, on page 233

for a list of all supported microagents.

Many of the following fields can use global variables. Click the Global Variables tab in the project panel to add or modify a global variable.

Table 15 Monitoring Configuration Options

Field

Enable Standard Microagent

Description

Allows you to turn on or off the standard TIBCO Hawk Microagent. Clicking the globe icon changes the checkbox to a text field, allowing you to specify a global variable.

When this is a text field, turn the microagent on and off by entering true

or false

Standard Microagent Name This is the name for the standard microagent that will be registered with the TIBCO

Hawk system. In most cases the default value is used,

COM.TIBCO.ADAPTER.adb.%%deployment%%.%%InstanceId%%

The value for the

%%deployment%%

global variable can be set or modified by selecting the session icon and then clicking the

Global Variables

tab in the project panel.

The

%%InstanceId%%

variable does not need to be set because it is automatically set at run time by the runtime adapter.

Standard Microagent Timeout Specifies the amount of time the Hawk Agent should wait for HMA method invocations to complete before timing them out. The default is 10000 milliseconds. Normally there is no need to change this value, however, on machines under extreme stress where method invocations are timing out, this new option allows the timeout value to be increased.

Enable Class Microagent

Class Microagent Name

Allows you to turn on or off the instance-specific or class-specific standard TIBCO

Hawk Microagent. You can configure how the class microagent is turned on and off in this field: clicking the globe icon changes the checkbox to a a true/false text field.

This is the name for the class microagent that will be registered with the TIBCO Hawk system. In most cases the default value is used,

COM.TIBCO.adb.%%deployment%%.%%InstanceId%%

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

56 | Chapter 3 Adapter Instance Options

Table 15 Monitoring Configuration Options (Cont’d)

Field

Class Microagent Timeout

Description

Specifies the amount of time the Hawk Agent should wait for HMA method invocations to complete before timing them out. The default is 10000 milliseconds. Normally there is no need to change this value, however, on machines under extreme stress where method invocations are timing out, this new option allows the timeout value to be increased.

Default Microagent Session This field is predefined and cannot be changed. The session is automatically generated by TIBCO Designer and will be used by the standard, class, and custom microagents.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Chapter 4

Adapter Service Options

After configuring an adapter instance, select one or more adapter services for the instance.

All configuration tasks are performed in TIBCO Designer.

| 57

Topics

•

Overview, page 58

•

Adding Child Tables, page 65

•

Publication Service Tabs, page 61

•

Subscription Service Tabs, page 77

•

Request-response Service Tabs, page 85

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

58 | Chapter 4 Adapter Service Options

Overview

The transport type (Rendezvous or JMS) you select for the runtime adapter determines which quality of service, delivery mode, and wire format the service can use. Only options that are compatible with a service’s transport type will be available for selection.

Quality of service, delivery mode, and wire formats are described below.

Quality of Service

This is the level of service that determines how messages are sent.

Possible values are:

• Reliable

(TIBCO Rendezvous transport type only) Reliable message delivery. Ensures that each multicast or broadcast message is received as long as the physical network and packet recipients are working, and that the loss of a message is detected. This choice can compensate for brief network failures because it can retransmit a message on request if the first attempt failed. This choice is appropriate when message delivery is expected but some loss can be tolerated. Messages are received without explicit confirmation.

• Certified

(TIBCO Rendezvous transport type only) Certified message delivery. Offers stronger assurances of message receipt, along with tighter control, greater flexibility and fine-grained reporting. Guarantees that every certified message reaches its intended recipient in the order sent. The message can be sent across network boundaries, and if a network fails, delivery attempts continue until delivery succeeds or until the message's time limit expires.

If certified message delivery is used, data is stored in a ledger file. The size of the ledger depends on several factors, the most important of which is the retention rate of stored data. That is, the ledger grows fastest in response to the cumulative length of undeliverable messages. You must ensure that sufficient disk space is available for the expected size of the ledger.

• Distributed

Queue

(TIBCO Rendezvous transport type only) A distributed queue is a group of cooperating transport objects, each in a separate process. To obtain load balancing among servers, the adapter uses distributed queues for one-of-n delivery of messages to a group of servers. Each member of a distributed queue listens for the same subject using the TIBCO Rendezvous

Distributed Queue

listener objects. Even though many

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Overview | 59 members listen for each inbound message (or task), only one member processes the message. For details on distributed queues, see TIBCO Rendezvous Concepts.

See

Load Balancing Across Adapter Instances on page 134

and TIBCO

ActiveEnterprise Concepts for more information.

• Transactional

This option is no longer supported. The option is only included for backward compatibility.

Delivery Mode

(JMS transport type only) The method of delivery for a JMS message. The semantics for these fields are somewhat more complex than the explanation given here. See TIBCO

Enterprise Message Service User’s Guide for more information.

• Persistent

In general, a message marked persistent will be available to a JMS client even if the

TIBCO Enterprise Message Service server goes down. Persistent messages are held in secondary storage in the server and have guaranteed delivery when sent to a topic that has durable subscribers. (If a topic has no durable subscribers, there are no subscribers that need messages resent in the event of a server failure and therefore messages do not need to be saved.) Performance is improved because disk I/O is not required.

• Non-Persistent

A message marked non persistent will not be available to a JMS client if the TIBCO

Enterprise Message Service server goes down. These messages are never written to persistent storage.

• Durable

(Topic only) Specify the subscriber as durable subscriber of the topic. Messages for durable subscriptions are stored on the server as long as durable subscribers exist for the topic.

• Non-Durable

(Topic only) Specify the subscriber as non-durable subscriber of a topic. Non-durable subscribers only receive messages when they are active. If messages arrive on the topic when the subscriber is not available, the subscriber does not receive those messages.

Wire Formats

Services must use the same wire format to exchange data.

• Rendezvous Message (TIBCO Rendezvous transport type only)

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

60 | Chapter 4 Adapter Service Options

A self-describing wire format used by TIBCO Rendezvous applications. Control information for validation is not sent in the message. If you use this format, the adapter is compatible with adapters not developed with TIBCO Adapter SDK.

• XML Message (TIBCO Rendezvous and JMS transport types)

The

XML Message

wire format conforms to specifically constructed and fully compliant

XML Schema (XSD) based on the existing definition of the TIBCO ActiveEnterprise schema.

• ActiveEnterprise Message (TIBCO Rendezvous transport type only)

An externally-described XML wire format supported by the TIBCO Adapter SDK.

Control information for validation is sent in the message. If no control information is included, an exception is returned to the subscriber. TIBCO ActiveEnterprise standard wire format provides class information and packing rules for the TIBCO Adapter

SDK set of data types. This format allows TIBCO ActiveEnterprise components to perform extra validation on messages sent or received.

See TIBCO Adapter SDK Programmer’s Guide for details about the control information generated and sent with TIBCO ActiveEnterprise messages.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Publication Service Tabs | 61

Publication Service Tabs

When running as a publisher, the adapter extracts data from the changed rows from database tables and publishes them on appropriate subject names.

You can configure parameters under the following tabs:

•

Configuration Tab on page 61

•

Tables Tab on page 62

•

Child Table Order By Tab on page 70

•

DB2/OS390 Tab on page 68

•

DB2/AS400 Tab on page 69

•

Publisher Options Tab on page 72

•

Advanced Tab on page 75

Configuration Tab

The wire format for the publication and subscription services must be the same, otherwise an error will occur.

Table 16 Publication Service: Configuration Tab

Field

Name

Description

You can use the default name or replace it with a name of your choice.

Transport Type Select the transport type (JMS or TIBCO Rendezvous) to be used by the runtime adapter. This selection determines which options appear in the rest of the Configuration tab.

The transport can be configured to use a trusted store and identity resource for use in SSL (Secure

Sockets Layer) configurations. TIBCO Rendezvous sessions and JMS topics have an SSL configuration field which uses a dialog to perform SSL configuration.

To enable and configure SSL, in the Project panel, expand the Advanced folder, then expand the

Sessions folder. Select the TIBCO Rendezvous session or JMS topic and click Use SSL?. The SSL configuration options are explained in the online help associated with the session dialog. Click the question mark to display the online help.

Quality of Service (Only available when TIBCO Rendezvous is selected as the transport type) Select the level of

of these options.

• Reliable

• Certified

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

62 | Chapter 4 Adapter Service Options

Table 16 Publication Service: Configuration Tab (Cont’d)

Field

Wire Format

Description

The wire format in which data will be sent. Note that the wire format for both the publisher and subscriber must be the same, otherwise an error will occur. See

Wire Formats on page 59 for a

description of these formats.

• ActiveEnterprise Message (TIBCO Rendezvous transport type only)

• Rendezvous Message (TIBCO Rendezvous transport type only)

• XML Message

Connection

Factory Type

Delivery Mode

(Only available when JMS is selected as the transport type) Connection Factory objects create JMS connections for sending and receiving messages. Available choices are:

• Topic

Publish-subscribe messaging. A message published to a topic is broadcast to one or more subscribers. All messages published to the topic are received by all services that have subscribed to the topic.

• Queue

Point-to-point messaging. A message sent to a queue is consumed by one and only one receiver.

Each message has only one receiver though multiple receivers may connect to the queue. The first receiver to access the queue gets the message. The other receivers do not.

(Only available when JMS is selected as the transport type) The delivery mode for each message sending operation. See

Delivery Mode on page 59

for a description of each mode.

• Persistent

• Non-persistent

Note the following restrictions:

• A service name must use alphanumeric characters. An underscore (_) character can be used. The entire instance name must be less than 80 characters. The space character cannot be used in an instance name.

• A service name cannot use global variables.

Tables Tab

You must set publisher table options before configuring other publisher options.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Publication Service Tabs | 63

Source table names can be qualified with a database user name. To access tables in other schemas, the database user specified in the

Design-time Connection Tab on page 37

tab

must have the proper set of permissions granted. This is described in

Referencing an

External Schema on page 64

If a primary key is not defined for a table, the update and delete triggers will not be

generated for the table. To define a primary key for the table, select the

User Key

column in a table row. The update and delete triggers will then be defined.

Icons

• Add Table — Click to display a dialog box that list tables available to the database user specified in the adapter Connection tab. Select the source table to publish from when data is inserted into it.

• Add Child Table — Displays a dialog box from which a secondary table can be added to the configuration.

• Add Table from Other Schema — Allows you to add a table from a different schema than the current database user schema. For instructions on granting access privileges to an external schema, see

Referencing an External Schema on page 64

You can use this icon to add different schema at the parent and child levels.

• Remove Table — Deletes the selected table from the list.

• Re-find Tables from Database — Causes TIBCO Designer to refresh stored table schema information by retrieving new information from the database.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

64 | Chapter 4 Adapter Service Options

• Load Table Schema from Database — Allows you to load a database table schema, convert it into a TIBCO ActiveEnterprise schema, and store it in the schema folder of an instance.

Allow Key Columns Only

When this box is checked, child columns are joined only to a key column. When unchecked, child columns can be joined to any column.

Select/Deselect All Columns to Publish

When this box is checked, all of the boxes in the Use column are checked, so all columns in the tables are published. Unchecking this box unselects all of the columns. You can also individually check and uncheck the Use? checkboxes.

Table 17 Publication Service Tables Tab

Field

Tables and

Columns

Description

The loaded tables and columns.

indicates a table or child table.

indicates a normal column.

indicates a

User Key column.

Type

AE Type

User Key

Update Trigger

Use?

Join To

The primitive type.

The primitive type mapped to an TIBCO ActiveEnterprise type.

Click to define the column as a user key.

Check the box to fire a trigger when an UPDATE statement changes a value in the column.

Click to publish this column when data is changed.

The name of a parent table column to join to for parent-child relationships.

Referencing an External Schema

To reference an external schema in TIBCO Designer, the default schema must have the proper access privileges. These are set in a command line. In the following syntax, adb_schema

refers to the default schema in create_user.sql

For Oracle, log in as system

and grant create any trigger

and drop any trigger

permissions to the default schema. For example: grant create any trigger to adb_schema grant drop any trigger to adb_schema

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Publication Service Tabs | 65

In addition, Oracle and Sybase users must have permission to

SELECT

from a source table in an external schema. If table relationships are used,

SELECT

permission is required for both parent and child tables.

SELECT

INSERT

UPDATE

, and

DELETE

permissions are required for accessing a destination table in an external schema.

For Sybase, execute the following before creating catalog tables for the external schema: sp_role "grant", sa_role, adb_schema

For SQL Server 7.0 and 2000, log in as sa

and then execute the following before creating catalog tables for the external schema: use master

EXEC sp_addsrvrolemember ' adb_schema

', 'sysadmin'

For DB2 on AS400 you can avoid table access problems by changing the ActiveDatabase user authority to *ALLOBJ.

Adding Child Tables

This section describes how to add a related child table definition for publishing data.

Data models typically contain tables that share column data through a relationship. You can configure a publishing table to include related data from another table when it publishes. Data from the related table is not copied into the publishing table, but is fetched by reference.

When rows are inserted into the publishing table, a message that includes data from the source table and related (child) table is published. On the subscriber side, a corresponding table with the same columns as the child table associated with the publishing table must be specified.

Adding child tables requires two separate procedures, one for the publisher adapter and another for the subscriber. First, you add child tables for the source table, then you add child tables for the destination table.

The database schema must be the same for all tables, but the table names can be different.

If the child table associated with the publishing table and the child table associated with the destination table have different names, you must set a mapping between the child tables.

The following restrictions apply to parent and child tables:

• The child table in the source database and child table in the destination database must have the same columns.

• When parent-child relationships are defined, a subscriber adapter must use the same repository as the publisher adapter.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

66 | Chapter 4 Adapter Service Options

When you add a child table, TIBCO Designer creates a class object in the repository for the child table, and an association object for the relationship.

To enable publishing child table related data, the publisher adapter properties file must have the adb.publishChildData

option set to on

After adding child tables for a subscriber adapter, you create mappings between child tables on the publisher side and child tables on the subscriber side. For instructions, see

Child Table Mappings Tab on page 80

To add child tables for parent-child relationships, do the following in the Publication

Service

Tables Tab

1. Click the name of the parent table to select it.

2. Click the Add Child Table icon. The Add Table dialog displays.

3. Select the related child table from the list and click the OK button.

4. Repeat the above steps to add more child tables.

When all of the child tables are added, you then designate a foreign key column as a key in each child table so that a relationship to the parent table can be defined.

5. Click the User Key checkbox for the foreign key column in the child table to select it.

A key icon displays next to the column name.

You must also specify the relationship between the primary column in the parent table and the foreign key column in the child table.

6. Click in the

Join To

field for the child table column, and select the name of the parent table primary key column from the drop-down list.

7. Click the Apply button.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Publication Service Tabs | 67

In the following example, a publication service that publishes newly inserted rows into the

source table is created.

Publisher Options Tab on page 72

explains how to configure the

publisher adapter to publish data by value or by reference.

In the following example, a subscription is created such that received data will be inserted into the

SUB_ORDER_DETAILS

destination table. All three columns of the destination table are configured to receive data.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

68 | Chapter 4 Adapter Service Options

The following example shows a child table mapped. The left column (

Subscriber Child Table

Name

) contains the subscriber child table and the right column (

Publisher Child Table Name

) contains the publisher child table.

DB2/OS390 Tab

This tab appears when the Vendor field in the Adapter Instance

Configuration Tab

is set to

DB2 OS390

When the DB2 load utility loads rows to the source table, it does not activate the table’s

INSERT triggers. Loaded data is not published.

Table 18 Publication Service DB2/OS390 Tab

Field

Database Name

Description

Enter the name of the database that you want to put your publisher table in.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Publication Service Tabs | 69

Table 18 Publication Service DB2/OS390 Tab (Cont’d)

Field

Table Space

Name

Description

Enter the name of the table space where the publisher table is located.

Storage Group Optional. Enter the designator of the storage group that will hold the publisher table indexes.

Buffer Pool

Index Suffix

Trigger Suffix

Optional. Enter the name of the buffer pool to be used for indexes.

Enter a suffix of your choice, up to 13 characters, that the adapter will append to each of the indexes

(

IDX1_

IDX2_

, and

IDX3_

Enter a suffix of your choice, up to 5 characters, that adapter software will append to each of the triggers (

, and

DB2/AS400 Tab

This tab appears when the Vendor field in the Adapter Instance Configuration Tab is set to

DB2 AS400.

Trigger Option

• Synchronous (deprecated) — The trigger is written in RPG. When copying from the source table to the publishing table, the prompt is not returned until all data is written.

• Asynchronous — When copying from the source table, data is inserted into a data queue and then inserted into the publishing table asynchronously. The prompt is not blocked, so you can continue working while data is inserted into the publishing table.

Specify values for the following options:

— Number of DataQueue Listeners: The number of prestarted listener jobs.

— Listener Job Queue: The name of the queue on the AS/400 machine where the listener jobs are submitted.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

70 | Chapter 4 Adapter Service Options

If you select Asynchronous, you must go to the adapter’s Design-time Connection tab and add

;transaction isolation level=none

to the end of the JDBC URL field. For example:

• SQL — The trigger is written in SQL. When copying from the source table to the publishing table, the prompt is not returned until all data is written.

Sybase Options

This tab appears when the Vendor field in the Adapter Instance Configuration Tab is set to

Sybase.

Check the Overwrite Triggers? checkbox to delete and re-create existing triggers of the publishing table.

Child Table Order By Tab

This tab allows you to specify the column(s) of an Order By Clause used for each children table queries. The adapter will return the child table result set in a particular sequence.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Click on a child table name and click the Select Column button.

Publication Service Tabs | 71

The Select Child Table Order By Columns dialog box appears.

Select the column(s) for the Order By Clause from the left panel and click the Apply button. Use the Up and Down buttons to arrange the column order by sequence. To sort in descending value, select the check box next to the column name.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

72 | Chapter 4 Adapter Service Options

Publisher Options Tab

When you add a new publishing table, a new entry is inserted into the repository for the publisher adapter. The entry includes the name of a publishing table along with a sequence, stored procedure, and trigger. A class object for the publication is created in the repository.

Table 19 Publication Service DB2/AS400 Options Tab

Field

Storage Mode

Description

For each publisher service, you must specify a Storage Mode: Publish by Value or Publish by

Reference. See Publish by Value on page 73

and

Publish by Reference on page 74 for more

information.

• Publish by Value copies all specified columns in the source table to the publishing table.

• Publish by Reference copies only key column values to the publishing table. If no key column is defined in the database, a substitute non-key column must be defined to publish by reference.

Publishing Table

Update Mode

Enable Loop

Detection

Name of the database table used to store a copy of data to be published. The table name can be qualified using the schema.table_name format. The publishing table cannot contain any user-created columns where the column name starts with

ADB_

. These characters are reserved for use by the adapter.

A common practice is to use the publishing table name prefixed by

. For example, if your source table is

MY_ORDER

, its publishing table should be named

P_MY_ORDER

A publishing table name must be less than 64 characters.

Select the method by which tables are updated.

Update updates a row in the destination table only if the row exists.

Upsert updates a row in the destination table if the row exists. If no such row exists, it performs an insert.

Select to enable loop detection and prevent an infinite loop from occurring when the publishing and destination table are the same table. Loop detection is disabled for DB2 on z/OS because of DB2 on z/OS feature limitations.

Do Not Generate

Triggers

Use Alerter

Enable Group

Messaging

Group Size

Select to prevent the generation of triggers. Although this option is not recommended, it allows you to manually manage the insertion of data into the publishing table.

Select to use the alerter. This option appears only if you are using an Oracle database. See Chapter 6,

Using the Alerter, on page 97

for details.

Select to use group messaging. Note that Rendezvous message wire format does not apply for group message.

Appears only when the Enable Group Messaging is checked. Specify the number of rows to publish in a single message.

Global variables are acceptable.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Publication Service Tabs | 73

Table 19 Publication Service DB2/AS400 Options Tab (Cont’d)

Field

Enable Load

Balancing

Description

Check to use load balancing which enables multiple publisher endpoints to poll and publish changes of the same source (publisher) table. Set batch polling size before selecting this option.

Mutex Name Appears only when the Enable Load Balancing checkbox is checked. Specify the name for the mutex table.

Publish by Value

With Publish by Value, all specified columns in the source table are copied to the publishing table. Publishing by value is fast, but does not support some data types, for example Oracle LONG and LONG RAW.

Note the following restrictions on publishing tables when you publish by value:

• Publishing tables cannot contain columns with LONG data types. If you have a source table that contains a column with a LONG data type, that column cannot be specified for inclusion in the publishing table. This is because the trigger generated by the palette cannot to the LONG column via the

:new

construct.

This is an Oracle restriction documented in the Oracle SQL Reference manual. The problem is not detected by Oracle during trigger creation. However, when the trigger fires and it attempts to copy the LONG column value to the publishing table, the database connection will hang for some time and then eventually terminate.

• If you define parent-child relationships between tables, the publishing table that is created for a parent table should not contain a column with a LONG data type.

However, a child table can contain a column with a LONG data type. This is because data on child table rows is not copied using the

:new

construct.

• LONG RAW data is not allowed in the publishing table.

These restrictions do not apply to publishing tables when you publish by reference and

LONG or LONG RAW are non-key types.

In the following example, the publishing table

P_CUSTOMER

is created for the source table,

CUSTOMER

. When

CUSTOMER

is updated, the new data will be copied to

P_CUSTOMER

. The adapter will poll

P_CUSTOMER

and publish the new data.

In this example, loop detection is enabled. If a subscription exists that uses the same subject and

CUSTOMER

as the destination table, any changes to

CUSTOMER

will not be published repeatedly.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

74 | Chapter 4 Adapter Service Options

Publish by Reference

With Publish by Reference, only key column values are copied to the publishing table. The publish by reference feature allows you to publish data directly from the source table without first copying the data from the source table to a publishing table. A trigger, stored procedure, and publishing table are created, but the publishing table contains the necessary adapter fields and only the key fields of the source table. For more information, see

Start or Stop the Adapter on page 94

The advantage of publishing by reference is that the data to be published is stored just once. Also, data types such as Oracle LONG and LONG RAW are supported for publishing by reference.

A key column or substitute key column is required when publishing by reference, since the publishing table contains only key values. If no column is specified, the publication is not added.

To use a view or other database object as the source table, you can configure the adapter to publish by reference object, where key columns are stored in the publishing table and data to publish is selected from the reference object. For details, see

Publishing by Reference

Object on page 171

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Publication Service Tabs | 75

In the following example, the publisher adapter is configured to publish from the

P_CUSTOMER

table with a key field

CUST_ID

. The publishing table is created with the necessary fields and the

CUST_ID

field. When a row in the

P_CUSTOMER

table is modified, the trigger fires, populating fields and copying the

CUST_ID

value to the publishing table.

When the adapter polls the publishing table, it detects the new row and selects from the

P_CUSTOMER

table using the

CUST_ID

value found in the publishing table. Then the message is published.

Advanced Tab

This tab allows you to specify values for the following fields:

Table 20 Publication Service Advanced Tab

Field

Destination

Description

(Only available when JMS is selected as the transport type in the Adapter Instance

Configuration

Tab on page 35

)

The publisher destination. A service uses a default destination generated using the

Domain

and

Deployment

global variables, the adapter acronym, the adapter instance name and the service name. If you use this default destination, make sure the values for

Domain

and

Deployment

are not empty.

Alternatively, you can manually enter a destination in this field. The destination does not have to be predefined in the TIBCO Enterprise Message Service server. The destination can be static or dynamic.

See

Subject and Destination Names on page 163 for information about specifying destinations.

See TIBCO Enterprise Message Service User’s Guide for more details about destinations.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

76 | Chapter 4 Adapter Service Options

Table 20 Publication Service Advanced Tab (Cont’d)

Field

Message Subject

Description

(Only available when TIBCO Rendezvous is selected as the transport type in the Adapter Instance

Configuration Tab on page 35

)

Publisher subject. By default, a service uses a message subject that is generated using the Domain and Deployment global variables, the adapter acronym, the adapter instance name and the service name. If you use this default subject, make sure the values for Domain and Deployment are not empty. You can type a TIBCO Rendezvous subject name different from the default in this field.

See

Subject and Destination Names on page 163 for information about specifying subjects.

See TIBCO Rendezvous Concepts for more details about subjects.

Endpoint

Reference

Class Reference

Displays the endpoint reference. Click the Browse icon to change the endpoint reference, the Go To icon to reconfigure the existing reference, or the Delete icon to delete the reference. Endpoint reference objects are explained in TIBCO Designer Palette Reference.

Click the Go To icon to reconfigure the existing reference.

Clear reference

can be used to remove the reference under Endpoint Reference. Class reference objects are explained in TIBCO Designer

Palette Reference.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Subscription Service Tabs | 77

Subscription Service Tabs

When running as a subscriber, the adapter listens on a subject, receives messages and updates the relevant tables in its associated database. The data is then available to other applications that have access to the database.

You can configure parameters under the following tabs:

•

Configuration Tab on page 77

•

Table Tab on page 78

•

Child Table Mappings Tab on page 80

•

Child Exception Table Mappings Tab on page 81

•

Subscriber Options Tab on page 82

•

Advanced Tab on page 84

Configuration Tab

This tab allows you to specify values for the following fields:

Table 21 Subscription Service Configuration Tab

Field

Name

Description

Type a name unique among all subscribers defined for this project. You can use the default name or replace it with a name of your choice.

A service name must use alphanumeric characters, including underscore (_). You cannot use a blank space. The entire instance name must be less than 80 characters.

A service name cannot use global variables.

Transport Select the transport type (JMS or TIBCO Rendezvous) to be used by the runtime adapter. This selection determines which options appear in the rest of the Configuration tab.

The transport can be configured to use a trusted store and identity resource for use in SSL (Secure

Sockets Layer) configurations. TIBCO Rendezvous sessions and JMS topics have an SSL configuration field which uses a dialog to perform SSL configuration.

To enable and configure SSL, in the

Project

panel, expand the

Advanced

folder, then expand the

Sessions

folder. Select the TIBCO Rendezvous session or JMS topic and click Use SSL?. The SSL configuration options are explained in the online help associated with the session dialog. Click the question mark to display the online help.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

78 | Chapter 4 Adapter Service Options

Table 21 Subscription Service Configuration Tab (Cont’d)

Field Description

Quality of Service Only available when TIBCO Rendezvous is selected as the transport type) Select the level of service that determines how messages are sent. See

Quality of Service on page 58

for a description of these options.

• Certified

• Reliable

• Distributed Queue

Wire Format

Connection

Factory Type

Delivery Mode

The wire format in which data will be sent. Note that the wire format for both the publisher and subscriber must be the same, otherwise an error will occur. See

Wire Formats on page 59 for a

description of these formats.

• Rendezvous Message (TIBCO Rendezvous only)

• XML Message (TIBCO Rendezvous or JMS)

• ActiveEnterprise Message (TIBCO Rendezvous only)

Connection Factory objects create JMS connections for sending and receiving messages.

• Topic (JMS only)

A message published to a topic is broadcast to one or more subscribers. All messages published to the topic are received by all services that have subscribed to the topic. This messaging model is known as publish-subscribe.

• Queue (JMS only)

A message sent to a queue is consumed by one and only one receiver. Each message has only one receiver though multiple receivers may connect to the queue. The first receiver to access the queue gets the message. The other receivers do not. This messaging model is known as point-to-point.

(Only available when JMS is the transport type and Topic is the connection factory type) The

delivery mode for each message sending operation. See Delivery Mode on page 59

for a description of each mode.

• Persistent

• Non-Persistent

Table Tab

You must set subscriber table options before configuring other subscriber options.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Subscription Service Tabs | 79

An incoming message need not contain data for all the columns defined in the subscriber table. An adapter can be configured to expect only a subset of the columns. The adapter checks the repository for attributes defined in the subscriber table's class object definition.

When a message arrives, the adapter iterates through the attributes in the subscriber table’s class object definition and looks for those same attributes in the incoming message.

Subscriber table names can be qualified with a schema name, such as

SCOTT.EMP

. To access tables in other schemas, the database user defined in the adapter

Connection

tab must have the proper set of permissions granted. For more information see TIBCO ActiveMatrix

Adapter for Database Concepts.

When configuring the destination table, subscribe only to columns that should be updated.

If you subscribe to a column that should not be updated and a message arrives with no data for that column, a

NULL

will be written to that column. For example:

• If a source table is configured to send data for columns, c1

, c2

and c3

and the destination table is configured to receive data for columns c1

, c2

, c3

, c4

, and c5

— For the

TIBCO Rendezvous message

wire format, columns c1

, c2

, and c3

will get the data and columns c4 and c5 will get a

NULL

value.

— For the

TIBCO ActiveEnterprise message

and

XML message

wire format, columns c4

and c5 will be ignored and take on whatever default values they are supposed to have.

• If a source table is configured to send data for columns, c1

, c2

, and c3

and the destination table is configured to receive data for columns c1

, c2

, and c3

but not configured to receive data for columns c4

and c5

, columns c4

and c5

will retain the defaults applicable to both tables.

When the publisher table is configured to use parent-child relationships, the subscriber adapter must use the same repository as the publisher adapter.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

80 | Chapter 4 Adapter Service Options

Icons

Add Table — Click to display a dialog box that list tables available to the database user specified in the adapter Connection tab. Select the table to be used as the subscription table where data is inserted when received.

Add Child Tabl e

— Displays a dialog box from which a secondary table can be added to the configuration.

Add Table from Other Schema — Allows you to enter a schema. For instructions

on granting access privileges to an external schema, see

Referencing an External

Schema on page 64

Remove Table — Deletes the selected table from the configuration.

Re-find Table from Database — Causes TIBCO Designer to refresh stored table schema information by retrieving new information from the database.

Allow Key Columns Only — If selected, child columns are joined only to a key colulmn. If unselected, child columns can be joined to any column.

Columns

Tables and Columns — Lists the table and columns.

Type — Lists the primitive type.

AE Type — Lists the primitive type mapped to an TIBCO ActiveEnterprise type.

User Key — Click to define as a user key.

Use? — Click to enable the column to be updated when a message arrives. Subscribe only to columns that should be updated. Columns not configured to receive data will retain their default value. For columns that have been configured to receive data but do not get updated:

— In the TIBCO Rendezvous wire format, the columns get a

NULL

value.

— In the TIBCO ActiveEnterprise and XML wire formats, the columns are ignored in the statement.

Join To — Joins two tables.

Child Table Mappings Tab

Child tables between a publisher and subscriber must be mapped unless the tables have the same name.

These options are only active when child tables have been specified on the

Table Tab

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Subscription Service Tabs | 81

The following example shows a child table mapped. The left column (Subscriber Child

Table Name) contains the subscriber child table and the right column (Publisher Child

Table Name) contains the publisher child table.

This tab allows you to specify values for the following fields:

Table 22 Subscription Service Child Table Mappings Tab

Field

Subscriber Child

Table Name

Description

Displays the child tables that can be mapped. Entries are automatically created when you add child tables for a subscription service.

Publisher Child

Table Name

Click in this column and type the name of a publisher child table. Prefix the table name with a database user if your database requires it.

Child Exception Table Mappings Tab

Each child table can be configured to use an exception table.

These options are only active when child tables have been specified on the

Table Tab

This tab allows you to specify values for the following fields:

Table 23 Subscription Service Child Exception Table Mappings Tab

Field

Subscriber Child

Table Name

Description

The child tables that can be mapped. Entries are automatically created when you add child tables for a subscription service.

Publisher Child

Table Name

Click in this column and type the name of a exception child table. Prefix the exception table name with a database user if your database requires it.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

82 | Chapter 4 Adapter Service Options

Subscriber Options for DB2 on OS/390 (z/OS)

This tab appears when the Vendor field in the Adapter Instance

Configuration Tab

is set to

DB2 OS390.

Table 24 Subsciption Service DB2/390 Options Tab

Field

Database Name

Description

Enter the name of the database that you want to put your exception table in.

Table Space

Name

LOB Table Space

Name

Enter the name of the table space where the exception table is located.

The name of the LOB table space name where auxiliary table of the opaque exception table is located.

Subscriber Options Tab

This tab allows you to specify values for the following:

Table 25 Subscription Service Subscriber Options Tab

Field

Exceptions Table

Description

Name of exception table where data is written if the adapter cannot write to the subscriber table.

This table will hold messages that caused an exception. If the table does not exist, the subscription

service creates it. For details, see Exception Table on page 149

The exception table cannot contain any user-created columns where the column name starts with

ADB_

. These characters are reserved for use by the adapter.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Subscription Service Tabs | 83

Table 25 Subscription Service Subscriber Options Tab (Cont’d)

Field

Use Opaque

Exceptions Table

Description

Check the checkbox to use an opaque exceptions table. The table records each message (entirely) into a column, along with the error message. A message is logged in the exceptions table if the subscription service fails to generate records in the destination table or the adapter fails to insert a message into an exception table.

For DB2/OS390 databases, you must create a Large Objects (LOB) tablespace before using the opaque exceptions table, which will use the LOB tablespace.

The name for the opaque exceptions table. Opaque

Exceptions Table

Pre Commit

Stored Procedure

Reply Sender

Quality of Service

The value entered here represents the name of a stored procedure the subscriber will call after the database insert, update, or delete and prior to commit.

If the subscriber must send a reply to the sender, this value identifies the quality of service or

delivery mode to use when sending the reply. See Quality of Service on page 58

and Delivery Mode on page 59 for a description of these fields.

• Reliable (TIBCO Rendezvous transport type only)

• Certified (TIBCO Rendezvous transport type only)

• Persistent (JMS transport type only)

• Non-persistent (JMS transport type only)

Use Separate

Service Thread

When selected, a new session is created and the service endpoint is moved to this session. The subscriber batch commit count towards the number of messages processed by all the endpoints of each session. You can select other subscription service sessions by changing the session reference field (under the Advanced tab). This allow multiple services to share the same session and dispatcher.

When selected, the group message will be processed within a single transaction by the subscription service. The adapter will either commit the whole message changes to the database, or none.

Enable Group

Message

Transaction

Support

Service Bulk

Insert Size

You can set a different bulk insert size for this service. If not set, the service will use the bulk insert size of adapter instance options.

If you are using the JMS transport, you must set the JMS Destination Prefix. See

JMS

Destination Prefix on page 47

for details.

Note that:

• All subscription service threads reconnect separately if the database connection is lost.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

84 | Chapter 4 Adapter Service Options

• TIBCO Hawk statistics display all subscription service thread information and operation count.

• Debug messages provide the subscription service thread name in order to distinguish which message is from which subscription service thread.

• If a subscription service thread encounter fatal errors such as failed to rollback transaction or failed to update the exception table, the adapter terminates.

• At startup the subscription service dispatchers wait for all component to start before dispatching subscriber messages.

Advanced Tab

This tab allows you to specify values for the following:

Table 26 Subscription Service Advanced Tab

Field

Destination

Description

(JMS transport type only)

The subscriber destination. A service uses a default destination generated using the

Domain

and

Deployment

global variables, the adapter acronym, the adapter instance name and the service name. If you use this default destination, make sure the values for

Domain

and

Deployment

are not empty.

See

Subject and Destination Names on page 163 for information about specifying destinations.

See TIBCO Enterprise Message Service User’s Guide for more details about destinations.

Message Subject

Endpoint

Reference

(TIBCO Rendezvous transport type only)

By default a service uses a message subject that is generated using the

Domain

and

Deployment

global variables, the adapter acronym, the adapter instance name and the service name. If you use this default subject, make sure the values for

Domain

and

Deployment

are not empty. You can type a

TIBCO Rendezvous subject name different from the default in this field.

See

Subject and Destination Names on page 163 for information about specifying subjects.

See TIBCO Rendezvous Concepts for more details about subjects.

Displays the endpoint reference. Click the Browse icon to change the endpoint reference or the Go

To icon to reconfigure the existing reference. You can also click the Delete icon to remove the reference. Endpoint reference objects are explained in TIBCO Designer Palette Reference.

Class Reference Click the Go To icon to reconfigure the existing reference. Class reference objects are explained in

TIBCO Designer Palette Reference.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Request-response Service Tabs | 85

Request-response Service Tabs

This service is often called a Request Reply Server or RPC (Remote Procedural Call)

Server. When running as a request-response service, the adapter receives requests from other applications, parses them, calls the appropriate component interface API to set the input fields, then calls another set of component interface APIs to get the output fields.

The output fields are wrapped in a schema and sent back to the caller.

A request-response service is renamed

ADBServer

when you drag its icon into the design panel. Configuration involves specifying its name, quality of service and wire format. A server operation allows the adapter to process requests from client applications and return results in a response to the client.

When using the RPC server, you can configure custom operations. These are configured under the

Call Operation Tab

You can configure parameters under the following tabs:

•

Configuration Tab on page 85

•

Call Operation Tab on page 87

•

Advanced Tab on page 88

Configuration Tab

This tab allows you to specify values for the following fields:

Table 27 Request-response Service Configuration Tab (Sheet 1 of 3)

Field

Name

Description

Type a name unique among all request-response services defined for this project. You can use the default name or replace it with a name of your choice.

A service name must use alphanumeric characters, including underscore (_). You cannot use a blank space. The entire instance name must be less than 80 characters.

A service name cannot use global variables.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

86 | Chapter 4 Adapter Service Options

Table 27 Request-response Service Configuration Tab (Sheet 2 of 3)

Field

Transport Type

Description

Select the transport type (JMS or TIBCO Rendezvous) to be used by the runtime adapter. This selection determines which options appear in the rest of the Configuration tab. Only the options that are available with the selected Transport Type, Connection Factory Type, Mode or Wire Format are displayed.

The transport can be configured to use a trusted store and identity resource for use in SSL (Secure

Sockets Layer) configurations. TIBCO Rendezvous sessions and JMS topics have an SSL configuration field which uses a dialog to perform SSL configuration.

To enable and configure SSL, in the Project panel, expand the

Advanced

folder, then expand the

Sessions

folder. Select the TIBCO Rendezvous session or JMS topic and click

Use SSL?

. The SSL configuration options are explained in the online help associated with the session dialog. Click the question mark to display the online help.

Quality of Service Only available when TIBCO Rendezvous is selected as the transport type) Select the level of service that determines how messages are sent. See

Quality of Service on page 58

for a description of these options.

• Certified

• Reliable

• Distributed Queue

Wire Format The wire format in which data will be sent. Note that the wire format for both the publisher and subscriber must be the same, otherwise an error will occur. See

Wire Formats on page 59 for a

description of these formats.

• Rendezvous Message (TIBCO Rendezvous only)

• XML Message (TIBCO Rendezvous or JMS)

• ActiveEnterprise Message (TIBCO Rendezvous only)

Connection

Factory Type

Connection Factory objects create JMS connections for sending and receiving messages.

• Topic (JMS only)

• Queue (JMS only)

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Request-response Service Tabs | 87

Table 27 Request-response Service Configuration Tab (Sheet 3 of 3)

Field

Delivery Mode

Description

(Only available when JMS is the transport type) The delivery mode for each message sending

operation. See Delivery Mode on page 59 for a description of each mode.

• Durable

• Non-Durable

Mode

Use Custom

Operations

Specify if this endpoint will be a Request Reply Server or RPC (Remote Procedural Call) Server.

• Request Reply: A subscriber endpoint will be created. This subscriber will listen to request and publish the reply to the reply subject.

• RPC: A server endpoint will be created. This server will receive a request from and send back the reply to the client.

This checkbox appears when the

Mode

field is set to

RPC

. Selecting this checkbox and clicking the

Apply button creates the

Call Operation Tab .

Call Operation Tab

This tab appears when the mode is set to RPC and the

Use Custom Operations

box is

checked in the Request-Response Service Configuration tab.

Click the New button to enter data into the fields. After making changes, click the Apply button.

TIBCO Designer retrieves the signature of each stored procedure and function from the database.

If you change the stored procedure or database connection while editing your project, you must return to this dialog and click the Refresh button to retrieve the changes from the database.

This tab allows you to specify values for the following:

Table 28 Request-response Call Operation Tab

Field

Name

Description

Enter a unique name for the call operation.

Catalog/Package (Optional, only applicable to databases that have more than one catalog or package.) The catalog or package in which the procedure resides. This name is used to resolve naming conflicts if more than one catalog or package in the database has the selected procedure with the same name. See your database documentation for more information about catalogs and packages.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

88 | Chapter 4 Adapter Service Options

Table 28 Request-response Call Operation Tab (Cont’d)

Field

Schema

Description

(Optional) The schema in which the procedure resides. This name is used to resolve naming conflicts if more than one schema in the database has the selected procedure with the same name.

Procedure Name Name of the database procedure or function to call.

Select Procedure

Maximum Rows

One Way

Queries the database for available procedures or functions or the Procedure Name field. Clicking this button displays a dialog showing the available procedure.

To select a procedure or function:

1. Select a call operation from the list on the left. Its input and output parameters, if any, are displayed in the fields on the right side of the dialog.

2. Click Select Procedure.

(Optional) The maximum number of rows to retrieve.

(Optional) Check this checkbox if you want to execute this procedure using a one-way operation. If left unchecked, the procedure will execute using a two-way operation.

Advanced Tab

This tab allows you to specify values for the following:

Table 29 Request-response Service Advanced Tab

Field

Destination

Description

(

JMS

transport type only)

The subscriber destination. A service uses a default destination generated using the

Domain

and

Deployment

global variables, the adapter acronym, the adapter instance name and the service name. If you use this default destination, make sure the values for

Domain

and

Deployment

are not empty.

See

Subject and Destination Names on page 163 for information about specifying destinations.

See TIBCO Enterprise Message Service User’s Guide for more details about destinations.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Request-response Service Tabs | 89

Table 29 Request-response Service Advanced Tab (Cont’d)

Field

Message Subject

Description

(TIBCO Rendezvous transport type only)

By default a service uses a message subject that is generated using the

Domain

and

Deployment

global variables, the adapter acronym, the adapter instance name and the service name. If you use this default subject, make sure the values for

Domain

and

Deployment

are not empty. You can type a

TIBCO Rendezvous subject name different from the default in this field.

See

Subject and Destination Names on page 163 for information about specifying subjects.

See TIBCO Rendezvous Concepts for more details about subjects.

Reply Subject

Endpoint

Reference

Type a TIBCO Rendezvous subject name that the adapter uses to respond, if no response subject is specified in the request message.

Displays the endpoint reference. Click the Browse icon to change the endpoint reference or the Go

To icon to reconfigure the existing reference. You can also click the Delete icon to remove the reference. Endpoint reference objects are explained in TIBCO Designer Palette Reference.

Class Reference Click the Go To icon to reconfigure the existing reference. Class reference objects are explained in

TIBCO Designer Palette Reference.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

90 | Chapter 4 Adapter Service Options

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Chapter 5

Deploying and Starting the Adapter Using

TIBCO Administrator

| 91

This chapter provides an overview about deploying, starting, stopping, and monitoring adapter services using the TIBCO Administrator web interface.

Topics

•

Create an EAR File in TIBCO Designer, page 92

•

Deploy the Project, page 93

•

Start or Stop the Adapter, page 94

•

Monitor the Adapter, page 95

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

92 | Chapter 5 Deploying and Starting the Adapter Using TIBCO Administrator

Create an EAR File in TIBCO Designer

Generate an Enterprise Archive file (EAR) that contains information about the adapter services to deploy.

The EAR file contains information on what you wish to deploy. This could be one or more adapter services, one or more TIBCO ActiveMatrix BusinessWorks process engines, or both.

Building an archive creates the EAR file, which you can then deploy from TIBCO

Administrator. If you make changes to the business processes or adapter services included in the archive, you need to rebuild the archive. Saving the project does not affect the archive.

In TIBCO Designer, follow these steps to create an EAR:

1. Configure the adapter services.

2. Drag and drop the Enterprise Archive resource from the palette panel to the design panel.

If there are any configured adapter services in your project, an Adapter Archive resource becomes available in the palette panel.

3. Drag the Adapter Archive into the design panel and specify information in the

Configuration tab.

4. Click the Apply button.

5. Go to the Enterprise Archive and click Build Archive to create the archive file.

See Also

See TIBCO Designer User’s Guide for more information about this procedure. The guide is available from the Designer Help menu.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Deploy the Project | 93

Deploy the Project

Before deploying a project, the machine on which the adapter is installed must be part of a

TIBCO administration domain. After you have installed the TIBCO Administration

Server, any machine on which you install TIBCO Runtime Agent (required by an adapter) can be added to the administration domain. The TIBCO software installed on the machine is then visible and accessible via the TIBCO Administrator GUI.

When you deploy a project, startup scripts and other information about the different components are sent to the machines to which the components were assigned. The project data store and TIBCO Administration Server are updated with the deployed components.

To deploy a project:

1. Import the EAR file into TIBCO Administrator.

2. Assign adapter archives in the EAR file to adapters installed in the administration domain and likewise assign process archives to process engines.

3. Specify startup options for each adapter service.

Password Handling

At design time, the adapter uses a password to connect to the backend application and fetch metadata. At runtime, the adapter uses a password to connect to the back-end application and interoperate with it. If you create a 4.x configuration using TIBCO

Designer 5.1, and use the configuration with a 4.x adapter version, some special considerations are required for security.

When deploying the adapter check the

Service

property of the global variable in the global variables section, then go to the Advanced tab of the adapter archive and set the password value under the

Runtime Variables

section.

Do not set the password to type

Password

in the global variables section for adapter configurations that are set to AE Version 4.0 or

AE Version 5.0

(in the Configuration tab

Version field) or any intermediate version.

See Also

See TIBCO Administrator User’s Guide for an introduction to the TIBCO administration domain and detailed information about the above steps.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

94 | Chapter 5 Deploying and Starting the Adapter Using TIBCO Administrator

Start or Stop the Adapter

The TIBCO Administrator

Application Management

module allows you to start, and stop deployed applications.

To start an adapter service from the module:

1. In the Administrator GUI left pane, expand Application Management > application_name > Service Instances.

2. In the Service Instance panel, select the checkbox next to the adapter service.

3. Click the Start Selected button.

The status changes from

Stopped

Starting up

Started

4. To stop the adapter service, click the Stop Selected button.

See Also

See TIBCO Administrator User’s Guide for more information.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Monitor the Adapter | 95

Monitor the Adapter

TIBCO Administrator offers a number of monitoring options.

• Specify alerts and TIBCO Hawk rulebases for each machine in the domain.

• Specify alerts and Hawk rulebases for each adapter service.

• View the log for each adapter service.

See Also

See TIBCO Administrator User’s Guide for information about configuring the above monitoring options.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

96 | Chapter 5 Deploying and Starting the Adapter Using TIBCO Administrator

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Chapter 6

Using the Alerter

This chapter explains how to configure and start an alerter for each supported database.

| 97

Topics

•

Introduction, page 98

•

Setting Up and Starting the Alerter on Oracle or Microsoft SQL Server 2005 and

Above, page 99

•

Setting Up and Starting the Alerter on Microsoft SQL Server 2000, page 103

•

Setting Up and Starting the Alerter on Sybase SQL Server, page 106

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

98 | Chapter 6 Using the Alerter

Introduction

The alerter process is used to asynchronously notify running publication service instances of database changes. The adapter does not need to poll its publishing table for existence of new rows. Use the alerter only when database changes are infrequent.

The procedures can be executed on the SQL command line or through any supported

Application Programming Interfaces (the procedures cannot be invoked successfully from within a trigger). The procedures commit the inserts into the database table and notify the adapter of the commit.

Because the alerter process runs with a database instance, not user schema, an adapter instance cannot poll the publishing table name for just one user schema. For example, if the same publishing table exists for two user schemas and two instances are monitoring the same publication table, each instance with a different user, both instances will check the same publication table whenever the alerter checks for changes in the publication table.

The alerter is available on the following databases.

Oracle and Microsoft SQL Server 2005

An alerter for Oracle is part of the adapter and available on all operating systems supported by the adapter. The alerter can be used in the TIBCO ActiveMatrix Adapter for

Database environment in cases where changes are infrequent and polling by the publication service would result in unnecessary and expensive operations. The alerter is supported on both the Rendezvous and JMS transports.

Microsoft SQL Server 2000

An alerter function for Microsoft SQL Server is available on all operating systems supported by the adapter. The procedures are executed on the SQL command line itself, and there is no separate program. The alerter functionality is embedded in a dynamic linked library. The alerter is only supported on the Rendezvous transport.

Sybase SQL Server

An alerter function for Sybase SQL Server is available on Microsoft Windows along with

Solaris. The procedures are executed on the SQL command line itself, and there is no separate program. The alerter functionality is embedded in a dynamic linked library. The alerter is only supported on the Rendezvous transport.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Setting Up and Starting the Alerter on Oracle or Microsoft SQL Server 2005 and Above | 99

Setting Up and Starting the Alerter on Oracle or Microsoft SQL

Server 2005 and Above

The alerter on Oracle uses the Oracle AQ package and on MS SQLServer 2005 and above uses the Service Broker component to send and receive information between sessions, asynchronously allowing two or more sessions in the same database instance to communicate.

The Microsoft SQL Server mentioned below in this section refers to version 2005 and above.

As shown in the following figure, when a source table is updated with data and the commit_and_notify

procedure executed, a trigger copies the data to the publishing table and notifies the Oracle AQ or MS SQLServer and that a publishing table has changed. The alerter gets the notification from Oracle AQ or MS SQLServer and sends a notification message to the adapter that a publishing table has changed. The adapter then queries all its configured publishing tables for the new data and sends it on a subject to the TIBCO transport. One or more instances can be notified.

Figure 4 Alerter Operation (Oracle and MSSQLServer)

If there are multiple publishing tables under the same database account, you can use the commit_and_notify_table

procedure to specify that only a particular table be checked by the adapter. This prevents the adapter from needlessly checking all its publishing tables for updates when only one table has been updated with new data. This notification can be sent to one or more instances.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

100 | Chapter 6 Using the Alerter

Name adb_alerter_qtbl

(Oracle only)

The following object types and stored procedures are available for committing messages when the alerter is used:

Type

AQ queue table adb_alerter_q

(Oracle only) adb_alerter_typ adb_alerter_contract

(Microsoft SQL Server 2005 only) instance_Id_q

(Microsoft SQL Server 2005 only) instance_Id_send_service

(Microsoft SQL Server 2005 only) instance_Id_rcv_service

(Microsoft SQL Server 2005 only) adb_alerter_typ commit_and_notify commit_and_notify_agent alerter_name

AQ queue

Service Broker

Message Type

Service Broker

Contract

Service Broker

Queue

Service Broker

Service

Service Broker

Service

Object

Procedure

Procedure commit_and_notify_table table_name Procedure stop_alerter stop_alerter_agent alerter_name

Procedure

Procedure config_alerter cleanup_alerter listen_pipe

Procedure

Description

Queue table for all alerters.

Queue for all alerters.

Object type for all messages.

The contract type used. The contract specifies the message types that can be used.

Created by the config_alerter stored procedure.

Object type for the payload message.

Sends a change notification to all adapters.

Sends a change notification to the named alerter.

Sends a change notification for a named table.

Stops all running alerters.

Stops the alerter for the named alerter.

Alerter call to register itself as an AQ subscriber.

Alerter call to unregister itself as an AQ subscriber.

Alerter call to block on alerts.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Setting Up and Starting the Alerter on Oracle or Microsoft SQL Server 2005 and Above | 101

Before Starting

When using the alerter functionality with Oracle database, make sure you have executed the create_user.sql

and alerter.sql

files with the database account used by the adapter, as described in Post-Installation Tasks in TIBCO ActiveMatrix Adapter for Database

Installation.

When using the alerter functionality with Microsoft SQL Server database, make sure you have enabled the service broker functionality in the database server. To check if the service broker is enabled, execute:

SELECT is_broker_enabled FROM sys.databases WHERE database_id = DB_ID()

The returned value should be

To enable service broker, execute

Alter database dbname

set enable_broker with rollback immediate

Configuring and Starting the Alerter

To use the alerter, you must install the Oracle AQ or Microsoft SQL Server package. See your Oracle documentation for information about installing the Oracle AQ or Microsoft

SQLServer package. When configuring the publication service, you must enable the alerter by checking the Use Alerter checkbox under the Publisher Options tab. When the adapter starts, the alerter will also start.

If an adapter that uses the alerter is not shutdown cleanly, you must call the cleanup_alerter stored procedure before restarting the adapter. The procedure is normally called by the adapter when it shuts down cleanly.

Oracle Alerter Example

This section describes how to execute the commit_and_notify_table

stored procedure. It assumes the rvpub.tra

configuration has its data source name, user account name ( demo

) and password defined in the repository. The rvpub

adapter publication service has been configured with the Use Alerter checkbox checked.

1. Start the adapter publication service instance by typing: adbagent --propFile rvpub.tra rvpub.tra

2. After inserting a message, execute the commit_and_notify_table

stored procedure with the publishing table monitored by the adapter. For example, if the adapter is monitoring the

PUB_ORDER

table: sqlplus demo/demo insert into ORDER_TABLE values(111,'Oak Table',499.95);

SQL> execute commit_and_notify_table (’PUB_ORDER’);

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

102 | Chapter 6 Using the Alerter

The procedure puts a message on an Oracle AQ. The publisher adapter then reads its publishing table and sends a message containing the changed data on its configured subject.

This example shows how to tell the adapter instance to poll a single table,

PUB_ORDER

, for changes. Use the commit_and_notify

stored procedure to poll all publishing tables for changes.

SQL Server Alerter Example

This section describes how to execute the commit_and_notify_table

stored procedure. It assumes the rvpub.tra

configuration has its data source name, user account name ( demo

) and password defined in the repository. The rvpub

adapter publication service has been configured with the Use Alerter checkbox checked.

1. Start the adapter publication service instance by typing: adbagent --propFile rvpub.tra rvpub.tra

2. After inserting a message, execute the commit_and_notify_table

stored procedure with the publishing table monitored by the adapter. For example, if the adapter is monitoring the

PUB_ORDER

table: isql -Udemo -Pdemo

SQL> insert into ORDER_TABLE values(111,'Oak Table',499.95);

SQL> execute commit_and_notify_table ’PUB_ORDER’;

The procedure puts a message to the service broker queue, which is picked up by the adapter. The publisher adapter then reads its publishing table and sends a message containing the changed data on its configured subject.

This example shows how to tell the adapter instance to poll a single table,

PUB_ORDER

, for changes. Use the commit_and_notify

stored procedure to poll all publishing tables for changes.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Setting Up and Starting the Alerter on Microsoft SQL Server 2000 | 103

Setting Up and Starting the Alerter on Microsoft SQL Server 2000

On Microsoft SQL Server the alerter mechanism is an extended stored procedure in a dynamic link library (provided with installation media) that is dynamically loaded into

SQL Server.

Two stored procedures are available for sending messages when using the alerter:

• notify

. Sends a TIBCO Rendezvous message to the given instance or instances that one or more publishing tables have been updated.

• notifytable table_name

. Sends a TIBCO Rendezvous message to the given instance or instances that the given publishing table has been updated.

Before Starting

A database account must have been created for running the adapter. This is typically done after installation. See TIBCO ActiveMatrix Adapter for Database Installation for details.

Alerter Setup

Before using the alerter you must copy the alerter dynamic link library adbalerter_mssql.dll

to the

Binn

directory where SQL Server is installed, add the notify

and notifytable

external stored procedures to the master database and set execute permission on the procedures for the database account used by the adapter.

1. Open a command window and change directory to the

TIB_ADADB_HOME

/lib directory.

2. Copy the alerter library to the

Binn

directory where SQL Server is installed, for example: copy adbalerter_mssql.dll \Mssql7\Binn

3. Ensure the procedures are not already defined in the master database: isql -Usa -P password

1> sp_dropextendedproc notify

2> go

1> sp_dropextendedproc notifytable

2> go

1> DBCC adbalerter_mssql(FREE)

2> go

DBCC execution completed. If DBCC printed error messages, contact your system administrator.

4. Add the procedures to the master database:

1> sp_addextendedproc 'notify','adbalerter_mssql.dll'

2> go

1> sp_addextendedproc 'notifytable','adbalerter_mssql.dll'

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

104 | Chapter 6 Using the Alerter

2> go

5. Set access permissions for the database account used by the adapter:

1> grant execute on notify to database_account

2> go

1> grant execute on notifytable to database_account

2> go

1> exit

6. Add

TIBCO_HOME

\tibrv\bin

to the system

PATH

variable.

Using the Alerter

When using the alerter, the adapter instance must be started with polling disabled. In this example, after adding a row in a table monitored by the adapter, the alerter procedure is invoked and the adapter checks for updates in its publishing table. The database server name is itaska

and database name is activedb

1. In a command window, start an adapter instance with polling disabled (set the adb.PollingInterval

value to 0 in the properties file): adbagent --propFile properties_file_name

2. In another command window, insert a row into the database table being monitored by the adapter, commit the transaction, then invoke the notify procedure: isql -Uadb -Padb -dactivedb

1> insert into ORDER_TABLE values(406,'walnut table',9899.89)

2> go

1> execute itaska.master.dbo.notify @agentname='rvpub'

2> go

Notifying: rvpub

You can also execute the notify

procedure for more then one adapter instance. Each configuration name must be separated using a space character. For example:

1> execute itaska.master.dbo.notify @agentname='rvpub rvpub2 rvpub3'

2> go

The notifytable

procedure can be invoked for one or more adapter instances and one publishing table. If the database used by the adapter and master database are on the same database server, the server prefix need not be given.

1> execute itaska.master.dbo.notifytable

@agentname='rvpub rvpub2',@tablename='P_ORDER_TABLE’

2> go

Modifying RV Configuration

The RV configuration parameters used by the alerter to connect to a remote daemon can be modified by including the configuration parameters when invoking the store procedure.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Setting Up and Starting the Alerter on Microsoft SQL Server 2000 | 105

For example, execute master.dbo.notify @agentname='rvpub', @service='7500', @network=’lan0’, @daemon='10.105.176.21:7500' execute master.dbo.notifytable @agentname='rvpub rvpub2', @pubtable='ADB_ORDER', @service='7500',

@network=’lan0’, @daemon='10.105.176.21:7500'

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

106 | Chapter 6 Using the Alerter

Setting Up and Starting the Alerter on Sybase SQL Server

On Sybase SQL Server the alerter mechanism is an extended stored procedure in a dynamic link library (provided with the installation media) that is dynamically loaded into

Sybase SQL Server. Two stored procedures are available for sending messages when the alerter is used:

• notify

. Sends a TIBCO Rendezvous message to the given configuration or configurations that one or more publishing tables have been updated.

• notifytable table_name

. Sends a TIBCO Rendezvous message to the given configuration or configurations that the given publishing table has been updated.

Before Starting

A database account must be created for running the adapter. This is typically done after installation. See TIBCO ActiveMatrix Adapter for Database Installation for details.

Alerter Setup on Solaris

Before using the alerter you must copy the alerter shared library to the

Sybase/lib

directory, add the notify

and notifytable

external stored procedures to the master database and set execute permission on the procedures for the database account used by the adapter. The name of the shared library file is adbalerter_sybase.so

1. Open a command window and change directory to the

TIB_ADADB_HOME

/lib directory. Copy the alerter library as follows: cp adbalerter_sybase.so sybase/lib

You may need to shut down and restart your

XP SERVER

after copying the shared library to the sybase/lib

directory.

2. Ensure that the procedures are not already defined in the master database: isql -Usa -P password

1> sp_dropextendedproc notify

2> go

1> sp_dropextendedproc notifytable

2> go

1> sp_freedll "adbalerter_sybase"

2> go

3. Add the procedures to the master database:

1>create procedure notify

2>@agentname varchar(255),

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Setting Up and Starting the Alerter on Sybase SQL Server | 107

3>@service varchar(255)=

’default_value’

4>@network varchar(255)=

’default_value’

5>@daemon varchar(255)=

’default_value’

6> as external name 'adbalerter_sybase'

7>go

1>create procedure notifytable

2>@agentname varchar(255),

3>@tablename varchar(255),

4>@service varchar(255)=

’default_value’

5>@network varchar(255)=

’default_value’

6>@daemon varchar(255)=

’default_value’

7> as external name 'adbalerter_sybase'

8>go

This example shows how to add procedures on Solaris.

4. Set access permissions for the database account used by the adapter:

1> grant execute on notify to database_account

2> go

1> grant execute on notifytable to database_account

2> go

1> exit

5. Add

TIBCO_HOME

/tibrv/lib/libtibrv.so

to the system

LD_LIBRARY_PATH

variable.

6. Add

TIBCO_HOME

/tibrv/rvd/bin

to the system

PATH

variable.

Alerter Setup on Microsoft Windows

Before using the alerter you must copy the alerter dynamic link library, add the external stored procedures to the master database and set execute permission on the procedures for the database account used by the adapter.

1. Open a command window and change directory to the

TIB_ADADB_HOME

\lib directory. Copy the alerter library as follows: copy adbalerter_sybase.dll \Sybase\dll

You may need to shutdown and restart your

XP SERVER

after copying adbalerter_sybase.dll

to the

\Sybase\dll

directory.

2. Ensure that the procedures are not already defined in the master database: isql -Usa -P password

1> sp_dropextendedproc notify

2> go

1> sp_dropextendedproc notifytable

2> go

1> sp_freedll "adbalerter_sybase"

2> go

3. Add the procedures to the master database:

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

108 | Chapter 6 Using the Alerter

1>create procedure notify

2>@agentname varchar(255),

3>@service varchar(255)=

’default_value’

4>@network varchar(255)=

’default_value’

5>@daemon varchar(255)=

’default_value’

6> as external name 'adbalerter_sybase'

7>go

1>create procedure notifytable

2>@agentname varchar(255),

3>@tablename varchar(255),

4>@service varchar(255)=

’default_value’

5>@network varchar(255)=

’default_value’

6>@daemon varchar(255)=

’default_value’

7> as external name 'adbalerter_sybase'

8>go

4. Set access permissions for the database account used by the adapter:

1> grant execute on notify to database_account

2> go

1> grant execute on notifytable to database_account

2> go

1> exit

5. Add

TIBCO_HOME

\tibrv\bin

to the system

PATH

variable.

Using the Alerter

When using the alerter, an adapter instance must be started with polling disabled. In this example, after adding a row in a table monitored by the adapter, the alerter procedure is invoked and the adapter checks for updates in its publishing table. The database server name is itaska

and database name is activedb

1. In a command window, start the adapter instance with polling disabled (set the adb.PollingInterval

value to 0 in the properties file): adbagent --propFile propFilename

2. In another command window, insert a row into the database table being monitored by the adapter, commit the transaction, then invoke the notify procedure: isql -Uadb -Padb -dactivedb

1> insert into ORDER_TABLE values(406,'walnut table',9899.89)

2> go

1> execute itaska.master.dbo.notify @agentname='rvpub'

2> go

Notifying: rvpub

You can also execute the notify

procedure for more than one adapter instance. Each configuration name must be separated using a space character. For example:

1> execute itaska.master.dbo.notify @agentname='rvpub rvpub2 rvpub3'

2> go

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Setting Up and Starting the Alerter on Sybase SQL Server | 109

The notifytable

procedure can be invoked for one or more adapter instances and one publishing table. For example:

1> execute itaska.master.dbo.notifytable

@agentname='rvpub rvpub2',@tablename='P_ORDER_TABLE'

2> go

If the database used by the adapter and master database are on the same database server, the server

prefix need not be given.

Modifying RV Configuration

The RV configuration parameters used by the alerter to connect to a remote daemon can be modified by including the configuration parameters when invoking the store procedure.

@network=’lan0’, @daemon='10.105.176.21:7500'

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

110 | Chapter 6 Using the Alerter

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Chapter 7

Using the Request-response Service

This chapter explains the request-response service, load balancing, and Oracle REF data type support features.

See TIBCO ActiveMatrix Adapter for Database Examples for request-response exercises.

| 111

Topics

•

Introduction, page 112

•

Request-response Mode, page 114

•

RPC Mode, page 122

•

Load Balancing, page 132

•

Oracle REF Data Type Support, page 139

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

112 | Chapter 7 Using the Request-response Service

Introduction

Request-response operations are set up using the Request-Response Service dialog. This dialog is described in

Configuration Tab on page 85

Using request-response semantics, client applications can send SQL statements, stored procedures, or both on a specified subject to an adapter instance. The adapter processes the request and returns the results in a response to the client.

1. A request may be a query to the database or any DDL or DML command to be performed on the database. Multiple statements, procedures or both can be sent in one message.

2. The adapter executes the statement, procedure or both. Requests within a message are processed as a single transaction.

3. The adapter sends back the response to the Inbox, subject or response subject that was set up by the client application. The response consists of a result code or one or more result sets, based on the request. A response can also be an error code or error description, if the request was not successful.

Multiple adapter instances can be configured so that any one of the configurations receives and processes the request:

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Introduction | 113

• For a single configuration, the number of threads can be configured that will be responsible for processing application requests. See

Load Balancing in a Single

Instance Using Threads on page 132

for details.

• For multiple configurations, TIBCO Rendezvous Distributed Queuing can be used to balance the load across a number of configurations in a queue. The task will be

assigned to the least loaded member of the queue. See

Load Balancing Across Adapter

Instances on page 134

for details.

Use of Quotes in Microsoft SQL Server

When constructing a request in your application that will be processed by the adapter with a Microsoft SQL Server database, you must take care when using quotes.

For example, the following procedure is part of a request from an application. Double quotation marks are used, which is incorrect. An error will be returned.

select @qry = "Update " + @tablename + " set ORDER_DESCRIPTION = 'UPDATE TEST'" + ", ORDER_PRICE =

10109.25"

The following procedure is the same as above, but uses single quotes. It will be correctly processed.

select @qry = 'Update ' + @tablename + ' set ORDER_DESCRIPTION = ''UPDATE TEST'', ORDER_PRICE =

10109.25'

See Delimited Identifiers in your Microsoft SQL Server documentation for details.

The SQL statement should contain only ASCII characters.

If your SQL statements contain non-ASCII characters, convert them into a stored procedure and invoke the procedure using custom RPC operations.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

114 | Chapter 7 Using the Request-response Service

Request-response Mode

TIBCO ActiveMatrix Adapter for Database request-response mode supports the

Rendezvous, ActiveEnterprise and XML message formats.

Requests

A request can contain one or more SQL statements, stored procedures, or both to be executed as a transaction. The text of the SQL statement follows the conventions for

ODBC SQL syntax. All SQL statements supported by the DBMS are allowed and placeholders (represented by a question mark, ‘?’) are permitted in the SQL statement, conforming to the ODBC rules. For performance reasons, it is recommended to use a SQL statement. The ‘?’convention should only be used to bind binary data or call stored procedures.

An adapter instance is configured for request-response activity as described in

Request-response Service Tabs on page 85

. In so doing, the adapter listens on the subject

on which the application sends requests. The application uses TIBCO Rendezvous or the

TIBCO Adapter SDK to send a self-describing message containing a request on the agreed subject to the adapter instance.

The following are supported:

• DDL and DML SQL statements

• The column size of the return resultset should not exceed 128

• Multiple statements or procedures in a single transaction that send a nested TIBCO

Rendezvous message

• rv_Send()

, rv_SendWithReply()

and rv_Rpc()

calls

• TIBCO Rendezvous C, C++, and Java APIs

If rv_SendWithReply()

or rv_Rpc()

calls are used, the adapter sends the response to the Inbox or subject that was set by the application for the response. Otherwise, the adapter sends the response on the response subject that was set at configuration time.

Requests are described in the following sections:

•

TIBCO ActiveEnterprise or XML Message Request Format, page 115

•

TIBCO Rendezvous Message Request Format, page 115

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Request-response Mode | 115

Responses

A response from the adapter to a client application has a result code and one or more result sets. Each result set contains nested self-describing messages, each of which encodes a result row, such as that returned from a query. A response can also return an error code and error description if the request was not successful.

Responses are described in the following sections:

•

TIBCO ActiveEnterprise or XML Message Response Format, page 118

•

TIBCO Rendezvous Message Response Format, page 118

TIBCO ActiveEnterprise or XML Message Request Format

In these formats, the input class is SQL_REQUEST. The SQL_REQUEST class is

described below. Also see

SQL_STATEMENT Class on page 126

</assoc>

</assoc>

</object>

TIBCO Rendezvous Message Request Format

This is an example structure of the nested self-describing request message sent by an application to the adapter.

Request

{ rv_Name = “closure”, rvmsg_Type = RVMSG_OPAQUE, rvmsg_Data = optional_closure_data rv_Name = “stmt”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data =

Statement rv_Name = “stmt”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data =

Statement

. . .

}

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

116 | Chapter 7 Using the Request-response Service

The closure

field is an optional field. If included in the request, the response returns the same closure argument untouched, so the client application can use this information as a means of matching requests with responses.

The value

Statement

is a TIBCO Rendezvous Message of the following structure:

Statement

{ rv_Name = “sql”, rvmsg_Type = RVMSG_STRING, rvmsg_Data =

SQL_statement_with_possible_bind_variables rv_Name = “maxrows”, rvmsg_Type = RVMSG_INT, rvmsg_Data = optional_max_number_of_rows_to_fetch rv_Name = “bind”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data =

Bind_data rv_Name = “bind”, rvmsg_Type = RVMSG_RVMSG, rvmsg_Data =

Bind_data

. . .

}

The value

Bind_data

is a

TIBCO Rendezvous Message

with the following structure:

Bind_data

{ rv_Name = "position", rvmsg_Type = RVMSG_INT, rvmsg_Data = position_of_placeholder_starting_with_1_from_left_to_right rv_Name = "column", rvmsg_Type = RVMSG_STRING, rvmsg_Data = in_format_table-name.column-name_whose_column_type_matches_this_bound_variable rv_Name = "data", rvmsg_Type = type_of_bound_data

, rvmsg_Data = value_of_bound_data

}

If the position

field is not specified, the order received is used.

Example TIBCO Rendezvous Message Requests

The section contains example requests that are based on SQL statements made by a client application and sent to an adapter instance for processing.

Simple SQL Request Statement

Given that a client application submits the following SQL statement:

INSERT INTO order_table (order_id, order_description, order_price) values (1, ‘Order 1’, 1.10)

The corresponding request could be formatted as a TIBCO Rendezvous Message similar to the following:

{ name = “closure” value = optional_closure_argument name = “stmt” value =

{

name = “sql” value = “INSERT INTO order_table (order_id, order_description, order_price) values (1, ‘Order 1’,

1.10)”

}

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Request-response Mode | 117

Bind Request Statement

Assume that a client application submits the following SQL statement, where

is a placeholder for an adbDateTime

value:

INSERT INTO order_table (order_id, order_date) values (2, ?)

The corresponding request could be formatted as a message in

TIBCO Rendezvous Message format similar to the following:

{ name = “closure” value = optional_closure_argument name = “stmt” value =

{

name = “sql” value = “INSERT INTO order_table (order_id, order_date) values (2, ?)”

name = “bind” value =

{

name = “order_table.order_date” type = RVMSG_STRING value = “1999-08-20 10:20:01”

}

To create a bind parameter for binary data, the actual data would be sent as an

RVMSG_OPAQUE

Not every data value sent to an SQL statement must be bound. The client can embed all these values into the actual text of the statement instead. Embedding the values directly into the SQL text results in better performance. However, binary values must be bound.

Types such as adbDateTime

can either be bound or included in the SQL text by using the native DBMS date conversion function.

For example, in ORACLE, you could use the

TO-DATE

function to enter a date:

INSERT INTO order_table (order_id, order_date) values (2,

TO_DATE(’1999-08-20 10:20:01’, ’YYYY-MM-DD HH24:MI:SS’));

Using Bind Entries

Bind entries are specific only to the stmt {}

that contains them. For example, if you want to insert three rows into

REPLYTEST

, you need to have three stmt {}

blocks (and thus, three sets of bind

statements): request: {

stmt={ sql="INSERT INTO REPLYTEST (id, timestamp, bincol) VALUES (5, ?, ?)" bind={ column="REPLYTEST.TIMESTAMP" data="1991-10-10 12:10:10"} bind={ column="REPLYTEST.BINCOL" data=[3 opaque bytes]}}

stmt={ sql="INSERT INTO REPLYTEST (id, timestamp, bincol) VALUES (5, ?, ?)" bind={ column="REPLYTEST.TIMESTAMP" data="1991-11-10 12:10:10"} bind={column="REPLYTEST.BINCOL" data=[4 opaque bytes]}}

stmt={ sql="INSERT INTO REPLYTEST (id, timestamp, bincol) VALUES (5, ?, ?)" bind={ column="REPLYTEST.TIMESTAMP" data="1991-12-10 12:10:10"} bind={ column="REPLYTEST.BINCOL" data=[5 opaque bytes]}}}

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

118 | Chapter 7 Using the Request-response Service

TIBCO ActiveEnterprise or XML Message Response Format

In the TIBCO ActiveEnterprise Message or XML format, the input class is

SQL_BATCHRETURN. This class is described in

SQL_ BATCHRETURN Class on page 125

TIBCO Rendezvous Message Response Format

If rv_SendWithReply()

or rv_Rpc()

is used to send the request, the response is sent back on the subject or Inbox that was associated with the request.

If rv_Send()

is used to send the request, because no response subject was specified with the request, the response subject set when the adapter was configured is used. To receive a response from the adapter, the client application must listen on the response subject.

The structure of a response message in TIBCO Rendezvous Message format is shown below.

{ rv_Name = “status” rvmsg_Type = RVMSG_INT rvmsg_Data = 0 rv_Name = “results” rvmsg_Type = RVMSG_RVMSG rvmsg_Data =

Result rv_Name = “closure”, rvmsg_Type = RVMSG_OPAQUE, rvmsg_Data = optional_closure_data

} where

Result

is a message in TIBCO Rendezvous Message format of the following structure:

Result

{ name = “row” type = RVMSG_RVMSG value =

List_of_columns name = “row” type = RVMSG_RVMSG value =

List_of_columns

. . .

} where

List_of_columns

is a message in TIBCO Rendezvous Message format of the following structure:

List_of_columns

{ rv_Name = column_name

, rvmsg_Type = type_of_bound_data

, rvmsg_Data = value_of_bound_data rv_Name = column_name

, rvmsg_Type = type_of_bound_data

, rvmsg_Data = value_of_bound_data rv_Name = column_name

, rvmsg_Type = type_of_bound_data

, rvmsg_Data = value_of_bound_data

. . .

}

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Request-response Mode | 119

If the request processing was not successful, the response could also return an error code and error description as shown next:

{ rv_Name = “status” rvmsg_Type = RVMSG_INT rvmsg_Data = nonzero_number rv_Name = “sql” rvmsg_Type = RVMSG_STRING rvmsg_Data =

SQL_statement_that_caused_error rv_Name = “error” rvmsg_Type = RVMSG_STRING rvmsg_Data = error_text rv_Name = “closure”, rvmsg_Type = RVMSG_OPAQUE, rvmsg_Data = optional_closure_data

}

The status

value is an integer specifying success or error. Possible values are:

0: ok // No error

1: noMem // Out of Memory

2: notInitialized // Object never initialized

3: typeConversion // Type conversion error

4: dbNotFound // Database not registered

5: serverError // Error reported by server

6: serverMessage // Message from server

7: vendorLib // Error in vendor's library

8: notConnected // Lost connection

9: endOfFetch // End of fetch

10: invalidUsage // invalid usage of object

11: columnNotFound // Column does not exist

12: invalidPosition // invalid positioning within

object,i.e.bounds err

13: notSupported // Unsupported feature

14: nullReference // Null reference parameter

15: notFound // Database Object not found

16: missing // Required piece of information is missing

17: noMultiReaders // This object cannot support multiple readers

18: noDeleter // This object cannot support deletions

19: noInserter // This object cannot support insertions

20: noUpdater // This object cannot support updates

21: noReader // This object cannot support readers

22: noIndex // This object cannot support indices

23: noDrop // This object cannot be dropped

24: wrongConnection // Incorrect connection was supplied

25: noPrivilege // This object cannot support privileges

26: noCursor // This object cannot support cursors

27: cantOpen // Unable to open

28: applicationError // For errors produced at the application level

29: notReady // For future use

Example TIBCO Rendezvous Message Responses

This section has two examples. The first shows a successful query response and the second shows an unsuccessful query response.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

120 | Chapter 7 Using the Request-response Service

Query Example

As an example, assume the SQL statement,

SELECT * FROM ORDER_TABLE

produces the following result:

SQL> SELECT * FROM ORDER_TABLE;

ORDER_ID ORDER_DESCRIPTION ORDER_PRICE

1 Order 1 1.00

2 Order 2 2.00

In this case, the self-describing message in TIBCO Rendezvous Message format produced by the adapter would have the following structure:

{ name = “closure” value = optional_closure_argument name = “status” value = 0 name = “results” value =

{

name = “row” value =

{

name = “order_id” type = RVMSG_INT value = 1

name = “order_description” type = RVMSG_STRING value = “Order 1”

name = “order_price” type = RVMSG_REAL value = 1.00

}

name = “row” value =

{

name = “order_id” type = RVMSG_INT value = 2

name = “order_description” type = RVMSG_STRING value = “Order 2”

name = “order_price” type = RVMSG_REAL value = 2.00

}

Error Example

If the request that was processed resulted in an error, the adapter returns a message containing an error code and description as shown below. In this example, assume the

SQL statement

SELECT * FROM ORDER_TABLE

produced an error because there was no table named

ORDER_TABLE

defined in the database:

SQL> SELECT * FROM ORDER_TABLE;

SELECT * FROM ORDER_TABLE

ERROR at line 1:

ORA-00942: table or view does not exist

The self-describing message produced by the adapter would have the following structure:

{ name = “closure” value = optional_closure_argument

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

name = “status” value = 5 name = “sql” value = “SELECT * FROM ORDER_TABLE” name = "error" value = "[INTERSOLV][ODBC SequeLink driver][DB2/400]ORDER_TABLE in *LIBL type *FILE not found.

}

Request-response Mode | 121

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

122 | Chapter 7 Using the Request-response Service

RPC Mode

TIBCO ActiveMatrix Adapter for Database uses the TIBCO Adapter SDK Operations

API for RPCServer.

In TIBCO Designer, you can configure an adapter to act as an RPC (remote procedure call) server on behalf of a client. Selecting RPC mode creates an object in the repository describing the RPC server that the adapter instance will start.

This section presents the structure of the TIBCO Repository class objects that provide

MOperation

support. Based on these class descriptions, you can create an RPC client to send requests to the adapter in the expected structure.

For convenience, class structure is shown in XML format.

Schema Types

Two schema types can be used for the server object created in the repository. For

Standard RPC Operation

, the standard request and reply object schema are pre-defined by TIBCO ActiveMatrix Adapter for Database. This schema can be used to describe the input and output of any database request, allowing a request/response service to process database operations on any tables or execute any stored procedures.

In some cases, using a standard schema can make the request/reply service difficult to integrate with third-party applications, as standard request and reply object schema do not describe the actual input and output values of a database operation or a stored procedure.

The third-party application has to do its own parsing and mapping of the request and reply

objects. The

Custom RPC Operation

, which allows you to define your operations, can be

used in these situations. You can specify the stored procedure to be executed at design time. These operation definitions are stored in the repository in a way that allows easy integration with other applications.

One-way and Two-way Invocation

An RPC operation uses two-way invocation by default, in which it expects a reply from the server. You can make an RPC operation use one-way invocation, where no reply is expected by the server.

Standard RPC Operation

The repository contains descriptions of the classes and operations provided for

MOperation support.

The

SQL_OPS

class describes the operations that the adapter instance, acting as an RPC server, can handle.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

RPC Mode | 123

The structure of the server object is:

<rvCmRpcServer

name = " agentName reqreprvcmRPCServer"

session = " agentName pubreqreprvcmRvCmSession"

subject = "ADB.SDK.OPERATION"

classRef = "SQL_OPS"

</servers>

Two types of operations are supported,

SQL_EXECUTE

and

SQL_BATCHEXECUTE

SQL_EXECUTE

takes a single SQL statement and processes it.

SQL_BATCHEXECUTE

takes a sequence of SQL statements and processes them. The other classes, such as

SQL_STATEMENT

SQL_BIND

, and

SQL_RETURN

, describe metadata for the input and output parameters to the operations.

• Use

SQL_BATCHEXECUTE

to send one or more SQL statements in a request.

•

SQL_BATCHRETRUN

is the return class.

• If an error occurs while executing a statement, the adapter returns the error immediately without executing the remaining statements.

• On Oracle only, all statements are executed within the same transaction.

SQL_OPS Class

The structure of the

SQL_OPS

class is:

<class

name = "SQL_OPS">

<operation

name = "SQL_EXECUTE"

returnClass = "SQL_RETURN">

</operation>

<operation

name = "SQL_BATCHEXECUTE"

returnClass = "SQL_BATCHRETURN">

</operation>

</class>

SQL_RESULTSET Class

The structure of the

SQL_RESULTSET

class is:

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

124 | Chapter 7 Using the Request-response Service

</attribute>

</attribute>

</attribute>

</class>

SQL_ROW Class

The structure of the

SQL_ROW

class is:

</attribute>

</class>

SQL_RETURN Class

The structure of the

SQL_RETURN

class is:

</assoc>

</assoc>

</assoc>

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

RPC Mode | 125

</assoc>

</assoc>

</object>

SQL_RETURNVALUE

</assoc>

</assoc>

</object>

SQL_ BATCHRETURN Class

The structure of the

SQL_BATCHRETURN

class is:

</attribute>

</attribute>

</attribute>

</attribute>

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

126 | Chapter 7 Using the Request-response Service

<attribute name = "CLOSURE" class = "any"

</attribute>

</class>

SQL_BIND Class

The structure of the

SQL_BIND

class is:

</attribute>

</attribute>

</attribute>

</attribute>

</class>

SQL_STATEMENT Class

The structure of the

SQL_STATEMENT

class is:

</attribute>

</attribute>

<attribute name = "CLOSURE" class = "any"

</attribute>

</attribute>

</class>

Custom RPC Operation

When you select Use Custom Operations in the Configuration tab of the

Request-Response dialog, you can create custom schema for your operations. You can define the call operations to be executed by the RPC server in advance. The palette automatically generates the input and output schema for the call operation.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

RPC Mode | 127

The operation takes one input class, REQUEST, which describes the input parameters and other input options for the stored procedure execution. The operation returns a class called

REPLY, which describe the output schema of the stored procedure or any error message the agent returns.

Table 30 Request Schema Description

Input

Item

INBINDS

Data Type or

Classname

INPUT_BINDS

Description

The input parameters of the stored procedure.

OPTIONS INPUT_OPTIONS

The input options:

Option Data Type Description

CLOSURE

Any

MAXROW

Integer The maximum number of rows to retrieve.

SQL

CACHE

String

Boolean

The SQL string use to execute the stored procedure.

This string is automatically generated by the palette.

True if user want the agent to cache the statement for performance optimization

PACKAGE

SCHEMA

String

String read only, uses the call operation form to modify the package of the stored procedure. read only, uses the call operation form to modify the package of the stored procedure.

Closure argument. The reply returns this closure argument untouched.

Table 31 Reply Schema Description

Output Item

OUTBINDS

Data Type or

Classname

OUTPUT_BINDS

RESULTSET[1..n]/RESUL

TSETS

STATUS

OUTPUT_ROWS/

SQL_RESULTSET

String

Description

The output parameters of the stored procedure

The result set(s) returned by the stored procedure, see section

'Result Set Support' for more description

SUCCESS

if the stored procedure is executed successfully.

FAILURE

if there is an error. Error details are stored in the

OPTIONS class

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

128 | Chapter 7 Using the Request-response Service

Table 31 Reply Schema Description (Cont’d)

Output Item

Data Type or

Classname

OPTIONS CUSTOM_OP_OUTPUT_OP

TION

CLOSURE

Any

Description

Contains the error description and the SQL statement if an error occurred.

Closure argument obtained from the request

Resultset Support

TIBCO ActiveMatrix Adapter for Database supports multiple resultsets returned for a stored procedure. The class generated for the resultset output depends on the schema information provided by the JDBC driver.

• For drivers that return valid information of a resultset schema, ADB creates an output class, named

OUTPUT_ROW[1..n]

, for each result set. This is shown in the screen below.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

RPC Mode | 129

• If a driver does not return valid information for the resultset schema, TIBCO

ActiveMatrix Adapter for Database uses the generic class

SQL_RESULTSETS

as the output schema, as described in

Standard RPC Operation on page 122

DataDirect JDBC 3.3 drivers only provide valid resultset schema information for Oracle

Server version 8.1.7 or higher.

Implementing Client RPC Programs

Two sample clients are provided in the

TIB_ADADB_HOME

\demo\operation

directory:

• a sample C++ client program that you can build and change

• a sample RPC client

Creating a Custom RPC Client

There are two tasks in creating a custom RPC client:

1. Write an RPC client program using the TIBCO Adapter SDK. This task is described in

TIBCO Adapter SDK Programmer’s Guide.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

130 | Chapter 7 Using the Request-response Service

2. Create a new entry for the RPC client in the repository. This task is described below.

For more information on RPC server and client endpoint type fields, see TIBCO Designer

Palette Reference.

To create a new RPC client entry in the repository:

Perform these steps after writing the client program and configuring the adapter, as described above. Detailed instructions for configuring a generic adapter are in TIBCO

Designer User’s Guide.

1. In TIBCO Designer, drag a Generic Adapter Configuration icon to the design panel.

2. Enter an Instance Name and an SDK AppName for the adapter.

3. Click the Apply button.

4. In the Project panel, expand the GenericAdapterConfiguration folder and expand the Adapter Services folder.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

5. Drag a Request-Response Invocation Service icon to the designer panel.

RPC Mode | 131

6. In the Configuration tab, set the name of the service and transport type of your client service.

7. In the Transport tab, set the message subject, quality of service, and wire format of your client service.

If using the TIBCO Rendezvous message transport, you must use the TIBCO

ActiveEnterprise wire format.

8. In the Schema tab, set the classReference

to point to the correct class schema.

— For a standard RPC schema, use the following class schema:

AESchemas/ae/ADB/adbmetadata/Classes/SQL_OPS

— For custom RPC schema, use the class schema that corresponds to the server endpoint:

AESchemas/ae/ADB/ serviceName

/Classes/ADBServer_OPS

9. Click Apply.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

132 | Chapter 7 Using the Request-response Service

Load Balancing

The adapter balances the load of requests coming in from applications in two ways, within a single adapter instance and across multiple adapter instances.

Load Balancing in a Single Instance Using Threads

An adapter instance performs load balancing within itself by allowing you to specify the number of threads that will be responsible for processing application requests. The number of threads to be spawned is specified in TIBCO Designer for an adapter instance.

To set load balancing parameters for a configuration:

1. In the project tree panel, click the corresponding ActiveDatabase Adapter resource to select it.

The TIBCO Designer window should look similar to the following:

2. Check the Show All Tabs checkbox.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

3. Display the Adapter Services tab.

Load Balancing | 133

4. Change the value of Number Of Request-Response Service Threads as needed.

5. Click the Apply button.

Each request-response service thread is dedicated to listening on an agreed request subject.

1. When a request message is received by the request-response communication thread, it enqueues it into an in-memory queue. Each database request-response thread has a connection to the database using the user name-password combination that was provided to the adapter.

2. When an item is enqueued by the communication thread, one of the database request-response threads picks it up and executes the one or more SQL statements in the message as an atomic transaction.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

134 | Chapter 7 Using the Request-response Service

3. It then composes a TIBCO Rendezvous self-describing response message and sends back a response on a response subject. If the original request was sending using rv_SendWithReply()

or rv_Rpc()

, the response is sent back on the subject that was specified by the requesting application. Otherwise, the response is sent back on the subject that was set up at configuration time.

While the request message can be sent with either reliable or certified quality of service, the response message is always sent back using the reliable quality of service.

Load Balancing Across Adapter Instances

To achieve load balancing across adapter instances, TIBCO Rendezvous Distributed

Queueing can be used to assign each application request to exactly one adapter instance.

For example, the following diagram shows three adapter instances each connected to a database server (not shown) that contains replicated data.

Figure 5 Request-Response Load Balancing

Request

Distributed Queue

Adapter 4

Request

Adapter 1

(Scheduler)

Request

Adapter 3

Adapter 2

TIBCO Messaging

Responses

Application

The adapter instances have been set up to use distributed queueing with one instance acting as the scheduler. Only one of the three adapter instances will receive an incoming request from an application. The scheduler will assign certified requests to the least loaded member of the queue.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Load Balancing | 135

A queue member’s load is determined by the number of pending processes that are waiting to be processed by the member’s database request-response thread. After the request is processed, the processing configuration sends a response back to the requesting application.

Reliable requests in a certified environment use a simpler type of load balancing. In this example, the scheduler distributes the first reliable request to

Adapter 2

, the second to

Adapter

, and the third to

Adapter 4

without evaluating a queue member’s load.

Configuring an Adapter Instance to use Distributed Queues

You can configure the adapter with a subscription service to use a distributed queue, then use TIBCO Administrator Enterprise Edition to deploy multiple instances of the adapter.

The instances can be deployed on the same machine, or multiple machines. In this scenario, each adapter instance uses the same (default) values for the distributed queue.

1. Start TIBCO Designer and create a new project.

2. Drag the ActiveDatabase Adapter Configuration icon to the design panel.

3. Configure the adapter instance with a design-time connection and

ODBC DSN

value.

4. Drag the

ADBSubscriber

icon to the design panel.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

136 | Chapter 7 Using the Request-response Service

5. Under the Configuration tab, set Transport Type to Rendezvous and Quality of

Service to Distributed Queue. For example:

6. Configure the service with a destination table name and other settings for your environment.

7. Click Project > Save.

8. Click Tools > Create Project EAR. Under the Configuration tab, provide a name and file location for the EAR file.

9. Click Build Archive.

After creating the EAR file, you are ready to import it into TIBCO Administrator

Enterprise Edition and add the adapter instance multiple times to the same machine or multiple machines.

1. Start TIBCO Administrator Enterprise Edition.

2. Select Application Management, then click the New Folder button. In

Name

, provide a name for the folder and click the Save button.

3. Select the folder, then click New Application.

4. Click the Browse button and navigate to the EAR file you created in Designer. Click the OK button.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

5. In the dialog that appears, click the Save button.

6. Expand the configuration, then double-click the name

.aar file.

Load Balancing | 137

7. Click the Add To Additional Machine button and select the machine to bind to and click the OK button.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

138 | Chapter 7 Using the Request-response Service

8. Repeat to create the number of adapter instances required for your environment. For example, the next screen shows that three adapter instances have been added.

9. Click the Save button.

The adapter instances are ready to be deployed. After the instances are deployed, when a message is sent to the adapter, the instance that is not busy will handle the request.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Oracle REF Data Type Support | 139

Oracle REF Data Type Support

The adapter supports the use of the REF data type (cursor) as an OUT parameter only in an Oracle stored procedure. The adapter returns a result in the same way as it does a result set from a SELECT query. The exact usage depends on the driver used (DataDirect

Connect or Oracle ODBC), as described below.

For example, consider the following PL/SQL procedure:

-- Create a REF cursor procedure

CREATE OR REPLACE PACKAGE ORDER_DEMO AS

TYPE OrderCurTyp IS REF CURSOR RETURN SUB_ORDER%ROWTYPE;

PROCEDURE FindOrders (price IN NUMBER, order_cv OUT OrderCurTyp);

END ORDER_DEMO;

CREATE OR REPLACE PACKAGE BODY ORDER_DEMO AS

PROCEDURE FindOrders (price IN NUMBER, order_cv OUT OrderCurTyp) IS

BEGIN

OPEN order_cv FOR SELECT * FROM SUB_ORDER where ORDER_PRICE > price;

END FindOrders;

END ORDER_DEMO;

Using DataDirect Connect Drivers

When using DataDirect Connect® (Merant) drivers, the procedure is called by leaving the

REF cursor parameter out of the procedure's call list. For example, the procedure

ORDER_DEMO.FindOrders

with an input price of $1.00 can be called through the request program with the following request:

{stmt={sql="{call ORDER_DEMO.FindOrders(?)}" bind={position=1 type="IN" data=1}}}

The REF cursor's data will be returned in the results section of the reply.

Also,

ProcedureRetResults=1

must be added to the data source entry in the odbc.ini

file.

Using Oracle ODBC Drivers

When using the Oracle ODBC Driver, the procedure is called by including the REF cursor parameters in the call list but not binding them. For example, the procedure

ORDER_DEMO.FindOrders

with an input price of $1.00 can be called through the request program with the following request:

{stmt={sql="{call ORDER_DEMO.FindOrders(?, ?)}" bind={position=1 type="IN" data=1}}}

The REF cursor's data will be returned in the results section of the reply.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

140 | Chapter 7 Using the Request-response Service

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Chapter 8

Working With Tables

This chapter describes advanced features such as the format of a publishing table, stored procedures and the triggers used to populate publishing tables and adapter instance options.

| 141

Topics

•

Publishing Table, page 142

•

Source Table, page 148

•

Exception Table, page 149

•

Opaque Exception Table, page 152

•

Incremental Parent-child Operation, page 154

•

Database Types, page 156

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

142 | Chapter 8 Working With Tables

Publishing Table

Publishing tables mirror tables that you have identified for monitoring. They contain additional columns, primarily a sequence number and delivery status, which are needed by the adapter to detect new rows. You create a publishing table for each table you want to activate using TIBCO Designer.

The trigger generated at design time will automatically populate the values for these additional columns. It is not recommended that you modify these values.

In addition to a copy of the source table’s columns, the publishing table has the following additional columns.

Table 32 Publishing Table Additional Columns (Sheet 1 of 2)

Column Name

ADB_SUBJECT

Type

VARCHAR2(255)

Description

Used to specify the subject to publish the current row. Length is

255. You can set a message subject in this field which will take precedence over the default service subject. The adapter will publish this row with this new message subject.

In group messaging, the group message will be sent to the subject set for the last row of the group.

ADB_SEQUENCE NUMBER(38) Stores the monotonically increasing sequence number that represents new rows in the publishing table. If a column with this name exists, the number is generated automatically.

By default, the schema type is string

. The adapter treats this number as a string. This number can be larger than an integer if the database supports it.

ADB_SET_SEQUENCE

ADB_TIMESTAMP

NUMBER(38)

DATE

Currently not used.

Time of row insertion in publishing table that is used to calculate expiration of rows. The timestamp is generated automatically.

For Oracle databases, the timestamp includes the time zone information.

For all new services:

Microsoft Windows platforms, the timestamp with time zone option should be selected in the Advanced Settings tab of the

ODBC connection.

Unix platforms, the LocalTimeZoneOffset parameter in the odbc.ini should be set to the local time zone. For example,

LocalTimeZoneOffset=+10:00.

Also the EnableTimestampWithTimeZone parameter in the odbc.ini file should be set to 1.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Publishing Table | 143

Table 32 Publishing Table Additional Columns (Sheet 2 of 2)

Column Name

ADB_TRACKINGID

Type

VARCHAR2(40)

Description

Tracking ID of the message.

This is automatically added to the publishing table and the publishing schema.

If you do not want to monitor the tracking id, you can manually remove this field from the project schema and the publishing table

ADB_OPCODE NUMBER(38) Operation code used by an adapter instance:

indicates INSERT.

indicates UPDATE.

indicates DELETE.

indicates UPSERT. UPDATE if row exists, otherwise INSERT.

indicates BYPASS (See Incremental Parent-child Operation on page 154 )

If an incoming TIBCO Rendezvous message does not have an operation code, an INSERT occurs.

ADB_UPDATE_ALL

ADB_REF_OBJECT

ADB_L_DELIVERY_STAT

ADB_L_CMSEQUENCE

ADB_MARK

ADB_INSTANCEID

NUMBER(38)

VARCHAR2(64)

CHAR(1)

NUMBER(38)

VARCHAR2(64)

VARCHAR2(200)

Currently not used.

When publish by reference object is used, contains the name of the reference object that provides source data.

Delivery status of a TIBCO Rendezvous message:

indicates pending acknowledgement.

indicates that a new message has arrived, but has not yet been published.

indicates complete.

indicates failed.

Certified messaging sequence number associated with this message.

It is a number that is retrieved from the publication load balancing mutex table when the service instance is started. It represents an identifier of each adapter instance in the publication load balancing group.

It is the adapter instance ID configured by the user.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

144 | Chapter 8 Working With Tables

When publishing parent-child record or in Publish By Reference mode, if the key value is empty (null) in the publishing table, the adapter will consider this as an error operation, and update the failure status in the publication table by setting adb_l_delivery_status

. The data will not be published.

The publication table cannot contain any user-created columns where the column name starts with

ADB_

. These characters are reserved for adapter use.

Removing Records from the Publication Table

An adapter instance does not remove the records from the publication table automatically, because often that information must be retained for auditing reasons. You can use the following command at the SQL prompt to manually remove records from the given publishing table. The command deletes all rows where ADB_L_DELIVERY_STATUS is

SQL> delete from publication_table_name

where ADB_L_DELIVERY_STATUS = "C" or

ADB_L_DELIVERY_STATUS = "F";

To automate the process, you could include this statement in a trigger.

Publication Example

The following is a listing of the SQL commands used to create a publication. The listing can be found in the

TIB_ADADB_HOME

\demo\demo1\demo_ database

.sql

file. The file shows the stored procedure, and insert, update and delete triggers that are generated for a publication.

-- *******************************************

-- TIBCO ActiveMatrix Adapter for Database

-- Demo SQL script

-- *******************************************

-- Spool the output of sql commands to a log file spool demo.log

-- *******************************************

-- Create sample tables

-- *******************************************

-- Publication source table

CREATE TABLE ORDER_TABLE (

ORDER_ID NUMBER PRIMARY KEY,

ORDER_DESCRIPTION VARCHAR2(128),

ORDER_PRICE NUMBER(10,3)

);

-- Create the destination table

CREATE TABLE SUB_ORDER (

ORDER_ID NUMBER PRIMARY KEY,

ORDER_DESCRIPTION VARCHAR2(128),

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Publishing Table | 145

ORDER_PRICE NUMBER(10,3)

);

-- *******************************************

-- Setup a publication

-- *******************************************

)

CREATE TABLE PUB_ORDER (

ORDER_ID NUMBER,

ORDER_DESCRIPTION VARCHAR2(128),

ORDER_PRICE NUMBER(10,3),

ADB_SUBJECT VARCHAR2(255) NULL,

ADB_SEQUENCE INTEGER NOT NULL,

ADB_SET_SEQUENCE INTEGER NULL,

ADB_TIMESTAMP DATE NULL,

ADB_OPCODE INTEGER NOT NULL,

ADB_UPDATE_ALL INTEGER NULL,

ADB_REF_OBJECT VARCHAR2(64) NULL,

ADB_L_DELIVERY_STATUS CHAR NULL,

ADB_L_CMSEQUENCE NUMBER(38, 0) NULL

CREATE UNIQUE INDEX IDX1_PUB_ORDER ON PUB_ORDER (ADB_SEQUENCE)

CREATE UNIQUE INDEX IDX2_PUB_ORDER ON PUB_ORDER (ADB_L_DELIVERY_STATUS,

ADB_SEQUENCE)

CREATE INDEX IDX3_PUB_ORDER ON PUB_ORDER (ADB_L_CMSEQUENCE)

CREATE SEQUENCE PUB_ORDER_SEQ

START WITH 1

INCREMENT BY 1

NOMAXVALUE

NOCYCLE

CACHE 10

CREATE OR REPLACE TRIGGER TRI_PUB_ORDER AFTER INSERT OR DELETE OR UPDATE ON

ORDER_TABLE FOR EACH ROW DECLARE updating_key_fields EXCEPTION;

BEGIN

IF INSERTING THEN

INSERT INTO PUB_ORDER VALUES (

:NEW.ORDER_ID,

:NEW.ORDER_DESCRIPTION,

:NEW.ORDER_PRICE,

NULL,

PUB_ORDER_SEQ.NEXTVAL,

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

146 | Chapter 8 Working With Tables

SYSDATE,

NULL,

'N',

-1);

END IF;

IF UPDATING THEN

IF UPDATING('ORDER_ID') THEN

RAISE updating_key_fields;

END IF;

INSERT INTO PUB_ORDER VALUES (

:OLD.ORDER_ID,

:NEW.ORDER_DESCRIPTION,

:NEW.ORDER_PRICE,

NULL,

PUB_ORDER_SEQ.NEXTVAL,

SYSDATE,

NULL,

'N',

-1);

END IF;

IF DELETING THEN

INSERT INTO PUB_ORDER VALUES (

:OLD.ORDER_ID,

:OLD.ORDER_DESCRIPTION,

:OLD.ORDER_PRICE,

NULL,

PUB_ORDER_SEQ.NEXTVAL,

SYSDATE,

NULL,

'N',

-1);

END IF;

EXCEPTION

WHEN updating_key_fields THEN raise_application_error(-20300, 'ActiveDB Error: cannot

END TRI_PUB_ORDER;

-- *******************************************

-- Setup a subscription

-- ******************************************* update key fields of source table.');

CREATE TABLE SUB_ORDER_EXCEP (

ORDER_ID NUMBER,

ORDER_DESCRIPTION VARCHAR2(128),

ORDER_PRICE NUMBER(10,3),

ADB_OPCODE INTEGER NULL,

ADB_UPDATE_ALL INTEGER NULL,

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Publishing Table | 147

)

ADB_ERROR_TEXT VARCHAR(4000) NULL,

ADB_ERROR_TIME DATE DEFAULT SYSDATE

COMMIT;

Changing the Publication Trigger to Publish a Subset of Rows

You can set up a publication to publish only a subset of the rows within a table. That is, there may be scenarios where it is desirable to publish only if the inserted, deleted, or updated row satisfies certain conditions. While it is possible to use the callout library to do this additional filtering, it is simpler and more efficient to use a trigger that directly tests whether publishing conditions are met.

For Oracle, add a when

clause to a row level trigger to test for the desired conditions. For

Sybase and Microsoft SQL Server, use the if

statement within a trigger body to test for the desired conditions.

For example, you could change the demo.sql

trigger described in the previous section to fire only if the ORDER_PRICE value is $1.00 or greater:

CREATE OR REPLACE TRIGGER TRI_P_ORDER_TABLE AFTER INSERT OR UPDATE OR DELETE ON

ORDER_TABLE

FOR EACH ROW WHEN (new.ORDER_PRICE >= 1.00)

Optimizing the Publication Sequence for Oracle RAC System

To optimize the performance and to avoid out of order generation of ADB_SEQUENCE, it is recommended that you add the ORDER option and also increase the cache size.

Consult your system administrator to confirm the impact of these changes.

CREATE SEQUENCE PUB_ORDER_SEQ

START WITH 1

INCREMENT BY 1

NOMAXVALUE

ORDER

NOCYCLE

CACHE 50

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

148 | Chapter 8 Working With Tables

Source Table

If loop detection is enabled, the following column will be added to the source table.

If the source table contains a field

ADB_TRACKINGID

, it will be updated using the tracking id of the message. If this field is not present, the tracking id field will be ignored..

Table 33 Source Table Additional Columns

Column Name

ADB_SOURCE

Type

CHAR

Description

Used for loop detection. Denotes whether the row was inserted or updated as the result of a TIBCO Rendezvous message, rather than user intervention.

Valid values are

NULL

indicates the row is not to be published.

NULL

indicates the row can be published.

ADB_TRACKINGID VARCHAR2(

40)

Tracking ID of the message.

The source table cannot contain any user-created columns where the column name starts with

ADB_

. These characters are reserved for adapter use.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Exception Table | 149

Exception Table

If a database restriction or failure occurs, an exception table can be configured to receive the message. If insertion into an exception table also fails, an error message will display and the adapter instance will terminate. You can build a TIBCO Hawk rulebase that detects when the configuration is down and automatically restarts it when the database is up. See TIBCO Hawk Administrator’s Guide for details about creating a rulebase.

For bulk insert operations, the agent will insert all the rows into the exception table. For example, if the agent attempts to perform a bulk insert of 500 rows to the destination table, and the first 300 rows are inserted successfully but the last 200 rows are unsuccessful, the agent will insert all 500 rows to the exception table. It will then commit the operation.

(The bulk insert operation is described in

Adapter Services Tab on page 43

In addition to destination table columns, the following columns are added to the exception table.

Table 34 Exception Table Additional Columns

Column Name

ADB_OPCODE

Type

NUMBER(38)

Description

Operation code used by the adapter:

1 indicates INSERT

2 indicates UPDATE

3 indicates DELETE

4 indicates UPDATE if row exists, otherwise INSERT.

If an incoming TIBCO Rendezvous message does not have an operation code, an INSERT occurs.

ADB_UPDATE_ALL

ADB_TRACKINGID

ADB_ERROR_TEXT

NUMBER(38)

VARCHAR2(40)

VARCHAR2(4000)

Currently not used.

Tracking ID of the message. This column is the primary key.

Each exception table that is mapped to a child table is connected to the parent’s exception table by this column

Text of the error from the database server, ODBC driver, or other source that caused the exception.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

150 | Chapter 8 Working With Tables

Table 34 Exception Table Additional Columns (Cont’d)

Column Name

ADB_ERROR_TIME

Type

DATE

Description

Timestamp of the inserted record.

For Oracle databases, the timestamp includes the time zone information.

For all new services:

Microsoft Windows platforms, the timestamp with time zone option should be selected in the Advanced Settings tab of the

ODBC connection.

Unix platforms, the LocalTimeZoneOffset parameter in the odbc.ini should be set to the local time zone. For example,

LocalTimeZoneOffset=+10:00

Also the EnableTimestampWithTimeZone parameter in the odbc.ini file should be set to 1.

ADB_JOIN_ID VARCHAR Joined column used to link a parent record with its child record.

ADB_JOIN_ID is generated from ADB_TRACKINGID and concatenated with the record number in the group. A child table’s exception table is connected to its parent’s table exception table by ADB_JOIN_ID.

The exception table cannot contain any user-created columns where the column name starts with

ADB_

. These characters are reserved for adapter use.

Child Exception Table

In addition to child table columns, the following columns are added to a child exception table.

Table 35 Child Exception Table Additional Columns

Column Name

ADB_ERROR_TEXT

Type

VARCHAR

Description

Text of the error from the database server, ODBC driver, or other source that caused the exception.

ADB_ERROR_VTIME

ADB_TRACKINGID

ADB_JOIN_ID

DATE

VARCHAR

Timestamp of the inserted record.

TrackingID of the message.

Tracking ID of the Message.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Exception Table | 151

Using an Exception Table as a Source Table

If you want to publish from an exception table and also want to use that exception table as the source table, do not use the

ADB_ERROR_TEXT

ADB_OPCODE

column names. Instead, follow these guidelines:

• Create a database view that mirrors the exception table, but rename the

ADB_ERROR_TEXT

and

ADB_OPCODE

columns so that they do not begin with

"ADB_

•

After renaming the columns, use Publish By Reference Object (see

Publishing by

Reference Object, page 171

) and choose your view as the reference object.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

152 | Chapter 8 Working With Tables

Opaque Exception Table

The subscription service uses two logical layers when processing a message. The first layer decodes data from the message and the second layer provides the database transaction. If an exception occurs in the first layer, the adapter logs the message to the opaque exception table. In the second layer, if any DML command fails at any level, the adapter rolls back this transaction and starts another transaction, inserting into exception tables. If the insert into exception table transaction fails, the adapter then logs the message to the opaque exception table.

The opaque exception table records the entire message into a column along with the error message. The opaque exception table has the following columns:

Table 36 Opaque Exception Table Columns

Column Name

ADB_TRACKINGID

Type

VARCHAR

Description

Tracking ID of the message.

ADB_ERROR_TEXT VARCHAR Text of the error from the database server,

ODBC driver, Adapter SDK or other source that caused the exception.

ADB_ERROR_TIME DATE

ADB_MSG

ADB_SUBTAB

ADB_SUBJECT

BLOB

VARCHAR

Timestamp of the inserted record.

For Oracle databases, the timestamp includes the time zone information.

For all new services:

Microsoft Windows platforms, the timestamp with time zone option should be selected in the

Advanced Settings tab of the ODBC connection.

Unix platforms, the LocalTimeZoneOffset parameter in the odbc.ini should be set to the local time zone. For example,

LocalTimeZoneOffset=+10:00

Also the EnableTimestampWithTimeZone parameter in the odbc.ini file should be set to 1.

Raw bytes of the message.

Destination table name.

Subscription service destination or subject.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Opaque Exception Table | 153

Table 36 Opaque Exception Table Columns (Cont’d)

Column Name

ADB_TRANSPORT

Type

INT

Description

Subscription service transport type:

0 unknown

1 Rendezvous

2 JMS

The ADB_SUBTAB column allows you to configure several subscription services using only one opaque exception table in the same database schema.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

154 | Chapter 8 Working With Tables

Incremental Parent-child Operation

To support incremental parent-child operations, each child row has an opcode, that is, an extra

ADB_OPCODE

field that is added to the child schema. The opcode

ADB_OPCODE_BYPASS is used to bypass the current table operation. The adapter determines if the operation is an incremental parent-child operation by checking the first level child opcode. If the first level child opcode is not set, the adapter treats it as a complete operation. For the subsequence child level, if the child opcode is not set, it will inherit the parent opcode.

Mixed parent-child operations are also supported. You can send a message to insert new child rows, update other child rows, and delete other child rows for an existing parent-child object. Following is an example of a mixed parent-child operation: adb.key

{

RVMSG_INT 2 ^type^ 1

RVMSG_INT 2 ^pfmt^ 10

RVMSG_INT 2 ^ver^ 30

RVMSG_INT 2 ^encoding^ 1

RVMSG_RVMSG 110 ^prefixList^

{

RVMSG_STRING 49 1 "/tibco/public/sequence/ae/class/ae/ADB/abc"

RVMSG_STRING 37 default "/tibco/public/class/ae/ADB/abc"

}

RVMSG_RVMSG 77 ^tracking^

{

RVMSG_STRING 30 ^id^ "Gi2--4--DGMSk--s-064zzw8L-zzw"

RVMSG_STRING 22 ^1^ "adb.key"

}

RVMSG_RVMSG 1200 ^data^

{

RVMSG_STRING 8 ^class^ "S_KEYP1"

RVMSG_INT 4 ADB_OPCODE 10

RVMSG_RVMSG 480 ADB_SEQUENCE_S_KEYP2

{

RVMSG_STRING 18 ^class^ "sequence[S_KEYP2]"

RVMSG_INT 4 ^idx^ 1

RVMSG_RVMSG 210 ^1^

{

RVMSG_STRING 8 ^class^ "S_KEYP2"

RVMSG_INT 4 ADB_OPCODE 10

RVMSG_RVMSG 119 ADB_SEQUENCE_S_KEYP3

{

RVMSG_STRING 18 ^class^ "sequence[S_KEYP3]"

RVMSG_INT 4 ^idx^ 1

RVMSG_RVMSG 58 ^1^

{

RVMSG_STRING 8 ^class^ "S_KEYP3"

RVMSG_INT 4 ADB_OPCODE 4

RVMSG_REAL 8 A 1

RVMSG_STRING 2 B "a"

RVMSG_REAL 8 C 4

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Incremental Parent-child Operation | 155

}

RVMSG_RVMSG 58 ^2^

{

RVMSG_STRING 8 ^class^ "S_KEYP3"

RVMSG_INT 4 ADB_OPCODE 3

RVMSG_REAL 8 A 1

RVMSG_STRING 2 B "a"

RVMSG_REAL 8 C 4

}

RVMSG_RVMSG 210 ^2^

{

RVMSG_STRING 8 ^class^ "S_KEYP2"

RVMSG_INT 4 ADB_OPCODE 1

RVMSG_REAL 8 A 2

RVMSG_STRING 2 B "a"

RVMSG_REAL 8 C 4

RVMSG_RVMSG 119 ADB_SEQUENCE_S_KEYP3

{

RVMSG_STRING 18 ^class^ "sequence[S_KEYP3]"

RVMSG_INT 4 ^idx^ 1

RVMSG_RVMSG 58 ^1^

{

RVMSG_STRING 8 ^class^ "S_KEYP3"

RVMSG_REAL 8 A 2

RVMSG_STRING 2 B "a"

RVMSG_REAL 8 C 4

}

When the adapter receives this message, it performs the following database operations in sequence:

1. Bypass the parent table operation

2. Bypass first row operation on child table S_KEYP2

3. UPDATE S_KEYP3 set B = 'a', C = 4 where A = 1;

4. DELETE FROM S_KEYP3 where A = 1;

5. INSERT INTO S_KEYP2 (A, B, C) values (2, 'a', 4);

6. INSERT INTO S_KEYP3 (A, B, C) values (2, 'a', 4);

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

156 | Chapter 8 Working With Tables

Database Types

The database data types listed in this section are supported.

Oracle

The following Oracle data types are supported:

• CHAR

• DATE

• LONG

• LONG RAW

• NUMBER

• TIMESTAMP WITH

TIMEZONE

•

NCHAR

DECIMAL

• XMLType

•

TIMESTAMP

RAW

VARCHAR2

CLOB

BLOB

• TIMESTAMP

WITH LOCAL

TIMEZONE

• NVARCHAR2

• NCLOB

The following ANSI data types in Oracle are supported:

• DOUBLE PRECISION

• FLOAT

• INT

•

INTEGER

SMALLINT

REAL

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Database Types | 157

SQL Server

Sybase and Sybase Adaptive Server Anywhere

The following Sybase data types are supported:

• BINARY

• BIT

• CHAR

• DATETIME

• DECIMAL

• FLOAT

• IMAGE (Publish by reference only)

• INT

• MONEY

• NUMERIC

• REAL

• SMALLDATETIME

• SMALLINT

• SMALLMONEY

• TEXT

• TINYINT

• VARCHAR

• VARBINARY

• BIGINT

• NCHAR

• NVARCHAR

DB2

The following SQL Server data types are supported:

• BIGINT

• BINARY

• BIT

•

CHAR

DATETIME

DECIMAL

FLOAT

IMAGE (Publish by reference only)

•

INT

MONEY

NCHAR

• NTEXT

• NUMERIC

• NVARCHAR

• REAL

• SMALLDATETIME

• SMALLINT

• SMALLMONEY

• TEXT (publish by reference only)

• TIMESTAMP

• TINYINT

• UNIQUEIDENTIFIER

• VARBINARY

• VARCHAR

The following DB2 data types are supported:

• CHARACTER

• DECIMAL

• DOUBLE PRECISION

• FLOAT

• INTEGER

• LONG VARGRAPHIC

•

NUMERIC

REAL

SMALLINT

TIMESTAMP

VARCHAR

LONG VARCHAR

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

158 | Chapter 8 Working With Tables

• DATE

• BIGINT

• BLOB

• DOUBLE

MySQL

• TIME

• CLOB

• CHAR

The following MySQL data types are supported:

•

BLOB

LONGBLOB

MEDIUMBLOB

TINYBLOB

BIT

BIGINT

MEDIUMINT

TINYINT

SMALLINT

INT

CHAR

VARCHAR

BINARY

BOOL

• DATETIME

• DATE

• TIMESTAMP

• TIME

• YEAR

• VARBINARY

• ENUM

• SET

• TEXT

• LONGTEXT

• MEDIUMTEXT

• TINYTEXT

• FLOAT

• DECIMAL

• DOUBLE

Teradata

The following Teradata data types are supported:

• BYTE

• BYTEINT

• DECIMAL(n,p)

• SMALLINT

• INTEGER

• NUMERIC(n,p)

•

CHAR(n)

VARCHAR(n)

VARBYTE

LONG VARCHAR

DATE

TIME(n)

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Database Types | 159

• FLOAT(n)

• REAL

• DOUBLE PRECISION

• TIME(n) WITH TIME

ZONE

• TIMESTAMP(n)

• TIMESTAMP(n) WITH

TIME ZONE

Mapping to Database Types

The adapter converts values fetched from the database to types supported by the wire format. Similarly, data fields received in a message must be converted to meaningful database types before being stored.

The following table shows the mapping used by the adapter for such conversion.

Table 37 Mapping to Database Types

ODBC Type

TIBCO

ActiveEnterprise

Type string SQL_CHAR

SQL_VARCHAR

SQL_LONGVARCHAR i4 SQL_SMALLINT

SQL_INTEGER

SQL_REAL

SQL_DOUBLE

SQL_FLOAT

SQL_DECIMAL

SQL_NUMERIC

SQL_BINARY

SQL_VARBINARY

SQL_LONGVARBINARY

SQL_TIMESTAMP r8 binary dateTime

TIBCO Rendezvous

Message Type

RVMSG_STRING

RVMSG_INT

RVMSG_REAL

RVMSG_OPAQUE

RVMSG_DATETIME

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

160 | Chapter 8 Working With Tables

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Chapter 9

Advanced Features

Topics

•

Subject and Destination Names, page 163

•

Preregistering a Certified Subscriber, page 167

•

Changing the Location of the Ledger File, page 169

•

Sending Messages to an Adapter Instance, page 170

•

Publishing by Reference Object, page 171

•

User Callout Library, page 179

•

Unique Connection Identifier for Oracle Databases, page 185

•

Publishing in a Commitment Controlled Environment, page 186

•

Using the Adapter with a Revision Control System, page 188

•

Using a Log File for an Adapter Instance, page 189

•

Using Database Deployment and Cleanup Scripts, page 194

•

Changing the SQL Statement Terminator (DB2 for z/OS Only), page 197

•

Fault Tolerance, page 198

•

SSL Data Encryption using DataDirect ODBC Drivers, page 200

•

OS Authentication, page 201

•

Query Timeout, page 202

•

Working with Multi-File Format Projects, page 203

•

Subscriber Reply Sender, page 204

•

Subscriber Pre-commit Stored Procedure Call, page 205

•

JMS Durable Subscriber Name, page 206

•

Runtime Schema, page 207

•

Runtime Table Schema Configuration, page 208

•

Group Message Transaction, page 209

•

Load Balancing and Multithreading, page 210

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

| 161

162 | Chapter 9 Advanced Features

•

Compressing JMS Messages, page 219

•

Configuring RVCMQ Backlog Size, page 220

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Subject and Destination Names | 163

Subject and Destination Names

An adapter instance sends and receives messages using subject names when using the

TIBCO Rendezvous transport type, and destination names when using the JMS transport type. Both subject and destination names are structured strings of alphanumeric characters divided into elements by the dot (

) character. For example,

Tibco.Tsi

and

News.Sports.Baseball

are valid subject and destination names.

Default subject or destination names are provided in TIBCO Designer. You can change these default values to specify a custom subject or destination name. A default subject or destination, depending on which transport type you choose to configure, is created each time an adapter service is created.

The following are restrictions on subject names and destination names:

• Length of subject and destination names

— Subject names are limited to a total length of 255 characters (including the dot delimiters). Even though TIBCO Rendezvous has a 255-character subject length limit, it is very unlikely that applications will need to use the full length. If you want to run an adapter instance against Microsoft SQL Server, you must design your subject space to conform to the length restrictions. There can be at most 100 elements in a subject name. The maximum element length is 127 characters.

— Destination names are limited to a total length of 249 characters. Even though JMS has a 249-character destination length limit, some of that length is reserved for internal use. The destination space must be designed to conform to the length restrictions. There can be at most 64 elements in a destination name. The maximum element length is 127 characters. Dot separators are not included in element length.

• Wildcard characters

The asterisk (

) and greater than (

) are wildcard characters that can be used when specifying subject names or destination names.

For example, if messages are published on the tsi.sales.sports

and tsi.sales.clothing

subjects and your subscriber adapter listens on the tsi.sales.* subject, the configuration will get messages sent on both subjects. This feature also applies to destination names.

• Reserved underscore (

)

Subject or destination names beginning with underscore (

) are reserved. Application programs cannot send subjects or destinations with an underscore as the first character of the first element, however,

_INBOX

and

_LOCAL

are exceptions for subject names, and

_INBOX

is an exception for destination names. It is also recommended that you do not use tabs, spaces, or any unprintable character.

An underscore can be used elsewhere in subject or destination names. Subject names are case sensitive.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

164 | Chapter 9 Advanced Features

• Empty strings

Empty strings (

) are not permitted.

• Dot character

The dot characer cannot be incorporated into an element by by using an escape sequence.

See TIBCO Rendezvous Concepts for a full explanation of subject names and TIBCO

Enterprise Message Service User’s Guide for destination names.

Parameterized Subject or Destination Names

During the usage of TIBCO ActiveMatrix Adapter for Database, a subject name can be created from one or more columns in a publishing table when using the TIBCO

Rendezvous transport type, and a destination name can be created when using the JMS transport type. A subject or destination created this way is known as a parameterized subject or destination. For example, you can use TIBCO Designer to define a publication subject as

MYSUBJECT.$COLUMN1.$COLUMN2

, where

COLUMN1

and

COLUMN2

are names of columns in the publishing table. For example:

TIBCO.ORDER.$ORDER_ID.$ORDER_DESCRIPTION

On publication, a subject or destination is created from the contents of those columns.

This allows receiving applications to filter publications based on the values of certain fields. Parameterized subject or destination names are supported with certified or reliable delivery.

Parameterized Subject and Destination Name Restrictions

The following are restrictions on parameterized subject names and destination names:

• Length of parameterized subject and destination names

— A TIBCO Rendezvous parameterized subject name can be at most 255 characters in length, with each component no more than127 characters.

— A JMS parameterized destination name can be at most 249 characters in length, with each component no more than 127 characters.

In the previous example, if the

ORDER_DESCRIPTION

column contains a description value that is longer than 127 characters, the parameter name

$ORDER_DESCRIPTION

is used as the subject or destination in place of the description value.

• Wildcard characters

The asterisk (

) or greater than (

) characters, or empty strings should not be used as attribute values (VARCHAR, CHAR) in a column that is part of a parameterized subject or destination. Doing so makes the subject or destination invalid.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Subject and Destination Names | 165

For example, if the

TIBCO.ORDER.$ORDER_ID.$ORDER_DESCRIPTION parameterized subject or destination name is defined and the following values are inserted into

ORDER_TABLE

: insert into ORDER_TABLE values(111,'*',88.81); and the following values are inserted into the

ORDER_DESCRIPTION

table: insert into ORDER_DESCRIPTION TABLE values(112,'>',99.91); the publisher would return an error.

• Data type restrictions

— Do not use columns that contain Date types as part of a parameterized subject or destination. Date values are likely to contain characters such as dashes and spaces that can cause problems when used as part of a subject or destination.

— Do not use columns that contain binary types as part of a parameterized subject or destination.

— Do not insert Float-type data as an attribute value in a column that is part of a parameterized subject or destination. Doing so makes the subject or destination invalid.

• Column name

Each element cannot represent more than one column. For example,

MYSUBJECT.$COLUMN1$COLUMN2

is an invalid parameterized subject name.

• Group messaging

The group messaging feature is not supported with parameterized subjects or destinations. An error message will display and the adapter will automatically disable the group messaging feature for the publisher. For example, if the TIBCO Rendezvous transport type is used, the error message will be:

Cannot use parameterized subject with group Publishing. Disable group publishing.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

166 | Chapter 9 Advanced Features

• Pre-registration

Pre-registration in the adapter can not work when a parameterized subject or destination is used.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Preregistering a Certified Subscriber | 167

Preregistering a Certified Subscriber

You can add one or more certified subscribers, or listeners, for a publisher adapter that sends messages on subjects using the RVCM quality of service. The name of the subscriber is added to the publisher adapter’s preregistered list. The subscriber can be a

TIBCO ActiveMatrix Adapter for Database subscriber, or any other TIBCO Rendezvous subscriber.

A subscriber adapter on the preregister list is certified to receive all messages sent on the specified subject using the RVCM quality of service. If a subscriber is not preregistered, it may miss one or more of the initial messages sent by the publisher adapter.

Wildcard TIBCO Rendezvous subject names are not supported for preregistered listeners.

Preregistration will not work when parametrized subjects are used.

To preregister a certified subscriber in TIBCO Designer:

1. In the Project panel, under the publisher adapter, expand Advanced > Sessions > adbadapterInstanceNamervcmRvCmSession endpoint object.

2. Click the publisher endpoint in the Design panel.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

168 | Chapter 9 Advanced Features

The Configuration Tab for this endpoint is displayed, as shown below.

3. Verify the name of the certified subscriber in the Preregistered Listeners field:

%%Domain%%.%%Deployment%%.adb.%% adapter_name

%%.CM

. In this example, the preregistered listener is the subscriber adapter named rvsub

4. Click the Apply button.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Changing the Location of the Ledger File | 169

Changing the Location of the Ledger File

The ledger file provides temporary storage for published messages that are sent by a publisher adapter using the TIBCO Rendezvous certified messaging quality of service.

Each message is held in the ledger until an acknowledgement is received from the subscriber that the message has been consumed. If there are many subscribers, the ledger file can grow to a substantial size. In this case, it might be preferable to store the ledger file in a directory other than the default directory (which is

TIB_ADADB_HOME/ ledger

To change the location of the ledger file in TIBCO Designer:

1. In the project tree panel, navigate to the open the Advanced > Sessions > adbadapterInstanceNamervcmRvCmSession object, as shown in the previous

section,

Preregistering a Certified Subscriber

2. Edit the Ledger File value to point to the new ledger file location.

In the following example the name of the ledger file has been changed to adbdemo2pubrvcm.ldg

, and it will be generated in the directory in which you run the adapter instance.

When the adapter instance is restarted, it writes the ledger file to the new location. For more information on using TIBCO Designer, see TIBCO Designer User’s Guide.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

170 | Chapter 9 Advanced Features

Sending Messages to an Adapter Instance

When TIBCO ActiveMatrix Adapter for Database publishes messages including datetime data, the wire format is handled implicitly since both publisher and subscriber use the same format.

In many scenarios, however, a separate product acts as the publisher, which means that you must explicitly specify the wire format. For example, an adapter instance might subscribe to messages published by another TIBCO ActiveEnterprise product, such as

TIBCO ActiveMatrix BusinessWorks, after some transformation has been performed.

Messages containing datetime data sent to TIBCO ActiveMatrix Adapter for Database adapters must have that data in a string format. If it is in a different format, the TIBCO

ActiveMatrix Adapter for Database adapter will not be able to process the date values.

Formatting dates as strings allows the adapter to handle date values outside the range allowed by

RVMSG_DATETIME

, January 1, 1970 to January 1, 2034.

The format used by the adbDateTime

metadata class is described below.

adbDateTime Object

Do not change any adbDateTime

object information in this screen. Use this information to determine how to format the third-party subscriber date value.

To view the structure of the adbDateTime

class, from the project tree panel, navigate to

AESchemas > ae > ADB > adbmetadata > Classes > adbDateTime > dateTime

The input is a string value with one of the following formats: yyyy-mm-dd yyyy-mm-dd hh:mm:ss.xxx

where xxx

represents the millisecond value.

Timezone values are not supported.

The adapter will return an error when the input data contains timezone information. The timezone information can be parsed using the TIBCO BusinessWorks XPath functionality before passing it to the adapter.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Publishing by Reference Object | 171

Publishing by Reference Object

When source data is stored in a view or other database object, you can publish this data using the publish by reference object feature. Publishing by reference object is an extension of the publish by reference feature. For a description of publishing by reference, see TIBCO ActiveMatrix Adapter for Database Concepts.

In both cases, only key values from the source table are stored in the publishing table. The difference when publishing by reference object is when a row changes in the source table and the associated trigger fires, the adapter fetches data from the reference object, rather than the source table. The name of the reference object is stored in an

ADB_REF_OBJECT

column in the publishing table. For a description of this column, see

Publishing Table on page 142

. Publishing by reference object is recommended when a view provides the most

efficient access to source data, for example when many levels of nesting exist between a parent and child table.

To Configure a Publisher Adapter to Publish Data by Reference Object:

1. Drag the ActiveDatabase Adapter Configuration icon to the design panel or select the resource in the project panel.

2. Drag a Publication Service icon to the design panel.

3. To add a source table for a publisher adapter, do the following in the Tables tab: a. Click the Add Table icon. The Add Table dialog displays.

b. Select a source table from the list and click the OK button.

If parent-child relationships are used, follow the steps under

Adding Child Tables on page 65

to add child tables.

You must explicitly designate a key column or substitute key column for the reference object, since a reference object has no external designation of the key column.

4. Specify the following options in the Publisher Options tab:

Storage Mode — From the drop-down list, select

Publish by Reference

Publishing Table — Type the table name to use for storage. A common practice is to use the source table name prefixed by

Referred Object — Type the name of the view or other database object to select source data from. To select from a list of tables in the current user schema, click the Add button. To select an object from a different schema, select Add From.

Update Mode — Select the method for updating tables from the drop-down list.

Choose Update to update a row in the destination table only if the row exists. Choose

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

172 | Chapter 9 Advanced Features

Upsert to update a row in the destination table if the row exists and, if no such row exists, perform an insert.

5. Click the Apply button.

Designating the Key Column

To designate a column of the reference object as the key:

1. In the TIBCO Designer project tree panel, navigate to AESchemas > ae > ADB > adapter_instance

> classes > ref_object

> key_column

. The TIBCO Designer window should look similar to the following:

2. In the Configuration tab, click the Key Field checkbox to select it.

3. Click the Apply button.

Changing Repository Objects for Parent-child Relationships

If your publication service includes parent-child relationships, you must also add a sequence and association to the metadata stored in the repository. These tasks are described in the following sections.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Publishing by Reference Object | 173

Adding a Sequence

To add a sequence:

1. In the TIBCO Designer project tree panel, navigate to AESchemas > ae > ADB > adapter_instance

Classes

> reference_object

2. Drag a Generic Sequence icon from the Palette panel to the Design panel to add it to the reference object class. The TIBCO Designer window should look similar to the following:

3. In the Name field, type

ADB_SEQUENCE_ child_table_name

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

174 | Chapter 9 Advanced Features

4. In the Select Sequence field, click the Browse button. The Select Resource dialog displays:

5. Click the name of the sequence that represents the child table for the publication service, for example, sequence[ORDER_DETAILS]

6. Click the OK button.

7. In TIBCO Designer, click the Apply button. The sequence is added to the metadata for the reference object.

Adding an Association

To add an association:

1. In the TIBCO Designer project tree panel, navigate to AESchemas > ae > ADB > adapter_instance

Associations.

Several associations could display, at least one for the parent table to the child table on the publisher side, and another for the destination parent table to the child table on the subscriber side.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Publishing by Reference Object | 175

2. Click each of the resource icons that represent the parent-child relationship on the publisher side. For example:

3. In the Configuration tab, click in the Name field and replace the name of the publishing table with the name of the reference object. For example,

P_CUSTOMER^ORDER_DETAILS

becomes

ORDER_VIEW^ORDER_DETAILS

4. Click the Apply button.

5. In the project tree panel, double-click the new association name to expand it.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

176 | Chapter 9 Advanced Features

6. In the Project panel, click Left Association to select it.

7. Enter a Role Name value that contains the reference object name. For example, roleORDER_TABLE

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Publishing by Reference Object | 177

8. In the Endpoint Class field, click the Browse icon. Navigate to the class that represents the reference object, in this case

ORDER_TABLE

, and click the OK button.

Example

9. In TIBCO Designer, click the Apply button.

In the following example, the publisher adapter is configured to publish source data from the

CUSTOMER

table and its child table,

EXTERNAL_ORDER_DETAILS

. The relevant key columns are

CUST_ID

and

ORDER_ID

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

178 | Chapter 9 Advanced Features

The publishing table is created with necessary adapter fields, as well as

CUST_ID and

ORDER_ID fields. When a row in

CUSTOMER is modified, the trigger fires, populating fields and copying the

CUST_ID

and

ORDER_ID

values, as well as the name of the reference object,

ORDER_VIEW

, to the publishing table. When the adapter polls the publishing table, it detects the new row. The adapter then selects the order and customer data from

ORDER_VIEW

, using the

CUST_ID and

ORDER_ID values along with the view name found in the publishing table.

Then the message is published.

Table to Record Sequence Numbers (DB2 on iSeries)

The palette will attempt to create the following table (if it does not exist) to record sequence numbers:

CREATE TABLE library

.ADB_SEQTAB (

PUB_TABLE VARCHAR(64) NOT NULL,

ADB_SEQ NUMERIC(20),

constraint ADB.ADB_SEQTAB_KEY primary key (PUB_TABLE))

The table must be journalled.

You can create this table or if journalling is automatically turned on, the palette will create the table automatically.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

User Callout Library | 179

User Callout Library

The user callout shared library allows the transformation of a message that the adapter publishes into a structure that you want to be published. The shared library can be customized to apply limited transformations to outgoing and incoming messages.

To use the callout library, the TIBCO Adapter SDK must be installed because the callout library uses SDK include files and links with SDK libraries. Additionally, you must use the same TIBCO Adapter SDK version that your adapter instance is using.

If a message is modified before it is sent by a publisher adapter, all subscribers will receive the modified message. If a message is modified before it is received by a subscriber adapter, only that adapter will get the modified message.

For example, at the publisher adapter, a message can be modified to have a field added, or publish an empty message if a certain criteria is met. At the subscriber adapter a message can be modified to be written to the database or not, based on a filter, or have the subject name inserted into the table.

Before a message is sent or received, the adapter checks the callout library. If the callout library has not been modified, the message is passed back to the adapter unchanged. If the callout library has been modified, the message is passed back to the adapter with the modification. After receiving a modified message from the callout library, the adapter instance sends or consumes the message like any other message.

• The altermsg.cpp

source file must be edited with your custom code.

• The callout library must be rebuilt for your platform.

The source code is included in your installation media in the

TIB_ADADB_HOME

\demo\altermsg

directory.

If you send or receive messages in the TIBCO Rendezvous Message wire format, the

TIBCO Rendezvous Message APIs cannot be used to directly alter those messages.

Instead, you will receive an

MTree

to which various functions can be applied to view or traverse the TIBCO Rendezvous message. If you must change the message, create a new message and pass it back to the adapter using the newmsg

argument.

Using the alterMsgPub and alterMsgSub Functions

Two functions are available in the altermsg.cpp

source file for creating callouts, alterMsgPub(

) to create a callout for a publisher and alterMsgSub()

to create a callout for a subscriber. Two examples are included in the altermsg.cpp

file. You can change the examples for your needs, or write new code in the file. The first example appends a new field to a message. The second example works in conjunction with the demo and returns an empty message if the message meets a certain criteria.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

180 | Chapter 9 Advanced Features

The alterMsgPub(

) and alterMsgSub()

functions are the entry points into the callout library.

These two function names and their signatures must not be changed.

The alterMsgPub

and alterMsgSub

functions allow you to alter messages in the TIBCO

ActiveEnterprise Message, TIBCO Rendezvous Message, and XML wire formats. The function signatures are: alterMsgPub(char * subj, const MTree *msg,

MTree **newmsg,

MInstance *pInst,

MApp *pMapp,

MMessageFormat dataformat); alterMsgSub(char * subj, const MTree *msg,

MTree **newmsg,

MInstance *pInst,

MApp *pMapp,

MMessageFormat dataformat);

Both functions share the same set of parameters. However, several parameters are specific to a particular wire format.

The following table contains parameter descriptions and a column for each format. If the

R column contains an

, use the parameter for TIBCO Rendezvous Message wire format.

If the M column contains an

, use the parameter for TIBCO ActiveEnterprise Message or

XML wire format. Otherwise, leave the value as

NULL

Table 38 Wire Format Parameters and Descriptions

Parameter subj

M Description

X Subject on which the message is sent or received.

msg X MTree containing the message to send or receive.

X newmsg pInst pMapp

New MTree user creates if msg must be altered.

X MInstance of the message. Alter directly if necessary.

X TIBCO Adapter SDK MApp structure for this MInstance.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

User Callout Library | 181

Table 38 Wire Format Parameters and Descriptions (Cont’d)

Parameter dataformat

M Description

X The data format of the message.

Valid values are:

M_RV_MESSAGE_FORMAT

M_AERV_MESSAGE_FORMAT

M_XMLJMS_MESSAGE_FORMAT

M_XMLRV_MESSAGE_FORMAT

Check TIBCO Adapter For SDK documentation for details of these value.

When sending or receiving messages in the TIBCO ActiveEnterprise Message wire format, you must use the pInst

argument to change the message.

Using the adbPreCommit Function

The adbPreCommit

function allows you to perform a custom operation, such as invoking a stored procedure or sending a TIBCO Rendezvous message, just before the transaction is committed. This function is called by the subscriber after all inserts, updates and delete operations have been performed on both parent and child tables.

The function signature is: adbPreCommit(SQLHDBC connectHandle,

MApp *pMapp,

MInstance *pInst,

MTree *pTree,

MMessageFormat dataformat);

The following table contains parameter descriptions.

Table 39 adbPreCommit Parameter Descriptions

Parameter connectHandle

TIBCO

Rendezvous

Format

TIBCO

ActiveEnterprise

Format

X pMapp pInst pTree

X X

Description

The database connection handle.

TIBCO Adapter SDK MApp structure for this

MInstance.

MInstance of the message.

MTree containing the message.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

182 | Chapter 9 Advanced Features

Table 39 adbPreCommit Parameter Descriptions (Cont’d)

Parameter dataformat

TIBCO

Rendezvous

Format

TIBCO

ActiveEnterprise

Format

Description

The data format of the message.

Valid values are:

M_RV_MESSAGE_FORMAT

M_AERV_MESSAGE_FORMAT

M_XMLJMS_MESSAGE_FORMAT

M_XMLRV_MESSAGE_FORMAT

Check TIBCO Adapter For SDK documentation for details of these value.

If an adapter is configured to use the adb.subBatchCommitTimeout

or adb.subBatchCommitSize

options, the custom operation is performed once for each message received. However, the entire transaction is not committed until the size or time-out values are reached. Adapter instances that use the bulk-insert-size

option cannot use adbPreCommit

For more information on these options, see

Appendix C, Adapter Properties File, on page 329

Building the Callout Library

The callout library is build with TIBCO Adapter SDK and TIBCO Rendezvous software.

For compiler requirements and instructions, see the TIBCO Adapter for SDK guide.

Building the Callout Library on Microsoft Windows

1. Using Visual C++, create a new workspace and insert a new project into the workspace.

2. In the new project, open the file:

TIB_ADADB_HOME

\demo\altermsg\altermsg.dsp

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

User Callout Library | 183

3. Select Project > Settings. In the Project Settings dialog box: a. As shown next, select the C/C++ tab. In the Category drop-down list, select

Preprocessor. In the Additional Include Directories field type the path to the

TIBCO Rendezvous include

directory.

b. As shown next, select the Link tab. In the Category drop-down list, select Input.

In the Additional Library Path field, enter the path to the TIBCO Rendezvous library

directory.

4. Select Build > Build

adbaltermsg.dll

to create the library.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

184 | Chapter 9 Advanced Features

5. After building the library, change to the

TIB_ADADB_HOME

/lib

directory.

a. Make a backup copy of the existing adbaltermsg.dll

library.

b. Copy the new adbaltermsg.dll

library into the bin

directory.

Building the Callout Library on UNIX

1. Using a text editor open the

MakeFile

and set the

RV_Home

environment variable. For example, for Solaris 8:

RV_HOME=/usr/tibco/tibrv

2. Using a text editor open the MakeFile and set the

SDK_Home

environment variable. For example:

SDK_HOME=/usr/tibco/adapter/sdk/5.6

3. Set the command to invoke your compiler. For example:

CC= CC

4. Set the options to be passed to your compiler. For example:

DEBUG=-g

OPT=-O4

5. Save the MakeFile and execute:

% make libadbaltermsg.so

6. After building the library, change to the

TIB_ADADB_HOME

\lib

directory.

a. Make a backup copy of the existing libadbaltermsg.so

library.

b. Copy the new libadbaltermsg.so

library into the lib

directory.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Unique Connection Identifier for Oracle Databases | 185

Unique Connection Identifier for Oracle Databases

Within each adapter instance, the adapter typically creates multiple database connections or sessions. Each connection has a different responsibility (such as selecting from the publishing table or inserting into the destination table) and each is identified using a unique connection identifier.

The unique identifier added to each session allows a database administrator to monitor the adapter’s database activity from Oracle by being able to identify what each database connection is doing. The Oracle DBA can query the

CLIENT_INFO

column of

V$SESSION

to identify each Oracle connection the adapter is using. The identifiers for each service are:

•

InstanceId.ADBPubPolling

(publication service polling connection)

•

InstanceId.ADBPubUpdate

(publication service update connection)

•

InstanceId.ADBPubConfirm

(publication service confirm connection)

•

InstanceId.ADBSubscriber

(subscription service connection)

•

InstanceId.ADBRequestReply.n

(request-response service connection where n

is the thread

ID)

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

186 | Chapter 9 Advanced Features

Publishing in a Commitment Controlled Environment

This feature applies only to DB2 on iSeries.

You can enable the adapter to publish messages in a commitment controlled environment.

In its standard functionality the adapter generates and attaches database triggers to an application table that is the source for publishing data. A trigger program is activated on a database event on the source table (Insert, Update, Delete) and the trigger program uses the source table data to reflect the database event change on a publishing table.

Therefore, if the source table is being accessed by an application under commitment control, it is critical from a database integrity standpoint that the trigger program be part of the same commitment cycle.

To publish messages in a commitment controlled environment:

These steps assume that the trigger program is being generated by the palette in the RPG

ILE language.

1. Once the adapter is configured and saved in TIBCO Designer, the trigger programs will be compiled and attached to the source table. Log on to the iSeries system using a profile that has *PGMR rights to the library and source file where the trigger program is created. The trigger program is always created in a source file called

TIBCOSRC

that is in a library representing the DB2 collection.

2. Edit the trigger program member in the

TIBCOSRC

file by adding the keyword '

Commit

' on the F-Spec for the publishing table. An example is given below.

FP_EMPL O E

Disk Rename(P_EMPL:Pub_Record)

UsrOpn

Commit

Make sure that the application program that is accessing the source table is running with commitment control enabled. Otherwise, the trigger program will encounter a runtime error with this keyword.

3. After editing the trigger program member, save and compile it with options

DFTACTGRP(*NO)

and

ACTGRP(*CALLER)

. These options ensure that the trigger program runs as part of the calling application program's commitment cycle. The trigger program will run in the application program's activation group. Any database updates done by the trigger program will be done or undone by a Commit or Rollback issued by the application program, thus ensuring database integrity.

4. To have the trigger program run under commitment control, the publishing table

(listed in the trigger program) must be journalized. This can be done by using the

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Publishing in a Commitment Controlled Environment | 187 iSeries command

STRJRNPF

. The journal that is being used to log changes to the source table can be used for the publishing table as well.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

188 | Chapter 9 Advanced Features

Using the Adapter with a Revision Control System

TIBCO Designer supports revision control systems such as MicroSoft Visual SourceSafe and Perforce. If you are using a revision control system, you must manually add some configured resources to the revision control system and check in the resources when completing the instance configuration.

As part of service configuration, the adapter creates schema files in project_ root

AESchemas > ae > adadb. For example, if you configure a service in an adapter configuration instance1

, the following files are created: project_ root

> AESchemas > ae > adadb

> Instance1.aeschema

project_ root

> AESchemas > ae > adadb

> Instance1 > businessObjects.aeschema

When the project is saved and a revision control system has been specified, the adapter displays a warning that additional files were created and should be added to the revision control system. This warning appears only when the files are created for the first time. The warning displays a Go To Resource button that helps in navigating to the resource. You should select Multi-User > Add Resources to RCS to add these files to the revision control system.

For information about how to use the Multi-User feature in TIBCO Designer, see TIBCO

Designer User’s Guide.

Copy, Cut, Paste and Move Operations

To successfully copy and paste a service from adapter instance1 to instance2, the adapter configuration and schema files for the instance2 must be checked out.

To successfully cut and paste a service from adapter instance1 to instance2, the adapter configuration and schema files for both instance1 and instance2 must be checked out.

To successfully move a service from adapter instance1 to instance2, the adapter configuration and schema files for both instance1 and instance2 must be checked out.

Regeneration When Moving, Copying and Pasting

• Default subjects are not regenerated to reflect the new instance name when a service is moved.

• Manually changed certified messaging and certified messaging queue ledger file names are regenerated to defaults when a service is moved, or copied and pasted to a new instance.

• If a service associated with a custom session is moved, or copied and pasted, the custom session is not moved, or copied and pasted. The session is regenerated as a default session.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Using a Log File for an Adapter Instance | 189

Using a Log File for an Adapter Instance

By default all error, warning and information messages are printed in the console window in which the configuration was started and to a default log file. The log file can be located anywhere on your file system.

The adapter will trace to whatever sink is present in your adapter instance configuration. If you have the default sinks of stdioSink

and fileSink

, the adapter will write to both the file and stdout

Only errors that originate in the adapter instance itself are logged in the log file. Errors from other sources, for example TIBCO Rendezvous APIs or TIBCO Adapter SDK APIs, are not logged to a log file, but are printed to the console window where the configuration started.

Fine-tuning Tracing Attributes

The tracing facility allows you to fine-tune where and what different types of information are sent.

To access tracing attributes for an adapter instance:

1. In the Project tree panel, click the corresponding ActiveDatabase Adapter resource to select it.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

190 | Chapter 9 Advanced Features

The TIBCO Designer window should look similar to the following:

2. Display the Logging Tab, as shown below.

The Log to Standard I/O checkbox is checked so that trace information can be written to the console window where the adapter instance was started. The log file is generated in the start directory unless specified otherwise in the properties file.

To disable file tracing for the adapter instance, delete this file name and click the Apply button.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Using a Log File for an Adapter Instance | 191

The following checkboxes control the level of trace information that is captured:

• Log Info Messages—Capture error and warning information.

• Log Debug Messages—Capture all available information.

• Log Warning Messages—Capture warning information only.

• Log Error Messages—Capture error information only.

Log File Size

When a log file name is specified in the Logging tab, the adapter does the following:

1. Creates a file with no extension, using the file name specified in TIBCO Designer.

2. Redirects all trace statements generated by this configuration to that file until it reaches the default file size of 30 KB.

3. When this file size is reached (that is, as soon as the file is greater than or equal to the limit), renames the current file to file

.1 and creates a new file with no extension.

Note that the log file can be slightly larger than the limit because the new file is only created after the limit has been reached.

4. Repeats this process of rolling log files and renaming files each time a new file is generated, until 3 log files exist.

With these default settings, the adapter instance overwrites the oldest file after 3 files have been created and the last file reaches 3 KB. For instructions on changing the default settings, see the next section.

Using Advanced Logging Features

The example in this section shows how to change default log file attributes in TIBCO

Designer.

To access advanced logging features in TIBCO Designer:

1. With the Logging tab selected in the Configuration panel, click the Use Advanced

Logging checkbox.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

192 | Chapter 9 Advanced Features

2. Click the Apply button. The following information displays:

3. In the Project panel, navigate to adapter_instance_name

> Advanced > Log Sinks > fileSink

The TIBCO Designer window looks similar to the following:

File Limit (bytes)

Sets the maximum size of a log file. A global variable can be used for this field.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Using a Log File for an Adapter Instance | 193

File Count

Specifies the maximum number of log files that are created for this adapter instance. A global variable can be used for this field.

Append Mode

When this box is checked (the default), information is written to the log file in the Append mode, where trace information is appended to existing entries in the file.

Unchecking this box changes to Overwrite mode, where the adapter instance overwrites the current log file the next time the adapter starts.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

194 | Chapter 9 Advanced Features

Using Database Deployment and Cleanup Scripts

Changing an existing adapter instance typically generates legitimate changes in the database. During this change process, the adapter creates a SQL script for changing the database objects and an associated cleanup script and stores them in the

TIB_ADADB_HOME

\sql

directory. If the legitimate database changes result in error messages, you may need to run these scripts. The messages and procedure for running the scripts are given in this section.

If the scripts created for legitimate database changes are not generated successfully, a message such as the following sample may display.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Using Database Deployment and Cleanup Scripts | 195

If the scripts created for legitimate database changes are generated successfully but an error occurs while these changes are being saved to the database, a message such as the following sample may display.

To Run the Deployment Scripts

The generated SQL script for changes to database objects is stored in the instance_ name

.sql

file under the

TIB_ADADB_HOME

\sql

directory. You can modify this script to deploy changes to different databases environment. For example, if the user schema is different between the production and testing environment, you can change the schema name of the database objects in the script and deploy the changes accordingly.

To Run the Cleanup Scripts

1. Select each message in the top portion of the message window and read the explanation for it in the bottom portion of the message window.

2. In TIBCO Designer, close the project containing the adapter instance that you changed.

3. Fix the errors that caused the database changes to fail, as indicated by the messages.

4. If necessary, clean up the old database configuration by running the scripts created by the adapter. The scripts are in the sql

directory and are named instanceId

.sql or instanceId

undo.sql

, where instanceId

is the name of the adapter instance you changed.

5. Reopen the project in TIBCO Designer.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

196 | Chapter 9 Advanced Features

6. Select the adapter instance you were attempting to change when the errors occurred.

7. Save the project.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Changing the SQL Statement Terminator (DB2 for z/OS Only) | 197

Changing the SQL Statement Terminator (DB2 for z/OS Only)

The SQL statement terminator by default is a semicolon ("

), but DB2 trigger statements use embedded semicolons as part of their syntax. Because of this, adapter SQL statements use a pound sign ("#") as the SQL statement terminator.

When using the adapter in the default (real-time) mode, where repoOnly=false

, the SQL statement terminator is not used and no changes are necessary.

However, when running the adapter in batch mode ( repoOnly=true

), you must change the

SQL statement terminator from the default semicolon to the pound sign ("

") in order to avoid conflicts with DB2 trigger statements.

Common methods of changing the SQL statement terminator are:

• Use

SPUFI

to set the terminator to

in the default panel.

• Include the following control statement at the beginning of the script file, or immediately before the DDL statement to be executed:

--#SET TERMINATOR #

• Use

DSNTEP2

DSNTIAD

to code the

RUN

command as follows:

RUN PROGRAM(DSNTEP2) PLAN(DSNTEP61) PARMS(’SQLTERM(#)’)

Task A Change the Statement Terminator

The following steps change the statement terminator to a '#', then executes the SQL from the script file.

1. In a Windows command prompt, go to the directory where the script file resides.

2. Connect to DB2/OS390. For example:

C:\ your_directory

DB2 Connect to S390LOC user logon_id

using password

3. Execute your script file. For example:

C:\ your_directory

DB2 -td# -f filen_ame

4. In the Window's Command Center, go to the

Script

menu and select options.

5. Check the Use Statement Termination Character checkbox and enter '#'.

6. Connect to DB2/OS390 from the Command Center GUI. For example:

Connect to S390LOC user logon_id

using password

7. Cut the SQL statements from the script file and paste them into the Command Center

GUI, then execute.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

198 | Chapter 9 Advanced Features

Fault Tolerance

Within the context of the adapter, a primary instance is the adapter instance that processes messages between the TIBCO environment and the database. The secondary instance uses the same adapter configuration but runs in a stand-by mode and takes over when the primary instance goes down.

To run in the fault tolerance mode, the property adb.mutex

has to be defined. The value of this property is the name of the table that an adapter instance will attempt to lock.

At start up, if the adb.mutex

property is present, the adapter will try to issue an exclusive lock on the table defined by the value of this property before processing any messages.

The named table is created at run time if it does not exist. The adapter instance that is able to lock this table is considered a primary instance. All instances that are not able to issue an exclusive lock on this table are considered secondary instances. Instances that specifies the same mutex table will be within a fault tolerance group.

The primary instance releases the lock prior to shutdown. If the primary instance terminates for an unknown reason, the lock is collected by the database system. As soon as the lock is released, one of the secondary instances will hold the lock and become the primary.

Both the primary and secondary instances will use a separate database connection to issue lock on the mutex table. The adapter will keep this connection active by executing a dummy query from time to time.

You can customize the adapter fault tolerance feature with the following adapter properties:

• adb.primary.heartbeat: The time interval that the primary instance will execute a dummy select statement to the database in order to keep the connection that hold the lock to remain active. Default value is 10000ms

• adb.secondary.heartbeat: The time interval that the secondary instance(s) will wait before sending the next query message to detect the existence of a primary instance.

Default value is 10000ms

• adb.heartbeat (deprecated): If none of the above parameter specified, this value will be used as both primary and secondary heartbeat. Default value is 10000ms

• adb.createMutexTable: By setting the TRA property to false, the adapter will not create the mutex table during start up. Default value is on. User can use the following

SQL statement to create the mutex table before starting the adapter:

CREATE TABLE mutex_table_name

(COL1 char(1))

• adb.maxQuery: The secondary instance will send a query message to detect the existence of the primary instance. This is the number of queries for which if no reply

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Fault Tolerance | 199 is received the secondary instance will consider that a primary instance no longer exists and will try to lock the mutex table.

• If the primary instance looses connection to the database, a reconnection will not be attempted. The adapter instance will release the lock and gracefully shutdown letting any secondary instance take over as the primary.

The time interval that the secondary instance(s) wait before attempting to lock the table specified by the adb.mutex

property is defined by the

adb.heartbeat and adb.maxQuery properties.

On Oracle, you have to set the

SQLNET.EXPIRE_TIME

in sqlnet.ora

script to a value greater than

0. This ensures that the server will collect the lock held by the invalid connection of the primary instance due to connection lost.

On DB2, make sure the

IDTHTOIN DSNZPARM

parameter is greater than adb.primary.heartbeat. This system parameter configures the timeout before the system cancels an idle thread.

Reconnection in the Fault Tolerance Mode

If the primary instance loses connection to the database, a reconnection will be attempted.

The adapter will perform reconnection base on the reconnection configuration, it will gracefully shutdown if reconnection is not successful, letting any secondary instance take over as the primary. If the secondary instance obtain the mutex lock while the primary instance is reconnecting, the secondary instance will take over as primary. The original primary instance will terminate if it cannot lock the mutex table after connection is re-established.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

200 | Chapter 9 Advanced Features

SSL Data Encryption using DataDirect ODBC Drivers

SSL data encryptions provide secure transmission of data. The adapter supports SSL data encryption between the database and the adapter with DataDirect Wire Protocol ODBC

Drivers.

You may want to use data encryption in the following scenarios:

• You have offices that share confidential information over an intranet.

• You send sensitive data, such as credit card numbers, over a database connection.

• You need to comply with government or industry privacy and security requirements.

See ODBC Driver documentation for more information on the available features and the required configuration details.

Data encryption may adversely affect performance because of the additional overhead required to encrypt and decrypt data.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

OS Authentication | 201

OS Authentication

This release of the adapter provides SQL Server OS Authentication on Windows.

Microsoft SQL Server uses integrated login security to establish connections using this data source, regardless of the current login security mode at the server. Any login ID or password supplied is ignored. The Microsoft SQL Server system administrator must have associated your Windows network ID with a Microsoft SQL Server login ID.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

202 | Chapter 9 Advanced Features

Query Timeout

This release of the adapter provides Query Timeout on all databases. The operation for database would return with error instead of hang if it can not be completed when the database server is busy. For the publication service, the polling operation would return null and wait for the next polling. For the subscription service, it would return the connection dead error, and then reconnect.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Working with Multi-File Format Projects | 203

Working with Multi-File Format Projects

The multi-file format creates one ActiveEnterprise XML file for each logical object (such as an adapter instance, a set of related ActiveEnterprise classes, or a TIBCO ActiveMatrix

BusinessWorks process flow) that occurs in the repository instance. This kind of project is referred to as a multi-file project.

Multi-file projects can be checked into a version control system, and a project can contain more than one adapter configuration. This allows a number of people to work on the same project at the same time, with different people working on each adapter configuration: a developer can check out the specific file corresponding to an object that needs to be changed, updated the file, and check it back in. TIBCO Designer accesses the local synchronized copies of the files on the developer’s hard drive.

The multi-file format provides a hierarchical structure with directories taking the place of

RepoDirectory nodes. In previous releases of TIBCO ActiveMatrix Adapter for Database, repository nodes contained references to other repository nodes (such as sessions and endpoints of that instance) using a format such as:

/tibco/public/endpoint/adapter/adb/test/instance1/publisher1

In the multi-file format, these references are replaced by URIs of the following form:

ProjectRoot

/ multi-file_project_name

/#type.name

For example, the first reference above would map to the following URI in a multi-file project:

ProjectRoot

/Adapters/adb/test/instance1/publisher1

For more information see TIBCO Designer User’s Guide.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

204 | Chapter 9 Advanced Features

Subscriber Reply Sender

The subscriber can be configured to send the subscription status as a reply to the message sender if the message contains a reply subject. This AE schema

ADB_SUBSCRIBER_STATUS is used for this reply message:

Table 40 Description of ADB_SUBSCRIBER_STATUS Class Schema

Field Name

RETURN_CODE

AE Type i4

Description return_code=0, when the data is inserted into destination table successfully.

return_code=-1, when the data is inserted into exception table. return_code=5, when the data is failed to insert in both destination and exception tables.

If you specified subscriber pre-commit stored procedure, this field will contain the value of the RETURN_CODE output parameter.

ADB_TEXT

CALLOUT_TEXT string string

Contains the status or error message of the subscriber operation.

Contains the error message from the database driver in case of error operation.

If you specified subscriber pre-commit stored procedure, this field will contain the value of the SP_TEXT output parameter.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Subscriber Pre-commit Stored Procedure Call | 205

Subscriber Pre-commit Stored Procedure Call

The subscriber can be configured to call a stored procedure after the database insert, update, or delete and prior to commit. You can use this stored procedure as a hook to accomplish further processing inside the database and return the results to the adapter.

User can specify this pre-commit stored procedure name in the Pre Commit Stored

Procedure field of the Subscription Service Subscriber Options.

The adapter will call the pre-commit stored procedure with the following syntax:

{call <pre-commit stored procedure name>(?, ?, ?)}.

This stored procedure need to be defined with a specific interface as specified below:

Table 41 Description of the Pre-commit Stored Procedure Parameters

Name

RETURN_

CODE

Type integer

Description

RETURN_CODE = 0, the adapter will assume the procedure was successful and write a success message to the SDK INFO trace role when the verbose mode is used.

RETURN_CODE <> 0, the adapter will assume the procedure was not successful and write

SP_TEXT

to the SDK ERROR trace role (whether verbose mode is on or off).

If the message has a reply subject, this output value will be returned to the message sender. See

Subscriber Reply Sender on page 204 for more details.

SP_TEXT varchar

DO_ROLL

BACK integer

If the message has a reply subject, this output string will be returned to the message sender. See

Subscriber Reply Sender on page 204 for more details.

DO_ROLLBACK = 0, the adapter will commit the transaction and confirm the original message.

DO_ROLLBACK <> 0, the adapter will rollback the transaction and not confirm the message. Note, not confirming the message changes the RVCM behavior. All subsequent RVCM messages will not be confirmed. It should only be done when this

RVCM behavior is really desired.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

206 | Chapter 9 Advanced Features

JMS Durable Subscriber Name

The JMS Durable Subscriber name can take the deployment time global variable value in this release.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Runtime Schema | 207

Runtime Schema

In the case where the schema name of the tables objects are different between development and production environment, you can use the following TRA properties to specify the schemas configuration.

For all database environments other than IBM UDB iSeries (AS00):

• adb.originalSchema

– Specify the design-time table objects schema.

• adb.runtime.schema

– Specify the runtime table objects schema.

— If adb.originalSchema

is specified, the adapter will compare the adb.originalSchema

with the prefix of the table objects. If they are the same, the adapter will replace the design-time schema with this runtime schema. Otherwise, no action will be taken.

— If adb.orignalSchema

is not specified, the adapter will append this runtime schema to all table objects that do not have any schema specified at design time.

• adb.runtime.publisherSchema

– Specify the runtime publisher table schema. This overrides the adb.runtime.schema

setting. This can be used if user has a different schema for the publishing table then the other table objects such as source table.

These configurations do not apply to the referred object in publish by reference mode.

User need to specify the runtime schema for the referred object during the design time, or in the ADB_REF_OBJECT column entry in the publishing table.

For IBM iSeries (AS00):

• adb.as400.defaultLibrary

– Specify the default iSeries library to be accessed.

• adb.as400.library

– Specify the name of the runtime iSeries library where the adapter will access.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

208 | Chapter 9 Advanced Features

Runtime Table Schema Configuration

You can specify the runtime schema global variables in the administrator console during the deployment of the adapter to enable the adapter to use these schemas in run time which are different from the design-time schema configuration. This makes it easy for you to move from one environment to another, most likely from the test environment to product environment.

For publisher by reference object, you need to make sure the right schema and reference object name are set correctly in the right publisher table, because the reference object name is fetched from the publisher table, not an property from the design-time DAT file or

TRA file.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Group Message Transaction | 209

Group Message Transaction

This feature allows you to configure a group message to be processed within a single transaction by the subscription service. The adapter will either commit the whole message changes to the database, or none. See

Subscriber Options Tab on page 82

for details.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

210 | Chapter 9 Advanced Features

Load Balancing and Multithreading

TIBCO ActiveMatrix Adapter for Database supports multithreading and load balancing to improve the performance in high load scenario.

Improving Performance Using Threads

You can improve the adapter Subscription Service and Request-response Service performance by specifying the number of threads that will be responsible for processing application requests. The number of threads to be spawned is specified in TIBCO

Designer for an adapter instance.

To set the number of threads for a configuration:

1. In the Project panel, click the corresponding ActiveDatabase Adapter resource to select it.

The TIBCO Designer window should look similar to the following:

2. Check the Show All Tabs checkbox.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

3. Display the Adapter Services tab.

Load Balancing and Multithreading | 211

4. Change the value of Number Of Request-Response Service Threads or Number Of

Request-Response Service Threads as needed.

5. Click the Apply button.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

212 | Chapter 9 Advanced Features

Subscription Service

You can select Use Separate Service Thread in the Subscriber Options tab during design time. When selected, a new session is created and the service endpoint is moved to this session.

During runtime, the adapter will create a separate dispatcher to dispatch event from this session. You can select other subscription service to use the same session by changing the sessionReference field under the Advanced tab. This allows multiple services to share the same session and dispatcher.

Request-Response Service

Each request-response service thread is dedicated to listening on an agreed request subject.

1. When a request message is received by the request-response communication thread, it enqueues it into an in-memory queue. Each database request-response thread has a

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Load Balancing and Multithreading | 213 connection to the database using the user name-password combination that was provided to the adapter.

2. When an item is enqueued by the communication thread, one of the database request-response threads picks it up and executes the one or more SQL statements in the message as an atomic transaction.

3. It then composes a TIBCO Rendezvous self-describing response message and sends back a response on a response subject. If the original request was sending using rv_SendWithReply()

or rv_Rpc()

, the response is sent back on the subject that was specified by the requesting application. Otherwise, the response is sent back on the subject that was set up at configuration time.

While the request message can be sent with either reliable or certified quality of service, the response message is always sent back using the reliable quality of service.

Load Balancing Across Adapter Instances

Subscription and Request-Response Service

To achieve load balancing across adapter instances for subscription and request-response services, TIBCO Rendezvous Distributed Queueing or TIBCO EMS Queue can be used to assign each application request to exactly one adapter instance. For example, the following diagram is an example for using TIBCO Rendezvous Distributed Queueing for load balancing. It shows three adapter instances each connected to a database server (not shown) that contains replicated data.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

214 | Chapter 9 Advanced Features

Figure 6 Request-response Load Balancing

Request

Distributed Queue

Adapter 4

Request

Adapter 1

(Scheduler)

Request

Adapter 3

Adapter 2

TIBCO Messaging

Responses

Application

Reliable requests in a certified environment use a simpler type of load balancing. In this example, the scheduler distributes the first reliable request to

Adapter 2

, the second to

Adapter

, and the third to

Adapter 4

without evaluating a queue member’s load.

Configuring an Adapter Instance to use TIBCO Rendezvous Distributed

Queues or TIBCO EMS Queue for Load Balancing

You can configure the adapter with a subscription service to use a distributed queue, then use TIBCO Administrator Enterprise Edition to deploy multiple instances of the adapter.

The instances can be deployed on the same machine, or multiple machines. In this scenario, each adapter instance uses the same (default) values for the distributed queue.

1. Start TIBCO Designer and create a new project.

2. Drag the ActiveDatabase Adapter Configuration icon to the design panel.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Load Balancing and Multithreading | 215

3. Configure the adapter instance with a design-time connection and

ODBC DSN

value.

4. Drag the ADBSubscriber icon to the design panel.

5. For using TIBCO Rendezvous transport, under the Configuration tab, select

Rendezvous in the Transport Type drop-down list, and Distributed Queue in the

Quality of Service drop-down list. For example:

For using TIBCO EMS Queue, set Transport Type to JMS and Quality of Service to

Queue.

6. Configure the service with a destination table name and other settings for your environment.

7. Click Project > Save.

8. Click Tools > Create Project EAR. Under the Configuration tab, provide a name and file location for the EAR file.

9. Click the Build Archive button.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

216 | Chapter 9 Advanced Features

Publication Service

You can check the Enable Load Balancing checkbox and specify the Mutex Name in the

Publisher Options tab during design time to balance load among multiple publication service endpoints. Publication service with the same Mutex name specified will be in the same load balance group.

When load balancing is enabled at design time, the adapter palette will create a publication table with an additional column

ADB_MARK

At runtime, the publication services of the same load balancing group will create a mutex table that was configured at design time, and poll the same publication table and distribute loads. The service will synchronize by locking the mutex table to obtain and update the sequence information.

When an adapter instance contains a publication service with load balancing enabled, it can only run in batch polling mode. To turn on batch polling, enable the Use Polling

Batch Size option and specify the Polling Batch Size for the adapter instance.

For Sybase, the publisher load balancing feature requires the ddl in tran

option be set to true: sp_dboption database_name,"ddl in tran", true

Deploying an Adapter Instance for Load Balancing

After creating the EAR file, you are ready to import it into TIBCO Administrator

Enterprise Edition and add the adapter instance multiple times to the same machine or multiple machines. Since these adapter instances have the same RVCMQ, EMS Queue, or

Mutex Name for publication configuration, they will participate as in same load balancing group at runtime.

1. Start TIBCO Administrator Enterprise Edition.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Load Balancing and Multithreading | 217

2. Select Application Management, then click the New Folder button. In

Name

, provide a name for the folder and click the Save button.

3. Select the folder, then click New Application.

4. Click the Browse button and navigate to the EAR file you created in Designer. Click the OK button.

5. In the dialog that appears, click the Save button.

6. Expand the configuration, then double-click the name

.aar file.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

218 | Chapter 9 Advanced Features

7. Click the Add to Additional Machine button and select the machine to bind to and click the OK button.

8. Repeat to create the number of adapter instances required for your environment. For example, the next screen shows that three adapter instances have been added.

9. Click the Save button.

The adapter instances are ready to be deployed. After the instances are deployed, when a message is sent to the adapter, the instance that is not busy will handle the request.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Compressing JMS Messages | 219

Compressing JMS Messages

JMS message compression is an instance-level option. It is especially useful when messages are to be stored on the TIBCO Enterprise Message Service server, including persistent queue messages, or topics with durable subscribers. Enabling compression ensures that messages take less memory space in storage and are handled faster by the

TIBCO Enterprise Message Service server. When JMS messages are compressed and stored, they are handled by the server in the compressed form.

The compression option only compresses the body of a message. Headers and properties are never compressed. It is best to enable compression when the message bodies are large and the messages are to be stored on a server.

When messages are not to be stored, compression is not as useful. Compression normally takes time, and therefore the time to send or publish and receive compressed messages is generally longer than the time to send the same messages uncompressed. There is little purpose to message compression for small messages that are not to be stored by the server.

You can enable or disable this feature for message senders with the following adapter property:

• adb.jmscompress

Either on

or off

. The default value is off

, which indicates that messages will not be compressed

JMS message compression is only for publication service with JMS transport.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

220 | Chapter 9 Advanced Features

Configuring RVCMQ Backlog Size

The RVCMQ scheduler receives the inbound messages and assigns them to the worker.

The scheduler stores tasks in a message queue. You can limit the maximum size of that queue with either one of the following two adapter properties or both of them:

• adb.taskBackLogLimitInBytes

: Specifies the maximum size of the scheduler task queue by number of bytes. This value must be an integer. The default value is unspecified.

• adb.taskBackLogLimitInMessages

: Specifies the maximum size of the scheduler task queue by number of messages. This value must be an integer. The default value is unspecified.

When the task messages in the queue exceed either of these limits, TIBCO Rendezvous deletes new inbound task messages.

If neither of the above properties are specified, there will be no limit to the size of the scheduler task queue.

RVCMQ backlog size configuration is for subscription and request-response services only, which have RVCMQ or RVDQ transport, not for publication service, which does not have this transport type.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Chapter 10

Setting Encoding Options

This chapter describes how to use TIBCO ActiveMatrix Adapter for Database in an international environment using non-ASCII languages.

| 221

Topics

•

Overview, page 222

•

Setting TIBCO Messaging Encoding, page 224

•

Configuring the Adapter to Communicate with the Database, page 226

•

Relevant Environment Settings, page 231

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

222 | Chapter 10 Setting Encoding Options

Overview

TIBCO ActiveMatrix Adapter for Database provides internationalization support by taking advantage of Unicode, which is supported by the TIBCO Adapter SDK. Currently the international data support is provided for text data only.

The following illustration shows an example of TIBCO ActiveMatrix Adapter for

Database in a Japanese language environment serving databases of different encodings.

The adapter converts the encoding between Unicode and the character sets of the databases.

Figure 7 Example of Unicode Conversion

Oracle DB in Shift-JIS

Oracle DB in

EUC-JP

Driver Manager/ODBC Driver/Database Client

Shift-JIS EUC-JP

Adapter Publishing

Service

UTF-8

Adapter

Subscription Service

UTF-8

TIBCO Messaging

In this example, Shift-JIS encoded Japanese data is retrieved from an Oracle database by the adapter publication service, which converts the data into UTF-8 and publishes the

UTF-8 data to the TIBCO messaging environment. An adapter subscription service receives this message and converts it from UTF-8 to EUC-JP, and inserts the data into an

Oracle EUC-JP database to which it is connected.

By using UTF-8 as the TIBCO Messaging encoding between TIBCO ActiveEnterprise components, the two adapter services can serve databases of different encodings by exchanging data without data garbling it.

In certain cases, intermediate entities (such as an ODBC driver, ODBC driver manager, or the database vendor's proprietary database client) may also perform some encoding conversion.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Overview | 223

In circumstances where only ASCII and Latin-1 data (including English and Western

European languages) are exchanged in the system, you can use Latin-1 encoding as the

TIBCO Messaging encoding between TIBCO ActiveEnterprise components. It is not necessary to use UTF-8 as the TIBCO Messaging encoding in this case. UTF-8 is only required when the data to be exchanged is not included in the Latin-1 character set, as is the case with Asian languages and other European languages.

To configure the adapter to work correctly in transmitting non-ASCII data, you must set the TIBCO messaging encoding property. The following sections explain how to do this.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

224 | Chapter 10 Setting Encoding Options

Setting TIBCO Messaging Encoding

TIBCO ActiveEnterprise components (TIBCO applications and adapters) use TIBCO

Messaging encoding when communicating with each other. In the case of TIBCO

ActiveMatrix Adapter for Database, publication services use this encoding to publish data into TIBCO messaging system, and subscription services use it to receive data from the

TIBCO messaging system.

The services do not use TIBCO Messaging encoding to connect to the backend database.

using a wire protocol driver. See

Configuring the Adapter to Communicate with the Database on page 226

for more information.

There are currently two choices for TIBCO Messaging encoding: Latin-1 (ISO8859-1) for transmitting ASCII and Latin-1 data, and UTF-8 for transmitting data of other languages.

The encoding property is set on the project itself at design time, and in the TIBCO administration server’s property file when creating a TIBCO administration domain.

Encoding in a Server-based Project

The TIBCO administration server setting is used when the project is exported to a server repository or deployed using TIBCO Administrator Enterprise Edition.

For a server based project, the TIBCO messaging encoding is set by the repo.encoding

property in the server's tibcoadmin domain_name

.tra configuration file (located in

TIBCO_HOME

/administrator/ version

/bin/

The encoding is set when using the TIBCO Domain Utility to create the domain or by editing the repo.encoding

property in the TRA configuration file.

Each adapter or TIBCO application that uses the same server for storing and retrieving configuration data uses this encoding setting when communicating to each other. This assures that all TIBCO components (including adapters and other TIBCO applications) that belong to the same project use the same encoding value to communicate.

Encoding in a Local Project File

If the project's configurations are saved in a local project file, which is the normal case when the project is in design stage before deployment, the TIBCO Messaging encoding is determined by the encoding property saved in the local project file.

The encoding value is set on the root project folder in TIBCO Designer. By default, the value is set to

ISO8859-1

. You can change the value by selecting the folder and under the

Project Settings tab, changing the value for the TIBCO Message Encoding field.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Setting TIBCO Messaging Encoding | 225

In order for different TIBCO components that each have their own local file repository to communicate with each other without data garbled, they must use the same TIBCO

Messaging encoding, meaning that all these components must set their local project encoding to the same value.

The encoding property of a local project file is only for determining the TIBCO

Messaging encoding, not the encoding used for the persistent storage of the project files.

The project files are always saved as UTF-8 encoded files.

After a project is deployed as a server-based project, the encoding property set at design time is superseded by the encoding property set for the TIBCO administration server.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

226 | Chapter 10 Setting Encoding Options

Configuring the Adapter to Communicate with the Database

The TIBCO message encoding is a project setting used for data conversion among different components. However, the adapter uses a different encoding value for exchanging data with the database. Because there are many intermediate entities between the adapter and the database (such as the ODBC driver manager, ODBC driver, and possibly the database native client), and each of these entities may conduct encoding conversions to the data stream flow between the service and the database, the data encoding from the database might not be known, while the data encoding to the database must be compatible to that of the database.

To eliminate the complexity introduced by these intermediate entities, you can make some configuration changes that ensure the service’s encoding setting are compatible with the database instance's encoding. This also boosts the performance by eliminating unnecessary intermediate data conversions.

The configuration changes differ depending on the operating system that the service is running on, the database vendor, the ODBC driver used, and other factors. The following sections explain how to configure the adapter to communicate with the database.

Configuring the Adapter at Design Time

Use the following steps to set the adapter’s encoding.

1. Determine your database server encoding. This is the encoding you want to use for the adapter’s encoding. For example, for the Oracle database, the encoding can be found by querying the database with: select * from nls_database_parameters;

2. Set the NLS_LANG environment variable for the client system.

Set the client machine's NLS_LANG environment variable to be consistent to the database instance's character set (NLS_CHARACTERSET) value. The client machine is where the adapter service is going to run. Consult your database administrator for the NLS_CHARACTERSET value of the database instance to connect to, and how to choose the right NLS_LANG value.

As an example, the system may use an Oracle database instance with the

NLS_CHARACTERSET value set to JA16SJIS. In this case, the client machine's

NLS_LANG environment variable must be set to JAPANESE_JAPAN.JA16SJIS.

The correct setting of the NLS_LANG environment variable eliminates the encoding conversion possibly conducted by the Oracle proprietary client.

3. Set the Adapter encoding in TIBCO Designer.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Configuring the Adapter to Communicate with the Database | 227

You must select or enter a valid encoding that the adapter understands. The adapter assumes the data coming from the database is in this encoding and ensures that data sent to the database is in this encoding. The encoding given here should match the encoding set for the database to which the adapter connects.

There are two ways to do this configuration:

— In TIBCO Designer, set this in the adapter resource. In the Configuration tab, check the Show All Tabs checkbox. In the General tab, choose the encoding that is compatible with the encoding of the database instance to be connected to. See

Table 43, TIBCO ActiveMatrix Adapter for Database and Oracle NLS_Lang

Values

The adapter may support more encoding values than those shown in TIBCO

Designer. You can type in these encoding values. For more information about these, See Appendix B in TIBCO Adapter Concepts.

— You can modify the adapter encoding property, adb.encoding

, in the adapter’s TRA configuration file. This setting supersedes the encoding option chosen in TIBCO

Designer.

4. Set the ODBC DSN in TIBCO Designer

This field is set under the adapter’s Runtime Connection tab. You must also define the

ODBC DSN on the machine on which the adapter is running.

— On Unix systems, modify the odbc.ini

file

TIB_ADADB_HOME

/odbc

. In addition, you must set the correct

IANAAppCodePage

to match the database encoding, if you are

Table 42, IANAAppCodePage, on page 227

for a list of

IANAAppCodePage

values. The complete list is available in

TIB_ADADB_HOME

/odbc/help/odbcref/odbcref.pdf

— On Windows systems, use the Windows ODBC GUI to define a system DSN. Note that if you are using a TIBCO wire protocol driver, the machine on which the adapter is running must be on the locale that matches the database encoding.

Table 42 IANAAppCodePage

Value

Encoding (Language)

ASCII (English)

113

ISO_8859-1 (Western European)

Shift_JIS (Japanese)

EUC_JP (Japanese)

EUC_KR (Korean)

GBK (Simplified Chinese)

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

228 | Chapter 10 Setting Encoding Options

Table 42 IANAAppCodePage (Cont’d)

Value

2026

Encoding (Language)

BIG5 (Traditional Chinese)

Using a non-Oracle Database

When using a database other than Oracle, contact the database vendor for information about whether the database's proprietary client performs any encoding conversion to the data flow, and how to configure the database client to eliminate the conversion possibly conducted by it. Several possibilities exist:

• The database client does not perform any conversion to the data flow in any cases. In this case, you only need to set the adapter encoding to be compatible with the database instance's encoding.

• The database client relies on a local setting, such as an environment variable, to determine whether or not a conversion should to be conducted. This is similar to the above Oracle example, where you need to set both this local setting and the adapter’s adapter encoding property to be compatible with the database server instance's encoding.

• The database client relies on the local system encoding to determine the conversion.

— When the local system encoding is compatible with the database instance encoding, no conversion will be conducted by the database client. You only need to set the adapter encoding to be compatible with the database server instance encoding;

— When the local system encoding is different from the database instance's encoding, the proprietary database client may do the encoding conversion between the two different encodings. This conversion cannot be avoided by any settings you can make. In this case, set the adapter encoding to be consistent with the local system encoding, because the data from the database has been converted to local system encoding by the database client.

When using the DataDirect non-wire protocol ODBC driver and UTF-8 as the adapter encoding to support multilingual data exchange, the configuration is totally different. See

the section

Special Configurations for Supporting a UTF-8 Database on page 228

Special Configurations for Supporting a UTF-8 Database

This section applies only to TIBCO ODBC drivers.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Configuring the Adapter to Communicate with the Database | 229

Companies doing business globally may require their database to be multilingual, that is, a single database instance supporting multiple languages so the data from the company's global business can be stored in it. Unicode is a natural choice for the encoding of this kind of database instance.

This requires the adapter to be able to use Unicode, or specifically, UTF-8 encoding, to communicate with the database. While this is already a supported feature, an exception exists when using TIBCO ODBC drivers.

TIBCO ActiveMatrix Adapter for Database contains a binary mode for use with an embedded TIBCO driver when UTF-8 is the encoding to communicate with the backend database instance. The configurations described below are applicable to both Windows and UNIX platforms, and both non-wire and wire protocol drivers.

1. Set the adapter’s encoding option to

UTF8

2. In the adapter’s

.tra

file, uncomment the following line:

#ADB.WCHAR = SQL_C_BINARY

This forces the adapter to use binary mode to communicate with the database.

3. Set the

NLS_LANG

environment variable to language

_ territory

.AL32UTF8

or language

_ territory

.UTF8

if using vendor or DataDirect non-wire driver.

These are for the internationalization configuration, which forces the adapter to use binary mode to communicate to the database instance. No further encoding related configurations are necessary. For example, on UNIX there is no need to set the

AppCodePage

attribute, and when using a non-wire driver there is no need to set the proprietary database client.

Special Configurations for Retrieving Unicode Data from Database

To retrieve unicode data from unicode character data types such as NCHAR and

NVARCHAR, the following adapter properties are required: adb.unicode

— specify the unicode type of the data, either UTF8 or UTF16 adb.wchar — specify whether to retrieve the unicode code as character or binary string.

When adb.unicode

is set, the adapter will automatically set the value of this property to

SQL_C_BINARY

When the adb.unicode

option and the database national character set are both UTF8, the adapter will add blanks after string values in published mess a age for nchar/nvarchar2 column.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

230 | Chapter 10 Setting Encoding Options

Runtime Environment Variables

In general, after deploying the adapter, all information should be in the correct place, however you should verify the deployed TRA file and platform settings. The encoding conversion is dependent on the TIB_ICU_DATA environment variable. The deployed adapter TRA file should have a property called tibco.env.TIB_ICU_DATA

. Make sure it points to the directory containing the tibicudata.dat

file.

For the Oracle database, make sure the installed NLS_LANG attribute’s value matches the database character set. If not, set NLS_LANG to the correct value before starting the adapter. See

TIBCO ActiveMatrix Adapter for Database and Oracle NLS_Lang Values on page 231

for a list of values.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Relevant Environment Settings | 231

Relevant Environment Settings

Shift_JIS (CP943)

Shift_JIS (TIBCO)

KSC-5601

Big5

In order to support international languages, the adapter uses the tibicudata.dat

file to convert between the original database encoding and the TIBCO Messaging encoding (usually

UTF-8). The environment variable TIB_ICU_DATA is already configured to point to the directory containing this file. Do not change this setting.

This environment variable setting is required on both Windows and Unix platforms.

The following table lists the TIBCO ActiveMatrix Adapter for Database encoding values as shown in TIBCO Designer.

Table 43 TIBCO ActiveMatrix Adapter for Database and Oracle NLS_Lang Values

Adapter Encoding

ASCII

Oracle NLS_LANG (containing

NLS_CHARACTERSET)

US7ASCII

Description

7-bit ASCII

ISO8859-1 language_territory.WE8ISO8859P1 ISO8859-1 (Latin-1), West European

JAPANESE_JAPAN.JA16SJIS

Japanese Shift-JIS, CP943

Variant of IBM-943 (created by TIBCO for flavoring some MS-932 conversions)

Korean KSC-5601

Traditional Chinese Big5 with Euro

GBK

EUC-JP

UTF8

KOREAN_KOREA.KO16KSC5601

TRADITIONAL

CHINESE_TAIWAN.ZHT16BIG5

SIMPLIFIED CHINESE_CHINA.

ZHS16CGB231280

JAPANESE_JAPAN.JA16EUC

AMERICAN_AMERICA.UTF8

Simplified Chinese GBK (superset of

GB2312-80)

Japanese EUC

Unicode Transformation Format-8

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

232 | Chapter 10 Setting Encoding Options

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Chapter 11

Monitoring the Adapter

Read this if you have installed TIBCO Hawk and want to use TIBCO Hawk microagents through the Monitoring tab of an adapter instance. TIBCO Hawk is an optional tool from

TIBCO Software Inc. that can be used in addition to the standard trace message logging method described under

Logging Tab on page 49

| 233

Topics

•

Overview, page 234

•

Starting TIBCO Hawk Software, page 235

•

The Auto-Discovery Process, page 236

•

Invoking Microagent Methods, page 237

•

Available Microagents, page 240

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

234 | Chapter 11 Monitoring the Adapter

Overview

TIBCO Hawk is a sophisticated tool for enterprise-wide monitoring and managing of all distributed applications and systems. System administrators can use it to monitor adapters in a wide area network of any size. TIBCO Hawk can be configured to monitor system and adapter parameters and to take actions when predefined conditions occur. These actions include: sending alarms that are graphically displayed in the TIBCO Hawk display, sending email, paging, running executables, or modifying the behavior of a managed adapter.

Unlike other monitoring applications, TIBCO Hawk relies on a purely distributed intelligent agent architecture using publish or subscribe to distribute alerts. TIBCO Hawk uses TIBCO Rendezvous for all messaging and thus gains the benefits and scalability from the TIBCO Rendezvous features of publish/subscribe, subject name addressing, interest-based routing, and reliable multicast.

TIBCO Hawk is a purely event-based system that uses alerts. The agents are configured with rules that instruct them on everything from what and how to monitor to what actions to take when problems are discovered. Thus the workload is fully distributed throughout the enterprise. Every agent is autonomous in that it does not depend on other components to perform its functions.

The TIBCO Hawk Enterprise Monitor consists of these components:

• Display—GUI front end that displays alarms and provides editors to create rule bases, create tests, view messages, and invoke microagents to request information or initiate an action.

• Agents—Intelligent processes that perform monitoring and take actions as defined in rules.

• Rulebases—Rules that are loaded by agents to determine agent behavior.

• Application Management Interface (AMI)—Manages network applications via

TIBCO Rendezvous and supports communication between a network application and monitoring TIBCO Hawk agents, including the ability to examine application variables, invoke methods, and monitor system performance.

• Microagents—Feed information back to TIBCO Hawk and expose action methods to rulebases.

For more information, see the TIBCO Hawk documentation.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Starting TIBCO Hawk Software | 235

Starting TIBCO Hawk Software

The TIBCO Hawk agent can be configured to start automatically during the system boot cycle. See TIBCO Hawk Installation and Configuration for information about starting

TIBCO Hawk.

TIBCO Hawk Administrator’s Guide explains how to start the TIBCO Hawk Display.

The guides are included in your TIBCO Hawk software installation area.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

236 | Chapter 11 Monitoring the Adapter

The Auto-Discovery Process

After you start an instance of TIBCO Hawk Display, it continually discovers machines running TIBCO Hawk Agents on your network. Container icons are created for each agent, and arranged hierarchically in clusters. By default, agent icons are clustered according to subnets.

At first, the Agents container is empty. Its counter displays a value of zero and, on the right, the Discovered counter is also at zero. Both icons are initially green in color to show that no alerts, or warning messages, are in effect. As agents are discovered, the counters increment to reflect the current number of discovered agents:

Monitored network nodes are arranged in a hierarchical tree of containers. Clicking a container in the left panel displays nested items on the right.

Icon colors change to reflect the highest level of alert found on discovered agents. For explanations of icon elements and characteristics, see TIBCO Hawk Administrator’s

Guide.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Invoking Microagent Methods | 237

Invoking Microagent Methods

A set of default microagents is loaded when a TIBCO Hawk Agent is started. When you install and start TIBCO ActiveMatrix Adapter for Database, its microagents are dynamically added to the local agent.

To invoke a microagent method:

1. In TIBCO Hawk Display, right-click on the agent icon and select Get Microagents.

If TIBCO Hawk security is implemented on your system and you do not have access to microagents on this agent, an error dialog displays. Select another agent, or contact your system administrator to obtain access.

The Microagents, Methods and Arguments dialog displays. The panel on the upper left lists microagents you can access on the current agent.

This dialog has two modes, Invoke and Subscribe. Invoking a method immediately returns a single set of current results. Subscribing provides updates of current results at regular intervals. Radio buttons at the bottom of the dialog control these modes.

2. Click a microagent name, such as Self, to display a list of associated methods and text descriptions in the panels below.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

238 | Chapter 11 Monitoring the Adapter

3. Click the name of the method to invoke, such as getComponentInfo

If the method accepts arguments, fields for each argument display in the upper right panel. Detailed help text displays in the lower panel.

4. Specify any arguments for the method invocation.

5. Verify that the Invoke radio button is selected.

6. Click the Invoke button to invoke the selected method.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Invoking Microagent Methods | 239

The Invocation Results dialog displays the results returned by the method.

7. Click the Done button to close the dialog.

These steps describe how to interactively invoke a microagent method and receive a single set of results in TIBCO Hawk Display. You can also use a microagent method as the data source of a TIBCO Hawk rule. Rules automatically receive method results, apply tests to evaluate them, then take action if necessary. For more information on building TIBCO

Hawk rules and rule bases, see TIBCO Hawk Administrator’s Guide.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

240 | Chapter 11 Monitoring the Adapter

Available Microagents

Each adapter has three microagents: a standard TIBCO Hawk microagent, a class microagent, and a custom microagent.

Microagents follow different naming conventions depending on how an adapter is started: from TIBCO Designer, or from TIBCO Administrator.

When an adapter is started in TIBCO Designer or through a console, the available microagents follow the below naming conventions:

• Standard Microagent:

COM.TIBCO.ADAPTER.adb.%%Deployment%%.%%InstanceId%%

• Class Microagent:

COM.TIBCO.adb.%%Deployment%%.%%InstanceId%%

• Custom Microagent:

COM.TIBCO.adb.custom.%%Deployment%%.%%InstanceId%%

When an adapter is started from a deployed project in TIBCO Administrator, the available microagents follow the below naming conventions:

• Standard Microagent:

COM.TIBCO.ADAPTER.adb.

domain_name

.%%Deployment%%.%%InstanceId%%

• Class Microagent:

COM.TIBCO.ADAPTER.adb.%%Deployment%%.%%InstanceId%%

• Custom Microagent:

COM.TIBCO.adb.custom.%%Deployment%%.%%InstanceId%%

These microagents provide:

• Business level statistics—statistics that report the progress of the adapter as it interacts with the database. For example, in a database adapter such statistics might indicate whether objects were successfully or unsuccessfully inserted, updated, or deleted in the database.

• Queries that return information about the state of the adapter. This can be an important tool for seeing the internals of an adapter and debugging it if something appears wrong. For example, methods can return information about threads, internal queues, or connections to the target system. Using these methods, one might be able to identify certain bottlenecks or gauge how successfully an adapter is scaling with respect to the current environment.

• Updates of the adapter runtime parameters. This includes retrieving the current runtime parameters and setting new runtime parameters without restarting the adapter.

An example of this is getting and setting the polling interval. Updating a runtime parameter through the Hawk microagent only affects the setting of the instance that is

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Available Microagents | 241 running. It does not make a permanent change of the setting in either the repository or the

.tra

file.

The following table lists each method available for the adapter. Although the Microagents,

Methods and Arguments dialog in TIBCO Hawk Display lists more methods than are documented here, only the following methods are supported.

Table 44 Standard Microagent Methods

Standard Method

activateTraceRole()

Description

Activates a mapping of a role to a sink at runtime.

deactivateTraceRole()

getAdapterServiceInformation()

getComponents()

getConfig()

getConfigProperties()

preRegisterListener()

reviewLedger()

Deactivates a mapping of a roles to sinks at runtime.

Returns information about the services implemented by this adapter.

Returns information about the publisher, subscriber and

IODescriptor.

Returns basic configuration information. More specific information is accessed by the more specific methods.

Returns a list of publishers and subscribers.

Returns standard and extended application information.

Returns information about all TIBCO Rendezvous sessions defined.

Returns general status information, such as the number of TIBCO Rendezvous messages received and published, the number of errors since the last call, the

PID of the application, and more.

Returns information about sinks to which traces currently go.

Returns the configuration ID, application name, version, and date for this adapter instance.

Displays alert messages sent to the current adapter.

Preregisters an anticipated listener.

Returns information retrieved from the ledger file of a certified messaging session for a publisher adapter.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

242 | Chapter 11 Monitoring the Adapter

Table 44 Standard Microagent Methods (Cont’d)

Standard Method

setTraceSinks()

Description

Adds a role or changes the file limit of a previously specified sink.

stopApplicationInstance()

Stops the running adapter instance.

unRegisterListener()

Unregisters a currently preregistered listener.

Table 45 Custom Microagent Methods

Custom Method

getEventQueueSize()

Description

Retrieves the size of the TIBCO Rendezvous event queue for the specified adapter instance.

setDebugLevel()

Sets the debug level for the current adapter instance.

getPollingBatchSize()

setPollingBatchSize()

Changes the value of the verbose flag from on to off, or the reverse.

Shows the configuration defined for the current agent.

Stops the current TIBCO ActiveMatrix Adapter for

Database agent.

Returns the current polling interval setting.

Set the polling interval for the publication service.

Get the polling batch size for the publication service.

Set the polling batch size for the publication service.

Table 46 Custom Microagent Methods with adb.perfMon

Custom Method

getActivityStatistics()

Description

Returns the total number of objects processed for all the schemas, based on the request type. Also, returns the number of success and error objects.

getActivityStatisticsByService

getActivityStatisticsByOperation()

Returns the total number of objects processed for each of the schemas associated with the specified service.

Returns the total number of objects processed for all the schemas by each service that is associated with a specified operation.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Available Microagents | 243

Table 46 Custom Microagent Methods with adb.perfMon (Cont’d)

Custom Method

getThreadStatistics()

Description

Return the operation counts of the current threads.

getQueueStatistics()

getConnectionStatistics()

resetActivityStatistics()

resetThreadStatistics()

resetQueueStatistics()

resetConnectionStatistics()

Return the current count of elements in any internal queue used by the adapter.

Returns the state and statistics for all the current connections used by the adapter.

Resets all the counts for the activity statistics.

Resets all the counts for the thread statistics.

Resets all the counts for the queue statistics.

Resets all the counts for the connection statistics.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

244 | Chapter 11 Monitoring the Adapter

activateTraceRole()

Purpose

Parameters

(Standard) Activates a mapping of a role to a sink at runtime. This replaces the now-deprecated setTraceSink()

TIBCO Hawk method.

Parameters roleName sinkName

Type string string

Description

Name of the role to activate.

Name of a sink for which to activate the role.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

deactivateTraceRole() | 245

deactivateTraceRole()

Purpose

Parameters

(Standard) Deactivates a mapping of a roles to sinks at runtime.

Parameters

Role Name

Sink Name

Type string string

Description

Name of the role to activate.

Name of a sink for which to activate the role.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

246 | Chapter 11 Monitoring the Adapter

getAdapterServiceInformation()

Purpose

Parameters

(Standard) Returns information about the services implemented by this adapter. The information is a summary of available adapter services.

Parameter

Service Name

Type string

Description

Name of the service from which to get information.

Default is

ALL.

Returns

Line

Name

Endpoint

Type

Quality of Service

Type

Integer string string string string

Adapter Name

Session Name string string

Subject string

Number of Messages Integer

Description

Sequential row number.

Name of the Service.

Name of the endpoint used for this service.

Type of the endpoint, for example, Publisher,

Subscriber.

Quality of service for the endpoint, for example,

RV, RVCM.

Name of the application for this sink.

Name of the TIBCO Rendezvous session.

Subject defined for this endpoint

Number of messages processed for this endpoint.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

getComponents() | 247

getComponents()

Purpose

Parameters

(Standard) Returns information about the currently active TIBCO Hawk components such as publishers, subscribers, or timers.

Parameters

Component Name

Component Type

Type string string

Description

Name of the TIBCO Hawk component. Default is all components.

Any of

Publisher

Subscriber

Timer

, or

IODescriptor

. The default value is

All

Returns

Component Name

Instance ID

Adapter Name

Session Name

Component Type

Description

Type string string string string string string

Description

Name of the TIBCO Hawk component.

Name of this adapter instance.

Name of the adapter.

Name of the TIBCO Rendezvous session.

The name of the TIBCO Adapter SDK class for this

TIBCO Hawk component, such as

MPublisher

MSubscriber

, or

MIODescriptorSource

. For more information, see your TIBCO Adapter SDK documentation.

Information about this TIBCO Hawk component, for example, time interval, signal type, validating publisher

(or subscriber) etc.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

248 | Chapter 11 Monitoring the Adapter

getConfig()

Purpose

Returns

(Standard) Retrieves generic configuration information. More specific configuration information is accessed through separate methods.

Returns

Instance ID

Adapter Name

Repository

Connection

Configuration URL

Type string string string string

Description

Configuration ID of this adapter.

Name of the adapter.

URL of the repository used for adapter instance.

Command string

Location of the adapter project; either a file name or configuration URL.

Command line arguments used to start the adapter.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

getConfigProperties() | 249

getConfigProperties()

Purpose

Parameters

(Standard) Returns all attributes and elements for the given repository object.

Parameter

Property

Type string

Description

Name of the property for which elements (tags) and attributes are desired. For example, rvpub/startup

If no value is given, all properties are returned.

Returns

Element Name

Attribute Name

Attribute Value

Line

Type string string string integer

Description

Repository directory for the property.

Name of the repository object attribute.

Value of the repository object attribute.

Line number in which this property is defined in the project file.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

250 | Chapter 11 Monitoring the Adapter

getHostInformation()

Purpose

Returns

(Standard) Returns standard and extended application information.

Returns

Name

Value

Type Description string string

Name of the property.

Value of the property.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

getRvConfig() | 251

getRvConfig()

Purpose

Parameters

(Standard) Returns information about the TIBCO Rendezvous session defined by this adapter. Information about all currently defined sessions is returned if no sessionName

is provided.

Parameter

Session Name

Type string

Description

Name of the TIBCO Rendezvous session for which configuration is required (default is all).

Returns

Instance ID

Adapter Name

Session Name

Service

Daemon

Network

Synchronous?

Session Type

Certified Name

Ledger File

CM Timeout

Type string string string string string string boolean string string string string

Description

The configuration ID of this adapter.

Name of the adapter.

Name of the session.

Service parameter for this session.

Daemon parameter for this session.

Network parameter for this session.

Returns

if this is a synchronous session,

otherwise.

Type of session; one of

M_RV

M_RVCM

, or

M_RVCMQ

Name of this certified session.

Ledger file for this certified messaging session. Returns the empty string for sessions that are not certified messaging sessions.

Timeout for this certified messaging session. Returns the empty string for sessions that are not certified messaging sessions.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

252 | Chapter 11 Monitoring the Adapter

getStatus()

Purpose

Returns

(Standard) Retrieves basic status information about the adapter.

This information is fairly limited; for more detail, additional methods are provided:

getConfig() on page 248

shuts down. You can configure the adapter for automatic reconnection (see

getRvConfig() on page 251

Returns

Instance ID

Adapter Name

Uptime

Messages Received

Messages Sent

New Errors

Total Errors

Process ID

Host

Type string string integer integer integer integer integer integer string

Description

Configuration ID for this adapter instance.

Name of the adapter.

Number of seconds since startup.

Number of TIBCO Rendezvous messages received.

Number of TIBCO Rendezvous messages published.

Number of errors since the last call to this method.

Total number of errors since startup.

Process ID of the application.

Name of host machine on which this adapter is running.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

getTraceSinks() | 253

getTraceSinks()

Purpose

Parameters

(Standard) Returns information about sinks to which traces currently go.

Parameters

Sink Name

Role Name

Type string string

Description

Name of the sink for which you need information. If no name is specified, information about all sinks is returned. Default is all.

Name of the role for which you need information for the specified sink or sinks. Default is all.

Returns

Instance ID

Adapter Name

Sink Name

Sink Type

Roles

Type string string string string string

Description

Name of this adapter instance as a string.

Name of the application for this sink.

Name of the sink

Type of this sink. One of fileSink

, rvSink

, hawkSink

, stderrSink

Roles this sink supports, as a string. For example

“warning, error, debug”

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

254 | Chapter 11 Monitoring the Adapter

getVersion()

Purpose

Returns

(Standard) Retrieves version information for the current application. Two lines may be returned, one for the TIBCO Adapter SDK, one for the adapter.

Returns

Instance ID

Adapter Name

Version

Description

The configuration ID as a string, for example

SDK

Name of the adapter as a string, for example rvpub

Version number as a string, for example

1.1

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

_onUnsolictedMsg() | 255

_onUnsolictedMsg()

Purpose

(Standard) Displays all alert messages sent from the adapter or an error if not successful.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

256 | Chapter 11 Monitoring the Adapter

preRegisterListener()

Purpose

Parameters

(Standard) Preregister an anticipated listener. Some sending applications can anticipate requests for certified delivery even before the listening applications start running. In such situations, the sender can preregister listeners, so TIBCO Rendezvous software begins storing outbound messages in the sender’s ledger. If the listening correspondent requires old messages, it receives the backlogged messages when it requests certified delivery.

Parameters

Session Name

Publisher Name

Listener Session

Name

Type string string string

Description

Name of the session that anticipates the listener.

Name of the component for which the listener should be preregistered.

Name of the listener to preregister.

Returns

OK if the listener was preregistered successfully, false otherwise.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

reviewLedger() | 257

reviewLedger()

Purpose

Parameters

(Standard) Returns information retrieved from the ledger file of a TIBCO Rendezvous certified messaging session. Before invoking this method, ensure that the certified messaging publisher adapter has established a certified delivery agreement with its subscriber agents.

Parameters

Session Name

Subject

Type string string

Description

Name of the TIBCO Rendezvous session for which ledger information is desired (default is all).

Name of the subject for which ledger information is desired.

Returns

Session Name

Subject

Last Sent Message

Total Messages

Total Size

Type string string integer string integer

Listener Session Name string

Last Confirmed string

Line

UnacknowledgedMess ages integer integer

Description

Name of the TIBCO Rendezvous CM session to which this information applies.

Subject name for this session.

Sequence number of the most recently sent message with this subject name.

Total number of pending messages with this subject name.

Total storage (in bytes) occupied by all pending messages with this subject name.

If the ledger contains ten messages with this subject name, then this field sums the storage space over all of them.

Within each listener submessage, the Listener Session Name field contains the name of the delivery-tracking listener session.

Within each listener submessage, the Last Confirmed field contains the sequence number of the last message for which this listener session confirmed delivery.

Row number in ledger file.

Number of RVCM messages pending for this listener. The value is computed by subtracting the last sent sequence number from the last acknowledged sequence number.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

258 | Chapter 11 Monitoring the Adapter

setTraceSinks()

Purpose

Parameters

(Standard) Adds a role or changes the file limit of a previously specified sink.

Parameters

Sink Name

Role Name

File Size

Type string string integer

Description

Name of the sink for which you want to add a role or change the file limit.

Name of the role you want to add to this sink (warning, error, debug, or user defined). Default is all.

Maximum file size for this sink.

This parameter is ignored if the sink specified by sinkName is not a file sink.

Returns

if successful or an error if not successful.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

stopApplicationInstance() | 259

stopApplicationInstance()

Purpose

Returns

(Standard) Stops the specified adapter by calling the internal stop()

method.

if successful or an error if not successful.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

260 | Chapter 11 Monitoring the Adapter

unRegisterListener()

Purpose

Parameters

(Standard) Unregisters a currently preregistered listener.

Parameters

Publisher Name

Listener Session

Name

Type string string

Description

Name of the component for which the listener should be preregistered.

Name of the listener to unregister.

Returns

True

if the listener was successfully unregistered,

False

otherwise.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

getEventQueueSize() | 261

getEventQueueSize()

Purpose

Parameters

(Custom) Retrieves the size of the TIBCO Rendezvous event queue for the specified adapter instance. For more information on events and event queues, see TIBCO

Rendezvous Concepts.

Parameter

Session

Type string

Description

Type of listener for this adapter instance. Possible values are

Subscriber

Request/Reply

. The default value is

Subscriber

Returns

Return

QueueCount

QueueLimit

Type integer integer

Description

The number of events currently in the event queue.

The maximum number of events this adapter instance can have in the event queue. This value is set using the adb.rvMaxQueueSize

option in the adapter’s properties file. The default value is

, which means the event queue has unlimited size.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

262 | Chapter 11 Monitoring the Adapter

setDebugLevel()

Purpose

Parameters

(Custom) Sets the debug level for the current adapter instance.

Parameter

DebugLevel

Type integer

Description

Sets the debug level to

(off),

, or

— No debug information displayed.

—SQL commands executed with the database shown.

—ODBC data source for each SQL command shown.

—All debug information displayed.

Returns

if successful or an error if not successful.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

toggleVerboseFlag() | 263

toggleVerboseFlag()

Purpose

Returns

(Custom) Changes the value of the verbose flag from on

off

, or the reverse.

This method returns

if successful or an error if not successful.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

264 | Chapter 11 Monitoring the Adapter

showConfiguration()

Purpose

Parameters

(Custom) Shows the configuration defined for the current agent.

Parameter

VerboseInfo

DebugLevelInfo

PollIntervalInfo

Type string string string

Description

The current setting for the verbose mode, on or off.

The debug level setting:

— No debug information displayed.

—SQL commands executed with the database shown.

—ODBC data source for each SQL command shown.

The poll interval in milliseconds.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

terminateADBagent() | 265

terminateADBagent()

Purpose

Remarks

Returns

(Custom) Stops the current TIBCO ActiveMatrix Adapter for Database agent.

Invoking this method displays a warning message with the text

MicroAgent returned error. AMI

Method invocation timed out

. The message can be ignored.

This method returns

if successful or an error if not successful.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

266 | Chapter 11 Monitoring the Adapter

getPollingInterval()

Purpose

Returns

(Custom) Returns the current polling interval setting.

Returns

PollingInterval

Type integer

Description

Polling interval in milliseconds.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

setPollingInterval() | 267

setPollingInterval()

Purpose

Parameters

(Custom) Set the polling interval for the publication service.

Parameter

PollingInterval

ServiceName

Type integer string

Description

Polling interval in milliseconds.

(Optional) Name of service where the polling interval is set.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

268 | Chapter 11 Monitoring the Adapter

getPollingBatchSize()

Purpose

Returns

(Custom) Get the polling batch size for the publication service.

Returns

BatchSize

Type integer

Description

The batch size for the publication service.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

setPollingBatchSize() | 269

setPollingBatchSize()

Purpose

Parameters

(Custom) Set the polling batch size for the publication service.

Parameter

BatchSize

Type integer

Description

The new batch size for the publication service.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

270 | Chapter 11 Monitoring the Adapter

getActivityStatistics()

Purpose

Parameters

(Custom with adb.perfMon

) Returns the total number of objects processed for all the schemas, based on the request type. Also, returns the number of success and error objects.

Parameter

Get Subtotal By

Type integer

Description

Statistics categorized by service or by operation.

Returns

Name

Total

Success

Failure

Type string integer integer integer

Description

Name of the service or operation. The operation can be one of the following:

Fetch

Poll

Insert

Update

Delete

Total number of objects processed for this schema for a publication service.

Total number of objects received for this schema for a subscription service.

The number of objects that were successfully identified for this schema which will be published or written to a file.

The number of objects that were identified for this schema but were not published because the header of the schema failed validation for the publication service, or was written to a file because the schema was not associated with the subscriber for a subscription service.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

getActivityStatisticsByService | 271

getActivityStatisticsByService

Purpose

Parameters

(Custom with adb.perfMon) Returns the total number of objects processed for each of the schemas associated with the specified service. Also, returns the number of success and error objects.

Parameter

Service Name

Type string

Description

Name of the service.

Returns

Operation

Schema Name

Total

Success

Failure

Type string string integer integer integer

Description

Type of operation that the service performs.

Name of the schema that is associated with the service.

Number of objects processed for this schema for a publication service.

Number of objects received for this schema for a subscription service.

The number of objects that were successfully identified for this schema which will be published or written to a file.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

272 | Chapter 11 Monitoring the Adapter

getActivityStatisticsByOperation()

Purpose

Parameters

(Custom with adb.perfMon) Returns the total number of objects processed for all the schemas by each service that is associated with a specified operation. Also, returns the number of success and error objects.

Parameter

Operation

Type string

Description

Name of operation. Pick from one of the following form the drop-down list.

Fetch

Poll

Insert

Update, and

Delete

Returns

Service Name

Total

Success

Failure

Type string integer integer integer

Description

Name of the service that is associated with the specified operation.

Total number of objects processed for this schema for a publication service.

Total number of objects received for this schema for a subscription service.

The number of objects that were successfully identified for this schema which will be published or written to a file.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

getThreadStatistics() | 273

getThreadStatistics()

Purpose

Returns

(Custom with adb.perfMon

) Return the operation counts of the current threads.

Returns

ThreadID

ThreadType

TaskType

TaskCount

Type string string string integer

Description

A unique identification of a particular thread.

A type or key that will match this thread to a queue or connection.

Short description of the tasks this thread processes.

Number of tasks processed by this thread.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

274 | Chapter 11 Monitoring the Adapter

getQueueStatistics()

Purpose

Returns

(Custom with adb.perfMon

) Return the current count of elements in any internal queue used by the adapter. This includes the TIBCO Rendezvous event queues automatically spawned by TIBCO Rendezvous for each adapter.

Returns

QueueID

QueueType

QueueCount

MaxQueueSize

Type string string integer integer

Description

A unique identification of a particular queue.

A type or key that will match this queue to a thread or connection.

Current number of elements in the queue.

Maximum number of elements in the queue.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

getConnectionStatistics() | 275

getConnectionStatistics()

Purpose

Returns

(Custom with adb.perfMon

) Returns the state and statistics for all the current connections used by the adapter.

Returns

Connection ID

Connection Type

State

NumRetries

Type string string string integer

TotalNumOperations integer

CurrentNumOperatio ns integer

Description

A unique identification of a particular connection.

A type or key that will match this connection to a thread or queue.

Current state:

CONNECTED

DISCONNECTED

Total number of times this connection had to be reestablished.

Total number of operations processed by this connection since the adapter started.

Total number of operations processed by this connection since the last reconnection.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

276 | Chapter 11 Monitoring the Adapter

resetActivityStatistics()

Purpose

(Custom with adb.perfMon

) Resets all the counts for the activity statistics.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

resetThreadStatistics() | 277

resetThreadStatistics()

Purpose

(Custom with adb.perfMon

) Resets all the counts for the thread statistics.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

278 | Chapter 11 Monitoring the Adapter

resetQueueStatistics()

Purpose

(Custom with adb.perfMon

) Resets all the counts for the queue statistics.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

resetConnectionStatistics() | 279

resetConnectionStatistics()

Purpose

(Custom with adb.perfMon

) Resets all the counts for the connection statistics.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

280 | Chapter 11 Monitoring the Adapter

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Appendix A

Frequently Asked Questions

This appendix lists answers to frequently asked questions.

Topics

•

General Questions, page 288

•

Request-response Questions, page 293

| 287

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

288 | Appendix A Frequently Asked Questions

General Questions

How can I determine the source of a problem or an error?

In some cases it is helpful to turn on ODBC tracing. Navigate to Control Panel >

Administrative Tools > ODBC Data Sources. Activate tracing by clicking the Start

Tracing Now button on the Tracing tab. For details, see your Microsoft Windows documentation.

How can I find the version number of an adapter instance?

A banner displays when an adapter instance starts. The banner lists component versions for the adapter and for TIBCO Adapter SDK software. You can use this information to diagnose compatibility issues, or to report any problem details to Customer Support.

You can also display version information in TIBCO Designer by selecting Help >

Runtime Environment.

Why is a database trigger error not logged in the exception table?

When using an adapter instance as a publisher, if an error occurs in the database trigger that is used to copy data from the source table to the publishing table, the database trigger error will not be logged in the exception table for the subscriber adapter.

How should the adapter react if the database connection is lost and the database is later restarted? Does it automatically try to reconnect?

If TIBCO ActiveMatrix Adapter for Database detects it has lost its database connection, it

Runtime

Connection Tab on page 45

). Alternatively, TIBCO Hawk rules can be written to detect

this and restart the adapter whenever this occurs.

Must an incoming message contain all the columns that are defined for the destination table?

The incoming message need not contain all the columns defined in the destination database table. You can configure the adapter to expect only a subset of the columns, defined in the repository. The adapter is driven from the subscribing class description and will iterate through the attributes in the class definition for the subscribing table and specifically look for those attributes in the incoming messages. It inserts NULLs for the attributes that it is expecting but does not find in the message. If there are more columns in the subscribing table than are listed in the subscribing class (set when adding a subscription), those extra columns will get whatever default values were specified during the table creation.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

General Questions | 289

Can an existing table be used as the publishing table?

No. TIBCO ActiveMatrix Adapter for Database requires additional columns in the publishing table. Even when every field in a table is published, a separate publishing table is required.

Does the TIBCO Rendezvous message that is published have to contain every field in the publishing table?

Yes. You can control which fields are copied to the publishing table by configuring the adapter and by changing the publication trigger to publish a subset of rows. You can also append additional fields to a message or drop a message based on some criteria using the user callout library. For more information on the user callout library, see

User Callout

Library on page 183

If multiple updates occur between polling intervals, are updates published in multiple TIBCO

Rendezvous messages or a single large message?

If you are using publish by value

, a TIBCO Rendezvous message is created for each individual update. If you are using publish by reference

, that operation will get the last update.

Is it possible to delete older entries in the publishing table?

Yes. When a row is published, the value of the ADB_L_DELIVERY_STATUS field in the publishing table changes to either

(complete) or

(failed). You can write a trigger in your publishing table that deletes the row when the delivery status changes to

You can also publish data directly from the source table by configuring the adapter instance to publish by reference. A publishing table is created, but it contains only required fields and key fields of the source table.

How does the exception table work?

Before starting an adapter instance, you must set the adb.useExceptTable

option in the adapter’s properties file to on

and specify an exception table when configuring the adapter instance. If an error occurs when inserting data into the destination table, it will be inserted into the exception table. The transaction will be committed and a confirmation sent back for the message (RVCM delivery). If the insertion into the exception table also fails, an error message will display and the adapter instance will terminate.

Can an adapter instance be used to replicate binary types, such as BLOB?

There is only limited support for binary large object (BLOB) data types. Oracle LONG and LONG RAW types are supported in top-level tables when the adapter is configured to publish by reference. Oracle BLOB and CLOB data types are supported.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

290 | Appendix A Frequently Asked Questions

Can an adapter instance write to tables that belong to a database account different from that used by the adapter?

Yes. A source table or destination table can belong to a different database user than the default account created in create_user.sql

. For more information on referencing external schemas, see TIBCO ActiveMatrix Adapter for Database Concepts.

Can a publisher adapter and a subscriber adapter use different projects?

Yes, unless the publisher adapter is configured to use parent-child relationships.

Can TIBCO ActiveMatrix Adapter for Database guarantee exactly once delivery of messages over RVCM?

Exactly once delivery of messages over RVCM is not currently guaranteed. The same quality of service that RVCM provides is supported, which is at least once. To get exactly once delivery requires combining the messaging operations and the database operations in a single atomic transaction, which is not supported in RVCM.

What guarantees does the adbagent make with regards to the order of database operations?

For instance, is it guaranteed that for a given table, modifications are made in the same order that they were made to the source database? What guarantees are made for operations across different tables?

TIBCO ActiveMatrix Adapter for Database guarantees that for database operations that are published on the same subject, the order of the operations is preserved. Usually, this applies to database operations made to one table. It does not usually apply to database operations across different tables.

When using RVCM for delivery, at what point does the subscribing adapter acknowledge an incoming message?

A TIBCO ActiveMatrix Adapter for Database subscriber confirms the message only after the database operation is committed. If there is an error and no exception table is used, the database operation is rolled back and no confirmation is sent. If there is an error and an exception table is used, the insert to the exception table is committed and the message is then confirmed.

By maintaining the publishing tables, all changes to the source table can be captured. If, however, there is a failure between the point of publishing a message using RVCM and updating the publishing table, will the adapter republish the message that has already been sent?

Yes, the message will be republished and the subscriber would have to deal with the duplicate message.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

General Questions | 291

For the subscriber adapter, if failure occurs after doing a database update and before sending an acknowledgement back to the publisher adapter, can the restarted configuration be prevented from redoing the update operation?

No. This would cause a duplicate insert.

For a certified subscriber adapter, if an insert exception occurs and no exception table is specified, what happens?

If the tibco.clientVar.DirTrace

option is specified in the adapter’s properties file when the adapter is started, exception handling information is written to the log file and the configuration continues to run. Since the insert could not be performed, the

ADB_L_DELIVERY_STATUS

publishing table column has a value of

for the message.

How do I pre-register non-TIBCO ActiveMatrix Adapter for Database subscribers, like custom adapters, to ensure no messages are lost?

Specify the

CM name

of the listener’s RVCM session

The session names are automatically created. Can these be changed, without confusing TIBCO

ActiveMatrix Adapter for Database, so that we can use a standard naming convention throughout the entire integration process?

No, the session names are fixed and used by TIBCO ActiveMatrix Adapter for Database internally. They cannot be altered.

What’s the proper way to permanently remove an adbagent subscriber when using CM? One way is to completely REMOVE the publisher’s ledger and to change all ’P’ records back to ’N’, then restart the publisher. Is there a better, more correct or automated method?

There is a TIBCO Hawk method, unRegisterListener()

, which unregisters a CM subscription.

This is the proper way to remove the adbagent subscriber as a CM listener.

Is it possible to run an adapter instance using a remote TIBCO Rendezvous daemon?

Yes. Change the default settings for network, service, and daemon parameters for the adapter using TIBCO Designer.

Is it possible to run two configurations of the adapter on the same machine?

It's possible to run multiple configurations of the adapter on the same machine if each adapter instance has a unique name. If both configurations use TIBCO Rendezvous certified messaging, each must use a different RVCM session.

Can an adapter instance collate information from several database tables to send as a single

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

292 | Appendix A Frequently Asked Questions

TIBCO Rendezvous message, or can it only publish data from a single table, in the format defined by that table?

There are two ways to publish related tables:

• Set the adb.publishChildData

option to on when configuring the adapter’s properties file.

When there are insertions into parent table, the adapter will publish parent rows and the corresponding child rows using TIBCO ActiveEnterprise or XML format.

Note that the adapter currently does not support publishing child data in the TIBCO

Rendezvous Message format. Update and delete on parent-child relationship when publishing is also not supported. See

Publisher Options Tab on page 76

• Combine several tables into one table using a trigger and then publish from the combined table.

When publishing or subscribing, an adapter instance allows you to change the message using the callout library. See

User Callout Library on page 183

for details.

Why does TIBCO Designer display a Java exception error while I’m trying to use TIBCO

Designer through Exceed?

When using Exceed to simulate an X Windows environment, start the X Windows server in the Exceed Session Startup Application. In this application, make sure the

Run X server checkbox is selected, then try TIBCO Designer again.

When my Sybase transaction log becomes full, the adapter hangs. How can I fix this problem?

When a Sybase transaction log becomes full, if the database setting abort trans on log full

is set to false, your application will hang instead of printing a transaction log full error. Execute the following command: sp_dboption dbname

, "abort tran on log full", true

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Request-response Questions | 293

Request-response Questions

When using request-response, can an INSERT statement with values only (without field names) be sent to the improve application's performance.?

Yes this is allowed. Your application can also send INSERT statements without the binds.

Can an application send UPDATE statements to a subscriber adapter with only those fields which are being updated? That is, if a table has ten records and only two should be updated, can an UPDATE statement be constructed and sent only for those fields?

Yes, this is supported.

Does an adapter instance send responses back as one large message with all rows in it or is the message sent in chunks?

The adapter sends results back to an application as one large message.

If a failure occurs when doing an insert or update, what is returned to the application?

If an error occurs while the adapter is processing a request, an error code and description is returned to the application. In the case of success, a result set and row count is returned to the application.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

294 | Appendix A Frequently Asked Questions

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Appendix B

Trace Messages

This appendix explains the trace messages in TIBCO ActiveMatrix Adapter for Database.

These include status messages, informational messages, error messages, and other types of messages.

| 295

Topics

•

Overview, page 296

•

Status Messages, page 299

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

296 | Appendix B Trace Messages

Overview

Trace messages provide information about adapter activities. The messages are logged to the console where the runtime adapter was started and to a log file in a location specified during configuration. Trace messages can also be redirected to the TIBCO Hawk Display application, or sent to other applications using the TIBCO Rendezvous transport.

Each trace message can include the following fields in the order shown:

Timestamp Adapter_Identifier Role Category Status_Code Tracking_Identifier

Application_Information

The above fields are explained in

Trace Message Fields on page 297

. The following example shows a trace message containing some of these fields and then identifies the fields.

2003 Feb 22 20:15:12:937 GMT -8 FileAdapter.FileAdapterConfiguration Info [Adapter]

AEFA-000067 Message containing class /tibco/public/class/ae/Customer received on subject

FROM.SAP tracking=#MU3oTJ/WWCV1MU96J0zzwA9kzzw#

Timestamp:

Adapter ID:

Role:

Category:

Status Code:

2003 Feb 22 20:15:12:937 GMT -8

FileAdapter.FileAdapterConfiguration

Info

[Adapter]

AEFA-000067 Message containing class

/tibco/public/class/ae/Customer received on subject FROM.SAP tracking=#MU3oTJ/WWCV1MU96J0zzwA9kzzw#

Tracking ID:

Example 1:

Adapter Started

Example Trace Messages

The following trace messages were written during a session where TIBCO Adapter for

Files received an object from TIBCO Adapter for R/3, then processed the object.

The following message indicates that TIBCO Adapter for Files has started. The timestamp indicates when the adapter started, and the role indicates that the trace message is informational, which means the activity is normal for the adapter. The category is identified, and the corresponding status code is displayed. The status code indicates that the adapter started successfully.

2003 Feb 22 20:14:51:718 GMT -8 FileAdapter.FileAdapterConfiguration Info [Configuration] AEFA-000058 TIBCO

Adapter for Files successfully initialized

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Overview | 297

Example 2:

Message

Received

Example 3:

Object Moved

The next set of trace messages indicates the adapter received an object that was sent on the

TIBCO Rendezvous subject,

FROM.SAP

. The

#MU3oTJ/WWCV1MU96J0zzwA9kzzw#

tracking identifier included in the trace message uniquely identifies the message. The adapter

(TIBCO Adapter for R/3) from which the message originated provided the identifier.

2003 Feb 22 20:15:12:937 GMT -8 FileAdapter.FileAdapterConfiguration Info [Adapter] AEFA-000067 Message containing class /tibco/public/class/ae/Customer received on subject FROM.SAP tracking=#MU3oTJ/WWCV1MU96J0zzwA9kzzw#

2003 Feb 22 20:15:12:937 GMT -8 FileAdapter.FileAdapterConfiguration Info [Adapter] AEFA-000068 Message containing class /tibco/public/class/ae/Customer written to working file customers.txt in Working Directory

F:\ca\integration\001\data_sets\files\wip tracking=#MU3oTJ/WWCV1MU96J0zzwA9kzzw#

The final trace message indicates the object has been moved to the output directory, which completes the adapter’s interaction with the object. Because the trace message is the termination point, the tracking identifier is not displayed.

2003 Feb 22 20:15:42:812 GMT -8 FileAdapter.FileAdapterConfiguration Info [Adapter] AEFA-000070 File customers.txt is moved to the Output Directory F:\ca\integration\001\data_sets\files\solutions\output

Trace Message Fields

Each trace message includes the following fields:

Table 47 Trace Message Fields (Sheet 1 of 2)

Field Name

Timestamp

Description

Timestamp of occurrence. For example,

2003 Feb 22 20:14:51:718 GMT -8

Adapter Identifier Name of the adapter that wrote the trace message. This is a combination of the adapter acronym and adapter configuration name. For example, the application identifier,

ADB.publisher1

identifies a TIBCO ActiveMatrix Adapter for Database service named publisher1.

Role A role can be:

Info. Indicates normal adapter operation. No action is necessary. A tracing message tagged with

Info indicates that a significant processing step was reached and has been logged for tracking or auditing purposes. Only info messages preceding a tracking identifier are considered significant steps.

Warn. An abnormal condition was found. Processing will continue, but special attention from an administrator is recommended.

Error. An unrecoverable error occurred. Depending on the error severity, the adapter may continue with the next operation or may stop altogether.

Debug. A developer-defined tracing message. In normal operating conditions, debug messages should not display.

When configuring the adapter you define what roles should or should not be logged. For example, you may decide not to log Info roles to increase performance.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

298 | Appendix B Trace Messages

Table 47 Trace Message Fields (Sheet 2 of 2)

Field Name

Category

Description

One of the following:

• Adapter. The adapter is processing an event.

• Application. The adapter is interacting with the database.

• Configuration. The adapter is reading configuration information.

• Database. The adapter is interacting with a database.

• Metadata. The adapter is retrieving metadata from the database.

• Palette. The adapter is interacting with the palette.

• Publisher Service. The publication service is reporting this trace message.

• Request-Response Client Service. The request-response invocation service is reporting this trace message.

• Request-Response Server. The request-response service is reporting this trace message.

• Shutdown. The adapter is shutting down.

• Startup. The adapter is starting.

• Subscription Service. The subscription service is reporting this trace message.

• System. This category is not linked to a specific event process. The trace message may be related to a Windows service related messages, memory allocation, file system error, and so on.

• TibRvComm. The adapter is communicating with TIBCO Rendezvous.

• XML. The adapter is parsing XML documents.

Status Code Unique code for the message and description. Status codes are identified by a unique number and description. If a trace message includes an error or warn role, the status code documentation includes a resolution. See

Status Messages on page 299 for details.

Tracking Identifier

Application

Information

A unique identifier that is "stamped" on each message by the originating adapter. The tracking identifier remains in effect from a message’s beginning to its completion as it is exchanged by

TIBCO applications. If the adapter is the termination point of the message, the tracking identifier is not displayed in the trace message.

You cannot modify the tracking identifier format or configure what information is displayed.

Application-specific information added to the tracking info to trace the message back to its source. Set initially by the originating adapter and carried forward. It is augmented by each intermediate component.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Status Messages | 299

Status Messages

Status Code

AEADB-100001

AEADB-100002

AEADB-100003

AEADB-100004

AEADB-100005

AEADB-100006

AEADB-100007

Role Category Resolution

%1Database connection succeeded.

infoRole Database

%1Database connection failed.

Normal operation; no action is necessary.

errorRole Database Check and test the ODBC configuration and restart the TIBCO Runtime Agent.

odbc connection as: DSN: %1, User: %2 infoRole Database Normal operation; no action is necessary.

Database driver code: %1Database vendor message: %2 errorRole Database See an ODBC manual and the manual of the native database by using the error code.

Unknown database system.

warnRole Database The adapter is unable to detect the DBMS type of the database it connects to. Make sure a supported

DBMS is used. This condition sometimes occurs because a native character set is used. If you are using a supported DBMS, ignore this warning.

%1SQL statement preparation succeeded.

infoRole Database Normal operation; no action is necessary.

%1SQL statement preparation failed.

errorRole Database Preparation of a SQL statement failed. Check the configuration for this adapter service and restart the adapter.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

300 | Appendix B Trace Messages

Status Code

AEADB-100008

AEADB-100009

AEADB-100010

AEADB-100011

AEADB-100012

AEADB-100013

AEADB-100014

AEADB-100015

AEADB-100016

AEADB-100017

Role Category Resolution (Cont’d)

Problem reading values for %1 from Database errorRole Database The adapter cannot retrieve data from tables. In the adapter properties file, set the adb.verbose option

to on

and the adb.debug

option to

to print the SQL statement to the log file then report this error to TIBCO support.

Database Connection Lost, Terminating....

errorRole Database Check the connection to the underlying database and restart the adapter.

JDBC connection as: Driver %1, URL %2, User %3 infoRole Database

%1Database connection closed

Normal operation; no action is necessary.

infoRole Database

%1Invalid statement

Normal operation; no action is necessary.

errorRole Database The adapter detected an invalid SQL statement. For request-response service, an invalid request is processed; otherwise, check your adapter service configuration and restart the adapter instance.

Attribute %1 (class %2): No column data ignoring

Normal operation; no action is necessary.

infoRole Database

Inserted %1into database infoRole Adapter

Deleted from database

Normal operation; no action is necessary.

infoRole Adapter

No rows deleted infoRole Adapter

Updated database infoRole Adapter

Normal operation; no action is necessary.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Status Messages | 301

Status Code

AEADB-100018

AEADB-100019

AEADB-100020

AEADB-200001

AEADB-200002

AEADB-200003

AEADB-200004

Role Category

No rows updated

Resolution (Cont’d) infoRole Adapter Normal operation; no action is necessary.

No columns specified for WHERE clause in %1 errorRole Adapter The adapter could not find key fields to construct the

WHERE clause. Check the repository definition of this class and make sure there is at least one field with isKey=true.

Building %1 criteria infoRole Adapter Normal operation; no action is necessary.

Foreign key attribute %1 not found in the publishing class.

errorRole Configuration Check your parent-child relationship in publisher configuration and make sure that the child table is joined with the parent table by a common key column, then restart the adapter.

%1Class registry not found: %2.

errorRole Configuration Check the configuration of that service to make sure that the class registry exists.

%1Class description not found: %2.

errorRole Configuration Check the configuration of that service to make sure that the class description exists. Sometimes, if the loadUrl

is not set correctly, this problem occurs.

Problem encountered when reading from ADB_PREREGLISTENER errorRole Configuration The adapter has problems reading from the

ADB_PREREGLISTENER table. Check to see that access to that table is allowed and the table is not corrupted.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

302 | Appendix B Trace Messages

Status Code

AEADB-200005

AEADB-200006

AEADB-200007

AEADB-200008

AEADB-200009

AEADB-200010

AEADB-200011

AEADB-200012

AEADB-200013

Role Category Resolution (Cont’d)

Could not register Hawk method %1 warnRole Configuration A description of a TIBCO Hawk method was not found in the repository. This can happen if the adapter instance is not the latest. Configure the adapter with the latest TIBCO Designer version.

Setting %1 = %2.

infoRole Configuration

%1 cannot be used with %2 warnRole Configuration

Normal operation; no action is necessary.

Incomplete options or conflicting options are used.

Check the log file for the detailed information and restart the adapter with correct options.

Preregistering %1 on %2 infoRole Configuration

%1 creation failed errorRole Configuration

Normal operation; no action is necessary.

There was an error initializing the publication. Check your project and re-configure the publication.

%1 cannot be larger than %2 errorRole Configuration Conflicting options are used. Check the log file and restart the adapter with the correct options.

Unsupported encoding type: %1, Use default ASCII Encoding.

errorRole Configuration An unknown character set is detected. Check the language configuration in the OS environment and restart the adapter.

AEADB-POLLINGINTERVAL-NOVALUE-ERR errorRole Configuration Unable to retrieve polling interval value from Hawk method. Retaining original value of %1 milliseconds.

Please make sure a value is specified before invoking the setPollingInterval

method.

AEADB-POLLINGINTERVAL-NEGATIVE-ERR

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Status Messages | 303

Status Code

AEADB-200014

AEADB-200015

AEADB-200016

AEADB-200017

AEADB-200018

AEADB-200019

AEADB-200020

AEADB-300001

Role errorRole

Category

Configuration

Resolution (Cont’d)

Negative value of %1 for polling interval not allowed. Retaining original value of %2 milliseconds. Please make sure to specify a non-negative value for the polling interval.

AEADB-POLLINGINTERVAL-SAME-WARN warnRole Configuration Polling interval already set to %1 milliseconds.

AEADB-POLLINGINTERVAL-CHANGED infoRole Configuration Polling interval changed to %1 milliseconds.

AEADB-POLLINGBATCHSIZE-NOVALUE-ERR errorRole Configuration Unable to retrieve polling batch size value from

Hawk method. Retaining original value of %1.

Please make sure a value is specified before invoking the setPollingBatchSize

method.

AEADB-POLLINGBATCHSIZE-NEGATIVE-ERR errorRole Configuration Negative value of %1 for polling batch size not allowed. Retaining original value of %2. Please make sure to specify a non-negative value for the polling batch size.

AEADB-POLLINGBATCHSIZE-SAME-WARN warnRole Configuration Polling batch size already set to %1.

AEADB-POLLINGBATCHSIZE-CHANGED infoRole Configuration Polling batch size changed to %1.

AEADB-POLLINGBATCHSIZE-CHANGED warnRole Configuration The repository encoding should be set to UTF-8 if your agent encoding is not ASCII or LATIN-1. Set the repository encoding to UTF-8.

%1exception thrown in %2.

errorRole System An adapter internal error. Contact TIBCO Support.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

304 | Appendix B Trace Messages

Status Code

AEADB-300002

AEADB-300003

AEADB-300004

AEADB-300005

AEADB-300006

AEADB-300007

AEADB-300008

Role Category

Not enough memory available.

Resolution (Cont’d) errorRole System Check the virtual memory of the system and restart the adapter. If it keeps happening, contact TIBCO

Support.

MException throw in %1: %2.

errorRole System An Adapter SDK exception was thrown. Report the

SDK error code and text to TIBCO Support.

%1 on connect socket in thread failed errorRole System A TCP system call failed. Check your computer’s network ports and TCP libraries. Rebooting the computer may solve the problem.

Binding address to socket failed. Listenport = %1 errorRole System A TCP system call failed. Check your computer’s network ports and TCP libraries. Rebooting the computer may solve the problem.

Listen call on socket failed errorRole System A TCP system call failed. Check your computer’s network ports and TCP libraries. Rebooting the machine may solve the problem.

Accept on socket failed errorRole System A TCP system call failed. Check your computer’s network ports and TCP libraries. Rebooting the computer may solve the problem.

Socket creation in thread failed errorRole System A TCP system call failed. Check your computer’s network ports and TCP libraries. Rebooting the computer may solve the problem.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Status Messages | 305

Status Code

AEADB-300009

AEADB-400001

AEADB-400002

AEADB-400003

AEADB-400004

AEADB-400005

AEADB-400006

AEADB-600001

Role Category Resolution (Cont’d)

Out of memory building the WHERE clause errorRole Adapter An adapter process has run out of memory. Increase the amount of memory allowed to the adapter on your system.

%1Unknown column name %2 errorRole Metadata Request is missing a column field in the Bind data.

Add a column, tableName.columnName

field, to your bind data.

%1Unknown column type: %2 for field: %3.

errorRole Metadata

Unknown column type, %1, %2

The type %2 is an invalid AE class type. Check in the repository for attribute %3 and change the class type to a valid AE class type.

Normal operation; no action is necessary.

infoRole Metadata

%1schema %2, tables: %3 debugRole Metadata

%1table %2, columns: %3 debugRole Metadata

Ill-formatted table name %1 errorRole Metadata A table name of this format is not supported by the adapter. Use a different table name.

%1Failed to set limit policy for event queue %2 on session %3: %4 errorRole TibRvComm TIBCO Rendezvous failed to set the limit policy according to the -rv-max-queue-size specification.

Please report this error text to TIBCO customer support.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

306 | Appendix B Trace Messages

Status Code

AEADB-600002

AEADB-600003

AEADB-600004

AEADB-600005

Role Category Resolution (Cont’d)

%1Failed to get queue count for event queue %2 on session %3: %4 errorRole TibRvComm TIBCO Rendezvous failed to get the queue count for the given session. Please report this error text to

TIBCO customer support.

%1Failed to get queue limit for event queue %2 on session %3: %4 errorRole TibRvComm TIBCO Rendezvous failed to get the limit policy for the given session. Report the this error text to TIBCO

Support.

OnEvent: eventname %1 infoRole TibRvComm Normal operation; no action is necessary.

MException thrown trying to publish message on "%1".

AEADB-600006

AEADB-700001

AEADB-700002

AEADB-700003 errorRole TibRvComm

%1Received ADVISORY %2 errorRole TibRvComm An unexpected TIBCO Rendezvous advisory was received. See your TIBCO Rendezvous documentation for resolution information.

SQL: %1

Unable to publish the message, check error description for details. Check your daemon connection.

infoRole Adapter Normal operation; no action is necessary.

%1Building SQL statement succeeded%2.

infoRole Adapter Normal operation; no action is necessary.

%1Binding data to placeholders: unknown column type, %1 for field %2.

Ignoring errorRole Adapter The type %1 is an invalid AE class type. Check in the repository for attribute %2 and change the class type to a valid AE class type.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Status Messages | 307

Status Code

AEADB-700004

AEADB-700005

AEADB-700006

AEADB-700007

AEADB-700008

AEADB-700009

AEADB-700010

AEADB-700011

AEADB-700012

Role Category Resolution (Cont’d)

%1database operation%2 succeeded infoRole Adapter

%1database operation%2 failed

Normal operation; no action is necessary.

errorRole Adapter The execution of this database statement failed. Use the error returned by the database to determine how to allow this SQL statement to succeed.

%1database transaction begin infoRole Adapter

%1database transaction commit

Normal operation; no action is necessary.

infoRole Adapter Normal operation; no action is necessary.

%1database transaction rollback.

infoRole Adapter Normal operation; no action is necessary.

%1Cannot bulk insert for variable binary type in column %2.%3.

warnRole Adapter The subscriber bulk insert option does not support a variable binary data type. Do not use bulk insert for tables with a variable binary data type.

%1Database transaction commit failed.

warnRole Adapter

Encoding error from %1 to %2.

The database was unable to commit the transaction.

Use the error returned by the database to determine how to allow this transaction to succeed.

errorRole Adapter An Adapter SDK error converting data to the specified encoding. Make sure the encoding is a supported one.

%1Cold start completed.

infoRole Adapter Normal operation; no action is necessary.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

308 | Appendix B Trace Messages

Status Code

AEADB-700013

AEADB-700014

AEADB-700015

AEADB-700016

AEADB-700017

AEADB-700018

AEADB-700019

AEADB-700020

AEADB-700021

AEADB-700022

AEADB-700023

Role Category

%1Cold start failed.

errorRole Adapter

%1Confirming message.

infoRole Adapter

%1 batch commit timeout.

infoRole Adapter

%1Bulk insert begins.

Resolution (Cont’d)

Run the adapter using debug 3 and verbose mode.

Normal operation; no action is necessary.

infoRole Adapter

%1Bulk insert ends.

Normal operation; no action is necessary.

infoRole Adapter Normal operation; no action is necessary.

Inserted %1into the corresponding exception table.

infoRole Adapter Normal operation; no action is necessary.

%1Exception table is not specified.

warnRole Adapter Reconfigure the subscriber by specifying an exception table, or turn off the adb.useExceptTable

option

(in the adapter properties file) when starting the adapter.

%1Cannot find bound data for %2.

Normal operation; no action is necessary.

infoRole

%1 = %2

Adapter debugRole Adapter

%1 = NULL debugRole Adapter

%1Bulk insert turning off.

infoRole Adapter Normal operation; no action is necessary.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Status Messages | 309

Status Code

AEADB-700024

AEADB-700025

AEADB-700026

AEADB-700027

AEADB-700029

AEADB-700030

AEADB-700031

AEADB-700032

AEADB-700033

AEADB-700034

AEADB-700035

Role Category

Polling publishing table %1 infoRole

%1 = %2

Resolution (Cont’d) infoRole Adapter Normal operation; no action is necessary.

Updating delivery status of publishing table %1.

Adapter Normal operation; no action is necessary.

debugRole Adapter

%1Publishing by reference and selecting from reference object %2 infoRole

Adapter Normal operation; no action is necessary.

Normal operation; no action is necessary.

infoRole Adapter

Received request %1.

infoRole Adapter

Built reply %1.

Normal operation; no action is necessary.

infoRole

%1sent to %2

Adapter infoRole

Adapter

Normal operation; no action is necessary.

infoRole Adapter

Bad date encountered: %1

Normal operation; no action is necessary.

errorRole Adapter Check your dateTime

-related message data and make sure it is in the correct format.

Parameterized subject %1 exceeds TibRv maximum subject length of %2 errorRole Adapter Shorten a parameterized subject string length.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

310 | Appendix B Trace Messages

Status Code

AEADB-700036

AEADB-700037

AEADB-700038

AEADB-700039

AEADB-700041

AEADB-700042

AEADB-700044

AEADB-700045

AEADB-700046

Role Category

Unrecognized event errorRole Adapter

Resolution (Cont’d)

An unrecognized event received. Disable it if possible.

%1 errorRole Adapter An unexpected error happened internally. Contact

TIBCO Support.

Poll for change failed errorRole Adapter Run the adapter using debug 3 and verbose mode.

Check printed database error code.

Update sequence Failed errorRole Adapter Run the adapter using debug 3 and verbose mode.

Check the update statement database error code.

%1, data = %2 infoRole Adapter Normal operation; no action is necessary.

Maximum of %1 thread allowed for %2 assuming %3 warnRole Adapter Maximum threads have been exceeded; however, the adapter runs by assuming the default thread count.

Currently a publisher manager, subscriber manager and request-response communication can only have one thread each.

Main thread (name: %1, id: %2)

Normal operation; no action is necessary.

infoRole Adapter

%1endpoints %2 infoRole Adapter

Confirming request infoRole Adapter

Normal operation; no action is necessary.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Status Messages | 311

Status Code

AEADB-700048

AEADB-700049

AEADB-700050

AEADB-700051

AEADB-700052

AEADB-700053

AEADB-700054

AEADB-700055

Role Category Resolution (Cont’d)

%1Error creating reply message errorRole Adapter Cannot create an Adapter SDK MTree object for a reply message. Contact TIBCO Support.

%1Request is being handled by thread %2 infoRole Adapter

%1Could not start transaction

Normal operation; no action is necessary.

errorRole Adapter Cannot set autoCommit to false. Check the status of the database you are trying to connect to and try again. If it still fails, contact TIBCO Support.

Request Reply: Error retrieving %1 errorRole Adapter Missing required "sql" field when sending a request

(rvMsg) to a request-response service for execution.

Reconstruct the request message to include a "sql" field.

%1Error binding variables errorRole Adapter Check the request message format. For a given field, make sure the data type in the message is the same as defined in the database.

%1Reply sent to %2 infoRole Adapter Normal operation; no action is necessary.

%1Error sending reply to %2 - %3 errorRole Adapter TIBCO Rendezvous failed to send a reply message to the request client. Report this error text to TIBCO

Support.

%1Failed to create sender for reply errorRole Adapter TIBCO Rendezvous failed to create a reply sender.

Please report this error text to TIBCO customer support.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

312 | Appendix B Trace Messages

Status Code

AEADB-700056

AEADB-700057

AEADB-700058

AEADB-700059

AEADB-700063

AEADB-700064

AEADB-700065

AEADB-700066

AEADB-700071

Role Category Resolution (Cont’d)

RequestReply: No reply name. Not sending reply errorRole Adapter Specify a reply-subject when defining an adapter request-response service.

%1Error retrieving bind position errorRole Adapter Check the request message format. For a given field in the message, make sure it is present in the database.

Stopped thread (%1) infoRole Adapter Normal operation; no action is necessary.

Starting thread (name: %1, id: %2) infoRole

%1starts

Adapter Normal operation; no action is necessary.

Normal operation; no action is necessary.

infoRole Adapter

%1Request: %2 debugRole Adapter

%1Reply: %2 debugRole Adapter

Load catalog table %1 infoRole Adapter

Duplicate agent found %1 errorRole Adapter

Normal operation; no action is necessary.

The adapter is terminated because a same-named configuration is started on the same TIBCO

Rendezvous network. For more information, see to

Notes on Configuring an Adapter on page 30

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Status Messages | 313

Status Code

AEADB-700072

AEADB-700073

AEADB-700074

AEADB-700075

AEADB-700076

AEADB-700077

AEADB-700078

AEADB-700079

Role Category Resolution (Cont’d)

%1MExceptionEvent - Not an RVMSG_RVMSG: %2 errorRole Adapter

%1Unknown message format errorRole Adapter The adapter received a TIBCO Rendezvous message of unknown format. Check other running components’ configurations to determine the source of this message.

%1Not processing message

The adapter received an

MExceptionEvent

where an

MDataEvent

is expected. Check other running components’ configurations to determine the source of this message.

errorRole Adapter The message is not being processed because an error has occurred. Check for related error messages to determine what the problem is.

%1Error converting event into an Mtree errorRole Adapter A conversion error occurred in the Adapter SDK layer. The message may be corrupted or of a wrong format. Check the Adapter SDK error message if any to determine what the problem is.

%1CM sender: %2, CM sequence number: %3 debugRole Adapter

Received message altered: infoRole Adapter Normal operation; no action is necessary.

Received message discarded by alterMsgSub() infoRole Adapter Normal operation; no action is necessary.

%1Unable to create AE object from the message: %2 warnRole Adapter An unpacking error occurred in the Adapter SDK layer. The message may be corrupted or of a wrong format. Check the Adapter SDK error message if any to determine what the problem is.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

314 | Appendix B Trace Messages

Status Code

AEADB-700080

AEADB-700081

AEADB-700082

AEADB-700083

AEADB-700084

AEADB-700085

AEADB-700086

AEADB-700087

AEADB-700088

AEADB-700089

Role Category Resolution (Cont’d)

Received its own message. Discarding.

infoRole Adapter

Batch confirming %1 messages

Normal operation; no action is necessary.

infoRole Adapter Normal operation; no action is necessary.

RequestReply: Bind argument %1 must include a table name errorRole Adapter The format of the Bind argument name should be tablename.columnname

. This message will not be processed.

Published message on %1 infoRole Adapter Normal operation; no action is necessary.

ADB_SEQUENCE class %1 not supported errorRole Adapter The class type of ADB_SEQUENCE can only be either string or i4. Make sure the class type of the

ADB_SEQUENCE column of the publishing table is specified correctly in the repository.

Received ADVISORY %1 infoRole Adapter Normal operation; no action is necessary.

Publisher batch confirm timeout infoRole Adapter

%1 method invoked

Normal operation; no action is necessary.

infoRole Adapter

Unknown driver %1

Normal operation; no action is necessary.

errorRole Adapter The adapter currently only supports ODBC drivers

(including the IBM client access driver).

%1Request received from %2 infoRole Adapter Normal operation; no action is necessary.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Status Messages | 315

Status Code

AEADB-700090

AEADB-700091

AEADB-700092

AEADB-700093

AEADB-700094

AEADB-700095

AEADB-700096

AEADB-700097

AEADB-700098

Role Category

Database error updating %1

Resolution (Cont’d) errorRole Adapter An error occurred while updating the publishing table. This is a fatal error and the adapter will terminate. Use the error returned by the database to determine how to solve the problem.

Publishing ADBOPAQUE format not supported errorRole Adapter The adapter currently does not support publishing in opaque format.

Keeping on original subject token %1 infoRole Adapter Normal operation; no action is necessary.

Binding data to insert placeholders infoRole Adapter

Polling for database change

Normal operation; no action is necessary.

infoRole Adapter

Terminating agent infoRole Adapter

Unable to insert %1 into list errorRole Adapter

Normal operation; no action is necessary.

Wildcard TIBCO Rendezvous subject names are not currently supported for preregistered listeners.

Updating CM sequence failed errorRole Adapter Currently not used.

%1Error binding parameter %2 errorRole Adapter There was a database error that occurred while binding parameters to a SQL statement. The message will not be processed. Use the database error if any to determine what the problem is.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

316 | Appendix B Trace Messages

Status Code

AEADB-700099

AEADB-700100

AEADB-700101

AEADB-700102

AEADB-700103

AEADB-700104

AEADB-700105

Role Category Resolution (Cont’d)

RequestReply: Error retrieving value for parameter %1 errorRole Adapter A request has no value specified for input parameter

%1. Add a (data, rvmsgData) field to the [Bind Data] of the request.

Received message: infoRole Adapter

Transaction rollback failed errorRole Adapter

Normal operation; no action is necessary.

The database was unable to rollback the transaction.

Use the error returned by the database to determine how to allow this transaction to roll back.

Database object %1 not found errorRole Adapter The database object was not found. Check to see if the object really exists (perhaps in another schema) and if you have permission to access it.

%1Unknown column type: %2 for field: %3. Ignoring warnRole Adapter The type %2 is an invalid AE class type. For this particular situation, the adapter will skip this attribute and continue processing. Check in the repository for attribute %3 and change the class type to a valid AE class type.

Insert into the exception table failed errorRole Adapter There was an error inserting into the exception table.

This is a fatal error and the adapter will terminate.

Use the error returned by the database to fix the inserts into the exception table.

%1%2 are not supported.

errorRole Adapter These AE/TIBCO Rendezvous data types are currently not supported by the adapter. Use only supported data types to represent this field instead; for example, a string or binary.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Status Messages | 317

Status Code

AEADB-700106

AEADB-700107

AEADB-700108

AEADB-700109

AEADB-700110

AEADB-700111

AEADB-700112

AEADB-700113

AEADB-700114

AEADB-AEADB

_700301

Role Category

No data fetched for %1 infoRole

New SQL: %1

Adapter

Resolution (Cont’d)

Normal operation; no action is necessary.

infoRole Adapter Normal operation; no action is necessary.

Bulk insert of %1 rows executed for %2 infoRole Adapter Normal operation; no action is necessary.

Error executing bulk insert of %1 rows for %2 errorRole Adapter There was an error doing the bulk insert into the table. Use the error returned by the database to determine how to fix inserts into the table.

Statement changed, flush all previous bulk insert rows infoRole Adapter Normal operation; no action is necessary.

Reassign data value to insert statement: infoRole Adapter Normal operation; no action is necessary.

Cannot find publication entry. Not publishing message.

errorRole Adapter

Error retrieving column %1

Internal error. Contact TIBCO Support.

errorRole Adapter The adapter could not retrieve this attribute from the message. Make sure the incoming message contains a value for this attribute.

%1 errorRole Adapter Internal error. Contact TIBCO Support.

Error executing listen_alert procedure call errorRole Adapter Check the corresponding database error.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

318 | Appendix B Trace Messages

Status Code

AEADB-AEADB

_700302

AEADB-AEADB

_700303

AEADB-AEADB

_700304

AEADB-AEADB

_700305

AEADB-AEADB

_700306

AEADB-AEADB

_700307

AEADB-890001

AEADB-890002

AEADB-890003

Role Category Resolution (Cont’d)

Error preparing listen_alert procedure call, stop alerter thread errorRole Adapter Check if the listen_alert procedure exists in the database and if the user has authorization to execute it.

Listen_alert procedure call not found, stop alerter thread errorRole Adapter Check if the listen_alert procedure exists in the database and if the user has authorization to execute it.

Cannot stop alerter successfully, stop_alerter_agent call failed.

errorRole Adapter Check if the listen_alert procedure exists in the database and if the user has authorization to execute it.

Error registering alerter, config_alerter procedure call failed, stop alerter thread errorRole Adapter The alerter failed to add the AQ subscriber. Check if the AQ database objects are configured properly in the database and if the user has authorization to access it

Error unregistering alerter, cleanup_alerter procedure call failed.

errorRole Adapter The alerter failed to remove the AQ subscriber.

Check if the AQ database objects are configured properly in the database and if the user has authorization to access it

Stopped ALerter infoRole Adapter

AEADB-CONN-RETRY

Normal operation; no action is necessary.

infoRole Adapter Reconnect attempt %1 for service %2.

AEADB-CONN-RETRYSUCCESS infoRole Adapter

AEADB-CONN-RETRYFAIL

Reconnect succeeded on attempt %1 for service %2.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Status Messages | 319

Status Code

AEADB-890004

AEADB-890005

AEADB-890006

AEADB-890007

AEADB-910004

AEADB-910005

Role warnRole

Category

Adapter

Resolution (Cont’d)

Reconnect failed on attempt %1 for service %2 -- will retry in %3 milliseconds. Make sure it is possible to establish an ODBC connection to the database.

AEADB-CONN-PUBDUP warnRole Adapter

AEADB-CONN-REQERR errorRole Adapter The request received could not be processed due to connection errors. Make sure it is possible to establish an ODBC connection to the database.

AEADB-CONN-STOP errorRole Adapter

AEADB-CONN-SVCSUSPEND

Adapter stopping due to persistent connection errors.

Please check your database and restart adapter. Make sure it is possible to establish an ODBC connection to the database.

infoRole Adapter Adapter suspending service %1 due to persistent connection errors.

AEADB-STARTUP-4 errorRole Startup Startup Error. SDK Exception %1 occurred in the adapter initialization while creating the

MAppProperties object. The Repository URL is %2 and the Configuration URL is %3. Please see SDK documentation for Repository URL and

Configuration URL specification. Please cut and paste from SDK documentation for the above.

AEADB-STARTUP-5

Connection reestablished for the publisher - message may be a duplicate of a previously published message.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

320 | Appendix B Trace Messages

Status Code Role errorRole

Category

Startup

Resolution (Cont’d)

Startup Error. SDK Exception %1 received on starting the adapter after initialization. The

Repository URL is %2 and the Configuration URL is

%3. Please verify your repository and environment settings. See the User Guide documentation.

AEADB-910007 AEADB-STARTUP-7 errorRole Startup Startup Error. Unable to create a connection with the target database using the dsn %1. The database error is: %2 Terminating adapter. Please verify your repository settings for the validity of connection parameters. See the User Guide documentation.

AEADB-920001 AEADB-SUB-1 errorRole Subscriber Subscription error. Subscription service %1 listening on %2 received an unexpected event: %3. The

Repository URL is %4 and the Configuration URL is

%5. Check the configuration of the application that is publishing the event and make sure that it matches the inbound event definition for the above subscription service. Please see User Guide for details on configuration of subscription service.

AEADB-920002 AEADB-SUB-2 errorRole Subscriber Subscription error. Subscription service %1 failed to deserialize the event received on subject %2 and

SDK exception thrown is %3. The event is: %4. The

Repository URL is %5 and the Configuration URL is

%6. Check the configuration of the application that is publishing the event and make sure that it matches the inbound event definition for the above subscription service. Please see User Guide for details on configuration of subscription service.

AEADB-920006 AEADB-SUB-6 errorRole Subscriber Subscription error. Subscription service %1 listening on subject %2 received error %3 in SDK message level UserExit %4. Make sure the UserExit parameters are valid and the user exit is invokable from SDK.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Status Code

AEADB-920007

Role Category

AEADB-SUB-7 errorRole Subscriber

Status Messages | 321

Resolution (Cont’d)

Subscription error. Subscription service %1 listening on subject %2 could not get the class description of

%3. The Repository URL is %4 and the

Configuration URL is %5. Please check the repository configuration for this service. Please make sure the classes to be used by this service are accessible in the repository. Please see User Guide for details on how to configure, run and test the subscription service.

AEADB-920015 AEADB-SUB-15 errorRole Subscriber Subscription error. Subscription service %1 listening on subject %2 failed due to database error: %3

Database is %4. The database commands and parameters are %5. Please look at the database error, note the database error code and consult with your database documentation.

AEADB-920017 AEADB-SUB-17 errorRole Subscriber Subscription error. Subscription service %1 listening on %2 could not send response %3 on reply subject

%4. The SDK error is %5. Please check your repository settings for the publish endpoint of this subscription service. Please see user guide on how to configure the subscription service.

AEADB-930002 AEADB-PUB-2 errorRole Publisher Publication error. Publication service %1 with publication subject %2 encountered database error:

%3 while trying to create publish event with schema

%4. Database is %5. The database command is %6.

Make sure that the publication service is configured properly. Please look at the database error, note the database error code and consult with your database documentation.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

322 | Appendix B Trace Messages

Status Code

AEADB-930003

AEADB-940001

AEADB-940009

AEADB-940010

AEADB-940012

Role Category

AEADB-PUB-3 errorRole Publisher

Resolution (Cont’d)

Publication error. Publication service %1 with publishing subject as %2 received event database

%3. It failed while converting the event to

"Minstance" as it could not get the class description for %4. Repository URL is %5 and the Configuration

URL is %6. Please verify the configuration of the publication service and check that the schema/class definitions are present in the repository. Please see

User Guide for details on how to configure a

Publication service.

AEADB-REQRESP-1 errorRole Request_Respo nse_Server

Request-Response error. Request-Response service

%1 listening on %2 received unexpected null data in incoming request. Expects object %3. The

Repository URL is %4 and the Configuration URL is

%5. Please check the configuration of the application that is requesting the event and make sure that it matches the inbound event definition for the above

RequestResponse service. Please see User Guide for details on configuration of RequestResponse service.

AEADB-REQRESP-9 errorRole Request_Respo nse_Server

Request-Response error. Request-Response service

%1 listening on subject %2 failed due to database error: %3Database is %4 and inbound event is %5.

Please check the target application command and the parameters and make sure they are valid. Please look at the database error, note the database error code and consult with your database documentation.

AEADB-REQRESP-10 errorRole Request_Respo nse_Server

Request-Response error. Request-Response service

%1 listening on subject %2 failed to create Reply

Business Object. Please check the database command and the parameters and make sure they are valid.

AEADB-REQRESP-12

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Status Messages | 323

Status Code

AEADB-990002

Role errorRole

Category

Request_Respo nse_Server

Resolution (Cont’d)

Request-Response error. Request-Response service

%1 listening on subject %2 receive an error while sending Data on Reply Address %3. Error Message

%4. Please check whether the request client is alive or message transport is functioning.

AEADB-SHUT-2 errorRole Shutdown Shutdown error. SDK cleanup exception = %1.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

324 | Appendix B Trace Messages

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Appendix C

Adapter Properties File

Topics

•

Overview, page 326

•

Properties File Format, page 327

•

Runtime Adapter Properties File Parameters, page 328

•

Obfuscating or Encrypting a Password in the Properties File, page 341

•

Using Hints, page 343

| 325

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

326 | Appendix C Adapter Properties File

Overview

The runtime adapter parses a properties file at startup. The default runtime adapter properties file is named adbagent.tra

The default properties file is located in the

TIB_ADADB_HOME

\bin

subdirectory.

Each line in a properties file is a single property. Each property consists of a key and a value. The key starts with the first non-whitespace character and ends at the first "

", "

", or whitespace character. The value starts at the first character after the equal sign (=). For example: tibco.configurl=/tibco/private/adapter/test/config/config1 tibco.repourl=tibcr://TEST_PROJECT tibco.username=admin tibco.password=samplePassword tibco.clientVar.service=7600 tibco.clientVar.daemon=tcp:7600

Properties defined in the properties file override the same properties defined in the project.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Properties File Format | 327

Properties File Format

The following restrictions apply to properties:

• The "

" character may not be used as a comment line indicator. Only the "

" character is recognized.

• The line continuation character is ignored (a value must fit on a line).

• The key may not contain any of the termination characters. Java allows termination characters by escaping the value with a preceding "\" character. TIBCO ActiveMatrix

Adapter for Database does not support this syntax.

Tagging Values for Obfuscation

The presence of a "

" character as the first character in a value (not the key) indicates that the value has been obfuscated or is to be obfuscated. The obfuscation command-line tool prompts for values to be obfuscated when it encounters a value with "

" as the first character in the properties file.

When the obfuscate tool is run, it rewrites the properties file with the obfuscated value in place. See

Obfuscating or Encrypting a Password in the Properties File on page 341

for more information.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

328 | Appendix C Adapter Properties File

Runtime Adapter Properties File Parameters

Properties are in two categories:

Required Properties

obfuscated using the instructions in Obfuscating or

Additional Properties

. These are

listed and described below.

Required Properties

In order for a properties file to be used with a runtime adapter, the following properties must be correct for the adapter’s configuration.

All paths inside a properties file, including Microsoft Windows directory names, must use forward slashes.

Table 48 Required Runtime Adapter Properties File Parameters

Property tibco.repourl repourl

Description

The absolute pathname to the local repository where the adapter instance is defined. For example:

C:/TIBCO/LocalRepositories/repo.dat

For a remote project, the repourl value should use the form tibco.repourl tibcr@ name where name is the repository name.

For example: tibco.repourl tibcr@ADBRepoDefault

For Unix systems, the path separator should include a single slash, "/". For example:

/local/tibco/repo/repo.dat

tibco.configurl relative_path or tibco.configurl absolute_path tibco.instanceid instance name tibco.clientVar.adb.password

The location of the adapter service inside the project file. If a relative path is specified, the adapter service is assumed to be under the default area in the project file (/ tibco/private/adapter/)

For example, the following value connects to an adapter service named adbpub

in the / tibco/private/adapter/

directory: tibco.configurl adbpub

If an absolute path is specified, the adapter instance is looked up in the repository as defined by the argument. For example: tibco:configurl /tibco/private/adapter/adbpub

The name of the adapter instance.

The length of the name cannot be larger than 80 characters.

The password to connect to the targeted database. This can be

Encrypting a Password in the Properties File on page 341 .

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Runtime Adapter Properties File Parameters | 329

Table 48 Required Runtime Adapter Properties File Parameters (Cont’d)

Property application.args

Description

The properties (

.tra

) file to pass to TIBCO ActiveMatrix

Adapter for Database. For example: application.args adb agent -system:propFile

C:/tibco/adapter/adadb/6.0/bin/ adb sub.tra

application.start.dir

The pathname of the adapter to start. For example: application.start.dir C:/tibco/adapter/adadb/6.0/bin/ application.library

application.ase.library

The name of the dynamic library of the adapter instance.

The name of the dynamic library of the adapter service engine instance.

This property is used only on the UNIX platforms.

Additional Properties

You can modify the following parameters as necessary. Properties that start with ntservice are available only on Microsoft Windows platforms. The following table is alphabetically sorted by the property name.

All paths inside a properties file, including Microsoft Windows directory names, must use forward slashes.

Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 1 of 12)

Property adb.

publication_service_name

.lookback

Description

Enables the adapter to look for remaining records if it did not fetch the number of records specified by the pollingBatchSize

parameter for the publisher.

For example, if the publisher service name is

ADBPublisher

, the property name is adb.ADBPublisher.lookback

. adb.

publication_service_name

.preRegister

edListeners

Preregisters RVCM names for the specified subjects.

For example, adb.ADBPublisher.preRegisteredListeners=adb.sub1:rvcm1,ad b.sub2:rvcm2 preregisters RVCM name rvcm1

to subject adb.sub1

, and RVCM name rvcm2

to subject adb.sub2

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

330 | Appendix C Adapter Properties File

Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 2 of 12)

Property adb.

table_name

.poll.hint. hint_value

Description

This feature helps improve the performance of your queries. This feature is only supported by Oracle and

SQLServer databases.

See

Using Hints on page 343 for more information.

adb.addCustomHawkMethodsToClassMAgent on|off

The property is not set by default. Setting the property to off

disallows adding custom methods to the adapter’s standard microagent. Setting to on allows custom methods to be added to the adapter’s standard microagent.

adb.as400.defaultLibrary

adb.as400.library

adb.batchPubStatusUpdates on|off -max_rows adb.createMutextable

adb.customScaleForNumberType

adb.database

The default iSeries library to be accessed.

The name of the library where the programs will be created.

When adb.PollingBatchSize

is used, this optimizes publishing performance by batching message status updates to the publishing table. Do not use this option when messages are published using a parameterized subject name.

If an adapter instance stops before a batch update is performed, the status column is not updated. As a result, duplicate messages are published when the instance is restarted.

When set to off

, the adapter does not create the mutex table that is used in the fault tolerance mode.

The mutex table can be manually created before starting the adapter with the following SQL command:

CREATE TABLE <mutex_table_name> (COL1 char(1))

The default value is on

This property sets the default scale of Oracle

Number(empty) datatype.

The DB2 database name for OS390. The adapter uses the value of this property when creating the table used by the fault tolerance functionality.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Runtime Adapter Properties File Parameters | 331

Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 3 of 12)

Property adb.debug

Description

The debug printing level. If not specified, the default,

, is used. Possible values are:

0 - No debug information displayed.

1 - SQL commands executed with the database display.

2 - In addition to 1, the ODBC data source for each

SQL command displays.

3 - Displays values for all ODBC placeholders.

adb.disableTerminationSubject

When this property is set to on

, the adapter does not terminate on receiving a termination subject message.

adb.dsn

adb.encoding

adb.groupsize

ODBC system data source name. If not specified, the system data source name is read from the repository.

The encoding to use. Required when using a non-ASCII character set, as in globalization. See

Overview, page 228 , and

Relevant Environment

Settings, page 237

, for more information.

Valid Values

The corresponding TIBCO Designer selection is in parenthesis.

(no value) defaults to ASCII ibm-1370 (Big5 ) tibx-eucJP ( EUC-JP) ibm-1386 (GBK )

LATIN_1 (ISO8859-1 ) ibm-949 (KSC-5601 ) ibm-943 ( Shift_JIS (CP943)) tibx-943 ( Shift_JIS (TIBCO))

UTF8 ( UTF8)

Specifies the number of rows to publish in a single message. Overrides the

Group Size

setting in the publication service configuration.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

332 | Appendix C Adapter Properties File

Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 4 of 12)

Property adb.heartbeat

Description

The time interval, in milliseconds, the secondary instance(s) waits before it tries to lock the table specified by the adb.mutex

property.

If neither the adb.primary.heartbeat

or adb.secondary.heartbeat

properties are specified, the value of this property will be used as both the primary and secondary heartbeat.

Default value is 10000ms adb.jmscompress on|off adb.maxLongLen

adb.maxQuery

adb.mutex

adb.noDupDetection

adb.originalSchema

Applies only to the publication service with JMS transport.

Either on

or off

. The default value is off

, which indicates that JMS messages will not be compressed.

The buffer size. Used for long data types such as

BLOB.

The maximum number of queries the secondary instance would send to the primary to determine if the primary instance is still active. Default value is

This is a table that is used by the fault tolerance functionality. When an adapter instance starts and this property is present, it will try to issue an exclusive lock on the named table before processing any messages.

The adapter instance that is able to lock this table is considered a primary instance. All instances that are not able to issue an exclusive lock on this table are considered secondary instances.

The table name is shared within a fault tolerance group. For example, adb.mutex FTtablename

Disables detection of duplicate configurations.

Either on or off. The default value is off which indicates that duplicate configurations will be detected.

The design-time table objects schema.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Runtime Adapter Properties File Parameters | 333

Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 5 of 12)

Property adb.password

Description

Password for the user account used to access your database. If not specified, the password stored in the repository is used. adb.payloadOnError on|off adb.perfMon on|off

This property specifies whether only the error information or all the logging information is printed in the log file.

Either on

off

. The default value is off

. If it is on or the Generate Payload On Error checkbox on the

General tab is checked when configuring an adapter instance, and the Log Info Messages checkbox on the

Logging tab is unchecked, only the error log information will be printed.

Either on

or off

. The default is off

adb.PollingBatchSize

adb.PollingInterval

adb.PollingCommitForDB2

adb.primary.heartbeat

Applies only to publisher instances. Limits the amount of messages to be picked up. The value indicates the number of parent rows to fetch for a poll interval. The default value,

, indicates that all new rows should be fetched.

Specific polling period. Applies only to publisher instances. If not specified the default, 10, 000 milliseconds, is used.

Either on or off. The default is off.

When using the adapter in the fault tolerance mode, this is the time interval (in ms) for which the adapter waits before issuing a dummy select statement.

This select statement is used to maintain the connection that holds the lock.

Default value is 10000.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

334 | Appendix C Adapter Properties File

Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 6 of 12)

Property adb.pubBatchConfirmSize

Description

Applies only to publisher instances with publications that use certified message delivery. Optimizes performance by batching message status advisories to the publishing table. The value indicates the number of advisory messages to include in a single batch.

Do not use this option when messages are published using a parameterized subject name.

Note: If an adapter instance stops before a batch update is performed, the status column is not updated. As a result, messages that were successfully published might still have a status of

(pending) in the publishing table when the adapter instance is restarted. In this case, the ledger file contains the correct status information. A smaller value for this property decreases this risk.

adb.pubBatchConfirmTimeout

Applies only to publisher instances with publications that use certified message delivery. This property specifies the number of milliseconds to wait before updating the status column. After this interval, an update is performed even if the batch size value is not reached. The default value is

10,000

(10 seconds). A value of 0 means that no timeout interval is used.

Do not use this option when messages are published using a parameterized subject name.

Note: If an adapter instance stops before a batch update is performed, the status column is not updated. As a result, messages that were successfully published might still have a status of

(pending) in the publishing table when the adapter instance is restarted. In this case, the ledger file contains the correct status information. A smaller value for this property decreases this risk. adb.publishChildData

adb.RequestResponseMaxRows

Either on or off. Applies only to publisher instances.

Enables publishing of table rows related to the source publishing table. By default, related table rows are not published.

This property specifies the maximum number of rows to fetch. This can be used limit the memory usage of the adapter. The unfetched rows will be ignored by the adapter.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Runtime Adapter Properties File Parameters | 335

Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 7 of 12)

Property adb.requestResponseThreads

Description

The number of threads used by the Request/response

Service. The default value is 1.

adb.RetryTotal

adb.runtime.publisherSchema

adb.runtime.schema

adb.rvAdvisoryNoLog on|off adb.rvMaxQueueSize

adb.secondary.heartbeat

adb.setClientInfo on|off

Total number of reconnection attempts.

The runtime publisher table schema. This overrides the adb.runtime.schema

setting. This can be used if the user has a different schema for the publishing table than the other table objects, such as the source table.

The runtime table objects schema.

• If adb.originalSchema

is specified, the adapter will compare the adb.originalSchema

with the prefix of the table objects. If they are the same, the adapter will replace the design-time schema with this runtime schema. Otherwise, no action will be taken.

• If adb.orignalSchema

is not specified, the adapter will append this runtime schema to all table objects that do not have any schema specified at design time.

This property specifies whether RV advisory messages are be logged in the adapter log files. The default value is off

Applies only to subscriber instances. Maximum number of messages to allow in the TIBCO

Rendezvous event queue. The default value is

, which means no limit is placed on event queue size.

The time interval that secondary instance waits before sending the next query message to detect the existence of the primary instance.

Default value is 10000.

When set to on

, the adapter will call

SET_CLIENT_INFO to set the database session client information.

The default value is on

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

336 | Appendix C Adapter Properties File

Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 8 of 12)

Property adb.setEmptyStringNullForRvMsg on|off

Description

Either on

or off

. Specifies whether the RVMSG fields of an empty string are treated as NULL or "" (empty strings). The default setting is off

If the property value is set to on

, empty strings are treated as NULL and if the property value is set to off

, empty strings are treated as empty strings if the database allows it.

adb.SleepBetweenRetries

adb.stmtCache

adb.subBatchCommitSize

adb.subBatchCommitTimeout

adb.subBulkInsertSize

Milliseconds of sleep between two reconnection attempts.

The number of cache statements for a generic RPC request/ reply service.

The number of statements that the adapter will cache so that it will execute the statement directly for repeated requests. If the cache is full, the adapter will remove the oldest message from the cache and will add the new statement. The default setting is off.

Example, adb.stmtCache 10

Applies only to subscriber instances. The number of messages to batch before invoking a commit operation. The default is

(zero).

Note: if messages greater than 32K are published, batching is automatically turned off.

Applies only to subscriber instances. The amount of time that can expire after which a batch commit operation is invoked. If not specified the default value of 10,000 milliseconds is used.

Applies only to subscriber instances. All incoming messages to insert are stored until this size is reached.

Then a bulk insert operation is performed on the destination table. This value must be less than or equal to the value specified for adb.subBatchCommitSize

, if used. The default value is

If an update statement is published while messages are being batched, the bulk insert is performed regardless of whether the size value has been reached. After records have been inserted, the update operation is performed.

Note: Do not use this option if LONG, LONG RAW, image, or varbinary records are published.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Runtime Adapter Properties File Parameters | 337

Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 9 of 12)

Property adb.tablespace

Description

The DB2 tablespace name for OS390. The adapter uses the value of this property when creating the table used by the fault tolerance functionality.

adb. taskBackLogLimitInBytes adb. taskBackLogLimitInMessages adb.terminateOnPubFail

The scheduler stores tasks in a queue. This property limits the maximum size of that scheduler task queue by the number of bytes. The properties can control the memory usage on the adapter side.

This value must be an integer. The default value is unspecified, which indicates that there is no limit to the size of the scheduler task queue.

The scheduler stores tasks in a queue. This property limits the maximum size of that scheduler task queue by the number of messages. The properties can control the memory usage on the adapter side.

This value must be an integer. The default value is unspecified, which indicates that there is no limit to the size of the scheduler task queue.

Specifies that if publication fails, the agent will terminate after the status has been updated to ’F’. The default value is off.

adb.traceOldMessages on|off adb.unicode

adb.useBetweenClause

Either on or off.

The unicode setting.

The default value is

UTF8

Valid values are

UTF8

and

UTF16

Additionally, the following options have to be set:

On Microsoft Windows, select the Enable N-CHAR option from the Advanced tab when configuring the

ODBC system data source.

On UNIX platforms, set the

EnableNcharSupport

option to 1 in the ODBC initialization files.

See the ODBC driver documentation for more details.

For Microsoft SQL Server, set the value of this property to UTF16.

This property disable the use of the BETWEEN clause in the select query of the publisher.

The default value is on

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

338 | Appendix C Adapter Properties File

Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 10 of 12)

Property adb.useExceptTable on|off

Description

Enables the use of the exception table. The exception table is defined when a subscription is created. adb.user

adb.useSqlColumns on|off adb.verbose on|off adb.wchar ntservice.account

ntservice.binary.path.absolute

ntservice.dependencies

Database account name used by the adapter to access your database. If not specified, the database username stored in the repository is used.

Either on

or off

. Specifies whether the adapter should use SQLColumns() instead of a SELECT query to retrieve metadata for a table.

Note: Typically, a

SELECT * FROM <table> WHERE 1>9

(which returns no results) is the fastest way to get metadata for that table. However, on some databases, such as DB2 OS390 v6, the database is not optimized for this query and a full table scan can result. Using an ODBC API call,

SQLColumns()

, can avoid this.

Verbose mode. Print all available information to the console window or log file location. By default the verbose mode is off.

Default is SQL_C_CHAR. Required when using

UTF-8 encoding with an adapter that uses a

DataDirect driver to retrieve UTF-8 data from the database.

If the adb.unicode is set, this property is set by default to SQL_C_BINARY to retreive unicode data.

Username under which to run the Windows Service.

You can use this property to initially set the account for the service, but once the service is installed, use the

Services

control to change the user account of services.

Absolute path to the executable that is run when the service is started. For example: ntservice.binary.path.absolute

C:/tibco/adapter/adadb/6.0/bin/ adb agent.exe

The number of dependencies.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Runtime Adapter Properties File Parameters | 339

Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 11 of 12)

Property ntservice.displayname

Description

Name to display in the Services control for this

Windows Service.

This property is useful if you wish to have multiple

Windows Services for the same executable. That is, you may wish to have two adapter running on the same machine. By specifying different service names and display names for the adapters, you can accomplish this. ntservice.interactive true|false Either true or false. Specifies whether the Windows

Service is interactive. Set to false if you are not using a system account.

ntservice.name

ntservice.password

ntservice.starttype manual|automatic

Name for this Windows Service.

This property is useful if you wish to have multiple

Windows Services for the same executable. That is, you may wish to have two adapters running on the same machine. By specifying different service names and display names for the adapters, you can accomplish this.

For example: ntservice.name adapter_instance_name

Password for the username in the ntservice.account

property.

You can use this property to initially set the password for the user account, but once the service is installed, use the

Services

control to change the password.

Start type for this Windows Service. Either manual

or automatic

. For example: ntservice.starttype automatic

You can use this property to initially set the start type for the service, but once the service is installed, use the Windows Services control to change the start type of services.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

340 | Appendix C Adapter Properties File

Table 49 Additional Runtime Adapter Properties File Parameters (Sheet 12 of 12)

Property tibco.clientVar

Description

Runtime values for global variables defined inside the repository. This value takes precedence over any global value set in the repository. Substitution takes place at runtime.

You append the global variable to tibco.clientVar

, then give its value. For example, a global variable named

DirLedger

is specified as follows: tibco.clientVar.DirLedger

C:/tibco/adapter/adadb/6.0/myledger

Do not include the

character of substitution variables. For example, to set

%%RvDaemon%%="tcp:7500"

, use tibco.clientVar.RvDaemon

"tcp:7500"

tibco.username

tibco.password

-version

User name and password used by the repository server to access the project. The password can be

obfuscated using the instructions in Obfuscating or

Encrypting a Password in the Properties File on page 341

Displays a banner with version information, then exits. This option is for troubleshooting purposes only.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Obfuscating or Encrypting a Password in the Properties File | 341

Obfuscating or Encrypting a Password in the Properties File

Password Handling

Designer 5.5, and use the configuration with a 4.x adapter version, some special considerations are required for security.

If you plan to run the adapter locally, define the runtime password value to be a global variable. Before starting the adapter, include the runtime password as client variable in the adapter's

.tra

file and obfuscate it using obfuscate tool. For example, if the password value is defined as

%%myPassword%%

, create a global variable named myPassword

in the global variables section with no value and include the following entry in the adapter's TRA file: tibco.clientVar.myPassword

Do not set the password by typing

Password

in the Global Variables section for adapter configurations that are set to

AE Version 4.0

AE Version 5.0

(in the Version field of the

Configuration tab) or any intermediate version.

Obfuscating a Password

The runtime adapter needs a password to access the backend database. If you have unchecked the Remember Password checkbox in the Design-time Connection tab, the global variable

%%adb.password%%

is saved in the project. For runtime, you open the

.tra

file and add the password in clear text in the tibco.clientVar.adb.password=# password

property. You can use the obfuscate tool to hide this password so it cannot be viewed by unauthorized users.

If you don’t want to obfuscate the password, remove the

at the beginning of the password.

To obfuscate the password:

1. Using TIBCO Designer, open the adapter configuration and display the Design-time

Connection tab.

2. Uncheck the Remember Password checkbox.

3. Apply the changes and save the project. This saves the global variable

%%adb.password%%

as the value of the password property in the project.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

342 | Appendix C Adapter Properties File

4. In the runtime adapter properties file, verify that the tibco.clientVar.adb.password=# password property is defined in clear text.

5. Run the obfuscation tool supplied with the adapter with the properties file. This tool is named obfuscate.exe

and resides in the

TIBCO_HOME

\tra\version\bin

directory.

The command syntax is: obfuscate

TRA_file_path where

TRA_file_path

is the absolute pathname of the adapter properties file that contains the tibco.clientVar.adb.password=# password

property.

For example, on Microsoft Windows :

C:\tibco\tra\version\bin>obfuscate C:\tibco\adapter\adadb\ version

\bin\adbagent.tra

The password is now obfuscated and you can start the adapter with the changed properties file.

Encrypting a Password

Encryption is only supported for version 5.x adapters and higher. If you have a property in a properties file the needs to be encrypted, follow these steps:

1. In the property file, add the #! characters in front of the value you wish to encrypt. For example:

Repo.serverPassword = #!mysecret

2. Invoke the obfuscate utility from the command line:

TIBCO_HOME

/tra/ version

/bin/obfuscate.exe

--propertyfile= property_file_name

The next time you open the property file, mysecret

will have been replaced with a random sequence of characters.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Using Hints | 343

Using Hints

Hints help improve the performance of your queries. When the adapter publication service executes a poll operation to fetch data from a table, using hints greatly enhances the query.

Note that in this release hints are only supported in Oracle and SQL Server databases.

Usage

To use hints add the following line to the adapter TRA properties file: adb.

table_name

.poll.hint hint_value where, table_name is the name of your table and

hint_value

is the hint.

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

344 | Appendix C Adapter Properties File

Examples

To force an index scan when polling in an Oracle database, set the property as follows: adb.p1.poll.hint /*+INDEX(P1,P1_INDX)*/ where p1

is the publisher table, and

P1_INDX

is the index created on the publishing table.

The adapter will execute this select query on the publishing table:

SELECT /*+INDEX(P1,P1_INDX)*/ * FROM P1 WHERE ID = ?

b. To use

NOLOCK

hint when polling in a SQL Server database, set the property as follows: adb.p1.poll.hint WITH(NOLOCK) where

is the publisher table.

The adapter will execute this select query on the publishing table, but will not issue shared locks or honor exclusive locks:

SELECT * FROM P1 WITH(NOLOCK) WHERE ADB_L_DELIVERY_STATUS =’N’ c.

To force an index scan when the adapter fetches records from a child table set the property as follows: adb.C1.poll.hint /*+INDEX(C1,C1_INDEX)*/ where

is the child table, and

C1_INDEX

is the index created on the child table.

The adapter will execute this select query on the child table:

SELECT /*+INDEX(C1,C1_INDEX)*/ * FROM C1 WHERE ID = ?

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

Index

Symbols

A

access to DB2 AS/400 tables

adapter changing a configuration

, 199

component (operation) information through TIBCO

Hawk

253

error messages when changing a configuration

naming restrictions

size limitations

stopping

tracing

194

unicode setting

343

adapter configuration, changing

199

Adapter Services folder

adapter setting client info

ADB_ERROR_TEXT

ADB_ERROR_TIME

time zone

ADB_L_CMSEQUENCE

ADB_L_DELIVERY_STATUS

148

ADB_OPCODE

147

154

ADB_REF_OBJECT column in the publishing table

ADB_SEQUENCE

ADB_SET_SEQUENCE

ADB_SOURCE

ADB_SUBJECT

ADB_TIMESTAMP

timezone

ADB_UPDATE_ALL

adbDateTime

adbPreCommit()

adding listeners

adding a sequence for parent-child

177

adding an association for parent-child

178

advanced folder

agents

alerter on Sybase SQL Server

110

alerts

auto-discovery process, TIBCO Hawk

242

B

binary type

169

bind statements

121

C

callout library

183

certified message delivery exception handling

291

moving ledger files

173

preregistering listeners

171

changes from the previous release

xvi

Class Microagent Name field, adapter

closure field

120

column names in an exception table

156

column names, reserved prefix

columns, maximum number

command line arguments

254

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

| 351

352 | Index commands adbagent

Connect

copy

isql

select

23 , 23 , 23 , 23 , 23

23 , 23 , 23 , 23

23 , 24

, 24 , 24

24 , 24 , 24 , 24 , 24

sqlplus

tibrvsend

commit_and_notify_table

103

CONFIG_HOME

xviii

configuration properties, retrieving through TIBCO

Hawk

254

custom RPC operation

131

customer support

xxi

examples

REF cursor procedure

143

Exceed FAQ

293

exception table structure of

154

exception table, column names in

156

F

fault tolerance

337

file format dat

Float data type

169

D

dat file format

data source, ODBC using

335

database errors, capturing

154

database type mapping

Date types

date/time values

dateTime

DB2 on OS/390 trigger statements syntax

202

debug, adapter option

334

delete trigger

Destination

distributed queues

dot character

dsn, adapter option

E

ENV_NAME

xviii

error messages about database cleanup

G

global variables

setting for monitoring

L

ledger files location

173

moving

173

publication size status

338

publication timeout status

339

retrieving information through TIBCO Hawk

263

listeners, adding

171

load balancing across adapters

in an adapter

Log File field, adapter

log file options

194

log files location

Log to Standard field, adapter

LONG data type

loop detection column used for

153

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

M

mapping database types

metadata

microagent methods supported

247

Microagent Session field, adapter

multiple file project

208

N

naming restrictions adapters

database columns

publishing table

subjects

notify procedure on Microsoft SQL Server

107

on Sybase

110

notifytable procedure on Microsoft SQL Server

107

on Sybase

110

NULL attributes

O

obfuscation

331

P

palettes

parameterized subject

binary type

Date types

Float type

illegal characters

Index | 353 parameters

AE Type

68 ,

Child Table Mapping

85 , 86

Class Reference

80 ,

Deploy On Save

Do Not Generate Triggers

Enable Loop Detection

Endpoint Reference

, 94

Join To

Publishing Table

Reply Subject

Subscriber Bulk Insert Size

Table Name

Tables and Columns

Type

Update Mode

Update Trigger

Use?

User Key

parent-child association

178

parent-child sequence

177

password property

346

PL/SQL procedure for REF cursor

143

preregistering listeners

171

publications size limitations

publish-child-data, adapter option

339

publishing by reference

source data

175

publishing table columns in

146

name size

restrictions for

Q

quality of service and load balancing

queue member load

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

354 | Index

R

record size, limitations

REF data type

143

reference object location

175

repository instance

request defined

118

request/response load balancing for

138

, 218

using

116

using multiple threads

136

215

response defined

119

reviewLedger, TIBCO Hawk method

RPC programs, client

rv_Rpc()

rv_Send()

rv_SendWithReply()

RVMSG_DATETIME

RVMSG_INT

RVMSG_OPAQUE

RVMSG_REAL

RVMSG_STRING

SQL_STATEMENT class, structure of

130 , 130

standard RPC operation

126

starting an alerter on Oracle

103

stopping an adapter

sub-batch-commit-timeout, adapter option

341

sub-bulk-insert-size, adapter option

341

subjects naming restrictions

parameterized

168

subscriber

using wildcards

, 171

subscriptions size limitations

wire format for

174

substitution

support, contacting

xxi

system configurl command-line argument

332

S

schema changes affecting adapter configuration

schema data

schemas for related tables

See

168

sequence number

146

source data publishing

175

source data publishing example

181

source table loop detection column

153

SQL statement terminator

202

SQL_BATCHRETURN class, structure of

129 , 129

SQL_BIND class, structure of

130

SQL_OPS class, structure of

127

SQL_RESULTSET class, structure of

128

SQL_RETURN class, structure of

128

SQL_ROW class, structure of

128

TIBCO ActiveMatrix Adapter for Database Configuration and Deployment

T

table access problems, overcoming

technical support

xxi

TIB_ADADB_HOME

xviii

TIBCO Hawk background information

enterprise monitor components

methods supported

247

Monitoring tab use with

TIBCO Hawk methods getComponents

getConfig

getRvConfig

getStatus

reviewLedger

TIBCO Rendezvous, retrieving configuration through

TIBCO Hawk

TIBCO_HOME

Tracing

tracing features

Tracing Levels and Fields

297 , 297

tracking identifier

296 ,

299

Index | 355 triggers no primary key

U

underscore character

update trigger

Use Advanced Logging field, adapter

user authority

user callout library

183

user schema

102

username property

346

use-trace-file, adapter option

194

V

variable substitution

variables

version, adapter option

346

W

wildcard subject names