iscEngineListenerPF

Purpose

iscEngineListenerPF defines the prototype that the user-defined listener function registered in iscEngineSetListener() should comply with.

Syntax

typedef isy_INT32 (*iscEngineListenerPF)(
    isy_UINT32  listenerData,
    ISCEVT*     event,
    isy_VOID*   pExtraInfo);

Function arguments

Table 139 lists the valid arguments used with the iscEngineSetListenerPF function type.

Table 139. iscEngineListenerPF arguments

Usage

To use a user-define listener function for monitoring the progress of synchronization you must first make the function comply with the iscEngineSetListenerPF function type. Next, register the listener function using the iscEngineSetListener() function. Then, the user-defined listener function will be notified when synchronization events occur. The event argument is a structure, which contains various information about that event.

Table 140 lists all the fields in the event structure and the purpose of each field.

Table 140. iscEngineListenerPF event fields

The event.info field contains some optional event-specific information. The event code is used to identify and interpret this information.

Table 141 lists all the event codes by category of event type.

Table 141. iscEngineListenerPF event codes

Table 142. iscEngineListenerPF event codes

Table 143. iscEngineListenerPF event codes

Table 144. iscEngineListenerPF event codes

Table 145. iscEngineListenerPF event codes

Table 146. iscEngineListenerPF event codes

Example:

isy_INT32 mySyncListener(
    isy_UINT32 listenerData,
    ISCEVT*  event,
    isy_VOID*  pExtraInfo)
{
    char *statusMsg = appEventCodeToMessage(event);
    int   timesRetried;
 
    switch (event->type) {
      case ISCEVTTYPE_Info:
        appStatusBar(statusMsg);
        // appStatusBar can be any routine which shows the statusMsg (e.g., in a
        // status bar)
        return ISCRTNCB_Done;
 
      case ISCEVTTYPE_Retry:
        timesRetried = event->retry;
        if (timesRetried >= 3) // Try no more than 3 times
            return ISCRTNCB_ReplyNo;
        else
            return appRetryCancelBox(statusMsg, 10); // 10 sec timeout
        // appRetryCancelBox can be any routine which shows a window with two
        // buttons: Cancel and Retry.  It returns
        //   ISCRTNCB_ReplyYes, if user clicks Retry
        //   ISCRTNCB_ReplyNo, if user clicks Cancel
        // If the user doesn't make choice, it returns ISCRTNCB_Default.
        break;
 
      // all other event types, don't care
				  default:
        return ISCRTNCB_Default;
    } // switch (event->type)
} // mySyncListener

Return codes

• ISCRTNCB_ReplyYes : The user replies Yes to the query.
• ISCRTNCB_ReplyNo* : The user replies No to the query.
• ISCRTNCB_Default : No reply; take the default action.

If the event type is ISCEVTTYPE_Retry, the listener function returns one of the following codes:

If the event type is ISCEVTTYPE_Query, the meaning of the return code depends on the value of event code. In other words, the listener checks the event code and returns the appropriate value. But if the user does not reply to the query, the application returns the following code:

• ISCRTNCB_Default : No reply; take the default action.

For event types other than ISCEVTTYPE_Retry and ISCEVTTYPE_Query, the sync engine ignores the return code. The listener simply returns ISCRTNCB_Done.

Note: For those events not of interest, the listener function simply returns ISCRTNCB_Default and allows the sync engine to take the default action.

Note: An asterisk (*) above indicates the default action for various event types.

Restrictions

The user-defined listener function should follow the protocol of the synchronization engine. Otherwise, the synchronization engine might not work correctly.

Related concepts

• The sample Sync Client C/C++ application

Related tasks

• Developing DB2 Everyplace Sync Client applications using C/C++

Related reference

• Comparisons between IBM Sync Client C-API Version 8.1 and Version 7.2
• IBM Sync Client C-API data types
• IBM Sync Client C-API function summary
• iscEngineSync()
• iscEngineSetListener()