ruby-oci8 2.1.7 → 2.1.8

data/ext/oci8/oci8.c

@@ -2,7 +2,7 @@
 /*
  * oci8.c - part of ruby-oci8
  *
- * Copyright (C) 2002-2013 KUBO Takehiro <kubo@jiubao.org>
+ * Copyright (C) 2002-2015 Kubo Takehiro <kubo@jiubao.org>
  *
  */
 #include "oci8.h"
@@ -30,6 +30,9 @@ extern rb_pid_t rb_w32_getpid(void);
 #ifndef OCI_ATTR_CLIENT_INFO
 #define OCI_ATTR_CLIENT_INFO 368
 #endif
+#ifndef OCI_ATTR_TRANSACTION_IN_PROGRESS
+#define OCI_ATTR_TRANSACTION_IN_PROGRESS 484
+#endif
 
 #define OCI8_STATE_SESSION_BEGIN_WAS_CALLED 0x01
 #define OCI8_STATE_SERVER_ATTACH_WAS_CALLED 0x02
@@ -63,24 +66,106 @@ static VALUE dummy_env_method_missing(int argc, VALUE *argv, VALUE self)
     return rb_apply(obj, SYM2ID(method_id), args);
 }
 
-static void oci8_dont_free_handle_free(oci8_base_t *base)
+static void oci8_handle_dont_free(oci8_base_t *base)
 {
     base->type = 0;
+    base->closed = 1;
     base->hp.ptr = NULL;
 }
 
-static oci8_base_vtable_t oci8_dont_free_handle_vtable = {
-    NULL,
-    oci8_dont_free_handle_free,
+static const oci8_handle_data_type_t oci8_session_data_type = {
+    {
+        "OCI8::Session",
+        {
+            NULL,
+            oci8_handle_cleanup,
+            oci8_handle_size,
+        },
+        &oci8_handle_data_type.rb_data_type, NULL,
+#ifdef RUBY_TYPED_WB_PROTECTED
+        RUBY_TYPED_WB_PROTECTED,
+#endif
+    },
+    oci8_handle_dont_free,
+    sizeof(oci8_base_t),
+};
+
+static VALUE oci8_session_alloc(VALUE klass)
+{
+    return oci8_allocate_typeddata(klass, &oci8_session_data_type);
+}
+
+static const oci8_handle_data_type_t oci8_server_data_type = {
+    {
+        "OCI8::Server",
+        {
+            NULL,
+            oci8_handle_cleanup,
+            oci8_handle_size,
+        },
+        &oci8_handle_data_type.rb_data_type, NULL,
+#ifdef RUBY_TYPED_WB_PROTECTED
+        RUBY_TYPED_WB_PROTECTED,
+#endif
+    },
+    oci8_handle_dont_free,
+    sizeof(oci8_base_t),
+};
+
+static VALUE oci8_server_alloc(VALUE klass)
+{
+    return oci8_allocate_typeddata(klass, &oci8_server_data_type);
+}
+
+static const oci8_handle_data_type_t oci8_environment_data_type = {
+    {
+        "OCI8::Environment",
+        {
+            NULL,
+            oci8_handle_cleanup,
+            oci8_handle_size,
+        },
+        &oci8_handle_data_type.rb_data_type, NULL,
+#ifdef RUBY_TYPED_WB_PROTECTED
+        RUBY_TYPED_WB_PROTECTED,
+#endif
+    },
+    oci8_handle_dont_free,
+    sizeof(oci8_base_t),
+};
+
+static VALUE oci8_environment_alloc(VALUE klass)
+{
+    return oci8_allocate_typeddata(klass, &oci8_environment_data_type);
+}
+
+static const oci8_handle_data_type_t oci8_process_data_type = {
+    {
+        "OCI8::Process",
+        {
+            NULL,
+            oci8_handle_cleanup,
+            oci8_handle_size,
+        },
+        &oci8_handle_data_type.rb_data_type, NULL,
+#ifdef RUBY_TYPED_WB_PROTECTED
+        RUBY_TYPED_WB_PROTECTED,
+#endif
+    },
+    oci8_handle_dont_free,
     sizeof(oci8_base_t),
 };
 
+static VALUE oci8_process_alloc(VALUE klass)
+{
+    return oci8_allocate_typeddata(klass, &oci8_process_data_type);
+}
+
 static void copy_session_handle(oci8_svcctx_t *svcctx)
 {
     VALUE obj = rb_ivar_get(svcctx->base.self, id_at_session_handle);
-    oci8_base_t *base;
+    oci8_base_t *base = oci8_check_typeddata(obj, &oci8_session_data_type, 1);
 
-    Check_Handle(obj, cSession, base);
     base->type = OCI_HTYPE_SESSION;
     base->hp.usrhp = svcctx->usrhp;
 }
@@ -88,9 +173,8 @@ static void copy_session_handle(oci8_svcctx_t *svcctx)
 static void copy_server_handle(oci8_svcctx_t *svcctx)
 {
     VALUE obj = rb_ivar_get(svcctx->base.self, id_at_server_handle);
-    oci8_base_t *base;
+    oci8_base_t *base = oci8_check_typeddata(obj, &oci8_server_data_type, 1);
 
-    Check_Handle(obj, cServer, base);
     base->type = OCI_HTYPE_SERVER;
     base->hp.srvhp = svcctx->srvhp;
 }
@@ -115,6 +199,7 @@ static void oci8_svcctx_free(oci8_base_t *base)
         void *data = strategy->prepare(svcctx);
         int rv;
         svcctx->base.type = 0;
+        svcctx->base.closed = 1;
         svcctx->logoff_strategy = NULL;
         rv = oci8_run_native_thread(strategy->execute, data);
         if (rv != 0) {
@@ -127,22 +212,41 @@ static void oci8_svcctx_free(oci8_base_t *base)
         }
     }
     svcctx->base.type = 0;
+    svcctx->base.closed = 1;
 }
 
-static void oci8_svcctx_init(oci8_base_t *base)
+static const oci8_handle_data_type_t oci8_svcctx_data_type = {
+    {
+        "OCI8",
+        {
+            NULL,
+            oci8_handle_cleanup,
+            oci8_handle_size,
+        },
+        &oci8_handle_data_type.rb_data_type, NULL,
+#ifdef RUBY_TYPED_WB_PROTECTED
+        RUBY_TYPED_WB_PROTECTED,
+#endif
+    },
+    oci8_svcctx_free,
+    sizeof(oci8_svcctx_t),
+};
+
+static VALUE oci8_svcctx_alloc(VALUE klass)
 {
-    oci8_svcctx_t *svcctx = (oci8_svcctx_t *)base;
+    VALUE self = oci8_allocate_typeddata(klass, &oci8_svcctx_data_type);
+    oci8_svcctx_t *svcctx = (oci8_svcctx_t *)RTYPEDDATA_DATA(self);
     VALUE obj;
 
     svcctx->executing_thread = Qnil;
     /* set session handle */
     obj = rb_obj_alloc(cSession);
-    rb_ivar_set(base->self, id_at_session_handle, obj);
-    oci8_link_to_parent(DATA_PTR(obj), base);
+    rb_ivar_set(self, id_at_session_handle, obj);
+    oci8_link_to_parent(DATA_PTR(obj), &svcctx->base);
     /* set server handle */
     obj = rb_obj_alloc(cServer);
-    rb_ivar_set(base->self, id_at_server_handle, obj);
-    oci8_link_to_parent(DATA_PTR(obj), base);
+    rb_ivar_set(self, id_at_server_handle, obj);
+    oci8_link_to_parent(DATA_PTR(obj), &svcctx->base);
 
     svcctx->pid = getpid();
     svcctx->is_autocommit = 0;
@@ -150,29 +254,43 @@ static void oci8_svcctx_init(oci8_base_t *base)
     svcctx->non_blocking = 1;
 #endif
     svcctx->long_read_len = INT2FIX(65535);
+    return self;
 }
 
-static oci8_base_vtable_t oci8_svcctx_vtable = {
-    NULL,
-    oci8_svcctx_free,
-    sizeof(oci8_svcctx_t),
-    oci8_svcctx_init,
-};
-
 static VALUE oracle_client_vernum; /* Oracle client version number */
 
+/*
+ * @overload oracle_client_vernum
+ *
+ *  Returns Oracle client version as <i>Integer</i>.
+ *  The Oracle version is encoded in 32-bit integer.
+ *  It is devided into 5 parts: 8, 4, 8, 4 and 8 bits.
+ *
+ *  @example
+ *    # Oracle 9.2.0.4
+ *    oracle_client_vernum # => 0x09200400
+ *                         # => 0x09 2 00 4 00
+ *                         # => 9.2.0.4.0
+ *
+ *    # Oracle 11.1.0.7.0
+ *    oracle_client_vernum # => 0x0b100700
+ *                         # => 0x0b 1 00 7 00
+ *                         # => 11.1.0.7.0
+ *
+ *  @return [Integer]
+ *  @private
+ */
 static VALUE oci8_s_oracle_client_vernum(VALUE klass)
 {
     return oracle_client_vernum;
 }
 
 /*
- * call-seq:
- *   OCI8.__get_prop(key)
+ * @overload OCI8.__get_prop(key)
  *
- * @param [Fixnum] key    1 or 2
- *
- * @private
+ *  @param [Fixnum] key    1, 2 or 3
+ *  @return [Object]       depends on +key+.
+ *  @private
  */
 static VALUE oci8_s_get_prop(VALUE klass, VALUE key)
 {
@@ -188,16 +306,18 @@ static VALUE oci8_s_get_prop(VALUE klass, VALUE key)
 
 
 /*
- * call-seq:
- *   OCI8.__set_prop(key, value)
+ * @overload OCI8.__set_prop(key, value)
  *
- * @param [Fixnum] key    1 or 2
- * @param [Object] value  depends on +key+.
+ *  @param [Fixnum] key    1, 2 or 3
+ *  @param [Object] value  depends on +key+.
  *
- * @private
+ *  @private
  */
 static VALUE oci8_s_set_prop(VALUE klass, VALUE key, VALUE val)
 {
+#ifdef HAVE_PLTHOOK
+    static int hook_functions_installed = 0;
+#endif
     switch (NUM2INT(key)) {
     case 1:
         oci8_float_conversion_type_is_ruby = RTEST(val) ? 1 : 0;
@@ -212,6 +332,16 @@ static VALUE oci8_s_set_prop(VALUE klass, VALUE key, VALUE val)
         }
         oci8_env_mode = NUM2UINT(val);
         break;
+    case 3:
+#ifdef HAVE_PLTHOOK
+        if (!hook_functions_installed) {
+            oci8_install_hook_functions();
+            hook_functions_installed = 1;
+        }
+#else
+        rb_raise(rb_eNotImpError, ":cancel_read_at_exit isn't implemented on this machine.");
+#endif
+        break;
     default:
         rb_raise(rb_eArgError, "Unknown prop %d", NUM2INT(key));
     }
@@ -219,23 +349,20 @@ static VALUE oci8_s_set_prop(VALUE klass, VALUE key, VALUE val)
 }
 
 /*
- * call-seq:
- *   OCI8.error_message(message_no) -> string
+ * @overload error_message(message_no)
  *
- * Get the Oracle error message specified by message_no.
- * Its language depends on NLS_LANGUAGE.
+ *  Get the Oracle error message specified by message_no.
+ *  Its language depends on NLS_LANGUAGE.
  *
- * Note: This method is unavailable if the Oracle client version is 8.0.
+ *  @example
+ *    # When NLS_LANG is AMERICAN_AMERICA.AL32UTF8
+ *    OCI8.error_message(1) # => "ORA-00001: unique constraint (%s.%s) violated"
  *
- * example:
- *   # When NLS_LANG is AMERICAN_AMERICA.AL32UTF8
- *   OCI8.error_message(1) # => "ORA-00001: unique constraint (%s.%s) violated"
- *   
- *   # When NLS_LANG is FRENCH_FRANCE.AL32UTF8
- *   OCI8.error_message(1) # => "ORA-00001: violation de contrainte unique (%s.%s)"
+ *    # When NLS_LANG is FRENCH_FRANCE.AL32UTF8
+ *    OCI8.error_message(1) # => "ORA-00001: violation de contrainte unique (%s.%s)"
  *
- * @param [Fixnum] message_no   Oracle error message number
- * @return [String]             Oracle error message
+ *  @param [Fixnum] message_no   Oracle error message number
+ *  @return [String]             Oracle error message
  */
 static VALUE oci8_s_error_message(VALUE klass, VALUE msgid)
 {
@@ -270,17 +397,18 @@ void oci8_do_parse_connect_string(VALUE conn_str, VALUE *user, VALUE *pass, VALU
 }
 
 /*
- * call-seq:
- *   parse_connect_string(string) -> [username, password, dbname, privilege]
+ * @overload parse_connect_string(connect_string)
  *
- * Extracts +username+, +password+, +dbname+ and +privilege+ from the specified +string+.
+ *  Extracts +username+, +password+, +dbname+ and +privilege+ from +connect_string+.
  *
- * example:
- *   "scott/tiger" -> ["scott", "tiger", nil, nil],
- *   "scott/tiger@oradb.example.com" -> ["scott", "tiger", "oradb.example.com", nil]
- *   "sys/change_on_install as sysdba" -> ["sys", "change_on_install", nil, :SYSDBA]
+ *  @example
+ *    "scott/tiger" -> ["scott", "tiger", nil, nil],
+ *    "scott/tiger@oradb.example.com" -> ["scott", "tiger", "oradb.example.com", nil]
+ *    "sys/change_on_install as sysdba" -> ["sys", "change_on_install", nil, :SYSDBA]
  *
- * @private
+ *  @param [String] connect_string
+ *  @return [Array] [username, password, dbname]
+ *  @private
  */
 static VALUE oci8_parse_connect_string(VALUE self, VALUE conn_str)
 {
@@ -317,9 +445,15 @@ static void *simple_logoff_execute(void *arg)
 {
     simple_logoff_arg_t *sla = (simple_logoff_arg_t *)arg;
     OCIError *errhp = oci8_errhp;
+    boolean txn = TRUE;
     sword rv;
 
-    OCITransRollback(sla->svchp, errhp, OCI_DEFAULT);
+    if (oracle_client_version >= ORAVER_12_1) {
+        OCIAttrGet(sla->usrhp, OCI_HTYPE_SESSION, &txn, NULL, OCI_ATTR_TRANSACTION_IN_PROGRESS, errhp);
+    }
+    if (txn) {
+        OCITransRollback(sla->svchp, errhp, OCI_DEFAULT);
+    }
     rv = OCILogoff(sla->svchp, errhp);
     xfree(sla);
     return (void*)(VALUE)rv;
@@ -358,9 +492,15 @@ static void *complex_logoff_execute(void *arg)
 {
     complex_logoff_arg_t *cla = (complex_logoff_arg_t *)arg;
     OCIError *errhp = oci8_errhp;
+    boolean txn = TRUE;
     sword rv = OCI_SUCCESS;
 
-    OCITransRollback(cla->svchp, errhp, OCI_DEFAULT);
+    if (oracle_client_version >= ORAVER_12_1) {
+        OCIAttrGet(cla->usrhp, OCI_HTYPE_SESSION, &txn, NULL, OCI_ATTR_TRANSACTION_IN_PROGRESS, errhp);
+    }
+    if (txn) {
+        OCITransRollback(cla->svchp, errhp, OCI_DEFAULT);
+    }
 
     if (cla->state & OCI8_STATE_SESSION_BEGIN_WAS_CALLED) {
         rv = OCISessionEnd(cla->svchp, oci8_errhp, cla->usrhp, OCI_DEFAULT);
@@ -389,16 +529,19 @@ static const oci8_logoff_strategy_t complex_logoff = {
 };
 
 /*
- * call-seq:
- *   logon2(username, password, dbname, mode) -> connection
+ * @overload logon2(username, password, dbname, mode)
  *
- * Creates a simple logon session by the OCI function OCILogon2().
+ *  Creates a simple logon session by the OCI function OCILogon2().
  *
- * @private
+ *  @param [String] username
+ *  @param [String] password
+ *  @param [String] dbname
+ *  @param [Integer] mode
+ *  @private
  */
 static VALUE oci8_logon2(VALUE self, VALUE username, VALUE password, VALUE dbname, VALUE mode)
 {
-    oci8_svcctx_t *svcctx = DATA_PTR(self);
+    oci8_svcctx_t *svcctx = oci8_get_svcctx(self);
     ub4 logon2_mode;
 
     if (svcctx->logoff_strategy != NULL) {
@@ -441,17 +584,16 @@ static VALUE oci8_logon2(VALUE self, VALUE username, VALUE password, VALUE dbnam
 }
 
 /*
- * call-seq:
- *   allocate_handles()
+ * @overload allocate_handles()
  *
- * Allocates a service context handle, a session handle and a
- * server handle to use explicit attach and begin-session calls.
+ *  Allocates a service context handle, a session handle and a
+ *  server handle to use explicit attach and begin-session calls.
  *
- * @private
+ *  @private
  */
 static VALUE oci8_allocate_handles(VALUE self)
 {
-    oci8_svcctx_t *svcctx = DATA_PTR(self);
+    oci8_svcctx_t *svcctx = oci8_get_svcctx(self);
     sword rv;
 
     if (svcctx->logoff_strategy != NULL) {
@@ -481,12 +623,13 @@ static VALUE oci8_allocate_handles(VALUE self)
 }
 
 /*
- * call-seq:
- *   server_attach(dbname, mode)
+ * @overload server_attach(dbname, mode)
  *
- * Attachs to the server by the OCI function OCIServerAttach().
+ *  Attachs to the server by the OCI function OCIServerAttach().
  *
- * @private
+ *  @param [String] dbname
+ *  @param [Integer] mode
+ *  @private
  */
 static VALUE oci8_server_attach(VALUE self, VALUE dbname, VALUE attach_mode)
 {
@@ -523,16 +666,17 @@ static VALUE oci8_server_attach(VALUE self, VALUE dbname, VALUE attach_mode)
 }
 
 /*
- * call-seq:
- *   session_begin(cred, mode)
+ * @overload session_begin(cred, mode)
  *
- * Begins the session by the OCI function OCISessionBegin().
+ *  Begins the session by the OCI function OCISessionBegin().
  *
- * @private
+ *  @param [Fixnum] cred
+ *  @param [Fixnum] mode
+ *  @private
  */
 static VALUE oci8_session_begin(VALUE self, VALUE cred, VALUE mode)
 {
-    oci8_svcctx_t *svcctx = DATA_PTR(self);
+    oci8_svcctx_t *svcctx = oci8_get_svcctx(self);
 
     if (svcctx->logoff_strategy != &complex_logoff) {
         rb_raise(rb_eRuntimeError, "Use this method only for the service context handle created by OCI8#server_handle().");
@@ -559,15 +703,14 @@ static VALUE oci8_session_begin(VALUE self, VALUE cred, VALUE mode)
 }
 
 /*
- * call-seq:
- *   logoff
+ * @overload logoff
  *
- * Disconnects from the Oracle server. The uncommitted transaction is
- * rollbacked.
+ *  Disconnects from the Oracle server. The uncommitted transaction is
+ *  rollbacked.
  */
 static VALUE oci8_svcctx_logoff(VALUE self)
 {
-    oci8_svcctx_t *svcctx = (oci8_svcctx_t *)DATA_PTR(self);
+    oci8_svcctx_t *svcctx = oci8_get_svcctx(self);
 
     while (svcctx->base.children != NULL) {
         oci8_base_free(svcctx->base.children);
@@ -576,6 +719,7 @@ static VALUE oci8_svcctx_logoff(VALUE self)
         const oci8_logoff_strategy_t *strategy = svcctx->logoff_strategy;
         void *data = strategy->prepare(svcctx);
         svcctx->base.type = 0;
+        svcctx->base.closed = 1;
         svcctx->logoff_strategy = NULL;
         chker2(oci8_call_without_gvl(svcctx, strategy->execute, data), &svcctx->base);
     }
@@ -583,43 +727,40 @@ static VALUE oci8_svcctx_logoff(VALUE self)
 }
 
 /*
- * call-seq:
- *   commit
+ * @overload commit
  *
- * Commits the transaction.
+ *  Commits the transaction.
  */
 static VALUE oci8_commit(VALUE self)
 {
-    oci8_svcctx_t *svcctx = DATA_PTR(self);
+    oci8_svcctx_t *svcctx = oci8_get_svcctx(self);
     chker2(OCITransCommit_nb(svcctx, svcctx->base.hp.svc, oci8_errhp, OCI_DEFAULT), &svcctx->base);
     return self;
 }
 
 /*
- * call-seq:
- *   rollback
+ * @overload rollback
  *
- * Rollbacks the transaction.
+ *  Rollbacks the transaction.
  */
 static VALUE oci8_rollback(VALUE self)
 {
-    oci8_svcctx_t *svcctx = DATA_PTR(self);
+    oci8_svcctx_t *svcctx = oci8_get_svcctx(self);
     chker2(OCITransRollback_nb(svcctx, svcctx->base.hp.svc, oci8_errhp, OCI_DEFAULT), &svcctx->base);
     return self;
 }
 
 /*
- * call-seq:
- *   non_blocking? -> true or false
+ * @overload non_blocking?
  *
- * Returns +true+ if the connection is in non-blocking mode, +false+
- * otherwise.
+ *  Returns +true+ if the connection is in non-blocking mode, +false+
+ *  otherwise.
  *
- * See also #non_blocking=.
+ *  @see #non_blocking=
  */
 static VALUE oci8_non_blocking_p(VALUE self)
 {
-    oci8_svcctx_t *svcctx = DATA_PTR(self);
+    oci8_svcctx_t *svcctx = oci8_get_svcctx(self);
 #ifdef NATIVE_THREAD_WITH_GVL
     return svcctx->non_blocking ? Qtrue : Qfalse;
 #else
@@ -631,45 +772,25 @@ static VALUE oci8_non_blocking_p(VALUE self)
 }
 
 /*
- * call-seq:
- *   non_blocking = true or false
- *
- * Sets +true+ to enable non-blocking mode, +false+ otherwise.
- * The default setting depends on the ruby version and ruby-oci8
- * version.
+ * @overload non_blocking=(non_blocking_mode)
  *
- * When the connection is in blocking mode (non_blocking = false),
- * SQL executions block not only the thread, but also the ruby
- * process. It makes the whole application stop while a SQL execution
- * needs long time.
+ *  Sets +true+ to enable non-blocking mode, +false+ otherwise.
+ *  The default value is +true+ except ruby 1.8.
  *
- * When in non-blocking mode (non_blocking = true), SQL executions
- * block only the thread. It does't prevent other threads.
- * A SQL execution which blocks a thread can be canceled by
- * OCI8#break.
+ *  When the connection is in non-blocking mode (non_blocking = true),
+ *  an SQL execution blocks the thread running the SQL.
+ *  It does't prevent other threads. The blocking thread can be canceled
+ *  by {OCI8#break}.
  *
- * === ruby 1.9
- * The default setting is +true+ if the ruby-oci8 version is 2.0.3 or
- * upper, +false+ otherwise.
- *
- * Ruby-oci8 makes the connection non-blocking by releasing ruby
- * interpreter's GVL (Global VM Lock or Giant VM Lock) while OCI
- * functions which may need more than one network round trips are in
- * execution.
- *
- * === ruby 1.8
- * The default setting is +false+.
- *
- * Ruby-oci8 makes the connection non-blocking by polling the return
- * values of OCI functions. When an OCI function returns
- * OCI_STILL_EXECUTING, the thread sleeps for 10 milli seconds to make
- * a time for other threads to run. The sleep time is doubled up to
- * 640 milli seconds as the function returns the same value.
+ *  When in blocking mode (non_blocking = false), an SQL execution blocks
+ *  not only the thread, but also the ruby process itself. It makes the
+ *  whole application stop until the SQL finishes.
  *
+ *  @param [Boolean] non_blocking_mode
  */
 static VALUE oci8_set_non_blocking(VALUE self, VALUE val)
 {
-    oci8_svcctx_t *svcctx = DATA_PTR(self);
+    oci8_svcctx_t *svcctx = oci8_get_svcctx(self);
 #ifdef NATIVE_THREAD_WITH_GVL
     svcctx->non_blocking = RTEST(val);
 #else
@@ -688,78 +809,87 @@ static VALUE oci8_set_non_blocking(VALUE self, VALUE val)
 }
 
 /*
- * call-seq:
- *   autocommit? -> true or false
+ * @overload autocommit?
  *
- * Returns +true+ if the connection is in autocommit mode, +false+
- * otherwise. The default value is +false+.
+ *  Returns +true+ if the connection is in autocommit mode, +false+
+ *  otherwise. The default value is +false+.
  */
 static VALUE oci8_autocommit_p(VALUE self)
 {
-    oci8_svcctx_t *svcctx = DATA_PTR(self);
+    oci8_svcctx_t *svcctx = oci8_get_svcctx(self);
     return svcctx->is_autocommit ? Qtrue : Qfalse;
 }
 
 /*
- * call-seq:
- *   autocommit = true or false
+ * @overload autocommit=(autocommit_mode)
  *
- * Sets the autocommit mode. The default value is +false+.
+ *  Sets the autocommit mode. The default value is +false+.
+ *
+ *  @param [Boolean] autocommit_mode
  */
 static VALUE oci8_set_autocommit(VALUE self, VALUE val)
 {
-    oci8_svcctx_t *svcctx = DATA_PTR(self);
+    oci8_svcctx_t *svcctx = oci8_get_svcctx(self);
     svcctx->is_autocommit = RTEST(val);
     return val;
 }
 
 /*
- * call-seq:
- *   long_read_len -> fixnum
+ * @overload long_read_len
+ *
+ *  Gets the maximum length in bytes to fetch a LONG or LONG RAW
+ *  column. The default value is 65535.
  *
- * Gets the maximum length in bytes to fetch a LONG or LONG RAW
- * column. The default value is 65535.
+ *  If the actual data length is longer than long_read_len,
+ *  the fetched valud is truncated and the value of {OCI8#last_error}
+ *  become {OCISuccessWithInfo} whose message is "ORA-01406: fetched column value was truncated".
  *
- * If the actual data length is longer than long_read_len,
- * "ORA-01406: fetched column value was truncated" is raised.
+ *  Note: long_read_len is also used for maximum length of XMLTYPE data type.
  *
- * Note: long_read_len is also used for XMLTYPE data type in 2.0.
+ *  @return [Integer]
+ *  @see #long_read_len=
  */
 static VALUE oci8_long_read_len(VALUE self)
 {
-    oci8_svcctx_t *svcctx = DATA_PTR(self);
+    oci8_svcctx_t *svcctx = oci8_get_svcctx(self);
     return svcctx->long_read_len;
 }
 
 /*
- * call-seq:
- *   long_read_len = fixnum
- *
- * Sets the maximum length in bytes to fetch a LONG or LONG RAW
- * column.
+ * @overload long_read_len=(length)
  *
- * See also #long_read_len
+ *  Sets the maximum length in bytes to fetch a LONG or LONG RAW
+ *  column.
  *
+ *  @param [Integer] length
+ *  @see #long_read_len
  */
 static VALUE oci8_set_long_read_len(VALUE self, VALUE val)
 {
-    oci8_svcctx_t *svcctx = DATA_PTR(self);
+    oci8_svcctx_t *svcctx = oci8_get_svcctx(self);
     Check_Type(val, T_FIXNUM);
-    svcctx->long_read_len = val;
+    RB_OBJ_WRITE(self, &svcctx->long_read_len, val);
     return val;
 }
 
 /*
- * call-seq:
- *   break
+ * @overload break
+ *
+ *  Cancels the executing SQL.
+ *
+ *  Note that this doesn't work when the following cases.
  *
- * Cancels the executing SQL.
+ *  * The Oracle server runs on Windows.
+ *  * {Out-of-band data}[http://en.wikipedia.org/wiki/Transmission_Control_Protocol#Out-of-band_data] are blocked by a firewall or by a VPN.
  *
- * See also #non_blocking=.
+ *  In the latter case, create an sqlnet.ora file in the path specified
+ *  by the TNS_ADMIN environment variable that sets {DISABLE_OOB=on}[http://www.orafaq.com/wiki/SQL*Net_FAQ#What_are_inband_and_out_of_band_breaks.3F].
+ *
+ *  @see OCI8#non_blocking=
  */
 static VALUE oci8_break(VALUE self)
 {
-    oci8_svcctx_t *svcctx = DATA_PTR(self);
+    oci8_svcctx_t *svcctx = oci8_get_svcctx(self);
 
     if (NIL_P(svcctx->executing_thread)) {
         return Qfalse;
@@ -772,18 +902,18 @@ static VALUE oci8_break(VALUE self)
 }
 
 /*
- * call-seq:
- *   oracle_server_vernum -> an integer
+ * @overload oracle_server_vernum
  *
- * Returns a numerical format of the Oracle server version.
+ *  Returns a numerical format of the Oracle server version.
  *
- * @see OCI8#oracle_server_version
- * @since 2.0.1
- * @private
+ *  @return [Integer]
+ *  @see OCI8#oracle_server_version
+ *  @since 2.0.1
+ *  @private
  */
 static VALUE oci8_oracle_server_vernum(VALUE self)
 {
-    oci8_svcctx_t *svcctx = DATA_PTR(self);
+    oci8_svcctx_t *svcctx = oci8_get_svcctx(self);
     char buf[100];
     ub4 version;
 
@@ -792,23 +922,23 @@ static VALUE oci8_oracle_server_vernum(VALUE self)
 }
 
 /*
- * call-seq:
- *   ping -> true or false
+ * @overload ping
  *
- * Makes a round trip call to the server to confirm that the connection and
- * the server are active.
+ *  Makes a round trip call to the server to confirm that the connection and
+ *  the server are active.
  *
- * OCI8#ping also can be used to flush all the pending OCI client-side calls
- * to the server if any exist.
+ *  This also flushes all the pending OCI client-side calls such as {OCI8#action=},
+ *  {OCI8#client_identifier=}, {OCI8#client_info=} and {OCI8#module=}.
  *
- * === Oracle 10.2 client or upper
- * A dummy round trip call is made by a newly added OCI function
- * OCIPing[http://download.oracle.com/docs/cd/B19306_01/appdev.102/b14250/oci16msc007.htm#sthref3540] in Oracle 10.2.
+ *  === Oracle 10.2 client or upper
+ *  A dummy round trip call is made by the OCI function
+ *  OCIPing[http://download.oracle.com/docs/cd/B19306_01/appdev.102/b14250/oci16msc007.htm#sthref3540] added in Oracle 10.2.
  *
- * === Oracle 10.1 client or lower
- * A simple PL/SQL block "BEGIN NULL; END;" is executed to make a round trip call.
+ *  === Oracle 10.1 client or lower
+ *  A simple PL/SQL block "BEGIN NULL; END;" is executed to make a round trip call.
  *
- * @since 2.0.2
+ *  @return [Boolean]
+ *  @since 2.0.2
  */
 static VALUE oci8_ping(VALUE self)
 {
@@ -826,33 +956,31 @@ static VALUE oci8_ping(VALUE self)
 }
 
 /*
- * call-seq:
- *   client_identifier = string or nil
+ * @overload client_identifier=(client_identifier)
  *
- * Sets the client ID. This information is stored in the V$SESSION
- * view.
+ *  Sets the specified value to {V$SESSION.CLIENT_IDENTIFIER}[http://docs.oracle.com/database/121/REFRN/refrn30223.htm#r62c1-t21].
  *
- * === Oracle 9i client or upper
+ *  === Oracle 9i client or upper
  *
- * This doesn't perform network round trips. The change is reflected
- * to the server by the next round trip such as OCI8#exec, OCI8#ping,
- * etc.
+ *  The specified value is sent to the server by piggybacking on the next network
+ *  round trip issued by {OCI8#exec}, {OCI8#ping} and so on.
  *
- * === Oracle 8i client or lower
+ *  === Oracle 8i client or lower
  *
- * This executes the following PL/SQL block internally.
- * The change is reflected immediately by a network round trip.
+ *  This executes the following PL/SQL block internally.
  *
- *   BEGIN
- *     DBMS_SESSION.SET_IDENTIFIER(:client_id);
- *   END;
+ *    BEGIN
+ *      DBMS_SESSION.SET_IDENTIFIER(:client_id);
+ *    END;
  *
- * See {Oracle Manual: Oracle Database PL/SQL Packages and Types Reference}[http://download.oracle.com/docs/cd/B19306_01/appdev.102/b14258/d_sessio.htm#i996935]
+ *  See {Oracle Manual: Oracle Database PL/SQL Packages and Types Reference}[http://download.oracle.com/docs/cd/B19306_01/appdev.102/b14258/d_sessio.htm#i996935]
  *
- * @since 2.0.3
+ *  @param [String] client_identifier
+ *  @since 2.0.3
  */
 static VALUE oci8_set_client_identifier(VALUE self, VALUE val)
 {
+    oci8_svcctx_t *svcctx = oci8_get_svcctx(self);
     const char *ptr;
     ub4 size;
 
@@ -869,9 +997,9 @@ static VALUE oci8_set_client_identifier(VALUE self, VALUE val)
         if (size > 0 && ptr[0] == ':') {
             rb_raise(rb_eArgError, "client identifier should not start with ':'.");
         }
-        chker2(OCIAttrSet(oci8_get_oci_session(self), OCI_HTYPE_SESSION, (dvoid*)ptr,
+        chker2(OCIAttrSet(svcctx->usrhp, OCI_HTYPE_SESSION, (dvoid*)ptr,
                           size, OCI_ATTR_CLIENT_IDENTIFIER, oci8_errhp),
-               DATA_PTR(self));
+               &svcctx->base);
     } else {
         /* Workaround for Bug 2449486 */
         oci8_exec_sql_var_t bind_vars[1];
@@ -883,7 +1011,7 @@ static VALUE oci8_set_client_identifier(VALUE self, VALUE val)
         bind_vars[0].indp = NULL;
         bind_vars[0].alenp = NULL;
 
-        oci8_exec_sql(oci8_get_svcctx(self),
+        oci8_exec_sql(svcctx,
                       "BEGIN\n"
                       "  DBMS_SESSION.SET_IDENTIFIER(:client_id);\n"
                       "END;\n", 0, NULL, 1, bind_vars, 1);
@@ -892,40 +1020,39 @@ static VALUE oci8_set_client_identifier(VALUE self, VALUE val)
 }
 
 /*
- * call-seq:
- *   module = string or nil
+ * @overload module=(module)
  *
- * Sets the name of the current module. This information is
- * stored in the V$SESSION view and is also stored in the V$SQL view
- * and the V$SQLAREA view when a SQL statement is executed and the SQL
- * statement is first parsed in the Oracle server.
+ *  Sets the specified value to {V$SESSION.MODULE}[http://docs.oracle.com/database/121/REFRN/refrn30223.htm#r40c1-t21].
+ *  This is also stored in {V$SQL.MODULE}[http://docs.oracle.com/database/121/REFRN/refrn30246.htm#r49c1-t58]
+ *  and {V$SQLAREA.MODULE}[http://docs.oracle.com/database/121/REFRN/refrn30259.htm#r46c1-t94]
+ *  when an SQL statement is first parsed in the Oracle server.
  *
- * === Oracle 10g client or upper
+ *  === Oracle 10g client or upper
  *
- * This doesn't perform network round trips. The change is reflected
- * to the server by the next round trip such as OCI8#exec, OCI8#ping,
- * etc.
+ *  The specified value is sent to the server by piggybacking on the next network
+ *  round trip issued by {OCI8#exec}, {OCI8#ping} and so on.
  *
- * === Oracle 9i client or lower
+ *  === Oracle 9i client or lower
  *
- * This executes the following PL/SQL block internally.
- * The change is reflected immediately by a network round trip.
+ *  This executes the following PL/SQL block internally.
  *
- *   DECLARE
- *     action VARCHAR2(32);
- *   BEGIN
- *     -- retrieve action name.
- *     SELECT SYS_CONTEXT('USERENV','ACTION') INTO action FROM DUAL;
- *     -- change module name without modifying the action name.
- *     DBMS_APPLICATION_INFO.SET_MODULE(:module, action);
- *   END;
+ *    DECLARE
+ *      action VARCHAR2(32);
+ *    BEGIN
+ *      -- retrieve action name.
+ *      SELECT SYS_CONTEXT('USERENV','ACTION') INTO action FROM DUAL;
+ *      -- change module name without modifying the action name.
+ *      DBMS_APPLICATION_INFO.SET_MODULE(:module, action);
+ *    END;
  *
- * See {Oracle Manual: Oracle Database PL/SQL Packages and Types Reference}[http://download.oracle.com/docs/cd/B19306_01/appdev.102/b14258/d_appinf.htm#i999254]
+ *  See {Oracle Manual: Oracle Database PL/SQL Packages and Types Reference}[http://download.oracle.com/docs/cd/B19306_01/appdev.102/b14258/d_appinf.htm#i999254]
  *
- * @since 2.0.3
+ *  @param [String] module
+ *  @since 2.0.3
  */
 static VALUE oci8_set_module(VALUE self, VALUE val)
 {
+    oci8_svcctx_t *svcctx = oci8_get_svcctx(self);
     const char *ptr;
     ub4 size;
 
@@ -939,9 +1066,9 @@ static VALUE oci8_set_module(VALUE self, VALUE val)
     }
     if (oracle_client_version >= ORAVER_10_1) {
         /* Oracle 10g or upper */
-        chker2(OCIAttrSet(oci8_get_oci_session(self), OCI_HTYPE_SESSION, (dvoid*)ptr,
+        chker2(OCIAttrSet(svcctx->usrhp, OCI_HTYPE_SESSION, (dvoid*)ptr,
                           size, OCI_ATTR_MODULE, oci8_errhp),
-               DATA_PTR(self));
+               &svcctx->base);
     } else {
         /* Oracle 9i or lower */
         oci8_exec_sql_var_t bind_vars[1];
@@ -953,7 +1080,7 @@ static VALUE oci8_set_module(VALUE self, VALUE val)
         bind_vars[0].indp = NULL;
         bind_vars[0].alenp = NULL;
 
-        oci8_exec_sql(oci8_get_svcctx(self),
+        oci8_exec_sql(svcctx,
                       "DECLARE\n"
                       "  action VARCHAR2(32);\n"
                       "BEGIN\n"
@@ -965,36 +1092,34 @@ static VALUE oci8_set_module(VALUE self, VALUE val)
 }
 
 /*
- * call-seq:
- *   action = string or nil
+ * @overload action=(action)
  *
- * Sets the name of the current action within the current module.
- * This information is stored in the V$SESSION view and is also
- * stored in the V$SQL view and the V$SQLAREA view when a SQL
- * statement is executed and the SQL statement is first parsed
- * in the Oracle server.
+ *  Sets the specified value to {V$SESSION.ACTION}[http://docs.oracle.com/database/121/REFRN/refrn30223.htm#r42c1-t21].
+ *  This is also stored in {V$SQL.ACTION}[http://docs.oracle.com/database/121/REFRN/refrn30246.htm#r51c1-t58]
+ *  and {V$SQLAREA.ACTION}[http://docs.oracle.com/database/121/REFRN/refrn30259.htm#r48c1-t94]
+ *  when an SQL statement is first parsed in the Oracle server.
  *
- * === Oracle 10g client or upper
+ *  === Oracle 10g client or upper
  *
- * This doesn't perform network round trips. The change is reflected
- * to the server by the next round trip such as OCI8#exec, OCI8#ping,
- * etc.
+ *  The specified value is sent to the server by piggybacking on the next network
+ *  round trip issued by {OCI8#exec}, {OCI8#ping} and so on.
  *
- * === Oracle 9i client or lower
+ *  === Oracle 9i client or lower
  *
- * This executes the following PL/SQL block internally.
- * The change is reflected immediately by a network round trip.
+ *  This executes the following PL/SQL block internally.
  *
- *   BEGIN
- *     DBMS_APPLICATION_INFO.SET_ACTION(:action);
- *   END;
+ *    BEGIN
+ *      DBMS_APPLICATION_INFO.SET_ACTION(:action);
+ *    END;
  *
- * See {Oracle Manual: Oracle Database PL/SQL Packages and Types Reference}[http://download.oracle.com/docs/cd/B19306_01/appdev.102/b14258/d_appinf.htm#i999254]
+ *  See {Oracle Manual: Oracle Database PL/SQL Packages and Types Reference}[http://download.oracle.com/docs/cd/B19306_01/appdev.102/b14258/d_appinf.htm#i999254]
  *
- * @since 2.0.3
+ *  @param [String] action
+ *  @since 2.0.3
  */
 static VALUE oci8_set_action(VALUE self, VALUE val)
 {
+    oci8_svcctx_t *svcctx = oci8_get_svcctx(self);
     const char *ptr;
     ub4 size;
 
@@ -1008,9 +1133,9 @@ static VALUE oci8_set_action(VALUE self, VALUE val)
     }
     if (oracle_client_version >= ORAVER_10_1) {
         /* Oracle 10g or upper */
-        chker2(OCIAttrSet(oci8_get_oci_session(self), OCI_HTYPE_SESSION, (dvoid*)ptr,
+        chker2(OCIAttrSet(svcctx->usrhp, OCI_HTYPE_SESSION, (dvoid*)ptr,
                           size, OCI_ATTR_ACTION, oci8_errhp),
-               DATA_PTR(self));
+               &svcctx->base);
     } else {
         /* Oracle 9i or lower */
         oci8_exec_sql_var_t bind_vars[1];
@@ -1022,7 +1147,7 @@ static VALUE oci8_set_action(VALUE self, VALUE val)
         bind_vars[0].indp = NULL;
         bind_vars[0].alenp = NULL;
 
-        oci8_exec_sql(oci8_get_svcctx(self),
+        oci8_exec_sql(svcctx,
                       "BEGIN\n"
                       "  DBMS_APPLICATION_INFO.SET_ACTION(:action);\n"
                       "END;\n", 0, NULL, 1, bind_vars, 1);
@@ -1031,33 +1156,31 @@ static VALUE oci8_set_action(VALUE self, VALUE val)
 }
 
 /*
- * call-seq:
- *   client_info = string or nil
+ * @overload client_info=(client_info)
  *
- * Sets additional information about the client application.
- * This information is stored in the V$SESSION view.
+ *  Sets the specified value to {V$SESSION.CLIENT_INFO}[http://docs.oracle.com/database/121/REFRN/refrn30223.htm#r44c1-t21].
  *
- * === Oracle 10g client or upper
+ *  === Oracle 10g client or upper
  *
- * This doesn't perform network round trips. The change is reflected
- * to the server by the next round trip such as OCI8#exec, OCI8#ping,
- * etc.
+ *  The specified value is sent to the server by piggybacking on the next network
+ *  round trip issued by {OCI8#exec}, {OCI8#ping} and so on.
  *
- * === Oracle 9i client or lower
+ *  === Oracle 9i client or lower
  *
- * This executes the following PL/SQL block internally.
- * The change is reflected immediately by a network round trip.
+ *  This executes the following PL/SQL block internally.
  *
- *   BEGIN
- *     DBMS_APPLICATION_INFO.SET_CLIENT_INFO(:client_info);
- *   END;
+ *    BEGIN
+ *      DBMS_APPLICATION_INFO.SET_CLIENT_INFO(:client_info);
+ *    END;
  *
- * See {Oracle Manual: Oracle Database PL/SQL Packages and Types Reference}[http://download.oracle.com/docs/cd/B19306_01/appdev.102/b14258/d_appinf.htm#CHEJCFGG]
+ *  See {Oracle Manual: Oracle Database PL/SQL Packages and Types Reference}[http://download.oracle.com/docs/cd/B19306_01/appdev.102/b14258/d_appinf.htm#CHEJCFGG]
  *
- * @since 2.0.3
+ *  @param [String] client_info
+ *  @since 2.0.3
  */
 static VALUE oci8_set_client_info(VALUE self, VALUE val)
 {
+    oci8_svcctx_t *svcctx = oci8_get_svcctx(self);
     const char *ptr;
     ub4 size;
 
@@ -1071,9 +1194,9 @@ static VALUE oci8_set_client_info(VALUE self, VALUE val)
     }
     if (oracle_client_version >= ORAVER_10_1) {
         /* Oracle 10g or upper */
-        chker2(OCIAttrSet(oci8_get_oci_session(self), OCI_HTYPE_SESSION, (dvoid*)ptr,
+        chker2(OCIAttrSet(svcctx->usrhp, OCI_HTYPE_SESSION, (dvoid*)ptr,
                           size, OCI_ATTR_CLIENT_INFO, oci8_errhp),
-               DATA_PTR(self));
+               &svcctx->base);
     } else {
         /* Oracle 9i or lower */
         oci8_exec_sql_var_t bind_vars[1];
@@ -1085,7 +1208,7 @@ static VALUE oci8_set_client_info(VALUE self, VALUE val)
         bind_vars[0].indp = NULL;
         bind_vars[0].alenp = NULL;
 
-        oci8_exec_sql(oci8_get_svcctx(self), 
+        oci8_exec_sql(svcctx, 
                       "BEGIN\n"
                       "  DBMS_APPLICATION_INFO.SET_CLIENT_INFO(:client_info);\n"
                       "END;\n", 0, NULL, 1, bind_vars, 1);
@@ -1101,11 +1224,11 @@ void Init_oci8(VALUE *out)
     oci8_cOCIHandle = rb_define_class("OCIHandle", rb_cObject);
     cOCI8 = rb_define_class("OCI8", oci8_cOCIHandle);
 #endif
-    cOCI8 = oci8_define_class("OCI8", &oci8_svcctx_vtable);
-    cSession = oci8_define_class_under(cOCI8, "Session", &oci8_dont_free_handle_vtable);
-    cServer = oci8_define_class_under(cOCI8, "Server", &oci8_dont_free_handle_vtable);
-    cEnvironment = oci8_define_class_under(cOCI8, "Environment", &oci8_dont_free_handle_vtable);
-    cProcess = oci8_define_class_under(cOCI8, "Process", &oci8_dont_free_handle_vtable);
+    cOCI8 = oci8_define_class("OCI8", &oci8_svcctx_data_type, oci8_svcctx_alloc);
+    cSession = oci8_define_class_under(cOCI8, "Session", &oci8_session_data_type, oci8_session_alloc);
+    cServer = oci8_define_class_under(cOCI8, "Server", &oci8_server_data_type, oci8_server_alloc);
+    cEnvironment = oci8_define_class_under(cOCI8, "Environment", &oci8_environment_data_type, oci8_environment_alloc);
+    cProcess = oci8_define_class_under(cOCI8, "Process", &oci8_process_data_type, oci8_process_alloc);
     id_at_session_handle = rb_intern("@session_handle");
     id_at_server_handle = rb_intern("@server_handle");
 
@@ -1130,8 +1253,8 @@ void Init_oci8(VALUE *out)
 
     rb_define_const(cOCI8, "VERSION", rb_obj_freeze(rb_usascii_str_new_cstr(OCI8LIB_VERSION)));
     rb_define_singleton_method_nodoc(cOCI8, "oracle_client_vernum", oci8_s_oracle_client_vernum, 0);
-    rb_define_singleton_method(cOCI8, "__get_prop", oci8_s_get_prop, 1);
-    rb_define_singleton_method(cOCI8, "__set_prop", oci8_s_set_prop, 2);
+    rb_define_singleton_method_nodoc(cOCI8, "__get_prop", oci8_s_get_prop, 1);
+    rb_define_singleton_method_nodoc(cOCI8, "__set_prop", oci8_s_set_prop, 2);
     rb_define_singleton_method(cOCI8, "error_message", oci8_s_error_message, 1);
     rb_define_private_method(cOCI8, "parse_connect_string", oci8_parse_connect_string, 1);
     rb_define_private_method(cOCI8, "logon2", oci8_logon2, 4);
@@ -1159,7 +1282,7 @@ void Init_oci8(VALUE *out)
 
 oci8_svcctx_t *oci8_get_svcctx(VALUE obj)
 {
-    return (oci8_svcctx_t *)oci8_get_handle(obj, cOCI8);
+    return (oci8_svcctx_t *)oci8_check_typeddata(obj, &oci8_svcctx_data_type, 1);
 }
 
 OCISession *oci8_get_oci_session(VALUE obj)