The sqlbreak() function

The sqlbreak() function sends the database server a request to interrupt processing of the current SQL request. You generally call this function to interrupt long queries.

Syntax

mint sqlbreak();

Usage

The sqlbreak() function sends the interrupt request to the database server of the current connection. When the database server receives this request, it must determine if the SQL request is interruptible. Some types of database operations are not interruptible and others cannot be interrupted at certain points. You can interrupt the following SQL statements.
  • ALTER INDEX
  • ALTER TABLE
  • CREATE INDEX
  • CREATE TABLE
  • DELETE
  • EXECUTE PROCEDURE
  • INSERT
  • OPEN
  • SELECT
  • UPDATE
If the SQL request can be interrupted, the database server takes the following actions:
  1. Discontinues execution of the current SQL request
  2. Sets SQLCODE (sqlca.sqlcode) to a negative value (-213)
  3. Returns control to the application

When the application regains control after an interrupted SQL request, any resources that are allocated to the SQL statement remain allocated. Any open databases, cursors, and transactions remain open. Any system-descriptor areas or sqlda structures remain allocated. The application program is responsible for the graceful termination of the program; it must release resources and roll back the current transaction.

While the database server executes an SQL request, the application is blocked, waiting for results from the database server. To call sqlbreak(), you must first set up some mechanism to unblock the application process. Two possible methods follow:
  • Provide the application user with the ability to interrupt an SQL request once it has begun execution.

    When the user presses the Interrupt key, the application becomes unblocked and calls the SIGINT signal-handler function. This signal-handler function includes a call to sqlbreak() to interrupt the database server. For more information, see Allow a user to interrupt.

  • Specify a timeout interval with the sqlbreakcallback() function.

    After the timeout interval elapses, the application becomes unblocked and calls the callback function. This callback function includes a call to sqlbreak() to interrupt the database server. For more information, see Set up a timeout interval.

Before your program calls sqlbreak(), verify with the sqldone() function that the database server is currently processing an SQL request.

Return codes

0
The call to sqlbreak() was successful. The database server connection exists and either a request to interrupt was sent successfully or the database server was idle.
!=0
No database server is running (no database connection exists) when you called sqlbreak().