Event API

These procedures and functions are provided to help create, send, and work with events in ESQL. These procedures and functions can be found in the EventAPI.esql file, with more procedures in the EventHelper.esql and ActionHelper.esql files.

Procedures found in EventAPI.esql

CreateEvent

Creates a new, partially populated event message. It is the responsibility of the caller to finish populating the event message.

Create statement for this procedure: CREATE PROCEDURE CreateEvent (OUT nReturnCode INTEGER, INOUT rEvent REFERENCE, IN cLocalInstanceId CHAR, IN cSeverity CHAR, IN cPriority CHAR, IN cSourceComponent CHAR, IN cReporterComponent CHAR, IN nTransactionID INTEGER, IN nBatchID INTEGER, IN nTransmissionID INTEGER, IN nSvcPartID INTEGER);

CreatePriorityEvent

Creates an event with the specified priority value. If the priority is disabled, this procedure behaves the same as the CreateEvent procedure. Before this procedure is called, declare refEvent with statements such as those shown in the following example.

CREATE FIRSTCHILD OF Environment.PMP.Variables NAME 'NewEvent';
DECLARE refEvent REFERENCE TO Environment.PMP.Variables.NewEvent;


CALL EventProcessingFlow.CreatePriorityEvent(nRetCode,                                   -- Return Code
                                             refEvent,                                   -- Event Reference
                                             cEventType,                                 -- Event Type
                                             '10',                                       -- Severity : 10 - Informational
                                             Cache.GetDefaultObjectPriorityAsChar(),     -- Priority : Use default priority
                                             'Heartbeat Flow',                           -- Source Component
                                             '',                                         -- Reporter Component
                                             -1,                                         -- Transaction ID
                                             -1,                                         -- Batch ID
                                             -1,                                         -- Transmission ID
                                             -1);                                        -- Logical Unit ID

Create statement for this procedure: CREATE PROCEDURE CreatePriorityEvent (OUT nReturnCode INTEGER, INOUT rEvent REFERENCE, IN cLocalInstanceId CHAR, IN cSeverity CHAR, IN cPriority CHAR, IN cSourceComponent CHAR, IN cReporterComponent CHAR, IN nTransactionID INTEGER, IN nBatchID INTEGER, IN nTransmissionID INTEGER, IN nSvcPartID INTEGER);

AddContextValue

Adds context data to the event tree. For example, after an event is created by using the CreatePriorityEvent, more fragment ID context data can be added, if appropriate, by using refEvent as the reference to the created event.


IF nFragId IS NOT NULL THEN
   CALL EventProcessingFlow.AddContextValue(retCode, refEvent, 'FRAGMENT', CAST(nFragId AS CHAR), TRUE);
END IF;

Create statement for this procedure: CREATE PROCEDURE AddContextValue (OUT returnCode INTEGER, INOUT refEvent REFERENCE, IN contextName CHAR,IN contextValue CHAR, IN isIdReference BOOLEAN);

SetContextValue

Sets the value of the context data that has the supplied name. If the named context data does not exist, it is added to the tree with the specified value. The following example is used to set the 'NOW' context for the heartbeat event.

CALL EventProcessingFlow.SetContextValue(nRetCode, rEvent, 'NOW', (TIMESTAMP_IN_DB2FMT(currentTS)));

Create statement for this procedure: CREATE PROCEDURE SetContextValue (OUT returnCode INTEGER, INOUT refEvent REFERENCE, IN contextName CHAR, IN contextValue CHAR);

AddWildcard

Creates an element at the end of the event with the specified name, namespace, and value. The element is always created, even if one exists.

Create statement for this procedure: CREATE PROCEDURE AddWildcard (IN refEvent REFERENCE, IN cNS CHAR, IN cName CHAR, IN rContext REFERENCE);

AddWildcardData

Creates an element at the end of the event with the specified name, namespace, and value, if it does not exist. If the element exists, the value is overwritten.

Create statement for this procedure: CREATE PROCEDURE AddWildcardData (IN refEvent REFERENCE, IN cNS CHAR, IN cName CHAR, IN rContext REFERENCE);

AddExtendedContext

Adds extended context data to the event tree.

Create statement for this procedure: CREATE PROCEDURE AddExtendedContext (IN refEvent REFERENCE, IN rContext REFERENCE);

AddExtendedContextWithName

Adds extended context data to the event tree with the specified name.

Create statement for this procedure: CREATE PROCEDURE AddExtendedContextWithName (IN refEvent REFERENCE, IN rContext REFERENCE, IN name CHAR);

SendEvent

Called to send a fully built event message. The event is not sent immediately, but is added to an event cache in the environment tree. At the end of the message flow, all events in the cache are propagated.

Create statement for this procedure: CREATE PROCEDURE SendEvent (OUT nReturnCode INTEGER, INOUT rEvent REFERENCE, INOUT rEventsCache REFERENCE);

CreateAndSendEvent

Combines the functions of both the CreateEvent and SendEvent procedures. This function is more efficient than creating and sending the event in separate steps.

Create statement for this procedure: CREATE PROCEDURE CreateAndSendEvent (INOUT rEvent REFERENCE, IN cLocalInstanceId CHAR, IN cSeverity CHAR, IN cPriority CHAR, IN cSourceComponent CHAR, IN cReporterComponent CHAR, IN nTransactionID INTEGER, IN nBatchID INTEGER, IN nTransmissionID INTEGER, IN nSvcPartID INTEGER, IN rContext REFERENCE, IN rEnv REFERENCE);

CreateAndSendPriorityEvent

Combines the functions of both the CreateEvent and SendEvent procedures and sets the priority of the event. If the priority is disabled, this procedure behaves the same as CreateAndSendEvent.

Create statement for this procedure: CREATE PROCEDURE CreateAndSendPriorityEvent (INOUT rEvent REFERENCE, IN cLocalInstanceId CHAR, IN cSeverity CHAR, IN cObjectPriority CHAR, IN cSourceComponent CHAR, IN cReporterComponent CHAR, IN nTransactionID INTEGER, IN nBatchID INTEGER, IN nTransmissionID INTEGER, IN nSvcPartID INTEGER, IN rContext REFERENCE, IN rEnv REFERENCE);

ContextValue

Returns a context value from an event message, refEvent. The inOpFlag argument sets whether the result is formatted for inserting into an SQL statement after an 'IN' clause.

Create statement for this procedure: CREATE PROCEDURE ContextValue (OUT result CHAR, IN contextName CHAR, IN refEvent REFERENCE, IN inOpFlag BOOLEAN)

Context

Returns a context value from an event message. The wrapper for ContextValue uses a return value instead of an OUT parameter to return the result.

Create statement for this procedure: CREATE FUNCTION Context (contextName CHAR, refEvent REFERENCE, inOpFlag BOOLEAN) RETURNS CHAR

GetOutEventName

This procedure returns the name of the event that is being propagated to IBM® MQ. Beginning with FTM version 3.0, the events that are going to IBM MQ are serialized as BLOB. Applications that relied on access to the Common Base Event tree to identify the localInstanceIdentifier event can call this procedure instead.

Create statement for this procedure: CREATE FUNCTION GetOutEventName (IN rEnv REFERENCE);

Procedures found in EventHelper.esql

These procedures offer some extra utility and convenience over the procedures in EventAPI.esql.

RaiseEvent

Calls RaiseEventWithContext with no context data. Use RaisePriorityEventWithContext for new development.

Create statement for this procedure: CREATE PROCEDURE RaiseEvent (IN cEventType CHAR, IN nPTId INTEGER, IN nBatId INTEGER, IN nTxnId INTEGER, IN nSPId INTEGER, IN cSeverity CHAR, IN cPriority CHAR, IN cAction CHAR, INOUT rEnv REFERENCE);

RaiseEventWithContext

Creates an event reference and then calls CreateAndSendEvent from EventAPI.esql with the reference as the first argument.

Create statement for this procedure: CREATE PROCEDURE RaiseEventWithContext (IN cEventType CHAR, IN nPTId INTEGER, IN nBatId INTEGER, IN nTxnId INTEGER, IN nSPId INTEGER, IN cSeverity CHAR, IN cPriority CHAR, IN cAction CHAR, IN rContext REFERENCE, INOUT rEnv REFERENCE);

RaisePriorityEvent

This procedure is the same as RaiseEvent, but it also sets the priority of the event. The following example shows how to call this procedure.

CALL Common.RaisePriorityEvent('E_TxnRepairFailed',                  -- Event Type
                               -1,                                   -- Transmission ID
                               -1,                                   -- Batch ID
                               nCurrentTxnId,                        -- Transaction ID
                               -1,                                   -- Participant ID
                               '10',                                 -- Severity
                               CAST(rObj.TECH_PRIORITY AS CHAR),     -- Priority
                               ACTION_NAME,                          -- Source Component
                               rEnv);                                -- Environment

Create statement for this procedure: CREATE PROCEDURE RaisePriorityEvent (IN cEventType CHAR, IN nPTId INTEGER, IN nBatId INTEGER, IN nTxnId INTEGER, IN nSPId INTEGER, IN cSeverity CHAR, IN cPriority CHAR, IN cAction CHAR, INOUT rEnv REFERENCE);

RaiseEventWithException

When an exception occurs in the environment, this procedure raises the event as usual, but adds the exception details in the "ExceptionList" as part of the extended context of the event. The event is created and then the exception detail is added as the context, if it is not null. Finally, the event is sent.

Create statement for this procedure: CREATE PROCEDURE RaiseEventWithException (IN cEventType CHAR, IN nPTId INTEGER, IN nBatId INTEGER, IN nTxnId INTEGER, IN nSPId INTEGER, IN cSeverity CHAR, IN cPriority CHAR, IN cAction CHAR, IN rContext REFERENCE, IN rException REFERENCE, INOUT rEnv REFERENCE);

RaisePriorityEventWithContext

This procedure is the same as RaiseEventWithContext, but it also sets the priority of the event. The following example shows how to call this procedure.

CALL Common.RaisePriorityEventWithContext(cEventName,                              -- Event Type
                                          CAST(rObj.TRANSMISSION_ID AS INTEGER),   -- Transmission ID
                                          nBatchId,                                -- Batch ID
                                          nCurrentTxnId,                           -- Transaction ID
                                          -1,                                      -- Participant ID
                                          cSeverity,                               -- Severity
                                          CAST(rObj.TECH_PRIORITY AS CHAR),        -- Priority
                                          ACTION_NAME,                             -- Source Component
                                          rEnv.Context                             -- context data
                                          rEnv);                                   -- Environment

Create statement for this procedure: CREATE PROCEDURE RaisePriorityEventWithContext ( IN cEventType CHAR, IN nPTId INTEGER, IN nBatId INTEGER, IN nTxnId INTEGER, IN nSPId INTEGER, IN cSeverity CHAR, IN cPriority CHAR, IN cAction CHAR, IN rContext REFERENCE, INOUT rEnv REFERENCE );

RaisePriorityEventWithException

This procedure is the same as RaisePriorityEvent, but with the referenced exception.

Create statement for this procedure: CREATE PROCEDURE RaisePriorityEventWithException (IN cEventType CHAR, IN nPTId INTEGER, IN nBatId INTEGER, IN nTxnId INTEGER, IN nSPId INTEGER, IN cSeverity CHAR, IN cPriority CHAR, IN cAction CHAR, IN rContext REFERENCE, IN rException REFERENCE, INOUT rEnv REFERENCE)

Procedures found in ActionHelper.esql

These procedures offer some extra utility when you work with events.

CurrentEventType

Returns the type of the current event.

Create statement for this procedure: CREATE FUNCTION CurrentEventType (IN rEnv REFERENCE) RETURNS CHAR;

CurrentEvent

Returns a reference to the current event.

Create statement for this procedure: CREATE FUNCTION CurrentEvent (INOUT rEnv REFERENCE);

EventType

Returns the type of the supplied event.

Create statement for this procedure: CREATE FUNCTION EventType (IN rEvent REFERENCE) RETURNS CHAR;

GetEventContextDataCount

Returns the number of instances of a specified context data element in an event that conforms to the Common Base Event specification.

Create statement for this procedure: CREATE FUNCTION GetEventContextDataCount (IN rEvent REFERENCE, IN contextName CHAR) RETURNS INTEGER

InitContextDataElementRef

Copies the context data with the specified name from rEvent to rCDE. This procedure is useful when a new event is created by using context from an input event. The following example shows how to call this procedure.

IF NOT InitContextDataElementRef('BATCH', rEvent, ref_BATCH_CTX ) THEN
   THROW USER EXCEPTION VALUES ('Error: Unable to locate context data in event', 'BATCH');
END IF;

Create statement for this procedure: CREATE FUNCTION InitContextDataElementRef (IN contextName CHAR, IN rEvent REFERENCE, INOUT rCDE REFERENCE) RETURNS BOOLEAN

GetCtxValueIndex

Searches the event reference for a context data element with the supplied name. If a context data element with the supplied name cannot be found, a user exception occurs.

Create statement for this procedure: CREATE FUNCTION GetCtxValueIndex (IN currentValue CHAR, INOUT rCurrentCtxInEvnt REFERENCE) RETURNS INTEGER

GetCtxValueByIndex

Returns the context data value for the specified index. This procedure can be used with GetCtxValueIndex to get the value of a named context field.

Create statement for this procedure: CREATE FUNCTION GetCtxValueByIndex (IN nIndex INTEGER, INOUT rTargetCtxInEvnt REFERENCE) RETURNS CHAR