ocilib.h

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

/*
   +----------------------------------------------------------------------+   
   |                                                                      |
   |                     OCILIB - C Driver for Oracle                     |
   |                                                                      |
   |                      (C Wrapper for Oracle OCI)                      |
   |                                                                      |
   +----------------------------------------------------------------------+
   |                      Website : http://ocilib.net                     |
   +----------------------------------------------------------------------+
   |               Copyright (c) 2007-2008 Vincent ROGIER                 |
   +----------------------------------------------------------------------+
   | This library is free software; you can redistribute it and/or        |
   | modify it under the terms of the GNU Library General Public          |
   | License as published by the Free Software Foundation; either         |
   | version 2 of the License, or (at your option) any later version.     |
   |                                                                      |
   | This library is distributed in the hope that it will be useful,      |
   | but WITHOUT ANY WARRANTY; without even the implied warranty of       |
   | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU    |
   | Library General Public License for more details.                     |
   |                                                                      |
   | You should have received a copy of the GNU Library General Public    |
   | License along with this library; if not, write to the Free           |
   | Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.   |
   +----------------------------------------------------------------------+
   |          Author: Vincent ROGIER <[e-mail]>             |
   +----------------------------------------------------------------------+ 
*/

/* ------------------------------------------------------------------------ *
 * $Id: include/ocilib.h, v 3.0.0 2008/10/09 09:54 Vince $
 * ------------------------------------------------------------------------ */

#ifndef OCILIB_H_INCLUDED 
#define OCILIB_H_INCLUDED

#ifdef __cplusplus
extern "C" {
#endif  /* __cplusplus */

/**
 * @mainpage
 *
 * @image html logo-160x120.png  
 *
 * @section s_intro Introduction 
 * 
 * OCILIB is an open source and portable Oracle Driver that delivers really fast
 * and reliable access to Oracle databases.
 *
 * The OCILIB library :
 *
 * - offers a rich, full featured and easy to use API
 * - runs on all Oracle platforms
 * - is written in pure ISO C code with native ISO C Unicode support
 * - encapsulates OCI (Oracle Call Interface)
 * - is the most complete available OCI wrapper
 * 
 * @section s_version Version information
 *
 * <b>Current version : 3.0.0 (2008-10-13)</b>
 *
 * @section s_feats Main features
 *
 * - Data binding
 * - Integrated smart define and fetch mecanisms
 * - Full Unicode support on all platorms
 * - Multi row fetching
 * - Binding array Interface for fast and massive bulk operations
 * - Reusable Statements
 * - Scrollable statements
 * - Connection Pooling
 * - Global Transactions
 * - Returning DML feature support
 * - ROWIDs support
 * - Named Types (Object types) support (User or Builtin)
 * - Collections (Varrays and Nested tables)
 * - Ref cursors
 * - Full PL/SQL support (blocks, cursors, Index by Tables and Nested tables)
 * - LOB (BLOBs/ FILEs)
 * - Supports lobs > 4Go
 * - Long datatype (piecewise operations)
 * - Provides "All in one" Formatted functions (printf's like)
 * - Smallest possible memory usage
 * - Date/time management
 * - Timestamps and Intervals support 
 * - Error handling
 * - Thread contextual error management
 * - Describe database schema objects
 * - Access columns by index or name
 * - Hash tables API
 * - Portable Threads and mutexes API
 * - Supports static / shared oracle linkage
 * - Support runtime loading (no OCI libs required at compile / time)
 *
 * @section s_down Download
 *
 * Get OCILIB from <a href="http://orclib.sourceforge.net">OCILIB Project page</a>
 * at Sourceforge Website
 *
 * @section s_author Author
 *
 * OCILIB is developped by <a href="mailto:[e-mail]">Vincent Rogier</a>
 *
 * @section s_changelog ChangeLog
 *
 * @include ChangeLog.txt
 *
 */

/* ------------------------------------------------------------------------ *
 * Platform config
 * ------------------------------------------------------------------------ */

#ifdef HAVE_CONFIG_H
  #include <config.h>
#endif

/* ------------------------------------------------------------------------ *
 * C headers
 * ------------------------------------------------------------------------ */

#include <stdlib.h>
#include <stdio.h>
#include <stdarg.h>
#include <ctype.h>
#include <string.h>
#include <time.h>
#include <errno.h>
#include <limits.h>

/* ------------------------------------------------------------------------ *
 * MS Windows plaform detection 
 * ------------------------------------------------------------------------ */

#ifndef _WINDOWS
  #if defined(_WIN32) || defined(_WIN64) ||defined(_WIN32_WINNT)
    #define _WINDOWS
  #endif
#endif

#ifdef _WINDOWS
  #ifdef boolean
    #undef boolean
  #endif  
  #include <windows.h>
  #ifdef boolean
    #undef boolean
  #endif 
#endif

/* ------------------------------------------------------------------------ *
 * OCILIB version information
 * ------------------------------------------------------------------------ */
 
#define OCILIB_MAJOR_VERSION     3
#define OCILIB_MINOR_VERSION     0
#define OCILIB_REVISION_VERSION  0

/* ------------------------------------------------------------------------ *
 * Installing OCILIB
 * ------------------------------------------------------------------------ */

/**
 * @defgroup g_install Installing OCILIB
 * @{
 *
 *
 * @par Compatibilities
 *
 * Actual version of OCILIB has been validated on :
 *
 * - Platforms : Windows, HP/UX, Linux, Mac OS, Solaris, AIX, OpenVMS 
 * - Architectures : 32/64bits
 * - Compilers : GCC / MinGW, MS Compilers, IBM XLC, CCs, LabView 
 * - Oracle versions : 8i, 9i, 10g, 11g 
 *
 * Please, contact the author if you have validated OCILIB on platforms or
 * compilers not listed here.
 *
 * @par Global build options 
 *
 * OCILIB supports the following global build options :
 *
 * => Oracle import : 
 *
 *     - OCI_IMPORT_LINKAGE for linkage at compile time <b>(default on unixes)</b>
 *     - OCI_IMPORT_RUNTIME for runtime loading <b>(default with prebuilt 
 *        OCILIB libraries on MS Windows)</b>
 * 
 * => Oracle charset
 *
 *     - OCI_CHARSET_ANSI for ansi <b>(default)</b>
 *     - OCI_CHARSET_UNICODE for unicode
 *     - OCI_CHARSET_MIXED (ansi for metadata, unicode for userdata)
 *
 * =>    Calling convention (WINDOWS ONLY)
 *
 *     - OCI_API = __cdecl or blank for C/C++ only ! <b>(default)</b>
 *     - OCI_API = __sdtcall to link OCILIB shared library with langage
 *       independance <b>(default with prebuilt OCILIB libraries on MS Windows)</b>
 *
 * @note
 * On Windows, OCI_API MUST be set to use prebuilt libraries
 *
 * @par Installing OCIB on Unix like systems
 *
 * OCILIB uses GNU tools for deployment and installation on Unix like platforms
 *
 * Uncompress the archive (ocilib-x.y.z-gnu.tar.gz)
 *  - $ cd ocilib-x.y.z
 *  - $ ./configure
 *  - $ ./make
 *  - $ ./make install (this step might require admin rights)
 *
 * Check the shared library path environment variable (LD_LIBRARY_PATH, 
 * LD_PATH, ..) :
 *  - it must include $ORACLE_HOME\lib 
 *  - it must include the path where OCILIB has been installed 
 *    (by example, typically /usr/local/lib under linux)
 *
 * In order to get thoses values loaded at login time, export thoses values in
 * your .profile confifuration file :
 *  - > export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ORACLE_HOME/lib:/usr/local/lib
 *
 * <b>GNU Installation options </b>:
 *
 * OCILIB supports some optionss that are not needed for most common
 * configurations.
 * 
 * List of available options :
 *
 *   - --with-oracle-import=(linkage|runtime)
 *   - --with-oracle-charset=(ansi|unicode|mixed)
 *   - --with-oracle-home=(custom oracle regular client directory)
 *   - --with-oracle-lib64=(yes|no - check out folders on mixed 32/64bits plaforms)
 *   - --with-oracle-header-path=(oracle header files directory)
 *   - --with-oracle-lib-path=(oracle shared lib directory)
 *   - --with-oracle-lib-name=(oracle shared lib name)
 *   - --with-custom-loader=(linker flag telling the linker which loader to use
 *       when loading dynamically at runtime Oracle shared libs. 
 *       This option must be provide if the platform does not use the default 
 *       loader flag "-ldl") and the --with-oracle-import is set to 'runtime'
 *
 * @note
 * --with-oracle-header-path and --with-oracle-lib-path are meant to be used with 
 * Instant client only.
 *
 * @par Installing OCILIB on Microsoft Windows 
 *
 * 32bits and 64bits DLLs are provided. 
 * Visual .NET (2005/2008) solutions are also provided to recompile the Dlls and 
 * demo.
 *
 * - Uncompress the archive (ocilib-x.y.z-windows.zip)
 * - Copy ocilib\include\ocilib.h to a folder listed in the compiler headers folders
 * - Copy ocilib\lib[32|64]\ocilib[x].lib to a folder listed in the linker 
 *   libraries folders
 * - Copy ocilib\lib[32|64]\ocilib[x].dll to a folder included in the PATH
 *   environement variable
 *
 * [x] is the compiled version of OCILIB ("a" -> ansi, "w" -> unicode, "m" -> mixed)
 *
 * @par Oracle Instant Client Support
 *
 * OCILIB supports Oracle Instant Client.
 * 
 * On Microsoft Windows, there is no difference between using a regular Oracle
 * client and an Instant Client with OCILIB
 *
 * On Unix-like systems, the Instant Client is divised in different packages.
 * 
 * Public headers and shared libs are not part of the same package. 
 *
 * So, you must provide the following options to the configure command :
 *
 * - with-oracle-header-path : location the public header files
 * - with-oracle-lib-path : location the oracle shared lib
 *
 * If your instant client package containing the shared libs does not have a
 * symbolic link 'libclntsh.[shared lib extension]' to the fully qualified 
 * shared lib real name, you must create it :
 * 
 * Example on Linux :
 *
 * - $ ln $ORALIBPATH/libclntsh.so $ORALIBPATH/libclntsh.so.10.1
 *
 * @}
 *
 */

/* Import mode */

#ifdef OCI_IMPORT_RUNTIME
#undef OCI_IMPORT_LINKAGE
#endif

#ifdef OCI_IMPORT_LINKAGE
#undef OCI_IMPORT_RUNTIME
#endif

#if !defined(OCI_IMPORT_RUNTIME) && !defined(OCI_IMPORT_LINKAGE)
#define OCI_IMPORT_LINKAGE
#endif

/* Charset mode */

#ifdef OCI_CHARSET_UNICODE
#undef OCI_CHARSET_ANSI
#undef OCI_CHARSET_MIXED
#endif

#ifdef OCI_CHARSET_MIXED
#undef OCI_CHARSET_ANSI
#undef OCI_CHARSET_UNICODE
#endif

#ifdef OCI_CHARSET_ANSI
#undef OCI_CHARSET_MIXED
#undef OCI_CHARSET_UNICODE
#endif

#if !defined(OCI_CHARSET_ANSI) && !defined(OCI_CHARSET_MIXED) && !defined(OCI_CHARSET_UNICODE)
#define OCI_CHARSET_ANSI
#endif

/* Calling convention */

#ifndef OCI_API
#define OCI_API 
#endif

/* Build mode */

#ifndef OCI_EXPORT
#define OCI_EXPORT 
#endif

/**
 * @defgroup g_charset Charset support
 * @{
 *
 * OCILIB supports Ansi and Unicode charsets
 *
 * Oracle started a real Unicode support with Oracle8i but only for user data.
 * All SQL and PL/SQ/ statements, metadata string, database objects names, etc, 
 * ... were still only supported in Ansi.
 *  
 * With Oracle 9i, Oracle provides a full unicode support.
 * 
 * So depending on the compile time Oracle library or the runtime loaded 
 * library, the unicode support differs.
 *
 * OCILIB supports :
 *
 * - ansi (char)
 * - unicode (wchar_t)
 * - mixed charset : ansi for metadata, unicode for userdata
 *
 * OCILIB uses two types of strings :
 * 
 * - mtext : for meta data, SQL strings, object attributes.
 * - dtext : for input binds and output data
 * 
 * mtext and dtext are declared as defines around char and wchar_t 
 * depending ont the charset option
 * 
 * @par Text macro
 *
 *   - MT() macro : "meta text" -> meta data and strings passed to OCI calls
 *   - DT() macro : "data text" -> user input/output data
 *
 * @par Option OCI_CHARSET_ANSI
 *
 *  - dtext	-->	char
 *  - DT(x)	-->	x
 *
 *  - mtext	-->	char
 *  - MT(x)	-->	x
 *
 * @par Option OCI_CHARSET_UNICODE
 *
 *  - dtext	-->	wchar_t
 *  - DT(x)	-->	L ## x
 *
 *  - mtext	-->	wchar_t
 *  --MT(x)	-->	L ## x
 *
 * @par Option OCI_CHARSET_MIXED
 *
 *  - dtext	-->	wchar_t
 *  - DT(x)	-->	L ## x
 *
 *  - mtext	-->	char
 *  - MT(x)	-->	x
 *
 * 
 * @par Unicode and ISO C
 *
 * Well, ISO C :
 * - doesn't know anything about Unicode.
 * - makes wide characters support tricky because the size of a wide character
 * is not defined and is freely adaptable by implementations.
 * 
 * OCILIB uses char/wchar_t strings for public interface and internal storage.
 *
 * OCILIB, for unicode builds, initialize OCI in UTF16 Unicode mode. Oracle 
 * implements this mode with a 2 bytes (fixed length) UTF16 encoding.
 * 
 * So, on systems implementing wchar_t as 2 bytes based UTF16 (eg. Ms Windows), 
 * input strings are directly passed to Oracle and taken back from it.
 *
 * On other systems (most of the unixes) that use UTF32 as encoding 
 * (4 bytes based wchar_t), OCILIB uses :
 * - temporary buffers to pass string to OCI for metadata strings
 * - buffer expansion from UTF16 to UTF32 for user data string :
 *     - allocation based on sizeof(wchar_t)
 *     - data filling based on sizeof(short) -> (UTF16 2 bytes) 
 *     - data expansion to sizeof(wchar_t). 
 *
 * The buffer expansion is done inplace and has the advantage of not requiring 
 * extra buffer.
 * That reduces the cost of the Unicode/ISO C handling overhead on unixes.
 *
 * 
 * @par Charset mapping macros
 * 
 * OCILIB main header file provides macro around most common string functions of
 * the C standard library.
 * 
 * Thoses macros are based on the model :
 * 
 * - mtsxxx() for mtext * typed strings
 * - dtsxxx() for dtext * typed strings
 *
 * xxx is the standard C library string function name without the character 
 * type prefix (str/wcs). 
 * 
 * List of available macros :
 * - mtsdup, dtsdup
 * - mtscpy, dtscpy
 * - mtsncpy, dtsncpy
 * - mtscat, dtscat
 * - mtsncat, dtsncat
 * - mtslen, dtslen
 * - mtscmp, dtscmp
 * - mtscasecmp, dtscasecmp
 * - mtsprintf, dtsprintf
 * - mtstol, dtstol
 *
**/

/* Unicode mode */

#ifdef OCI_CHARSET_UNICODE
    #define OCI_METADATA_UNICODE
    #define OCI_USERDATA_UNICODE
    #define OCI_INCLUDE_WCHAR
#endif

#ifdef OCI_CHARSET_MIXED
    #define OCI_USERDATA_UNICODE
    #define OCI_INCLUDE_WCHAR
#endif

/* include wchar header if needed */

#ifdef OCI_INCLUDE_WCHAR
#include <wctype.h>

  #if (_MSC_VER < 1300) && defined(__cplusplus)
    extern "C++" {
  #endif 
  #include <wchar.h>
  #if (_MSC_VER < 1300) && defined(__cplusplus)
    }
  #endif
#endif

/* Charset macros */

#ifdef OCI_METADATA_UNICODE
    #define MT(x)           L ## x
    #define mtext           wchar_t
#else
    #define MT(x)           x
    #define mtext           char
#endif

#ifdef OCI_USERDATA_UNICODE
    #define DT(x)           L ## x
    #define dtext           wchar_t
#else
    #define DT(x)           x
    #define dtext           char
#endif

/*
   For ISO conformance, strdup/wcsdup/stricmp/strncasecmp are not used.
   All wide char routines are "officialy" C99.  
   but we weed an ansi equivalent to swprintf => ocisprintf 
   OCILIB exports the following helper functions

*/

OCI_EXPORT int       ocisprintf(char *str, int size, const char *format, ...);
OCI_EXPORT char    * ocistrdup(const char * src);
OCI_EXPORT int       ocistrcasecmp(const char *str1, const char *str2);

#ifdef OCI_INCLUDE_WCHAR
OCI_EXPORT wchar_t * ociwcsdup(const wchar_t * src);
OCI_EXPORT int       ociwcscasecmp(const wchar_t *str1, const wchar_t *str2);
#endif

/* special defines for Microsoft C runtime that is not C ISO compliant   */

#ifdef _MSC_VER
  #ifdef OCI_INCLUDE_WCHAR
    #if (_MSC_VER < 1300)  
      #define swprintf _snwprintf 
    #endif
#endif
#endif

/* helpers mapping macros */

#ifdef OCI_METADATA_UNICODE
    #define mtsdup          ociwcsdup
    #define mtscpy          wcscpy
    #define mtsncpy         wcsncpy
    #define mtscat          wcscat
    #define mtsncat         wcsncat
    #define mtslen          wcslen
    #define mtscmp          wcscmp
    #define mtscasecmp      ociwcscasecmp
    #define mtsprintf       swprintf
    #define mtstol          wcstol
#else
    #define mtsdup          ocistrdup
    #define mtscpy          strcpy
    #define mtsncpy         strncpy
    #define mtscat          strcat
    #define mtsncat         strncat
    #define mtslen          strlen
    #define mtscmp          strcmp
    #define mtscasecmp      ocistrcasecmp
    #define mtsprintf       ocisprintf
    #define mtstol          strtol
#endif

#ifdef OCI_USERDATA_UNICODE
    #define dtsdup          ociwcsdup