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:

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.

See also

“Asynchronous programming”, “Callbacks”, ct_callback, ct_wakeup