ocilib.h

ORACLE编程的好东西,纯C写的OCI封装.很好用,支持数据池.

 * TRUE on success otherwise FALSE
 *
 */

OCI_EXPORT boolean OCI_API OCI_Commit
(
    OCI_Connection *con
);

/**
 * @brief 
 * Cancel current pending changes
 *
 * @param con - Connection handle
 * 
 * @return 
 * TRUE on success otherwise FALSE
 *
 */

OCI_EXPORT boolean OCI_API OCI_Rollback
(
    OCI_Connection *con
);

/**
 * @brief 
 * Enable / disable auto commit mode
 *
 * The auto commit mode allows commit changes after every executed SQL order 
 *
 * @param con    - Connection handle
 * @param enable - Enable (TRUE) or disable (FALSE)
 * 
 * @return 
 * TRUE on success otherwise FALSE
 *
 */

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

/**
 * @brief 
 * Get current auto commit mode status
 *
 * @param con - Connection handle
 * 
 * @return 
 * TRUE if auto commit mode is activated otherwise FALSE
 *
 */

OCI_EXPORT boolean OCI_API OCI_GetAutoCommit
(
    OCI_Connection *con
);

/**
 * @brief 
 * Create a new global transaction or a serializable/read-only local transaction
 *
 * @param con     - Connection handle
 * @param timeout - Time that a transaction stays inactive after being stopped
 * @param mode    - Connection mode
 * @param pxid    - pointer to a global transaction identifier stucture
 *
 *
 * @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
 *
 */

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

/**
 * @brief 
 * Free current transaction
 *
 * @param trans - Connection handle
 * 
 * @return 
 * TRUE on success otherwise FALSE
 *
 */

OCI_EXPORT boolean OCI_API OCI_TransactionFree
(
    OCI_Transaction * trans
);

/**
 * @brief 
 * Start global transaction
 *
 * @param trans - Connection handle
 * 
 * @return 
 * TRUE on success otherwise FALSE
 *
 */

OCI_EXPORT boolean OCI_API OCI_TransactionStart
(
    OCI_Transaction * trans
);

/**
 * @brief 
 * Stop current global transaction
 *
 * @param trans - Connection handle
 * 
 * @return 
 * TRUE on success otherwise FALSE
 *
 */

OCI_EXPORT boolean OCI_API OCI_TransactionStop
(
    OCI_Transaction * trans
);

/**
 * @brief 
 * Resume a stoppped global transaction
 *
 * @param trans - Global transaction handle
 * 
 * @return 
 * TRUE on success otherwise FALSE
 */

OCI_EXPORT boolean OCI_API OCI_TransactionResume
(
    OCI_Transaction * trans
);

/**
 * @brief 
 * Prepare a global transaction validation
 *
 * @param trans - Global transaction handle
 * 
 * @return 
 * TRUE on success otherwise FALSE
 *
 */

OCI_EXPORT boolean OCI_API OCI_TransactionPrepare
(
    OCI_Transaction * trans
);

/**
 * @brief 
 * Cancel the prepared global transaction validation
 *
 * @param trans - Global transaction handle
 * 
 * @return 
 * TRUE on success otherwise FALSE
 *
 */

OCI_EXPORT boolean OCI_API OCI_TransactionForget
(
    OCI_Transaction * trans
);

/**
 * @brief 
 * Return global transaction mode.
 *
 * @note:
 * see OCI_TransactionCreate() for possible values
 *
 * @param trans - Global transaction handle
 *
 * @return
 * Transaction mode or OCI_UNKNOW if trans is NULL
 *
 */

OCI_EXPORT unsigned int OCI_API OCI_TransactionGetMode
(
    OCI_Transaction * trans
);

/**
 * @brief 
 * Return global transaction Timeout
 *
 * @param trans - Global transaction handle
 *
 * @return
 * Transaction timeout or 0 if trans is NULL
 *
 */

OCI_EXPORT unsigned int OCI_API OCI_TransactionGetTimeout
(
    OCI_Transaction * trans
);

/**
 * @}
 */

/**
 * @defgroup g_exec Executing statements
 * @{
 *
 * Executing SQL statements or PL/SQL blocks is really simple with OCILIB.
 *
 * First, call OCI_StatementCreate() to allocate a statement handle. Then :
 *
 * - Parse the SQL with OCI_Prepare()
 * - Execute it with OCI_Execute()
 *
 * These two steps can be done together by calling OCI_ExecuteStmt() that 
 * parses and executes in one go.
 * 
 * To find out if the statement has affected any rows, call OCI_GetAffectedRows()
 * 
 * Finally, release the statement and its resources with OCI_StatementFree()
 *
 * @note
 * A statement can be parsed once and executed as many times as needed (see 
 * Binding variables section)
 *
 * @note
 * A OCI_Statement can be used to prepare and/or execute different SQL and PL/SQL 
 * statements as many times as needed.
 * for example, if the SQL processsing of an application is sequential, only
 * one statement handle is required
 *
 * @note
 * OCILIB supports nested levels of SQL statement processing. 
 * An application can loop through the resultset of the statement handle A,
 * executing statement B and fetching statement C at every loop, and so on ...
 *
 * @par Example
 * @include exec.c
 *
 */

/**
 * @brief 
 * Create a statement object and return its handle
 *
 * @param con - Connection handle
 * 
 * @return 
 * A statement handle on success otherwise NULL
 *
 */

OCI_EXPORT OCI_Statement * OCI_API OCI_StatementCreate
(
    OCI_Connection *con
);

/**
 * @brief 
 * Free a statement and all resources associated to it (resultsets, ....)
 *
 * @param stmt - Connection handle
 * 
 * @return 
 * TRUE on success otherwise FALSE
 *
 */

OCI_EXPORT boolean OCI_API OCI_StatementFree
(
    OCI_Statement *stmt
);

/**
 * @brief 
 * Prepare a SQL statement or PL/SQL block.
 *
 * @param stmt - Statement handle
 * @param sql  - SQL order or PL/SQL block
 * 
 * @note
 * With version 1.3.0 and above, do not call this function for fetched
 * statement handle (REF cursors)
 *
 * @return 
 * TRUE on success otherwise FALSE
 */

OCI_EXPORT boolean OCI_API OCI_Prepare
(
    OCI_Statement *stmt, 
    const mtext *sql
);

/**
 * @brief 
 * Execute a prepared SQL statement or PL/SQL block.
 *
 * @param stmt - Statement handle
 *
 * @return 
 * TRUE on success otherwise FALSE
 */

OCI_EXPORT boolean OCI_API OCI_Execute
(
    OCI_Statement *stmt
);

/**
 * @brief 
 * Parse and execute a SQL statement or PL/SQL block.
 *
 * @param stmt - Statement handle
 * @param sql  - SQL order - PL/SQL block
 *
 * @return 
 * TRUE on success otherwise FALSE
 */

OCI_EXPORT boolean OCI_API OCI_ExecuteStmt
(
    OCI_Statement *stmt, 
    const mtext *sql
);

/**
 * @brief 
 * Return the last SQL or PL/SQL statement parsed by the statement
 *
 * @param stmt - Statement handle
 * 
 */

OCI_EXPORT const mtext * OCI_API OCI_GetSql
(
    OCI_Statement *stmt
);

/**
 * @brief 
 * Return the error position in the SQL statement where the error occured in 
 * case of SQL parsing error
 *
 * @param stmt - Statement handle
 *
 * @note
 * Positions start at 1.
 * 
 */

OCI_EXPORT unsigned int OCI_API OCI_GetSqlErrorPos
(
    OCI_Statement *stmt
);


/**
 * @brief 
 * Return the number of rows affected by the SQL statement
 *
 * @param stmt - Statement handle
 *
 * The returned value is :
 *
 *  - For UPDATEs : number of rows updated 
 *  - For INSERTs : number of rows inserted 
 *  - For DELETEs : number of rows deleted 
 * 
 * @note
 * For SELECTs  statement, use OCI_GetRowCount() instead
 *
 */

OCI_EXPORT unsigned int OCI_API OCI_GetAffectedRows
(
    OCI_Statement *stmt
);

/**
 * @}
 */

/**
 * @defgroup g_bind Binding variables and arrays
 * @{
 *
 * OCILIB supports OCI data binding APIs
 *
 * Programs variables can be binded to an Oracle SQL PL/SQL statement in order to :
 * 
 * - Provide input data for SQL statement
 * - Provide input/outpout data for PL/SQL blocks
 * 
 * OCILIB provides a set of binding functions to use with :
 *
 * - Basic datatypes  : string (char/wchar_t *), int, double, raw
 * - Object datatypes : lobs, files,longs, dates, cursors, statements,
 *                      timestamps, intervals, objects
 *
 * To use binding :
 * 
 * - Prepare a statement with OCI_Prepare() (see Executing statements)
 * - Bind variables by calling one if the OCI_Bindxxxxx() function for every 
 *   input variable referenced by the SQL statement
 * - Setup up values of the program variables
 * - Call OCI_Execute() as many times as needed 
 * - Each OCI_Execute() call may be preceeded by an update of the program
 *   variables (for INSERTs for example) 
 *
 * OCILIB supports the OCI array Interface by binding arrays of C scalar types
 * and OCILIB object types.
 *
 * - all types supported the library can be used for array binding except 
 *   OCI_Statement and OCI_Long
 * - Array binding is really fast for massive DML operations
 * - For string/RAW arrays, the input array MUST BE a contiguous block of data 
 *   and not an array of pointers. So to bind an array of 10 elements for a 
 *   varchar2(30) column, binded variable must be a like array[10][31]
 *
 * OCILIB does not pre-parse statements (like other frameworks such as jdbc, ...)
 * and lets Oracle recognize input variables embedded within the SQL statements. 
 * 
 * Bind variables must be precedeed in the SQL code by the character ':'.
 *
 * Oracle and OCILIB supports two ways of binding :
 * 
 * - by name (default mode in OCILIB) : Oracle looks for variables in the SQL
 *   statement  by searching their names provided to the binding function.
 *   So a variable can be binded once and used many times in the statement
 * - by position : Oracle binds variables by position, so every variable is 
 *   binded with a position number
 *
 * OCILIB Default binding mode is OCI_BIND_BY_NAME.
 * 
 * When using binding by position, provide the position to OCI_BindXXXX() call
 * throught the name parameter. Within this mode the bind name must be the 
 * position preceeded by a semicolon like ':1', ':2', ....
 *
 * @par Basic input bind Example
 * @include bind.c
 *
 * @par Array interface Example
 * @include array.c
 *
 */

/**
 * @brief 
 * Set the input array size for bulk operations
 *
 * @param stmt - Statement handle
 * @param size - Array size
 * 
 * @warning
 * Do not use OCI_BindArraySetSize() for PL/SQL tables binding
 *
 * @return 
 * TRUE on success otherwise FALSE
 */

OCI_EXPORT boolean OCI_API OCI_BindArraySetSize
(
    OCI_Statement *stmt, 
    unsigned int size
);

/**
 * @brief 
 * Return the input array size for bulk operations
 *
 * @param stmt - Statement handle
 *
 * @return 
 * Array size value or 0 if OCI_BindArraySetSize() has not been called
 *
 */

OCI_EXPORT unsigned int OCI_API OCI_BindArrayGetSize
(
    OCI_Statement *stmt
);

/**
 * @brief 
 * Bind an short variable
 *
 * @param stmt - Statement handle
 * @param name - Variable name
 * @param data - Pointer to short variable
 * 
 * @return 
 * TRUE on success otherwise FALSE
 */

OCI_EXPORT boolean OCI_API OCI_BindShort
(
    OCI_Statement *stmt, 
    const mtext *name,
    short *data
);

/**
 * @brief 
 * Bind an array of shorts
 *
 * @param stmt   - Statement handle
 * @param name   - Variable name
 * @param data   - Array of shorts
 * @param nbelem - Number of element in the array
 * 
 * @return 
 * TRUE on success otherwise FALSE
 */

OCI_EXPORT boolean OCI_API OCI_BindArrayOfShorts
(
    OCI_Statement *stmt, 
    const mtext *name,
    short *data,
    un