How the connector works

This section describes how meta-data enhances the connector's flexibility and presents a high-level description of business object processing and event notification.

The connector and meta-data

The connector is meta-data-driven. Meta-data, in the WebSphere environment, is application-specific data that is stored in business objects and that assists the connector in its interaction with the application. A meta-data-driven connector handles each business object that it supports based on meta-data encoded in the business object definition rather than on instructions hardcoded in the connector.

Business object meta-data includes the structure of a business object, the settings of its attribute properties, and the content of its application-specific information. Because the connector is meta-data driven, it can handle new or modified business objects without requiring modifications to the connector code.

The connector executes SQL statements or stored procedures to retrieve or change data in the legacy application. To build dynamic SQL statements or stored procedures, the connector uses application-specific meta-data. These SQL statements and stored procedures perform the required retrieval from or changes to the legacy application for the business object and for the verb that the connector is processing. For details about using application-specific information, see Developing business objects for the Mainframe Adapter Suite.

Business object processing

This section provides an overview of how the connector processes business object requests and application events. For more detailed information, see Business object verb processing.

Processing business object requests

When the connector receives a request to perform an application operation, the connector processes hierarchical business objects recursively; that is, it performs the same steps for each child business object until it has processed all individual business objects. The order in which the connector processes child business objects and the top-level business object depends on whether the child business objects are contained with or without ownership and whether they are contained with single cardinality or multiple cardinality.

Note:
The term hierarchical business object refers to a complete business object, including all the child business objects that it contains at any level. The term individual business object refers to a single business object, independent of any child business objects it might contain or that contain it. The term top-level business object refers to the individual business object at the top of the hierarchy that does not itself have a parent business object.

Business object retrieval

When a business object request asks the connector to retrieve a hierarchical business object from the legacy application, the connector attempts to return a business object that exactly matches the current application representation of that business object. In other words, all simple attributes of each individual business object returned match the value of the corresponding field in the application. Also, the number of individual business objects in each array contained by the returned business object match the number of children in the application for that array.

To perform such a retrieval, the connector uses the primary key values in the top-level business object received from the integration broker to recursively descend through the corresponding data in the application.

Business object RetrievalByContent

When a business object request asks the connector to retrieve a hierarchical business object based on values in non-key attributes in the top-level business object, the connector uses the value of all non-null attributes as the criteria for retrieving the data.

Business object creation

When a business object request asks the connector to create a hierarchical business object in the application, the connector performs the following steps:

  1. Recursively creates each single-cardinality child business object contained with ownership into the application. Processes each single-cardinality child business object contained without ownership.
    Note:
    All single cardinality child business objects are processed based on occurrence in the business object and before the parent business object is processed. Child object ownership and non-ownership do not determine the processing sequence, but do determine the type of processing.
  2. Creates the top-level business object in the application.
  3. Creates each single-cardinality child business object that stores the parent/child relationship in the child.
  4. Creates each multiple-cardinality child business object.

Business object modification

When a business object request asks the connector to update a hierarchical business object in the application, the connector performs the following steps:

  1. Uses the primary key values of the source business object to retrieve the corresponding entity from the application.
  2. Recursively updates all single-cardinality children of the top-level business object.
  3. Updates all simple attributes of the retrieved business object except those whose corresponding attribute in the source business object contain the value CxIgnore.
  4. Processes all arrays of the retrieved business object.

Business object deletion

When a business object request asks the connector to delete a hierarchical business object from the application, the connector performs the following steps:

  1. Deletes the single-cardinality children.
  2. Deletes the multiple-cardinality children.
  3. Deletes the top-level business object.

Processing application events

An event table should be used to store events associated with business object operations. The connector is notified of application events such as create, update and delete by means of a database trigger or some other suitable mechanism. The event table must be populated with these application events. The event table resides in the application database.

The connector handles the Create, Update, and Delete events generated by the application in the manner described below.

Note:
The CICS/TS, Natural, IDMS Database, VSAM, and IMS/TM legacy applications may not support all of the features described below.

Create notification

When the connector encounters a Create event in the event table, it creates a business object of the type specified by the event, sets the key values for the business object (using the keys specified in the event table), and retrieves the business object from the application. After it retrieves the business object, the connector sends it with the Create verb to the integration broker.

Update notification

When the connector encounters an Update event in the event table, it creates a business object of the type specified by the event, sets the key values for the business object (using the keys specified in the event table), and retrieves the business object from the application. After it retrieves the business object, the connector sends it with the Update verb.

Delete notification

When the connector encounters a Delete event in the event table, it creates a business object of the type specified by the event, sets the key values for the business object (using the keys specified in the event table), and sends it with the Delete verb to the integration broker. All values other than the key values are set to CxIgnore. If any of the non-key fields are significant at your site, modify the value of the fields.

The connector handles logical and physical Delete operations that are triggered by its application. In the case of physical deletes, the SmartFiltering mechanism removes all of the business object's unprocessed events (such as Create or Update) before inserting the Delete event into the event table. In the case of logical deletes, the connector inserts a Delete event in the event table without removing other events for the business object.

Retrieving business objects for event processing

A Retrieve can be done in two ways on a business object for event processing. The first is a Retrieve based on key attributes in a business object. The second is a Retrieve based on both key and non-key attributes. In this case, the business object needs to support the RetrieveByContent verb and must use name_value pair for the object keys.

Note:
If the object key does not use name_value pair, the keys in the object key field should follow the same order as the keys in the business object.

Event processing

The connector's event detection mechanism uses an event table, an archive table, stored procedures, and database triggers. Because there are potential failure points associated with the processing of events, the event management process does not delete an event from the event table until it has been inserted it into the archive table.

The database triggers populate an event table whenever an event of interest occurs in the application database. The connector polls this table at a regular, configurable interval, retrieves the events, and processes the events first by priority and then sequentially. When the connector has processed an event, the event's status is updated. You must add the triggers to the application database as part of the installation procedure.

The setting of its ArchiveProcessed property determines whether the connector archives an event into the archive table after updating its status. For more information on the ArchiveProcessed property, see Configuring the connector.

Table 2 illustrates the archiving behavior depending on the setting of the ArchiveProcessed property.

Table 2. Archiving behavior

Archive processed setting Reason deleted from event table Connector behavior
true or no value Successfully processed Archived with status of Sent to InterChange

Unsuccessfully processed Archived with status of Error

No subscription for business object Archived with status of Unsubscribed
false
Successfully processed Not archived and deleted from event table

Unsuccessfully processed Remains in event table with status of s

No subscription for business object Remains in event table with status of Unsubscribed

WebSphere has implemented SmartFiltering, a mechanism within the database triggers that minimizes the amount of processing the integration broker performs. For example, if an application has updated the Contract business object 15 times since the connector last polled for events, the SmartFiltering stores those changes as a single Update event.

Handling lost database connections

There are numerous reasons for losing a connection to the application or database. If this occurs, the connector terminates. The JDBC specification does not provide a mechanism for detecting lost connections. The PingQuery property is provided to handle this detection. If a failure occurs during a service call request, the connector executes this PingQuery to confirm that the failure was not due to a lost connection to an application/database. If the PingQuery fails and the AutoCommit property is set to false, the connector will attempt to create a new connection to the database.If it succeeds in creating a new connection to the database it will continue processing, otherwise the connector returns an APPRESPONSETIMEOUT, which results in the termination of the connector.

The PingQuery is executed if a failure occurs when accessing an application for any type of transaction. For example:

Copyright IBM Corp. 1997, 2003