INFORMIX-ESQL/C Programmer's Manual ESQL/C Function Library

The sqlbreakcallback() function allows you to specify a time-out 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.

Warning: Do not use the sqlbreakcallback() function if your ESQL/C application uses shared memory (olipcshm) as the nettype to connect to an Universal Server database server. Shared memory is not a true network protocol and does not handle the non-blocking 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

is 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 time-out value.




immediately calls the function that callbackfunc_ptr indicates.




 >0  

sets the time-out 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  

is a pointer to the user-defined callback function.

Once 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 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 ESQL/C control functions: sqldone(), sqlbreak(), and sqlbreakcallback(). For more information about the callback function, see page 12-38.

If you call sqlbreakcallback() with a time-out value of zero (0), 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 time-out value to a nonzero value, as follows:
sqlbreakcallback(timeout, callbackfunc_ptr);

Important: Small time-out values might adversely affect the performance of your application.

For more information about the time-out interval, see page 12-38.

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.