The sqlbreakcallback() function

The sqlbreakcallback() function allows you to specify a timeout interval and to register a callback function. The callback function provides a method for the application to regain control when the database server is processing an SQL request.

Restriction: Do not use the sqlbreakcallback() function if your Informix® ESQL/C application uses shared memory (onipcshm) as the nettype to connect to the HCL Informix® database server. Shared memory is not a true network protocol and does not handle the nonblocking I/O that is needed to support a callback function. When you use sqlbreakcallback() with shared memory, the call appears to register the callback function successfully (it returns zero); however, during SQL requests, the application never calls the callback function.

Syntax

mint sqlbreakcallback(timeout, callbackfunc_ptr);
   int4 timeout;
   void (* callbackfunc_ptr)(int status);

timeout

The interval of time to wait for an SQL request to execute before the application process regains control.

This value can be as follows:

-1: Clears the timeout value.
0: Immediately calls the function that callbackfunc_ptr indicates.
>0: Sets the timeout interval to the number of milliseconds to elapse before the application calls the function that callbackfunc_ptr indicates.

The timeout parameter is a 4-byte variable. This parameter is operating-system dependent: it can be a variable with an int, long, or short data type.

callbackfunc_ptr

A pointer to the user-defined callback function.

Usage

After you register a callback function with sqlbreakcallback(), the application calls this function at three different points in the execution of an SQL request. The value in the status argument of the callback function indicates the point at which the application calls the function. The following table summarizes the status values.


When callback function is called	Value of status argument
When the database server begins processing an SQL request	status = 1
While the database server executes an SQL request, when the timeout interval has elapsed	status = 2
When the database server completes the processing of an SQL request	status = 0

When you call the callback function with a status value of 2, the callback function can determine whether the database server can continue processing with one of following actions:

It can call the sqlbreak() function to cancel the SQL request.
It can omit the call to sqlbreak() to continue the SQL request.

The callback function, and any of its subroutines, can contain only the following Informix® ESQL/C control functions: sqldone(), sqlbreak(), and sqlbreakcallback(). For more information about the callback function, see The timeout interval.

If you call sqlbreakcallback() with a timeout value of zero, the callback function executes immediately. The callback function executes over and over again unless it contains a call to sqlbreakcallback() to redefine the callback function with one of the following actions:

It disassociates the callback function to discontinue the calling of the callback function, as follows:
```
sqlbreakcallback(-1L, (void *)NULL);
```
It defines some other callback function or resets the timeout value to a nonzero value, as follows:
```
sqlbreakcallback(timeout, callbackfunc_ptr);
```

Important: Small timeout values might adversely affect the performance of your application.

For more information about the timeout interval, see The timeout interval.

You must establish a database server connection before you call the sqlbreakcallback() function. The callback function remains in effect for the duration of the connection or until the sqlbreakcallback() function redefines the callback function.

Return codes

0: The call to sqlbreakcallback() was successful.
<0: The call to sqlbreakcallback() was not successful.