A completion callback is defined as follows:
CS_RETCODE CS_PUBLIC completion_cb(connection, cmd, function,status) CS_CONNECTION *connection; CS_COMMAND *cmd; CS_INT function; CS_RETCODE status;
where:
connection is a pointer to the CS_CONNECTION structure representing the connection that performed the I/O for the routine.
cmd is a pointer to the CS_COMMAND structure for the routine. cmd can be NULL.
function indicates which routine has completed. Table 2-4 lists the symbolic values possible for function:
Value |
Meaning |
---|---|
BLK_DONE |
blk_done has completed. |
BLK_INIT |
blk_init has completed. |
BLK_ROWXFER |
blk_rowxfer has completed. |
BLK_SENDROW |
blk_sendrow has completed. |
BLK_SENDTEXT |
blk_sendtext has completed. |
BLK_TEXTXFER |
blk_textxfer has completed |
CT_CANCEL |
ct_cancel has completed. |
CT_CLOSE |
ct_close has completed. |
CT_CONNECT |
ct_connect has completed. |
CT_DS_LOOKUP |
ct_ds_lookup has completed. |
CT_FETCH |
ct_fetch has completed. |
CT_GET_DATA |
ct_get_data has completed. |
CT_OPTIONS |
ct_options has completed. |
CT_RECVPASSTHRU |
ct_recvpassthru has completed. |
CT_RESULTS |
ct_results has completed. |
CT_SEND |
ct_send has completed. |
CT_SEND_DATA |
ct_send_data has completed. |
CT_SENDPASSTHRU |
ct_sendpassthru has completed. |
A user-defined value. This value must be greater than or equal to CT_USER_FUNC. |
A user-defined function has completed. |
status is the completion status of the completed routine. This value corresponds to the value that would be returned by a synchronous call under the same conditions. To find out what values status can have, see “Returns” on the reference page for the routine that corresponds to the value of the function parameter.
If the application calls ct_wakeup to invoke the completion callback, the call to ct_wakeup specifies the status value received by the completion callback.
A completion callback routine calls any Client-Library or CS-Library routine except cs_objects (CS_SET), ct_init, ct_exit, ct_setloginfo, and ct_getloginfo. cs_objects(CS_SET) is not asynchronous-safe, and ct_init, ct_exit, ct_setloginfo, and ct_getloginfo perform system-level memory allocation and deallocation.
If a completion callback calls an asynchronous Client-Library routine, it should return the value returned by the routine itself. Otherwise, there are no restrictions on what a completion callback can return. Sybase recommends, however, that the completion callback return CS_SUCCEED, if the completion callback succeeded, or CS_FAIL, if an error occurred.
The following is an example of a completion callback. This code is from the Client-Library sample programs (file ex_alib.c):
/*
** ex_acompletion_cb()
**
** Type of function:
** example async lib
**
** Purpose:
** Installed as a callback into Open Client. It
** will dispatch to the appropriate completion
** processing routine based on async state.
**
** Another approach to callback processing is to
** have each completion routine install the
** completion callback for the next step in
** processing. We use one dispatch point to aid
** in debugging the async processing (only need
** to set one breakpoint).
**
** Returns:
** Return of completion processing routine.
**
** Side Effects:
** None
*/
CS_STATIC CS_RETCODE CS_PUBLIC
ex_acompletion_cb(connection, cmd, function, status)
CS_CONNECTION *connection;
CS_COMMAND *cmd;
CS_INT function;
CS_RETCODE status;
{
CS_RETCODE retstat;
ExAsync *ex_async;
/*
** Extract the user area out of the command
** handle.
*/
retstat = ct_cmd_props(cmd, CS_GET, CS_USERDATA,
&ex_async, CS_SIZEOF(ex_async), NULL);
if (retstat != CS_SUCCEED)
{
return retstat;
}
fprintf(stdout, "\nex_acompletion_cb: function \
%ld Completed", function);
/* Based on async state, do the right thing */
switch ((int)ex_async->state)
{
case EX_ASEND:
case EX_ACANCEL_CURRENT:
retstat = ex_asend_comp(ex_async, connection,
cmd, function, status);
break;
case EX_ARESULTS:
retstat = ex_aresults_comp(ex_async,
connection, cmd, function, status);
break;
case EX_AFETCH:
retstat = ex_afetch_comp(ex_async,
connection, cmd, function, status);
break;
case EX_ACANCEL_ALL:
retstat = ex_adone_comp(ex_async, connection,
cmd, function, status);
break;
default:
ex_apanic("ex_acompletion_cb: unexpected \
async state");
break;
}
return retstat;
}