Using SQL interruption

Interrupt long running SQL queries, or interrupt queries waiting for locked data.

If the database server supports SQL interruption, a program can interrupt a long running SQL statement.

SQL interruption is not enabled by default. Use the OPTIONS SQL INTERRUPT ON instruction to enable SQL interruption.

Note: The OPTIONS SQL INTERRUPT ON instruction must be used together with signal handling instructions DEFER INTERRUPT and DEFER QUIT, otherwise the program will stop immediately in case of an interruption event.
When the program receives an interruption event (either a SIGINT signal from the system, or an interrupt event from the front-end) and SQL interrupt is enabled with OPTIONS SQL INTERRUPT ON, the following happens:
  • The running SQL statement is stopped,
  • The INT_FLAG global variable is set to TRUE,
  • The SQLCA.SQLCODE is set with error -213.

SQL interruption results in abnormal SQL statement execution and raises a runtime error. Therefore, the SQL statement that can be interrupted must be protected by a WHENEVER ERROR exception handler or TRY/CATCH block.

MAIN
  DEFINE n INTEGER
  DEFER INTERRUPT
  OPTIONS SQL INTERRUPT ON
  DATABASE test1
  WHENEVER ERROR CONTINUE
  -- Start long query (self join takes time)
  -- From now on, user can hit CTRL-C in TUI mode to stop the query 
  SELECT COUNT(*) INTO n FROM customers a, customers b 
       WHERE a.cust_id <> b.cust_id 
  IF SQLCA.SQLCODE == -213 THEN
     DISPLAY "Statement was interrupted by user..."
     EXIT PROGRAM 1
  END IF
  WHENEVER ERROR STOP
  ...
END MAIN

When SQL interruption is supported by a database server type other than IBM® Informix®, the database drivers will return error -213 in case of interruption, to behave as in IBM Informix.

Important: Not all database servers support SQL interruption.
Table 1. Database server support of SQL interruption
Database Server Type SQL Interruption API SQL error code for interrupted query
IBM DB2® LUW (Since version 9.x) SQLCancel() Native error -952
IBM Informix sqlbreak() Native error -213
IBM Netezza® SQLCancel() Native error 46
Microsoft™ SQL Server (Only 2005+ with SNC driver) SQLCancel() SQLSTATE HY008
Oracle® MySQL KILL QUERY Native error -1317
Oracle Database Server OCIBreak() Native error -1013
PostgreSQL PQCancel() SQLSTATE 57014
SAP® ASE ct_cancel() SQLSTATE HY008
SAP HANA® SQLCancel() Native error -139
SQLite sqlite3_interrupt() Native error SQLITE_ABORT