ocilib.h

oci的源码,可以在任何平台上编译,相当方便实用

/*
   +----------------------------------------------------------------------+
   |                                                                      |
   |                     OCILIB - C Driver for Oracle                     |
   |                                                                      |
   |                      (C Wrapper for Oracle OCI)                      |
   |                                                                      |
   +----------------------------------------------------------------------+
   |                      Website : http://ocilib.net                     |
   +----------------------------------------------------------------------+
   |               Copyright (c) 2007-2009 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.2.0 2009/04/20 00:00 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.2.0 (2009-04-20)</b>
 *
 * @section s_feats Main features
 *
 * - Data binding
 * - Integrated smart define and fetch mechanisms
 * - Full Unicode support on all platforms
 * - Support for all Oracle SQL and PL/SQL datatypes
 * - 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 Built-in)
 * - 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
 * - Supports Direct Path API
 * - 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 developed 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     2
#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 user data)
 *
 * => Calling convention (WINDOWS ONLY)
 *
 *     - OCI_API = __cdecl or blank for C/C++ only ! <b>(default)</b>
 *     - OCI_API = __stdcall to link OCILIB shared library with language
 *       independence <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 theses values loaded at logon time, export theses values in
 * your .profile configuration file :
 *  - > export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ORACLE_HOME/lib:/usr/local/lib
 *
 * <b>GNU Installation options </b>:
 *
 * OCILIB supports some options 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 platforms)
 *   - --with-oracle-headers-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-headers-path and --with-oracle-lib-path are meant to be used with
 * Instant client only but can used for regular client of libs and headers are
 * not located in usual folders
 *
 * @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
 * the 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
 *   environment 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 divided 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-headers-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 -s $ORALIBPATH/libclntsh.so.10.1 $ORALIBPATH/libclntsh.so
 *
 * @}
 *
 */

/* Import mode */

#define OCI_IMPORT_MODE_LINKAGE  1
#define OCI_IMPORT_MODE_RUNTIME  2

#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

#ifdef OCI_IMPORT_RUNTIME
  #define OCI_IMPORT_MODE OCI_IMPORT_MODE_RUNTIME
#else
  #define OCI_IMPORT_MODE OCI_IMPORT_MODE_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 user data
 *
 * OCILIB uses two types of strings:
 *
 * - mtext: for metadata, SQL strings, object attributes.
 * - dtext: for input binds and output data
 *
 * mtext and dtext are declared as defines around char and wchar_t
 * depending on 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 (e.g. 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.
 *
 * Theses 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>

  #ifdef _MSC_VER

    #if (_MSC_VER < 1300) && defined(__cplusplus)
      extern "C++" {
    #endif

    #include <wchar.h>
      #if (_MSC_VER < 1300) && defined(__cplusplus)
      }
    #endif

  #else

    #include <wchar.h>

#endif

#endif

/* Charset macros */

#define OCI_CHAR_ANSI     1
#define OCI_CHAR_UNICODE  2

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

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

/*
   For ISO conformance, strdup/wcsdup/stricmp/strncasecmp are not used.
   All wide char routines are "officially" 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 _WINDOWS

  #define vsnprintf  _vsnprintf

  #ifdef OCI_INCLUDE_WCHAR
    #define swprintf _snwprintf
  #endif

#endif

/* helpers mapping macros */

#ifdef OCI_METADATA_UNICODE
    #define mtsdup          ociwcsdup
    #define mtscpy          wcscpy
    #define mtsncpy         wcsncpy
    #define mtscat          wcscat
    #define mtsncat         wcsncat