Managing transactions
C API

## Detailed Description

OCILIB supports local and global transactions.

Local transactions are implicit within connection objects and there is no specific call or programming step for using it.

In order to control changes made in the database:

- OCI_Commit() validates current pending modifications
- OCI_Rollback() discards current pending modifications

OCILIB supports a feature called 'Auto Commit' that performs an implicit and automatic commit call after every execute call

Note
  Those actions are executed within a connection context and not directly to a transaction.

Warning
  Global transactions are optional and are designed for distributed or global transaction environments.

OCILIB supports them by :

- Creating/Destroying explicitly a transaction object
- Starting/Stopping/Resuming explicitly the transaction
- Preparing the transaction for specific calls

## Functions

OCI_EXPORT boolean OCI_API | OCI_Commit (OCI_Connection *con)
| Commit current pending changes. More...
OCI_EXPORT boolean OCI_API | OCI_Rollback (OCI_Connection *con)
| Cancel current pending changes. More...
OCI_EXPORT boolean OCI_API | OCI_SetAutoCommit (OCI_Connection *con, boolean enable)
| Enable / disable auto commit mode. More...
OCI_EXPORT boolean OCI_API | OCI_GetAutoCommit (OCI_Connection *con)
| Get current auto commit mode status. More...
OCI_EXPORT OCI_Transaction *OCI_API | OCI_TransactionCreate (OCI_Connection *con, unsigned int timeout, unsigned int mode, OCI_XID *pxid)
| Create a new global transaction or a serializable/read-only local transaction. More...
OCI_EXPORT boolean OCI_API | OCI_TransactionFree (OCI_Transaction *trans)
| Free current transaction. More...
OCI_EXPORT boolean OCI_API | OCI_TransactionStart (OCI_Transaction *trans)
| Start global transaction. More...
OCI_EXPORT boolean OCI_API | OCI_TransactionStop (OCI_Transaction *trans)
| Stop current global transaction. More...
OCI_EXPORT boolean OCI_API | OCI_TransactionResume (OCI_Transaction *trans)
| Resume a stopped global transaction. More...
OCI_EXPORT boolean OCI_API | OCI_TransactionPrepare (OCI_Transaction *trans)
| Prepare a global transaction validation. More...
OCI_EXPORT boolean OCI_API | OCI_TransactionForget (OCI_Transaction *trans)
| Cancel the prepared global transaction validation. More...
OCI_EXPORT unsigned int OCI_API | OCI_TransactionGetMode (OCI_Transaction *trans)
| Return global transaction mode. More...
OCI_EXPORT unsigned int OCI_API | OCI_TransactionGetTimeout (OCI_Transaction *trans)
| Return global transaction Timeout. More...

## Function Documentation

## OCI_Commit()

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

`#include <ocilib.h>`

Commit current pending changes.

Parameters

  con | - Connection handle

Returns
  TRUE on success otherwise FALSE

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

## OCI_Rollback()

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

`#include <ocilib.h>`

Cancel current pending changes.

Parameters

  con | - Connection handle

Returns
  TRUE on success otherwise FALSE

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

## OCI_SetAutoCommit()

OCI_EXPORT boolean OCI_API OCI_SetAutoCommit | ( | OCI_Connection * | con,
|  | boolean | enable
| ) |  |

`#include <ocilib.h>`

Enable / disable auto commit mode.

The auto commit mode allows commit changes after every executed SQL order

Parameters

  con | - Connection handle
  enable | - Enable (TRUE) or disable (FALSE)

Returns
  TRUE on success otherwise FALSE

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

## OCI_GetAutoCommit()

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

`#include <ocilib.h>`

Get current auto commit mode status.

Parameters

  con | - Connection handle

Returns
  TRUE if auto commit mode is activated otherwise FALSE

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

## OCI_TransactionCreate()

OCI_EXPORT OCI_Transaction* OCI_API OCI_TransactionCreate | ( | OCI_Connection * | con,
|  | unsigned int | timeout,
|  | unsigned int | mode,
|  | OCI_XID * | pxid
| ) |  |

`#include <ocilib.h>`

Create a new global transaction or a serializable/read-only local transaction.

Parameters

  con | - Connection handle
  timeout | - Time that a transaction stays inactive after being stopped
  mode | - Transaction mode
  pxid | - pointer to a global transaction identifier structure

Note
  The parameter 'mode' can be one of the following values :

- Global transactions:
  - OCI_TRS_NEW : By default starts a new, tightly coupled and migratable branch.
  - OCI_TRS_TIGHT : explicitly specifies a tightly coupled branch
  - OCI_TRS_LOOSE : specifies a loosely coupled branch
- Global and local transactions :
  - OCI_TRS_READONLY - start a read-only transaction
  - OCI_TRS_READWRITE - start a read-write transaction
  - OCI_TRS_SERIALIZABLE : start a serializable transaction

Note
  For local transaction:
  - pass a NULL value for pxid

Referenced by ocilib::Transaction::Transaction().

## OCI_TransactionFree()

OCI_EXPORT boolean OCI_API OCI_TransactionFree | ( | OCI_Transaction * | trans | ) |

`#include <ocilib.h>`

Free current transaction.

Parameters

  trans | - Connection handle

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::Transaction::Transaction().

## OCI_TransactionStart()

OCI_EXPORT boolean OCI_API OCI_TransactionStart | ( | OCI_Transaction * | trans | ) |

`#include <ocilib.h>`

Start global transaction.

Parameters

  trans | - Connection handle

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::Transaction::Start().

## OCI_TransactionStop()

OCI_EXPORT boolean OCI_API OCI_TransactionStop | ( | OCI_Transaction * | trans | ) |

`#include <ocilib.h>`

Stop current global transaction.

Parameters

  trans | - Connection handle

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::Transaction::Stop().

## OCI_TransactionResume()

OCI_EXPORT boolean OCI_API OCI_TransactionResume | ( | OCI_Transaction * | trans | ) |

`#include <ocilib.h>`

Resume a stopped global transaction.

Parameters

  trans | - Global transaction handle

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::Transaction::Resume().

## OCI_TransactionPrepare()

OCI_EXPORT boolean OCI_API OCI_TransactionPrepare | ( | OCI_Transaction * | trans | ) |

`#include <ocilib.h>`

Prepare a global transaction validation.

Parameters

  trans | - Global transaction handle

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::Transaction::Prepare().

## OCI_TransactionForget()

OCI_EXPORT boolean OCI_API OCI_TransactionForget | ( | OCI_Transaction * | trans | ) |

`#include <ocilib.h>`

Cancel the prepared global transaction validation.

Parameters

  trans | - Global transaction handle

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::Transaction::Forget().

## OCI_TransactionGetMode()

OCI_EXPORT unsigned int OCI_API OCI_TransactionGetMode | ( | OCI_Transaction * | trans | ) |

`#include <ocilib.h>`

Return global transaction mode.

Note
  : see OCI_TransactionCreate() for possible values

Parameters

  trans | - Global transaction handle

Returns
  Transaction mode or OCI_UNKNOW if trans is NULL

Referenced by ocilib::Transaction::GetFlags().

## OCI_TransactionGetTimeout()

OCI_EXPORT unsigned int OCI_API OCI_TransactionGetTimeout | ( | OCI_Transaction * | trans | ) |

`#include <ocilib.h>`

Return global transaction Timeout.

Parameters

  trans | - Global transaction handle

Returns
  Transaction timeout or 0 if trans is NULL

Referenced by ocilib::Transaction::GetTimeout().