Aborting long operations

## Detailed Description

The Oracle OCI provides the ability to establish a server connection in :

- blocking mode: each call to an OCI function returns control to the application when the call completes
- non-blocking mode (based on polling paradigm) : the application have to call each function until its has completed its job

OCILIB implements OCI in blocking mode. The application has to wait for OCI calls to complete to continue.

Some operations can be long to be processed by the server.

In order to cancel the current pending call, OCILIB provides OCI_Break() that cancel the last internal OCI Call and then raise an OCI abortion error code.

Note
  Any call to OCI_Break() has to be done from a separate thread because the thread that has executed a long OCI call is waiting for its OCI call to complete.

Example
  #include "ocilib.h"
  #if defined(_WINDOWS)
  #define sleep(x) Sleep(x*1000)
  #else
  #include <unistd.h>
  #endif
  void long_oracle_call(OCI_Thread *thread, void *data)
  {
  clock_t t_start = clock();
  int err_code = 0;
  if (!OCI_ExecuteStmt((OCI_Statement *)data, "begin dbms_lock.sleep(10); end;"))
  {
  OCI_Error *err = OCI_GetLastError();
  if (err)
  {
  err_code = OCI_ErrorGetOCICode(err);
  }
  }
  printf("call duration %d, expected oracle error is 1013, got %d", clock() - t_start, err_code);
  }
  int main(void)
  {
  OCI_Connection *cn;
  OCI_Statement *st;
  OCI_Thread *th;
  if (!OCI_Initialize(NULL, NULL, OCI_ENV_THREADED | OCI_ENV_CONTEXT))
  {
  return EXIT_FAILURE;
  }
  th = OCI_ThreadCreate();
  cn = OCI_ConnectionCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT);
  st = OCI_StatementCreate(cn);
  OCI_ThreadRun(th, long_oracle_call, st);
  sleep(1);
  OCI_Break(cn);
  OCI_ThreadJoin(th);
  OCI_ThreadFree(th);
  OCI_StatementFree(st);
  OCI_ConnectionFree(cn);
  OCI_Cleanup();
  return EXIT_SUCCESS;
  }

## Functions

OCI_EXPORT boolean OCI_API | OCI_Break (OCI_Connection *con)
| Perform an immediate abort of any currently Oracle OCI call. More...

## Function Documentation

## OCI_Break()

OCI_EXPORT boolean OCI_API OCI_Break | ( | OCI_Connection * | con | ) |

`#include <ocilib.h>`

Perform an immediate abort of any currently Oracle OCI call.

Parameters

  con | - connection handle

Note
  The current call will abort and generate an error

Returns
  Returns FALSE if connection handle is NULL otherwise TRUE

Referenced by ocilib::Connection::Break().