When an ODBC application program accesses HiRDB, the program can execute the ODBC functions asynchronously.

When ODBC functions are executed simultaneously, the ODBC driver does not return control to the application until function calling ends. However, when ODBC functions are executed asynchronously, the ODBC driver can return control to the application program at any time. The application program can therefore execute other processes when the ODBC functions are being executed asynchronously.

The following ODBC functions can be executed asynchronously:

• SQLColumnPrivileges
• SQLColumns
• SQLExecute
• SQLExecDirect
• SQLParamData
• SQLProcedureColumns
• SQLFetch
• SQLStatistics
• SQLTablePrivileges
• SQLTables
• SQLProcedures

To execute asynchronous ODBC functions:

1. To enable asynchronous execution in a specific hstmt (statement handle) only, use the SQL_ASYNC_ENABLE option to call SQLSetStmtOption.¹ To enable asynchronous execution in all hstmt handles related to hdbc (connection handle), use the SQL_ASYNC_ENABLE option to call SQLSetConnectOption.²
2. When an ODBC function that can be executed asynchronously¹ is called with an hstmt for which asynchronous execution has been enabled, the ODBC driver starts asynchronous execution of that function and returns SQL_STILL_EXECUTING. (If asynchronous execution is not set or if an error occurs, the ODBC driver returns a synchronous execution code, such as SQL_SUCCESS or SQL_ERROR.)
3. The application program can execute another process while an ODBC function is being executed asynchronously. An application program can call only the SQLAllocStmt, SQLCancel, and SQLGetFunctions with the hstmt that is executing the function asynchronously. If any other function is called (except the function being executed asynchronously), the driver manager returns a sequence error.
4. The application program calls the ODBC function that was being executed asynchronously to check whether execution of that function terminated. If the function is still executing, SQL_STILL_EXECUTING is returned. If the process has terminated, a return code such as SQL_SUCCESS or SQL_ERROR is returned.
   When an application program calls a function to check the execution status, all specified arguments, except hstmt, are ignored. (However, the specified argument values must be effective; otherwise, an error can occur if an incorrect address or value is specified.) For example, if SQLExecDirect is executed asynchronously with the INSERT statement function, and SQLExecDirect is called again, the execution status of the INSERT statement is returned, even if the UPDATE statement is specified.
   

Note

To disable asynchronous execution in a specific hstmt only, use the SQL_ASYNC_ENABLE option to call SQLSetStmtOption. To disable asynchronous execution in all hstmt handles related to hdbc, use the SQL_ASYNC_ENABLE option to call SQLSetConnectOption.

¹ The settings for SQLSetStmtOption are shown as follows.

Option	Setting
SQL_ASYNC_ENABLE	SQL_ASYNC_ENABLE_OFF or SQL_ASYNC_ENABLE_ON
SQL_BIND_TYPE	Cannot be set.
SQL_MAX_LENGTH	Limit specified by server or value specified by user
SQL_NOSCAN (Default=FALSE)	SQL_NOSCAN_OFF or SQL_NOSCAN_ON
SQL_QUERRY_TIMEOUT	Cannot be set.
SQL_MAX_ROWS	Limit specified by server or value specified by user

² The settings for SQLSetConnectOption are shown as follows.

Option	Setting
SQL_ACCESS_MODE	Fixed to SQL_MODE_READ_WRITE
SQL_AUTOCOMMIT	SQL_AUTOCOMMIT_OFF or SQL_AUTOCOMMIT_ON
SQL_LOGON_TIMEOUT	Cannot be set.
SQL_OPT_TRACE	Fixed to 0 (Off). This option is returned from the ODBC driver manager.
SQL_OPT_TRACEFILE	Fixed to NULL. This option is returned from the ODBC driver manager.
SQL_TRANSLATE_DLL	Cannot be set.
SQL_TRANSLATE_OPTION	Cannot be set.
SQL_TXN_ISOLATION	SQL_TXN_READ_UNCOMMITED
SQL_ASYNC_ENABLE	SQL_ASYNC_ENABLE_OFF or SQL_ASYNC_ENABLE_ON

(a) Cancelling asynchronous execution of an ODBC function

To cancel an ODBC function during asynchronous execution, call SQLCancel.

SQLCancel issues a process cancellation request to the server as soon as it confirms that the specified hstmt is currently undergoing asynchronous execution.

The return value for SQLCancel only reports whether the cancel request was completed. To find out whether asynchronous execution of the function was actually cancelled, call the function that was being processed asynchronously and check the return value. If the function is still executing, SQL_STILL_EXECUTING is returned. If cancel processing was completed, SQL_ERROR and SQLSTATE S1008 (process cancellation) are returned. If the function has already terminated normally, or if an error occurred, a code such as SQL_SUCCESS or SQL_ERROR is returned.

(b) Cancelling asynchronous execution in a multi-thread application program

A multi-thread application program can cancel an ODBC function that is being executed asynchronously with hstmt. To cancel the function, the application program calls SQLCancel from a different thread and uses the same hstmt as that used by the function being cancelled.

The return value of SQLCancel indicates whether the driver received the request correctly. The return values of the original function are SQL_SUCCESS, or SQL_ERROR and SQLSTATE S1008 (process cancellation).

Note

The HiRDB cancel process is executed for an individual connection, and the connection with the server is forcibly disconnected. (The server outputs KFPS00993-I: Server process termination REQUEST=clt_attention). Consequently, all statements of the hstmt handlers related to the specified hstmt are cancelled (the transaction is rolled back). Carefully consider any data being updated before cancelling an ODBC function that is being executed asynchronously.

The following is an example of coding for asynchronous execution:

SQLSetStmtOption(hstmst, SQL_ASYNC_ENABLE, SQL_ASYNC_ENABLE_ON);
         ...
 Retrieval processing with SQLFetch
rc=SQLFetch(hstmt);
while(rc==SQL_STILL_EXECUTING)
{
         ...
 Continue processing of UAP being executed asynchronously
         ...
  if(process cancel request was issued)
  {
        rc=SQL_Cancel(hstmt);
        if(rc==SQL_ERROR){ To error processing for cancel
                           request failure }
  }
 rc=SQLFetch(hstmt);
}
if(rc == SQL_ERROR){ To error processing }
 To retrieval data manipulation processing
       ...