IIapi_catchEvent() Function—Retrieve a Database Event

The IIapi_catchEvent() function retrieves a database event previously registered by an application. The application first registers for a database event using IIapi_query() to invoke the register dbevent statement. It then captures each occurrence of the event and retrieves its data by calling IIapi_catchEvent().

IIapi_catchEvent() allows the application to specify the database event by the event parameters. If ce_selectEventName and ce_selectEventOwner are specified, one specific event is captured when the function completes. If only ce_selectEventOwner is specified, any events owned by the specific owner are captured. If only ce_selectEventName is specified, any events with the event name are captured. If neither ce_selectEventName nor ce_selectEventOwner are specified, all events are captured.

When IIapi_catchEvent() returns, it provides an event handle as immediate output. This handle is used to retrieve additional event information, to cancel the event retrieval, or to clean up after the event is retrieved.

Calling IIapi_catchEvent() captures one occurrence of a database event. After it has captured the event, the application can immediately issue another IIapi_catchEvent() with the same event handle to capture the next occurrence.

IIapi_catchEvent() operates in a manner similar to the embedded SQL statement set_sql(dbeventhandler=<dbevent_handler>). IIapi_catchEvent() does not result in any communication with the server. Since database event notification is passed along with other SQL result information, the application must continue with other database operations after calling IIapi_catchEvent() to enable retrieval of database events.

IIapi_getEvent() can be used to receive database event notifications when the application has no other database operations to perform. IIapi_getEvent() operates in a manner similar to the embedded SQL statement GET DBEVENT. See IIapi_getEvent() for further details.

If IIapi_catchEvent() completes with ce_eventInfoAvail set to TRUE, the application should call IIapi_getDescriptor() and IIapi_getColumns() to access additional event information.

If the application no longer wants to retrieve a pending database event, it calls IIapi_cancel() to cancel the event retrieval. A canceled event retrieval completes with a failure status. After an event is canceled, or an event retrieval has completed, the application calls IIapi_close() to free the event handle and associated internal resources.

If an event notification occurs for which there is no active matching event handle, the database event is ignored. IIapi_setEnvParam() permits a callback function to be registered, which will be called for each database event that fails to match to an active event handle and would otherwise be ignored. See IIAPI_EP_EVENT_FUNC and related documentation in the description for IIapi_setEnvParam().

This function has the following syntax:

typedef struct _IIAPI_CATCHEVENTPARM
{
      IIAPI_GENPARM  ce_genParm;
      II_PTR         ce_connHandle;
      II_CHAR        *ce_selectEventName;
      II_CHAR        *ce_selectEventOwner;
      II_PTR         ce_eventHandle;
      II_CHAR        *ce_eventName
      II_CHAR        *ce_eventOwner
      II_CHAR        *ce_eventDB;
      IIAPI_DATAVALUE ce_eventTime;
      II_BOOL         ce_eventInfoAvail;
} IIAPI_CATCHEVENTPARM;

This function has the following parameters:

Specifies the connection handle, identifying the connection to the target server, or the environment handle.

Specifies the name of the event to retrieve. This parameter is NULL if the application wants to receive the next event indiscriminately; otherwise, it is a NULL-terminated string containing the name of the event the application is requesting.

Specifies the owner of the event to retrieve. This parameter is NULL if the application requests events by any owner; otherwise, it is a NULL‑terminated string containing the name of the event owner.

Specifies the event handle identifying the event retrieval. Set to NULL to begin a new event retrieval. After receiving the requested event, the application may call IIapi_catchEvent() with the same event handle to receive the next event. The application should clean up resources when event retrieval is no longer desired by calling IIapi_close() with this event handle.

The memory for this parameter is managed by the OpenAPI. For more information, see Output Parameters Allocated by OpenAPI.

The memory for this parameter is managed by OpenAPI. For more information, see Output Parameters Allocated by OpenAPI).

Indicates the server where the event occurred. This parameter contains a NULL-terminated string containing the name of the server.

The memory for this parameter is managed by the OpenAPI. For more information, see Output Parameters Allocated by OpenAPI).

Indicates whether the is additional information associated with the event. The parameter is FALSE if there is no additional information associated with the event; otherwise, the application should call IIapi_getDescription() and IIapi_getColumns() with ce_eventHandle to retrieve the additional event information.