sqlora.h

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

 *         </ul>
 * @since Version 2.2
 * @par Example:
 * @include ex13.c
 */
int sqlo_lob_write_buffer __P((sqlo_db_handle_t dbh, sqlo_lob_desc_t loblp, unsigned int loblen, 
                               void *bufp, unsigned int bufl, unsigned int piece));
/**
 * Append lob data from buffer to 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 (always when OCILobWriteAppend is not available in your Oracle version)
 *         </ul>
 * @since Version 2.2 and Oracle version >= 8.1
 * @par Example:
 * @include ex13.c
 */
int sqlo_lob_append_buffer __P((sqlo_db_handle_t dbh, sqlo_lob_desc_t loblp, 
                                unsigned int loblen, 
                                void *bufp, unsigned int bufl, 
                                unsigned int piece));

/**
 * Write lob data from a file into the lob column. This function reads the 
 * data from the stream and writes it into the lob column via 
 * @ref sqlo_lob_write_buffer.
 *
 * @attention The function does not close or rewind the fp.
 *
 * @param dbh     I - A database handle.
 * @param loblp   I - A lob locator.
 * @param filelen I - The size of the file (total lob length)
 * @param fp      I - The filepointer
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li>SQLO_ERROR
 * </ul>
 * @since Version 2.2
 * @par Example:
 * @include ex14.c
 *
 * @see sqlo_lob_write_buffer
 */
int sqlo_lob_write_stream __P((sqlo_db_handle_t dbh, sqlo_lob_desc_t loblp, unsigned int filelen, FILE * fp));


/**
 * Get the length of a lob
 *
 * @param dbh      I - Database handle
 * @param loblp    I - A lob descriptor
 * @param loblenp  O - The length of the lob
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li>SQLO_STILL_EXECUTING
 * <li>SQLO_ERROR
 * </ul>
 */
int sqlo_lob_get_length __P((sqlo_db_handle_t dbh, sqlo_lob_desc_t loblp, unsigned int * loblenp));

/**
 * Read lob data from lob column into a buffer
 *
 * Reads data from the lob and writes it into the supplied buffer.
 *
 * Use @ref sqlo_lob_get_length to get the loblen you have to use here.
 *
 * @param dbh     I - A database handle.
 * @param loblp   I - A lob locator.
 * @param loblen  I - The length of the lob
 * @param bufp    O - The output data.
 * @param bufl    I - The capacity of the buffer in terms of bytes.
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li>SQLO_NEED_DATA
 * <li>SQLO_STILL_EXECUTING
 * <li>SQLO_ERROR
 * </ul>
 *
 * @since Version 2.2
 * @par Example:
 * @include ex15.c
 */
int sqlo_lob_read_buffer __P((sqlo_db_handle_t dbh, sqlo_lob_desc_t loblp, unsigned int loblen, void *bufp, unsigned int bufl));


/**
 * Read lob data from lob column into a stream
 *
 * Use @ref sqlo_lob_get_length to get the loblen you have to use here.
 *
 * @param dbh     I - A database handle.
 * @param loblp   I - A lob locator.
 * @param loblen  I - The length of the lob
 * @param fp      I - A filepointer
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li>SQLO_STILL_EXECUTING
 * <li>SQLO_ERROR
 * </ul>
 * @since Version 2.2
 *
 * @par Example:
 * @include ex16.c
 *
 * @see sqlo_lob_read_buffer
 */
int sqlo_lob_read_stream __P((sqlo_db_handle_t dbh, sqlo_lob_desc_t loblp, unsigned int loblen, 
                              FILE *fp));
/** @} */

/** 
 * @defgroup misc Miscellaneous functions
 * @{
 */
/**
 * Get the specified OCI handle
 * 
 * You can get the oci handles here, if you want to call other OCI functions.
 *
 * @param sqloh I - Either a statement or a database handle depending on the handle type
 *                  you want to get.
 * @param ocihp O - The requested OCI handle.
 * @param type  I - The OCI handle type (see @ref sqlo_oci_handle_types_e)
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li> < 0 on error
 * </ul>
 *
 * @see sqlo_oci_handle_types_e
 */
int sqlo_get_oci_handle __P((int sqloh, void * ocihp, sqlo_oci_handle_types_e type));

/**
 * Return the database handle of a statement handle.
 * 
 * @param sth  I - A statement handle
 * @return <ul>
 * <li>The database handle
 * <li> < 0 on error
 * </ul>
 */
int sqlo_get_db_handle __P((sqlo_stmt_handle_t sth));


/**
 * Set OCI blocking mode on/off.
 *
 * By default a database connection is in blocking mode. This means
 * the call does not return until the task is finished. With this
 * function you can change to non-blocking mode. 
 * In this case some functions can return SQLO_STILL_EXECUTING.
 *
 * The functions are:
 * <ul>
 * <li>sqlo_open2 (when called for queries)
 * <li>sqlo_reopen (when called for queries)
 * <li>sqlo_fetch (when called for non-queries)
 * <li>sqlo_exec
 * <li>sqlo_execute
 * </ul>
 * @param dbh I - A database handle where the blocking should be changed.
 * @param on  I - SQLO_ON switches blocking mode on, SQLO_OFF switches to 
 *                non-blocking mode
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li>SQLO_INVALID_DB_HANDLE
 * <li> < 0 on error
 * </ul>
 * @since Version 2.2
 */
int sqlo_set_blocking __P((sqlo_db_handle_t dbh, unsigned int on));


/**
 * Get OCI blocking mode
 *
 * Returns the the blocking mode.
 *
 * @param dbh      I - A database handle
 * @param blocking O - SQL_ON if in blocking mode (database default), or SQLO_OFF if
 *                     in non-blocking mode.
 * @return SQLO_SUCCESS or OCI status code.
 * @since Version 2.2
 */
int sqlo_get_blocking __P((sqlo_db_handle_t dbh, unsigned int * blocking));


/**
 * Abort all operations in non-blocking mode
 *
 * This call performs an immediate (asynchronous) abort of any 
 * currently executing OCI function that is associated with a connection.
 *
 * If the connection is in blocking mode, SQLO_SUCCESS is returned without
 * doing an abort.
 *
 * The cursor in "SQLO_STILL_EXECUTING" status is closed.
 *
 * @param dbh A database handle
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li>SQLO_ERROR
 * <li>SQLO_INVALID_DB_HANDLE
 * </ul>
 * @since Version 2.2
 */
int sqlo_break __P((sqlo_db_handle_t dbh));


/**
 * Set the prefetch row attribute for a statement.
 * This functions sets the oci attribute OCI_ATTR_PREFETCH_ROWS to the
 * given value. 
 * @note This does not affect the global setting passed by the enviroment
 * variable SQLORA_PREFETCH_ROWS.
 * @param sth    I - The statement handle
 * @param nrows  I - The value of the attribute.
 * @return SQLO_SUCCESS or < 0 on error
 * @since Version 2.2
 */
int sqlo_set_prefetch_rows __P((sqlo_stmt_handle_t sth, unsigned int nrows));


/**
 * Get the server version string.
 *
 * Returns the server version string which might look like this:
 @verbatim
   Oracle8i Enterprise Edition Release 8.1.5.0.0 - Production
   With the Partitioning and Java options
   PL/SQL Release 8.1.5.0.0 - Production.
  @endverbatim
    The buffer is null terminated.
  * @param dbh    I - The database handle
  * @param bufp   O - The version string
  * @param buflen I - Supply her the capacity of your buffer.
 * @return SQLO_SUCCESS or < 0 on error.
 * @since Version 2.2
 */
int sqlo_server_version __P((sqlo_db_handle_t dbh, char *bufp, unsigned int buflen));

/**
 * Get the state of the statement
 * @note Don't use this in Oracle versions < 9.0! 
 * @param sth I - A statement handle
 * @return The state (see @sqlo_statement_states) or < 0 n error.
 * @since Version 2.2
 */ 
int sqlo_get_stmt_state __P((sqlo_stmt_handle_t sth));

/**
 * Get the sql statement text for the statement handle
 * @param sth  I - A statement handle
 * @return The sql text.
 * @since Version 2.2
 */
CONST char * sqlo_get_stmt __P((sqlo_stmt_handle_t sth));

/**
 * Get the datatype of a column in the select list
 * @param sth I - The statement handle
 * @param pos I - The column position (1 based).
 * @return <ul>
 * <li>The datatype (see @ref sqlo_data_types)
 * <li>SQLO_INVALID_STMT_HANDLE
 * <li>SQLO_INVALID_COLPOS
 * </ul>
 * @since Version 2.2
 */
int sqlo_get_ocol_dtype __P((sqlo_stmt_handle_t sth, unsigned int pos));


/**
 * Switches Oracle trace on/off
 *
 * Use this to switch the Oracle trace facility (tkprof) on or off.
 *
 * @param dbh I - A database handle
 * @param on  I - A flag indicating if we switch tracing on (SQLO_ON) or off (SQLO_OFF)
 *
 * @return <ul>
 * <li> SQLO_SUCCESS
 * <li> < 0 on error
 * </ul>
 */
int sqlo_trace __P((sqlo_db_handle_t dbh, int on ));


/**
 * Print info about the statement to stdout
 *
 * @deprecated  This function will not be enhanced or maintained. This is a kind
 * of debuging code, but better use the builtin trace facility.
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li> < 0 on error
 * </ul>
 * @param sth A statement handle
*/
int sqlo_print __P(( sqlo_stmt_handle_t sth ));

/**
 * Register a signal handler for interrupts.
 * Because oracle catches SIGINT, you can register here a handler, which is called by
 * oracle, when SIGINT is catched.
 * @note Don't do any database operation in this handler.
 * @param handle O - The created handle. Needed by @ref sqlo_clear_int_handler to 
 *                   clear a signal handler
 * @param signal_handler I - The address of the signal handler to register.
 *
 * @return SQLO_SUCCESS or SQLO_ERROR on error.
 */
int sqlo_register_int_handler __P((int * handle, sqlo_signal_handler_t signal_handler));

/**
 * Clear an interrupt handler
 * @param handle I - The handle created by @ref sqlo_register_int_handler.
 *
 * @return SQLO_SUCCESS or SQLO_ERROR on error.
 */
int sqlo_clear_int_handler __P((int handle));


/**
 * }@
 */

/*-----------------------------------------------------------------------*/
/* Functions to keep backward compatibility                              */
/* Dont use this for new developments                                    */
/*-----------------------------------------------------------------------*/
#ifndef DOXYGEN_SHOULD_SKIP_THIS

int sql_init __P(( void ));

int sql_trace __P(( int on ));

CONST char * sql_geterror __P(( void ));

int sql_geterrcode __P(( void ));

int sql_exists __P((CONST char  * table, CONST char  * field,
                    CONST char * value, CONST char * where ));
int sql_run __P((CONST char * stmt, int argc, CONST char ** argv));

int sql_open __P((CONST char * stmt, int argc, 
                                    CONST char ** argv));

int sql_reopen __P((int sth, int argc, CONST char ** argv));

int sql_fetch __P((int sth ));

CONST char **sql_values __P(( int sth, int * num, int dostrip ));

CONST char *sql_command __P(( int sth ));

int sql_close __P(( int sth ));

int sql_print __P(( int sth ));

int sql_finish __P((void));

CONST char * sql_getdatabase __P(( void ));

CONST char ** sql_cnam __P(( int sth, int in, int * num ));

CONST char ** sql_sclen __P(( int sth, int in, int * num ));

int sql_prows __P(( int sth ));

int sql_connect __P(( CONST char  * connect_str ));

int sql_commit __P(( void ));

int sql_rollback __P(( void ));

int sql_count __P((CONST char * table,
                   CONST char * field,
                   CONST char * value,
                   CONST char * where ));

int sql_exec __P(( CONST char * stmt ));

int sql_setparam __P(( int argc , CONST char ** argv));

char CONST ** sql_getparam __P(( int namec, CONST char ** name, int *numvalues ));
int sql_isopen __P((int sth));

int sql_prepare __P((CONST char * stmt));

int sql_bind_by_name __P((int sth, CONST char * name, int param_type, 
                          CONST void * param_addr, unsigned int param_size, 
                          short * ind_addr, int is_array));

int sql_bind_by_pos __P((int sth, int position, int param_type, CONST void * param_addr, unsigned int param_size, short * ind_addr, int is_array));

int sql_define_by_pos __P((int sth, int value_pos, int value_type,
                           CONST void * value_addr,
                           unsigned int value_size,
                           short * ind_addr,
                           short * rlen_addr,
                           int is_array));

int sql_execute __P((int sth, int iterations));

char CONST **sql_ocol_names __P((int sth, int * num));

int CONST *sql_ocol_name_lens __P((int sth, int * num));

unsigned short CONST * sql_value_lens __P((int sth, int * num));

int sql_ncols __P((int sth, int in));

int sql_getdbh __P((void));

#define  SQLO_DEFDBH  (sql_getdbh())
#endif /* DOXYGEN_SHOULD_SKIP_THIS */

__END_DECLS


#endif