sqlora.h

一个很好用的Linux/Unix下Oracle OCI开发接口封装库

 *
 * @param dbh      I - A database handle
 * @param username I - The username for authentication, or a complete Oracle 
 *                     connect string.
 * @param password I - The password for authentication
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li> < 0 on error
 * </ul>
 *
 * @see sqlo_server_attach, sqlo_session_end
 * @since Version 2.2
 */
int sqlo_session_begin __P((sqlo_db_handle_t dbh, CONST char * username, CONST char * password));

/**
 * Detach from server.
 * 
 * Closes all open sessions and detaches from the server. 
 *
 *
 * @param dbh I - A database handle
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li> < 0 on error
 * </ul>
 *
 * @see sqlo_server_attach
 * @since Version 2.2
 */
int sqlo_server_detach __P((sqlo_db_handle_t dbh));

/**
 * End a session
 * 
 * Does a logout, but does not detach from the server. It is possible to create a
 * new session via @ref sqlo_session_begin.
 *
 * @attention Closing a session this way, means also to close all the cursors. 
 * Oracle is doing an implicit commit. This is maybe not be what you want.
 *
 * @param dbh I - A database handle
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li> < 0 on error
 * </ul>
 *
 * @see sqlo_session_begin
 * @since Version 2.2
 */
int sqlo_session_end __P((sqlo_db_handle_t dbh));


/**
 * Returns the tnsname
 *
 * Returns the tnsname (or service name) of the given dbh.
 * @attention The function returns the database name passed to 
 * @ref sqlo_connect or @ref sqlo_server_attach,
 * not the real SID, which can be different!
 *
 * @param dbh I - A database handle
 *
 * @return The tnsname or NULL in case of an invalid dbh
 */
CONST char * sqlo_getdatabase __P((sqlo_db_handle_t dbh ));

/** @} */

/**
 * @defgroup transactions Transaction control functions
 * @{
 */

/**
 * Commit
 * 
 * Execute a commit on this database.
 *
 * @param dbh I - A database handle.
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li> < 0 on error
 * </ul>
 *
 */
int sqlo_commit __P((sqlo_db_handle_t dbh));

/**
 * Rollback
 * 
 * Execute a rollback on this database.
 *
 * @param dbh I - A database handle.
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li> < 0 on error
 * </ul>
 *
 */
int sqlo_rollback __P((sqlo_db_handle_t dbh));
/** @} */

/**
 * @defgroup complex The advanced interface.
 *
 * This functions offer more flexibility in terms of
 * datatypes, but they need (much) more parameters.
 * Use these functions if you want to execute PL/SQL or stored procedures.
 *
 * @{
 */

/** 
 * Parse a statement
 *
 * This functions must be used to parse a statement if you want to bind manually
 * the parameters. By doing this you can use native datatypes.
 * This is the more complex form of @ref sqlo_open2.
 *
 * If the stmt is a SELECT statement, the function sets the attribute 
 * OCI_ATTR_PREFETCH rows to the max arraysize parameter of the library.
 * This is a kind of internal array fetch Oracle provides to speed up the fetching.
 *
 * @param dbh  I - A database handle
 * @param stmt I - sql statement.

 * @return <ul>
 * <li>A new statement handle
 * <li> < 0 on error.
 * </ul>
 *
 * @see sqlo_bind_by_name, sqlo_bind_by_pos, sqlo_define_by_pos, sqlo_open2.
 */
int sqlo_prepare __P((sqlo_db_handle_t dbh, CONST char * stmt));

/**
 * Bind a variable by name
 *
 * Use this to bind a variable in a query or a stored procedure call.
 *
 * If is_array is 1, the parameters param_addr and ind_addr must point to arrays.
 * ind_addr is optional and can be passed a NULL.
 * The param_size is still the size of one array element, not the whole array size!
 *
 * @param sth        I - The statement handle.
 * @param name       I - The bind parameter name.
 * @param param_type I - The datatype of the bind parameter (see @ref sqlo_data_types).
 * @param param_addr I - The address of a variable or array.
 * @param param_size I - The size of the object at param_addr in bytes.
 * @param ind_addr   I - The pointer to the NULL indicator variable (optional).
 * @param is_array   I - 1 means param_addr points to an array, 0 means a single variable.
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li> < 0 on error
 * </ul>
 *
 * @par Example:
 * @anchor ex9
 * @include ex9.c
 *
 * @see sqlo_prepare, sqlo_bind_by_pos, sqlo_define_by_pos
 */
int sqlo_bind_by_name __P((sqlo_stmt_handle_t sth, 
                           CONST char * name, 
                           int param_type, 
                           CONST void * param_addr, 
                           unsigned int param_size, 
                           short * ind_addr, 
                           int is_array));

/**
 * Bind a REF CURSOR
 *
 * Binds a ref cursor and returns a new sth, which you can use to retrieve
 * the data.
 * @note You can also use @ref sqlo_bind_by_name and supply as SQLOT_RSET as type
 * and the address of the new statement handle as param_addr. All other parameters
 * are ignored.
 *
 * @param sth         I - The statement handle
 * @param cursor_name I - The bind name of the cursor
 * @param sth2p       O - The new statement handle for the ref cursor.
 *
 * @par Example:
 * Example using sqlo_values to get the result:
 * @include ex17.c
 * Example using bind variables:
 * @include ex18.c
 */
int sqlo_bind_ref_cursor __P((sqlo_stmt_handle_t sth, CONST char * cursor_name, int * sth2p));

/**
 * Bind a variable by position
 *
 * If is_array is 1, the parameters param_addr and ind_addr must point to arrays.
 * ind_addr is optional and can be passed a NULL.
 * The param_size is still the size of one array element, not the whole array size!
 *
 * @param sth        I - The statement handle
 * @param position   I - The bind parameter position in the string. Starts with 
 *                       1 for the first.
 * @param param_type I - The datatype of the bind parameter (see @ref sqlo_data_types).
 * @param param_addr I - The pointer to the parameter data.
 * @param param_size I - The size of the object at param_addr in bytes.
 * @param ind_addr   I - The pointer to the NULL indicator variable (optional).
 * @param is_array   I - 1 means param_addr points to an array, 0 means a single variable.
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li> < 0 on error
 * </ul>
 *
 * @par Example:
 * @include ex10.c
 * @see sqlo_prepare, sqlo_bind_by_name, sqlo_define_by_pos
 */
int sqlo_bind_by_pos __P((sqlo_stmt_handle_t sth, 
                          int position, 
                          int param_type, 
                          CONST void * param_addr, 
                          unsigned int param_size, 
                          short * ind_addr, 
                          int is_array));

/**
 * Bind a variable by position
 *
 * Bind the input variables. This new version supports arrays of structures. Set
 * the skip_size to the size of the structure. rcode and ind must be part of
 * the structure.
 *
 * @param sth        I - The statement handle
 * @param position   I - The bind parameter position in the string. Starts with 
 *                       1 for the first.
 * @param param_type I - The datatype of the bind parameter (@ref sqlo_data_types).
 * @param param_addr I - The pointer to the parameter data.
 * @param param_size I - The size of the object at param_addr in bytes.
 * @param ind_addr   I - The pointer to the NULL indicator variable (optional).
 * @param rcode_addr I - The pointer to the variable that should return the column level
 * @param skip_size  I - In case into an array of structures, set to sizeof(your_struct),
 *                       otherwise set it to 0.
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li> < 0 on error
 * </ul>
 *
 * @see sqlo_prepare, sqlo_bind_by_name, sqlo_define_by_pos
 * @since Version 2.2
 */
int sqlo_bind_by_pos2 __P((sqlo_stmt_handle_t sth, 
                           int position, 
                           int param_type, 
                           CONST void * param_addr, 
                           unsigned int param_size, 
                           short * ind_addr,
                           unsigned short * rcode_addr, 
                           unsigned int skip_size));


/**
 * Define a output variable of the select list
 *
 * Use this to define the output variables.
 *
 * If is_array is 1, the parameters value_addr, rlen_addr and ind_addr must point to 
 * arrays.
 * ind_addr is optional and can be passed a NULL. Passing NULL is only usefull for
 * NOT NULL columns. If you ommit the indicator and a NULL is fetched, @ref sqlo_execute
 * will fail with an Oracle error (FETCHED COLUMN VALUE IS NULL).
 *
 * The value_size is still the size of one array element, not the whole array size!
 *
 * @param sth         I - The statement handle
 * @param value_pos   I - The bind parameter position in the string. Starts with 
 *                        1 for the first.
 * @param value_type  I - The datatype of the bind parameter (@ref sqlo_data_types).
 * @param value_addr  I - The pointer to the parameter data.
 * @param value_size  I - The size of the object at param_addr in bytes.
 * @param ind_addr    I - The pointer to the NULL indicator variable (optional).
 * @param rlen_addr   I - The pointer where @ref sqlo_execute writes the actual returned 
 *                        length.
 * @param is_array   I - 1 means param_addr points to an array, 0 means a single variable.
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li> < 0 on error
 * </ul>
 *
 * @par Example:
 * @include ex11.c
 *
 * @see sqlo_prepare, sqlo_bind_by_name, sqlo_define_by_pos
 */
int sqlo_define_by_pos __P((sqlo_stmt_handle_t sth, 
                            int value_pos, 
                            int value_type,
                            CONST void * value_addr,
                            unsigned int value_size,
                            short * ind_addr,
                            short * rlen_addr,
                            int is_array));

/**
 * Define a output variable of the select list
 *
 * Use this to define where the result of the query should go.
 * This new version supports filling arrays of structures.
 * If skip_size is not 0, the parameter value_addr must point to an array of structures.
 * If used, the structure must contain variables for ind, rlen and rcode.
 *
 * The value_size is still the size of one array element, not the whole array size!
 *
 * @param sth        I - The statement handle
 * @param value_pos  I - The bind parameter position in the string. 
 *                       Starts with 1 for the first.
 * @param value_type I - The datatype of the bind parameter (@ref sqlo_data_types).
 * @param value_addr I - The pointer to the parameter data.
 * @param value_size I - The size of the object at param_addr in bytes.
 * @param ind_addr   I - The pointer to the NULL indicator variable (optional).
 * @param rlen_addr  I - The pointer where library puts the actual return length.
 * @param rcode_addr I - The address where the library puts the return code for the column
 * @param skip_size  I - In case into an array of structures, set to sizeof(your_struct),
 *                       otherwise set it to 0.
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li> < 0 on error
 * </ul>
 *
 * @par Example:
 * @anchor ex12
 * This is an example of a fetch into an array of structure.
 * @include ex12.c
 *
 * @see sqlo_prepare, sqlo_bind_by_name, sqlo_define_by_pos, sqlo_execute
 * @since Version 2.2
 */
int sqlo_define_by_pos2 __P((sqlo_stmt_handle_t sth, 
                             int value_pos, 
                             int value_type,
                             CONST void * value_addr,
                             unsigned int value_size,
                             short * ind_addr,
                             unsigned short * rlen_addr,
                             unsigned short * rcode_addr,
                             unsigned int skip_size));

/**
 * Define a nested table
 * Please visit the example for details. 
 * @note You can also use @ref sqlo_define_by_pos with type == SQLOT_RSET
 * and passing the address of the new sth as value_addr and set all other
 * parameters to 0.
 *
 * @param sth         I - The statement handle
 * @param pos         I - The define position of the nested table
 * @param sth2p       O - The new statement handle for the nested table.
 * @par Examples:
 * @include ex19.c
 */
int sqlo_define_ntable __P((sqlo_stmt_handle_t sth, unsigned int pos, int * sth2p));


/**
 * Execute a statement
 * 
 * Execute a PL/SQL block or a statement after you prepared it with sqlo_prepare and bound input
 * and output variables.
 * If you are fetching into arrays, you can set iterations to the actual array
 * size. For PL/SQL blocks it must be set to 1.
 *
 * @param sth        I - A parsed statement handle
 * @param iterations I - How many times the statement should be exectuted. 
 *                       Must be 1 if you execute a PL/SQL block
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li>SQLO_NO_DATA
 * <li>SQLO_STILL_EXECUTING (non-blocking)
 * <li> < 0 on error
 * </ul>
 *
 * @see sqlo_prepare, sqlo_define_by_pos, sqlo_define_by_pos2, sqlo_bind_by_name
 */
int sqlo_execute __P((sqlo_stmt_handle_t sth, unsigned int iterations));

/** @} */

/**
 * @defgroup lob Functions to insert/select LOBs
 *
 * @{
 */

/**
 * Allocate a lob descriptor
 *
 * @param dbh    I - A database handle
 * @param loblpp O - The lob locator
 *
 * @return SQLO_SUCCESS or < 0 on error
 * @since Version 2.2
 */
int sqlo_alloc_lob_desc __P((sqlo_db_handle_t dbh, sqlo_lob_desc_t *loblpp));

/**
 * Free a lob descriptor
 *
 * Frees the descriptor and sets *loblp to NULL.
 *
 * @param dbh    I - A database handle
 * @param loblpp I/O - A address where we find the lob locator.
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li> < 0 on error
 * </ul>
 * @since Version 2.2
 */
int sqlo_free_lob_desc __P((sqlo_db_handle_t dbh, sqlo_lob_desc_t *loblpp));

/**
 * Write lob data from buffer into the lob column
 *
 * @param dbh     I - A database handle.
 * @param loblen  I - The length of the lob.
 * @param loblp   I - A lob locator.
 * @param bufp    I - A buffer of data.
 * @param bufl    I - The length of the buffer in terms of bytes.
 * @param piece   I - The piece indicator
 *                    <ul>
 *                    <li>SQLO_ONE_PIECE
 *                    <li>SQLO_FIRST_PIECE
 *                    <li>SQLO_NEXT_PIECE
 *                    <li>SQLO_LAST_PIECE
 *                    </ul>
 *
 * @return <ul>
 *         <li>SQLO_SUCCESS
 *         <li>SQLO_STILL_EXECUTING
 *         <li>SQLO_ERROR