The callback function

A callback function is a user-defined HCL OneDB™ ESQL/C function that specifies actions to take during execution of an SQL request. This function must have the following declaration:

void callbackfunc(status)
mint status;

The integer status variable identifies at what point in the execution of the SQL request the callback function was called. Within the callback function, you can check this status variable to determine at which point the function was called. The following table summarizes the valid status values.

Table 1. Status values of a callback function

Point at which callback is called	Callback argument value
After the database server has completed the SQL request	0
Immediately after the application sends an SQL request to the database server	1
While the database server is processing an SQL request, after the timeout interval has elapsed	2

Within the callback function, you might want to check the value of the status argument to determine what actions the function takes.

The callback function, and any of its subroutines, can contain only the following HCL OneDB ESQL/C control functions:

• The sqldone() library function determines whether the database server is still busy.

  If sqldone() returns error -439, the database server is still busy and you can proceed with the interrupt.

• The sqlbreakcallback() library function disassociates the callback function from the timeout interval.
  Call sqlbreakcallback() with the following arguments:

  sqlbreakcallback(-1L, (void *)NULL);

  This step is not necessary if you want the callback function to remain for the duration of the current connection. When you close the current connection, you also disassociate the callback function.

• The sqlbreak() library function interrupts the execution of the database server.

If the application calls a callback function because a timeout interval has elapsed, the function can prompt the user for whether to continue or cancel the SQL request, as follows:

• To continue execution of the SQL request, the callback function skips the call to sqlbreak().

  While the callback function executes, the database server continues processing its SQL request. After the callback function completes, the application waits for another timeout interval before it calls the callback function again. During this interval, the database server continues execution of the SQL request.

• To cancel the SQL request, the callback function calls the sqlbreak() function, which sends an interrupt request to the database server.

  Execution of the callback function continues immediately after sqlbreak() sends the request. The application does not wait for the database server to respond until it completes execution of the callback function.

Use the sqlbreakcallback() function to set the timeout interval (in milliseconds) and to register a callback function, as follows:

sqlbreakcallback(timeout, callbackfunc_ptr);

This callbackfunc_ptr must point to a callback function that you already defined (see The callback function). Within the calling program, you must also declare this function, as follows:

void callbackfunc_ptr();