Nonstop Database, HiRDB Version 9 UAP Development Guide
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:
To execute asynchronous ODBC functions:
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 |
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 |
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.
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).
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 ...
All Rights Reserved. Copyright (C) 2011, Hitachi, Ltd.