Creating business objects

The connector uses message family-specific stored procedures for application event object processing and message type-specific stored procedures for service call request processing.

The following sections describe these methods.

Using the GETNXT-stored procedure for event retrieval

The connector uses the appropriate GETNXT-stored procedure to retrieve events from the message family staging tables. The signature for the GETNXT procedure varies from one message family to another.

The typical GETNXT-stored procedure call looks like this:

PROCEDURE GETNXT( O_status_code    OUT    VARCHAR2,
                 O_error_text      OUT    VARCHAR2,
                 O_message_type   OUT    VARCHAR2,
                 O_message        OUT    CLOB,
                 O_msg_1
    ...
);

O_status_code -- Denotes the status of the call, which may be one of four values:

O_error_text--The text associated with an error or warning.

O_message_type--The type of the message payload. A specific type is associated with one or more business events.

O_message--The message payload formatted as an XML string.

O_msg_1-- Additional optional message family-specific parameters.

Note:
The status code, error text, message type, and message payload are common to all procedures but can be followed by a number of message family-specific output parameters, which need to be placed in the ID or routing fields of the Retek Message Header business object. Occasionally, input parameters may be present as well. For more information on message family-specific metaobjects, see "Specifying Retek metadata business objects".

Steps for event retrieval and processing

The connector performs the following steps:

  1. Uses the message family metadata business object passed in during instantiation to prepare a statement for the GETNXT call:
    1. Registers local variables for the first 4 common output parameters (status code, error text, message type, and message payload).
    2. Maps the message family-specific attributes in the GETNXT metaobject to the corresponding parameters of the GETNXT-stored procedure.
  2. Calls the GETNXT procedure to retrieve message data; the message family metadata business object attributes that correspond to output parameters are populated by GETNXT.
  3. Creates a business object as follows:
  4. Instantiates a Retek Message Header business object and populates the ID and routingInfo attributes based on the information retrieved in the message family metadata business object. For more information related to this step, see "Specifying Retek metadata business objects".
  5. Sets the value of the source attribute to this connector instance name.
  6. Assigns the Retek Message Header business object to the corresponding child business object of the created message business object.
  7. Sets the verb as described in "Retek business object verbs".
  8. For a generic business object sets the ID attribute of the header as follows:
    1. Retrieves the KeyMO metaobject, if one was configured.
    2. For all attributes marked as keys in the metaobject (family, type, and/or ID), adds the value of the corresponding attribute in the header to the ID, as follows:
      • family--Adds the value to the ID.
      • type--Adds the prefix of the message type to the ID, without including the "action" suffix.

        Example: For "VendorCre," it adds "Vendor"

      • ID--For the NameValue pairs in the ID attribute, adds the string <name>=<value>.
  9. Delivers the Retek message business object to the broker by calling gotApplEvent.

For a summary of the status and error information related to the GETNXT-stored procedure, see Overview of the connector.

Using the CONSUME-stored procedure for request processing

The CONSUME message family type-specific stored procedure is used to perform incoming message processing (service call requests). The connector's business object handler's doVerbFor method invokes the message family type-specific CONSUME stored procedure to process the business object it receives as input.

The typical CONSUME-stored procedure call looks like this:

PROCEDURE CONSUME(O_status_code		           IN OUT  VARCHAR2,
O_error_message                           OUT  VARCHAR2,
I_message                                 IN OUT  CLOB);

O_status_code--Denotes the status of the call, which may be one of the following values:

O_error_message--The text associated with any error condition.

I_message--The payload XML text used as input to the stored procedure.

Note:
The status code, error text, and message payload parameters are common to all procedures, but can be followed by a number of application-specific input parameters.

Example: For RDM there is a fourth parameter called facility_type.

Steps for the CONSUME-stored procedure

The procedure takes place as follows:

  1. The connector receives a Retek message business object as input.
  2. If the message business object is generic, the connector retrieves the XML payload from the business object.

    If the message business object is message-specific, the connector calls the XML data handler, passing in the message-specific business object and gets back the corresponding XML as output.

  3. The business object handler constructs the name of the CONSUME API as follows:
    <app_name>SUB_<message_type>.CONSUME
    

    <app_name>--The name of the application being serviced by this instance, per AppName property.

    <message_type>--The message type, from the message type attribute of the Retek message business object.

  4. The business object handler builds the SQL statement for the CONSUME call as follows:
    1. Uses local variables to register the error code and error message.
    2. Builds a clob object from the XML payload and registers it for the message parameter.
    3. Retrieves any other input parameters for the CONSUME call. The ConsumeMO metaobject must contain attributes for all extra input parameters in the order they appear in the CONSUME-stored procedure. For more information on the ConsumeMO metaobject, see "Specifying Retek metadata business objects".
    4. For each attribute in the CONSUME metaobject:

      It looks for a routing field with the same name as the attribute in the Retek Message Header; if found, it sets the attribute value to the value of the routing field. In cases where the header does not contain the appropriate routing field, it uses the default value of the attribute.

      It registers the attribute as the next input parameter for the SQL statement.

  5. The business object handler calls the CONSUME API to process the message.

    Results: One of the following occurs:

Copyright IBM Corp. 1997, 2003