sqlora.h

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

#ifndef __SQLORA8_H_LOADED
#define __SQLORA8_H_LOADED
/* $Id: sqlora.h,v 1.1 2005/01/13 02:56:43 cvsroot Exp $ */
/** 
 * @file sqlora.h
 * libsqlora8 - Easy C API to Oracle using OCI.
 *
 * @version 2.2
 * 
 * @author Kai Poitschke
 *
 * Copyright (c) 1991-2002 Kai Poitschke (kai[_at_]poitschke.de)
 *   
 * This file is part of the libsqlora8 package which can be found
 * at http://www.poitschke.de/libsqlora8/
 */
/*
 *
 * Permission to use, copy, modify, and distribute this software for
 * any purpose with or without fee is hereby granted, provided that
 * the above copyright notice and this permission notice appear in all
 * copies.
 *
 *    THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 *    WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 *    MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 *    IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
 *    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 *    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 *    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 *    USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 *    ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 *    OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 *    OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 *    SUCH DAMAGE.
 *
 */


/**
 * @defgroup env Environment Variables
 * @{
 * The library evaluates the following enviroment variables during
 * initialization:
 * <ul>
 * <li>SQLORA_PREFETCH_ROWS (1 .. ; initial value 100)
 * <li>SQLORA_TRACE_LEVEL 
 *   <ul>
 *   <li>0 : Trace disabled (default)
 *   <li>1 : Print errors to tracefile
 *   <li>2 : Print function calls to tracefile
 *   <li>3 : Print more detailed information to tracefile
 *   <li>4 : Print also malloc/realloc operations.
 *   </ul>
 *
 * <li>SQLORA_TRACE_FILE (The trace file; default sqlora8.trc)
 * <li>SQLORA_LONGSIZE   (Max size of a fetched long; default 64K).
 * </ul>
 * During login, the library reads ORACLE_SID, if no tnsname was specified in
 * the connect string.
 * @}
 */
#ifndef DOXYGEN_SHOULD_SKIP_THIS
#include <stdio.h>
#include "libsqlora8-config.h"
#endif /* DOXYGEN_SHOULD_SKIP_THIS */

/*
 * Definitions that allow this header file to be used either with or
 * without ANSI C features like function prototypes.
 */


/* @def __BEGIN_DECLS
 * __BEGIN_DECLS should be used at the beginning of your declarations,
 *  so that C++ compilers don't mangle their names.  Use @ref__END_DECLS at
 *  the end of C declarations. 
 */

/* @def __END_DECLS
 * Opposite of @ref __BEGIN_DECLS
 */
#undef __BEGIN_DECLS
#undef __END_DECLS
#ifdef __cplusplus
# define __BEGIN_DECLS extern "C" {
# define __END_DECLS }
#else
# define __BEGIN_DECLS /* empty */
# define __END_DECLS /* empty */
#endif

/*
 * @def __P
 * __P is a macro used to wrap function prototypes.
 *
 * Compilers that don't understand ANSI C prototypes still work, and ANSI C
 * compilers can issue warnings about type mismatches. 
 * Use autoconf macro AC_C_PROTOTYPES to check for prototypes.
*/
#undef __P
#if (defined(PROTOTYPES) || defined(__STDC__) || defined(__cplusplus) )
# define __P(protos) protos
#else
# define __P(protos) ()
#endif

/*
 * @def CONST
 * Used to define constants.
 *
 * For ANSI C compilers this expands to const, for others its an empty definition.
 * @note AC_C_CONST defines const empty if it is not supported.
 */
#undef CONST

#ifndef const
#  if (defined(__STDC__) || defined(PROTOTYPES) || defined(__cplusplus))
#    define CONST const
#  else
#    define CONST
#  endif
#else
#  define CONST
#endif

/**
 * @defgroup constants Constants
 * @{
 */

/** 
 * @enum sqlo_status_codes
 * Constants defining the return codes of the functions.
 * 
 * These codes map basically to the OCI return codes.
 */
enum sqlo_status_codes {
  SQLO_SUCCESS             = 0,   /**< General success code (maps to OCI_SUCCESS) */
  SQLO_ERROR               = -1,      /**< General error code (maps to OCI_ERROR) */
  SQLO_INVALID_HANDLE      = -2,                  /**< Maps to OCI_INVALID_HANDLE */
  SQLO_STILL_EXECUTING     = -3123,              /**< Maps to OCI_STILL_EXECUTING */
  SQLO_CONTINUE            = -24200,                    /**< Maps to OCI_CONTINUE */
  SQLO_SUCCESS_WITH_INFO   = 1,                /**< Maps to OCI_SUCCESS_WITH_INFO */
  SQLO_NEED_DATA           = 99,                       /**< Maps to OCI_NEED_DATA */
  SQLO_NO_DATA             = 100                         /**< Maps to OCI_NO_DATA */
};

/**
 * @enum sqlo_error_codes
 * Constants defining error codes returned by the library
 *
 * All Error codes are < -30000 to be seperated from the oracle error space.
 */
enum sqlo_error_codes {
  SQLO_ERROR_BASE          = -30000,     /**< All our codes are below this value */
  SQLO_INVALID_DB_HANDLE   = (SQLO_ERROR_BASE - 1),      /**< Invalid dbh passed */
  SQLO_ERRMALLOC           = (SQLO_ERROR_BASE - 2),  /**< Cannot allocate memory */
  SQLO_INVALID_STMT_HANDLE = (SQLO_ERROR_BASE - 3), /**< Invalid statement handle passed*/
  SQLO_STMT_NOT_OPENED     = (SQLO_ERROR_BASE - 4), /**< Tried to reopen a not opened 
                                                       cursor in @ref sqlo_reopen */
  SQLO_INVALID_STMT_TYPE   = (SQLO_ERROR_BASE - 5), /**< Tried to parse a PL/SQL block 
                                                       with @ref sqlo_open */
  SQLO_STMT_NOT_PARSED     = (SQLO_ERROR_BASE - 6), /**< Tried to bind in/out variables 
                                                       for a non-parsed statement */
  SQLO_INVALID_OCI_HANDLE_TYPE = (SQLO_ERROR_BASE - 7), /**< Passed a wrong handle type 
                                                           to @ref sqlo_get_oci_handle */
  SQLO_MALFORMED_VERSION_STR = (SQLO_ERROR_BASE - 8), /**< Passed an invalid version 
                                                         string to @ref sqlo_version */
  SQLO_WRONG_VERSION       = (SQLO_ERROR_BASE - 9), /**< The version of the library does
                                                      not match your request */
  SQLO_INVALID_COLPOS      = (SQLO_ERROR_BASE - 10), /**< Column position passed to a function is wrong */
  SQLO_INVALID_SQL         = (SQLO_ERROR_BASE -11) /**< A invalid sql statement was passed to @ref sqlo_open or @ref sqlo_open2 */
};

/**
 * @enum sqlo_constants
 * Some constants used to pass to the functions.
 */
enum sqlo_constants {
  SQLO_OFF                 =  0, /**< use this to switch something off */
  SQLO_ON                  =  1, /**< use this to switch someting on */
  SQLO_NULL_IND            = -1, /**< NULL indicator */
  SQLO_NOT_NULL_IND        =  0, /**< NOT NULL indicator */
  SQLO_STH_INIT            = -1, /**< You must init the sth with this before the 
                                    first call of @ref sqlo_open2 */

  /* constants for piece operations (lob writes). */
  SQLO_ONE_PIECE           = 0, /**< Piecewise operation code in 
                                   @ref sqlo_lob_write_buffer  */
  SQLO_FIRST_PIECE         = 1, /**< Piecewise operation code in
                                   @ref sqlo_lob_write_buffer  */
  SQLO_NEXT_PIECE          = 2, /**< Piecewise operation code in 
                                   @ref sqlo_lob_write_buffer  */
  SQLO_LAST_PIECE          = 3 /**< Piecewise operation code in 
                                  @ref sqlo_lob_write_buffer  */
  
};

/**
 * @enum sqlo_data_types
 * The data types for bind variables
 * The oracle constants are copied from $ORACLE_HOME/rdbms/demo/ocidfn.h
 * @note Not all datatypes are implemented in this module (especially exotic
 * ones)
 * @see sqlo_bind_by_name sqlo_bind_by_pos sqlo_defined_by_pos
 */
enum sqlo_data_types {
  SQLOT_CHR  = 1,                      /**< (ORANET TYPE) character string */
  SQLOT_NUM  = 2,                        /**< (ORANET TYPE) oracle numeric */
  SQLOT_INT  = 3,                               /**< (ORANET TYPE) integer */
  SQLOT_FLT  = 4,                 /**< (ORANET TYPE) Floating point number */
  SQLOT_STR  = 5,                              /**< zero terminated string */
  SQLOT_VNU  = 6,                      /**< NUM with preceding length byte */
  SQLOT_PDN  = 7,                /**< (ORANET TYPE) Packed Decimal Numeric */
  SQLOT_LNG  = 8,                                                /**< long */
  SQLOT_VCS  = 9,                           /**< Variable character string */
  SQLOT_NON  = 10,                    /**< Null/empty PCC Descriptor entry */
  SQLOT_RID  = 11,                                              /**< rowid */
  SQLOT_DAT  = 12,                              /**< date in oracle format */
  SQLOT_VBI  = 15,                               /**< binary in VCS format */
  SQLOT_BIN  = 23,                                /**< binary data(DTYBIN) */
  SQLOT_LBI  = 24,                                        /**< long binary */
  SQLOT_UIN  = 68,                                   /**< unsigned integer */
  SQLOT_SLS  = 91,                      /**< Display sign leading separate */
  SQLOT_LVC  = 94,                                /**< Longer longs (char) */
  SQLOT_LVB  = 95,                                 /**< Longer long binary */ 
  SQLOT_AFC  = 96,                                    /**< Ansi fixed char */
  SQLOT_AVC  = 97,                                      /**< Ansi Var char */
  SQLOT_CUR  = 102,                                      /**< cursor  type */
  SQLOT_RDD  = 104,                                  /**< rowid descriptor */
  SQLOT_LAB  = 105,                                        /**< label type */
  SQLOT_OSL  = 106,                                      /**< oslabel type */
  SQLOT_NTY  = 108,                                 /**< named object type */
  SQLOT_REF  = 110,                                          /**< ref type */
  SQLOT_CLOB = 112,                                     /**< character lob */
  SQLOT_BLOB = 113,                                        /**< binary lob */
  SQLOT_BFILEE = 114,                                 /**< binary file lob */
  SQLOT_CFILEE = 115,                              /**< character file lob */
  SQLOT_RSET = 116,                                   /**< result set type */
  SQLOT_NCO  = 122,    /**< named collection type (varray or nested table) */
  SQLOT_VST  = 155,                                    /**< OCIString type */
  SQLOT_ODT  = 156,                                      /**< OCIDate type */

/* datetimes and intervals */
  SQLOT_DATE                   = 184,                      /**< ANSI Date */
  SQLOT_TIME                   = 185,                           /**< TIME */
  SQLOT_TIME_TZ                = 186,            /**< TIME WITH TIME ZONE */
  SQLOT_TIMESTAMP              = 187,                      /**< TIMESTAMP */
  SQLOT_TIMESTAMP_TZ           = 188,       /**< TIMESTAMP WITH TIME ZONE */
  SQLOT_INTERVAL_YM            = 189,         /**< INTERVAL YEAR TO MONTH */
  SQLOT_INTERVAL_DS            = 190,         /**< INTERVAL DAY TO SECOND */
  SQLOT_TIMESTAMP_LTZ          = 232         /**< TIMESTAMP WITH LOCAL TZ */
};

/* cxcheng: this has been added for backward compatibility -
   it needs to be here because ocidfn.h can get included ahead of sqldef.h */
#define SQLOT_FILE SQLOT_BFILEE                              /* binary file lob */
#define SQLOT_CFILE SQLOT_CFILEE
#define SQLOT_BFILE SQLOT_BFILEE

/**
 * @enum sqlo_statement_states
 * Possible statement states returned by @ref sqlo_get_stmt_state.
 */
enum sqlo_statement_states {
  SQLO_STMT_STATE_INITIALIZED = 1, /**< Statement initialized */
  SQLO_STMT_STATE_EXECUTED    = 2, /**< Statement executed */
  SQLO_STMT_STATE_END_OF_FETCH = 3 /**< Statement end of fetch reached */
};

/** @} */

/**
 * @defgroup typedefs Typedefs
 * @{
 */

/**
 * A database handle type.
 */
typedef int sqlo_db_handle_t;

/**
 * A statement handle type.
 */
typedef int sqlo_stmt_handle_t;

/**
 * Oracle OCI Handle types used by @ref sqlo_get_oci_handle
 */
typedef enum {
  SQLO_OCI_HTYPE_ENV     = 1,   /**< Environment handle */
  SQLO_OCI_HTYPE_ERROR   = 2,   /**< Error handle */
  SQLO_OCI_HTYPE_SVCCTX  = 3,   /**< Service context handle */
  SQLO_OCI_HTYPE_SERVER  = 4,   /**< Server handle */
  SQLO_OCI_HTYPE_SESSION = 5,   /**< Session handle */
  SQLO_OCI_HTYPE_STMT    = 6    /**< Statement handle  */
} sqlo_oci_handle_types_e;


/**
 * @typedef (void*) sqlo_lob_desc_t
 * LOB descriptor type
 * Hides the Oracle type OCILobLocator*
 */
typedef void * sqlo_lob_desc_t;


/**
 * The type of the signal handler function
 */
typedef void (*sqlo_signal_handler_t) __P((void));


/** @} */

/*-------------------------------------------------------------------------
 * Version Information
 *-----------------------------------------------------------------------*/
/**
 * @defgroup exvars  Exported Variables 
 * @{ 
 */

/**
 * @var sqlo_major_version
 * The major version of the library
 */
extern CONST unsigned sqlo_major_version;
/**
 * @var sqlo_minor_version
 * The minor version of the library
 */
extern CONST unsigned sqlo_minor_version;
/**
 * @var sqlo_micro_version
 * The micro version of the library
 */
extern CONST unsigned sqlo_micro_version;
/**
 * @var sqlo_interface_age
 * The interface age used by libtool
 */
extern CONST unsigned sqlo_interface_age;
/**
 * @var sqlo_binary_age
 * The binary age used by libtool
 */
extern CONST unsigned sqlo_binary_age;

/* to keep backward compatibility with <= 2.2, otherwise we break too much */
extern CONST unsigned sqlora8_major_version;
extern CONST unsigned sqlora8_minor_version;
extern CONST unsigned sqlora8_micro_version;
extern CONST unsigned sqlora8_interface_age;
extern CONST unsigned sqlora8_binary_age;
#define SQLORA8_MAJOR_VERSION LIBSQLORA8_MAJOR_VERSION
#define SQLORA8_MINOR_VERSION LIBSQLORA8_MINOR_VERSION
#define SQLORA8_MICRO_VERSION LIBSQLORA8_MICRO_VERSION

/* @} */

/**
 * @def SQLORA8_CHECK_VERSION
 * A macro used during compile time to check the version
 * This macro is used during the configure process of your program to check
 * for the right version. Used in libsqlora8.m4
 */
#define SQLORA8_CHECK_VERSION(major,minor,micro)    \
    (LIBSQLORA8_MAJOR_VERSION > (major) || \
     (LIBSQLORA8_MAJOR_VERSION == (major) && LIBSQLORA8_MINOR_VERSION > (minor)) || \
     (LIBSQLORA8_MAJOR_VERSION == (major) && LIBSQLORA8_MINOR_VERSION == (minor) && \
      LIBSQLORA8_MICRO_VERSION >= (micro)))



/*-------------------------------------------------------------------------
 * FUNCTION DECLARATIONS
 *-----------------------------------------------------------------------*/
__BEGIN_DECLS

/**
 * @defgroup init Initialization
 * @{
 */

/**
 * Init the library.
 *
 * Reads the environment and sets up the global variables for trace-level/-file,
 * and arraysize. Initializes the OCI library.
 * This is the first function you should call, before you use the library. Make
 * sure you call it only once!
 *
 * @param threaded_mode  I - SQLO_ON threading enabled, SQLO_OFF threading disabled.
 * @param max_db         I - The maximum number of parallel connections
 * @param max_cursors    I - The maximum number of cursors across all connections
 *
 * @return <ul>
 * <li> SQLO_SUCCESS
 * <li> < 0 on error
 * </ul>
 * @par Example:
 * @include examples.c
 */
int sqlo_init __P((int threaded_mode, unsigned int max_db, unsigned int max_cursors));

/**
 * Checks if the version is sufficient
 *
 * You can use this during runtime, to check if the dynamic linker did
 * a good job and linked you to the right version.
 *
 * @param version_str  I - The minimum version in the format major.minor.micro
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li>SQLO_WRONG_VERSION 
 * <li>SQLO_MALFORMED_VERSION_STR 
 * </ul>
 */
int sqlo_version __P((CONST char * version_str));

/** @} */

/**
 * @defgroup error Error handling functions 
 * @{
 */

/**
 * Return last error string
 *
 * @param dbh I - A database handle
 *
 * @return A string containing the last error message for this dbh
 */
CONST char * sqlo_geterror __P(( sqlo_db_handle_t dbh ));

/**
 * Return the last error code
 *
 * @param dbh I - A database handle
 *
 * @return The last error code for this dbh.
 */
int sqlo_geterrcode __P(( sqlo_db_handle_t dbh ));