Open Client Client-Library/C Reference Manual

Home

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Callbacks

Completion callbacks

A completion callback signals an application that an asynchronous routine has completed.

A context or a connection is defined to be asynchronous so that routines that read to or write from the network return immediately rather than blocking until the necessary I/O operations have completed. The value of a connection structure's CS_NETIO property determines whether Client-Library routines behave asynchronously. See "Network I/O" for details.

When a connection is asynchronous, Client-Library routines that perform network I/O return CS_PENDING immediately rather than completing the requested operation before returning. In a fully asynchronous application (CS_NETIO is CS_ASYNC_IO), a completion callback is needed to notify the mainline code of the asynchronous operation's completion.

For more information on Client-Library's asynchronous programming modes, see "Asynchronous programming".

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:

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;


	Expand Search