ct_poll

Description

Poll connections for asynchronous operation completions and registered procedure notifications.

Syntax

CS_RETCODE ct_poll (context, connection,
                   milliseconds, compconn,
                   compcmd, compid, compstatus)
 
CS_CONTEXT            *context;
CS_CONNECTION     *connection;
CS_INT                       milliseconds;
CS_CONNECTION     **compconn;
CS_COMMAND          **compcmd;
CS_INT                       *compid;
CS_RETCODE            *compstatus;

Parameters

context

A pointer to a CS_CONTEXT structure.

Either context or connection must be NULL. If context is NULL, ct_poll checks only a single connection.

connection

A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/server connection.

Either context or connection must be NULL. If connection is NULL, ct_poll checks all open connections within the context.

milliseconds

The length of time, in milliseconds, to wait for pending operations to complete.

If milliseconds is 0, ct_poll returns immediately. To check for operation completions without blocking, pass milliseconds as 0.

If milliseconds is CS_NO_LIMIT, ct_poll does not return until any of the following is true:

A server response arrives. This can be a registered procedure notification or the data needed to complete a call to an asynchronous routine.
No asynchronous-routine completions are pending. If no completions are pending when ct_poll is called, then it returns CS_QUIET (see the Return value section for more information).
A system interrupt occurs.

ct_poll does not wait for the arrival of notification events. However, ct_poll does trigger the notification callback for notification events that are present when it is called or that arrive while ct_poll is waiting for asynchronous routine completions.

compconn

The address of a pointer variable. If connection is NULL, all connections are polled and ct_poll sets *compconn to point to the connection structure owning the first completed operation it finds.

If no operation has completed by the time ct_poll returns, ct_poll sets *compconn to NULL.

If connection is supplied, compconn must be NULL.

compcmd: The address of a pointer variable. ct_poll sets *compcmd to point to the command structure owning the first completed operation it finds. If no operation has completed by the time ct_poll returns, ct_poll sets *compcmd to NULL.

compid

The address of an integer variable. ct_poll sets *compid to one of the following symbolic values to indicate what has completed:

**Table 3-50: Values for ct_poll *compid parameter**
Value of compid	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_NOTIFICATION	A notification has been received.
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.

compstatus: A pointer to a variable of type CS_RETCODE. ct_poll sets *compstatus to indicate the final return code of the completed operation. This value corresponds to the value that would be returned by a synchronous call to the routine under the same conditions. This can be any of the return codes listed for the routine, with the exception of CS_PENDING.

Returns

ct_poll returns the following values:

**Table 3-51: ct_poll return values**
Return value	Meaning
CS_SUCCEED	An operation has completed.
CS_FAIL	An error occurred.
CS_TIMED_OUT	The timeout value specified by milliseconds elapsed before any operation completed. Asynchronous operations may be in progress.
CS_QUIET	ct_poll was called with milliseconds as 0 (to indicate that it should return immediately). No asynchronous operations are in progress, and no completed operations or registered procedure notifications were found.
CS_INTERRUPT	A system interrupt has occurred.

ct_poll returns CS_FAIL if it polls a connection that has died.

Examples

Example 1

/*

 ** BusyWait()

**

 ** Type of function:

 **   async example program api

**

 ** Purpose:

 **   Silly routine that prints out dots while waiting

 **   for an async operation to complete. It demonstrates

 **   the ability to do other work while an async

 **   operation is pending.

**

 ** Returns:

 **   completion status.

**

 ** Side Effects:

 **   None

*/

 CS_STATIC CS_RETCODE CS_INTERNAL

 BusyWait(connection, where)

 CS_CONNECTION   *connection;

 char            *where;

    CS_COMMAND      *compcmd;

    CS_INT          compid;

    CS_RETCODE      compstat;

    CS_RETCODE      retstat;

    fprintf(stdout, "\nWaiting [%s]", where);

    fflush(stdout);

do

      fprintf(stdout, ".");

      fflush(stdout);

      retstat = ct_poll(NULL, connection, 100, NULL, &compcmd,

                       &compid, &compstat);

      if (retstat != CS_SUCCEED

          && retstat != CS_TIMED_OUT

          && retstat != CS_INTERRUPT)

        fprintf(stdout,

                "\nct_poll returned unexpected status of %d\n",

                retstat);

        fflush(stdout);

        break;

    } while (retstat != CS_SUCCEED);

    if (retstat == CS_SUCCEED)

      fprintf(stdout,

        "\nct_poll completed: compid = %ld, compstat = %ld\n",

              compid, compstat);

      fflush(stdout);

    return compstat;

This code excerpt is from the ex_amain.c example program.

Usage

Table 3-52 summarizes ct_poll usage.

**Table 3-52: Summary of ct_poll parameters**
context	connection	compconn	Result
NULL	Must have a value.	Must be NULL.	Checks the single connection specified by connection.
Has a value	Must be NULL.	Must have a value.	Checks all connections within this context. Sets *compconn to point to the connection owning the first completed operation it finds.

ct_poll polls either a specific connection or all connections within a specific context.

On platforms where Client-Library uses signals to implement asynchronous network I/O, the application’s callback routines can execute at the system interrupt level.

Do not call ct_poll from within any Client-Library callback function or within any other function that can execute at the system interrupt level.

Calling ct_poll at the system-interrupt level can corrupt Open Client/Server internal resources and cause recursion in the application.
If a platform does not provide interrupt- or thread-driven I/O, then an application must periodically read from the network to recognize asynchronous operation completions and registered procedure notifications.

All routines that can return CS_PENDING read from the network. If an application is not actively using any of these routines, it must call ct_poll to recognize asynchronous operation completions and registered procedure notifications.
- ct_poll must be called periodically to recognize asynchronous operation completions. ct_poll reports which routine has completed and the completion status of the asynchronous operation. If a completion callback is installed for the connection on which the completion occurred, then the completion callback is invoked by ct_poll.
- For registered procedure notifications, the application can be reading from the connection (as part of the normal process of sending commands processing results) or call ct_poll to cause Client-Library to recognize notification events. The notification callback can be invoked by ct_poll or by any routine which is reading from the connection. If the application is not actively sending commands and processing results on the connection, it should poll the connection with ct_poll to receive the notification event.
If CS_ASYNC_NOTIFS is CS_FALSE, ct_poll does not read from the network. This means that an application must be reading results for ct_poll to report a registered procedure notification.
If a platform allows the use of callback functions, ct_poll automatically calls the proper callback routine, if one is installed, when it finds a completed operation or a notification.
ct_poll does not check for asynchronous operation completions if the CS_DISABLE_POLL property is set to CS_TRUE.
If there are no pending asynchronous operations, ct_poll returns immediately, regardless of the value of milliseconds.