Defining a completion callback

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:

**Table 2-4: Values for the completion callback function parameter**
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.

Completion callback example

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;