oracledb 2.1.0 → 2.3.0

package/odpi/src/dpiOracleType.c

@@ -301,6 +301,8 @@ static dpiOracleTypeNum dpiOracleType__convertFromOracle(uint16_t typeCode,
         case DPI_SQLT_FLT:
         case DPI_SQLT_NUM:
         case DPI_SQLT_VNU:
+        case DPI_SQLT_BFLOAT:
+        case DPI_SQLT_BDOUBLE:
             return DPI_ORACLE_TYPE_NUMBER;
         case DPI_SQLT_DAT:
         case DPI_SQLT_ODT:
@@ -314,10 +316,8 @@ static dpiOracleTypeNum dpiOracleType__convertFromOracle(uint16_t typeCode,
         case DPI_SQLT_INT:
         case DPI_OCI_TYPECODE_SMALLINT:
             return DPI_ORACLE_TYPE_NATIVE_INT;
-        case DPI_SQLT_BFLOAT:
         case DPI_SQLT_IBFLOAT:
             return DPI_ORACLE_TYPE_NATIVE_FLOAT;
-        case DPI_SQLT_BDOUBLE:
         case DPI_SQLT_IBDOUBLE:
             return DPI_ORACLE_TYPE_NATIVE_DOUBLE;
         case DPI_SQLT_DATE:

package/odpi/src/dpiPool.c

@@ -119,6 +119,31 @@ static int dpiPool__create(dpiPool *pool, const char *userName,
             DPI_OCI_ATTR_SPOOL_GETMODE, "set get mode", error) < 0)
         return DPI_FAILURE;
 
+    // set the session timeout on the pool
+    if (dpiOci__attrSet(pool->handle, DPI_OCI_HTYPE_SPOOL, (void*)
+            &createParams->timeout, 0, DPI_OCI_ATTR_SPOOL_TIMEOUT,
+            "set timeout", error) < 0)
+        return DPI_FAILURE;
+
+    // set the wait timeout on the pool (valid in 12.2 and higher)
+    if (pool->env->versionInfo->versionNum > 12 ||
+            (pool->env->versionInfo->versionNum == 12 &&
+             pool->env->versionInfo->releaseNum >= 2)) {
+        if (dpiOci__attrSet(pool->handle, DPI_OCI_HTYPE_SPOOL, (void*)
+                &createParams->waitTimeout, 0, DPI_OCI_ATTR_SPOOL_WAIT_TIMEOUT,
+                "set wait timeout", error) < 0)
+            return DPI_FAILURE;
+    }
+
+    // set the maximum lifetime session on the pool (valid in 12.1 and higher)
+    if (pool->env->versionInfo->versionNum >= 12) {
+        if (dpiOci__attrSet(pool->handle, DPI_OCI_HTYPE_SPOOL, (void*)
+                &createParams->maxLifetimeSession, 0,
+                DPI_OCI_ATTR_SPOOL_MAX_LIFETIME_SESSION,
+                "set max lifetime session", error) < 0)
+            return DPI_FAILURE;
+    }
+
     // set reamining attributes directly
     pool->homogeneous = createParams->homogeneous;
     pool->externalAuth = createParams->externalAuth;
@@ -154,26 +179,37 @@ void dpiPool__free(dpiPool *pool, dpiError *error)
 static int dpiPool__getAttributeUint(dpiPool *pool, uint32_t attribute,
         uint32_t *value, const char *fnName)
 {
+    int status, supported = 1;
     dpiError error;
-    int status;
 
     if (dpiPool__checkConnected(pool, fnName, &error) < 0)
         return dpiGen__endPublicFn(pool, DPI_FAILURE, &error);
     DPI_CHECK_PTR_NOT_NULL(pool, value)
     switch (attribute) {
-        case DPI_OCI_ATTR_SPOOL_BUSY_COUNT:
         case DPI_OCI_ATTR_SPOOL_MAX_LIFETIME_SESSION:
+            if (pool->env->versionInfo->versionNum < 12)
+                supported = 0;
+            break;
+        case DPI_OCI_ATTR_SPOOL_WAIT_TIMEOUT:
+            if (pool->env->versionInfo->versionNum < 12 ||
+                    (pool->env->versionInfo->versionNum == 12 &&
+                     pool->env->versionInfo->releaseNum < 2))
+                supported = 0;
+            break;
+        case DPI_OCI_ATTR_SPOOL_BUSY_COUNT:
         case DPI_OCI_ATTR_SPOOL_OPEN_COUNT:
         case DPI_OCI_ATTR_SPOOL_STMTCACHESIZE:
         case DPI_OCI_ATTR_SPOOL_TIMEOUT:
-            status = dpiOci__attrGet(pool->handle, DPI_OCI_HTYPE_SPOOL, value,
-                    NULL, attribute, "get attribute value", &error);
             break;
         default:
-            status = dpiError__set(&error, "get attribute",
-                    DPI_ERR_NOT_SUPPORTED);
+            supported = 0;
             break;
     }
+    if (supported)
+        status = dpiOci__attrGet(pool->handle, DPI_OCI_HTYPE_SPOOL, value,
+                NULL, attribute, "get attribute value", &error);
+    else status = dpiError__set(&error, "get attribute value",
+            DPI_ERR_NOT_SUPPORTED);
     return dpiGen__endPublicFn(pool, status, &error);
 }
 
@@ -185,10 +221,10 @@ static int dpiPool__getAttributeUint(dpiPool *pool, uint32_t attribute,
 static int dpiPool__setAttributeUint(dpiPool *pool, uint32_t attribute,
         uint32_t value, const char *fnName)
 {
+    int status, supported = 1;
+    void *ociValue = &value;
     uint8_t shortValue;
-    void *ociValue;
     dpiError error;
-    int status;
 
     // make sure session pool is connected
     if (dpiPool__checkConnected(pool, fnName, &error) < 0)
@@ -201,18 +237,29 @@ static int dpiPool__setAttributeUint(dpiPool *pool, uint32_t attribute,
             ociValue = &shortValue;
             break;
         case DPI_OCI_ATTR_SPOOL_MAX_LIFETIME_SESSION:
+            if (pool->env->versionInfo->versionNum < 12)
+                supported = 0;
+            break;
+        case DPI_OCI_ATTR_SPOOL_WAIT_TIMEOUT:
+            if (pool->env->versionInfo->versionNum < 12 ||
+                    (pool->env->versionInfo->versionNum == 12 &&
+                     pool->env->versionInfo->releaseNum < 2))
+                supported = 0;
+            break;
         case DPI_OCI_ATTR_SPOOL_STMTCACHESIZE:
         case DPI_OCI_ATTR_SPOOL_TIMEOUT:
-            ociValue = &value;
             break;
         default:
-            dpiError__set(&error, "set attribute", DPI_ERR_NOT_SUPPORTED);
-            return dpiGen__endPublicFn(pool, DPI_FAILURE, &error);
+            supported = 0;
+            break;
     }
 
     // set value in the OCI
-    status = dpiOci__attrSet(pool->handle, DPI_OCI_HTYPE_SPOOL, ociValue, 0,
-            attribute, "set attribute value", &error);
+    if (supported)
+        status = dpiOci__attrSet(pool->handle, DPI_OCI_HTYPE_SPOOL, ociValue,
+                0, attribute, "set attribute value", &error);
+    else status = dpiError__set(&error, "set attribute value",
+            DPI_ERR_NOT_SUPPORTED);
     return dpiGen__endPublicFn(pool, status, &error);
 }
 
@@ -226,7 +273,6 @@ int dpiPool_acquireConnection(dpiPool *pool, const char *userName,
         dpiConnCreateParams *params, dpiConn **conn)
 {
     dpiConnCreateParams localParams;
-    size_t structSize;
     dpiError error;
     int status;
 
@@ -239,10 +285,9 @@ int dpiPool_acquireConnection(dpiPool *pool, const char *userName,
 
     // use default parameters if none provided
     if (!params || pool->env->context->dpiMinorVersion == 0) {
-        dpiContext__initConnCreateParams(pool->env->context, &localParams,
-                &structSize);
+        dpiContext__initConnCreateParams(&localParams);
         if (params)
-            memcpy(&localParams, params, structSize);
+            memcpy(&localParams, params, sizeof(dpiConnCreateParams__v20));
         params = &localParams;
     }
 
@@ -309,8 +354,11 @@ int dpiPool_create(const dpiContext *context, const char *userName,
         dpiContext__initCommonCreateParams(&localCommonParams);
         commonParams = &localCommonParams;
     }
-    if (!createParams) {
+    if (!createParams || context->dpiMinorVersion < 4) {
         dpiContext__initPoolCreateParams(&localCreateParams);
+        if (createParams)
+            memcpy(&localCreateParams, createParams,
+                    sizeof(dpiPoolCreateParams__v23));
         createParams = &localCreateParams;
     }
 
@@ -433,6 +481,17 @@ int dpiPool_getTimeout(dpiPool *pool, uint32_t *value)
 }
 
 
+//-----------------------------------------------------------------------------
+// dpiPool_getWaitTimeout() [PUBLIC]
+//   Return the pool's wait timeout value.
+//-----------------------------------------------------------------------------
+int dpiPool_getWaitTimeout(dpiPool *pool, uint32_t *value)
+{
+    return dpiPool__getAttributeUint(pool, DPI_OCI_ATTR_SPOOL_WAIT_TIMEOUT,
+            value, __func__);
+}
+
+
 //-----------------------------------------------------------------------------
 // dpiPool_release() [PUBLIC]
 //   Release a reference to the pool.
@@ -486,3 +545,14 @@ int dpiPool_setTimeout(dpiPool *pool, uint32_t value)
             __func__);
 }
 
+
+//-----------------------------------------------------------------------------
+// dpiPool_setWaitTimeout() [PUBLIC]
+//   Set the pool's wait timeout value.
+//-----------------------------------------------------------------------------
+int dpiPool_setWaitTimeout(dpiPool *pool, uint32_t value)
+{
+    return dpiPool__setAttributeUint(pool, DPI_OCI_ATTR_SPOOL_WAIT_TIMEOUT,
+            value, __func__);
+}
+

package/odpi/src/dpiStmt.c

@@ -22,7 +22,7 @@ static int dpiStmt__getQueryInfo(dpiStmt *stmt, uint32_t pos,
 static int dpiStmt__getQueryInfoFromParam(dpiStmt *stmt, void *param,
         dpiQueryInfo *info, dpiError *error);
 static int dpiStmt__postFetch(dpiStmt *stmt, dpiError *error);
-static int dpiStmt__preFetch(dpiStmt *stmt, dpiError *error);
+static int dpiStmt__beforeFetch(dpiStmt *stmt, dpiError *error);
 static int dpiStmt__reExecute(dpiStmt *stmt, uint32_t numIters,
         uint32_t mode, dpiError *error);
 
@@ -184,18 +184,13 @@ static int dpiStmt__bind(dpiStmt *stmt, dpiVar *var, int addReference,
     }
 
     // bind object, if applicable
-    if (var->objectIndicator && dpiOci__bindObject(var, bindHandle, error) < 0)
+    if (var->buffer.objectIndicator &&
+            dpiOci__bindObject(var, bindHandle, error) < 0)
         return DPI_FAILURE;
 
-    // setup dynamic bind, if applicable; reset actual array size to 0 as
-    // dynamic bind doesn't get called if there are no rows returned in a DML
-    // returning statement
-    if (dynamicBind) {
-        if (stmt->isReturning)
-            var->actualArraySize = 0;
-        if (dpiOci__bindDynamic(var, bindHandle, error) < 0)
-            return DPI_FAILURE;
-    }
+    // setup dynamic bind, if applicable
+    if (dynamicBind && dpiOci__bindDynamic(var, bindHandle, error) < 0)
+        return DPI_FAILURE;
 
     return DPI_SUCCESS;
 }
@@ -510,7 +505,7 @@ static int dpiStmt__define(dpiStmt *stmt, uint32_t pos, dpiVar *var,
     }
 
     // define objects, if applicable
-    if (var->objectIndicator && dpiOci__defineObject(var, defineHandle,
+    if (var->buffer.objectIndicator && dpiOci__defineObject(var, defineHandle,
             error) < 0)
         return DPI_FAILURE;
 
@@ -543,21 +538,28 @@ static int dpiStmt__execute(dpiStmt *stmt, uint32_t numIters,
     // buffer structures
     for (i = 0; i < stmt->numBindVars; i++) {
         var = stmt->bindVars[i].var;
-        for (j = 0; j < var->maxArraySize; j++) {
-            data = &var->externalData[j];
+        if (var->isArray && numIters > 1)
+            return dpiError__set(error, "bind array var",
+                    DPI_ERR_ARRAY_VAR_NOT_SUPPORTED);
+        for (j = 0; j < var->buffer.maxArraySize; j++) {
+            data = &var->buffer.externalData[j];
             if (var->type->oracleTypeNum == DPI_ORACLE_TYPE_STMT &&
                     data->value.asStmt == stmt)
                 return dpiError__set(error, "bind to self",
                         DPI_ERR_NOT_SUPPORTED);
-            if (dpiVar__setValue(var, j, data, error) < 0)
+            if (dpiVar__setValue(var, &var->buffer, j, data, error) < 0)
                 return DPI_FAILURE;
+            if (var->dynBindBuffers)
+                var->dynBindBuffers[j].actualArraySize = 0;
         }
         if (stmt->isReturning || var->isDynamic)
             var->error = error;
     }
 
-    // for queries, set the prefetch rows to the fetch array size in order to
-    // avoid the network round trip for the first fetch
+    // for queries, set the OCI prefetch to a fixed value; this prevents an
+    // additional round trip for single row fetches while avoiding the overhead
+    // of copying from the OCI prefetch buffer to our own buffers for larger
+    // fetches
     if (stmt->statementType == DPI_STMT_TYPE_SELECT) {
         prefetchSize = DPI_PREFETCH_ROWS_DEFAULT;
         if (dpiOci__attrSet(stmt->handle, DPI_OCI_HTYPE_STMT, &prefetchSize,
@@ -595,9 +597,8 @@ static int dpiStmt__execute(dpiStmt *stmt, uint32_t numIters,
             stmt->statementType == DPI_STMT_TYPE_CALL) {
         for (i = 0; i < stmt->numBindVars; i++) {
             var = stmt->bindVars[i].var;
-            for (j = 0; j < var->maxArraySize; j++) {
-                if (dpiVar__getValue(var, j, &var->externalData[j],
-                        error) < 0)
+            for (j = 0; j < var->buffer.maxArraySize; j++) {
+                if (dpiVar__getValue(var, &var->buffer, j, 0, error) < 0)
                     return DPI_FAILURE;
             }
             var->error = NULL;
@@ -606,6 +607,7 @@ static int dpiStmt__execute(dpiStmt *stmt, uint32_t numIters,
 
     // create query variables (if applicable)
     if (stmt->statementType == DPI_STMT_TYPE_SELECT &&
+            !(mode & DPI_MODE_EXEC_PARSE_ONLY) &&
             dpiStmt__createQueryVars(stmt, error) < 0)
         return DPI_FAILURE;
 
@@ -620,7 +622,7 @@ static int dpiStmt__execute(dpiStmt *stmt, uint32_t numIters,
 static int dpiStmt__fetch(dpiStmt *stmt, dpiError *error)
 {
     // perform any pre-fetch activities required
-    if (dpiStmt__preFetch(stmt, error) < 0)
+    if (dpiStmt__beforeFetch(stmt, error) < 0)
         return DPI_FAILURE;
 
     // perform fetch
@@ -840,7 +842,7 @@ static int dpiStmt__postFetch(dpiStmt *stmt, dpiError *error)
     for (i = 0; i < stmt->numQueryVars; i++) {
         var = stmt->queryVars[i];
         for (j = 0; j < stmt->bufferRowCount; j++) {
-            if (dpiVar__getValue(var, j, &var->externalData[j], error) < 0)
+            if (dpiVar__getValue(var, &var->buffer, j, 1, error) < 0)
                 return DPI_FAILURE;
             if (var->type->requiresPreFetch)
                 var->requiresPreFetch = 1;
@@ -853,13 +855,13 @@ static int dpiStmt__postFetch(dpiStmt *stmt, dpiError *error)
 
 
 //-----------------------------------------------------------------------------
-// dpiStmt__preFetch() [INTERNAL]
+// dpiStmt__beforeFetch() [INTERNAL]
 //   Performs work that needs to be done prior to fetch for each variable. In
 // addition, variables are created if they do not already exist. A check is
 // also made to ensure that the variable has enough space to support a fetch
 // of the requested size.
 //-----------------------------------------------------------------------------
-static int dpiStmt__preFetch(dpiStmt *stmt, dpiError *error)
+static int dpiStmt__beforeFetch(dpiStmt *stmt, dpiError *error)
 {
     dpiQueryInfo *queryInfo;
     dpiData *data;
@@ -883,10 +885,11 @@ static int dpiStmt__preFetch(dpiStmt *stmt, dpiError *error)
             dpiGen__setRefCount(var, error, -1);
         }
         var->error = error;
-        if (stmt->fetchArraySize > var->maxArraySize)
+        if (stmt->fetchArraySize > var->buffer.maxArraySize)
             return dpiError__set(error, "check array size",
-                    DPI_ERR_ARRAY_SIZE_TOO_SMALL, var->maxArraySize);
-        if (var->requiresPreFetch && dpiVar__extendedPreFetch(var, error) < 0)
+                    DPI_ERR_ARRAY_SIZE_TOO_SMALL, var->buffer.maxArraySize);
+        if (var->requiresPreFetch && dpiVar__extendedPreFetch(var,
+                &var->buffer, error) < 0)
             return DPI_FAILURE;
     }
 
@@ -949,7 +952,7 @@ static int dpiStmt__reExecute(dpiStmt *stmt, uint32_t numIters,
     // so that it does not return with the invalid metadata; again, if this
     // cannot be done, let the original error propagate
     origHandle = stmt->handle;
-    status = dpiStmt__prepare(stmt, sql, sqlLength, NULL, 0, &localError);
+    status = dpiOci__stmtPrepare2(stmt, sql, sqlLength, NULL, 0, &localError);
     newHandle = stmt->handle;
     stmt->handle = origHandle;
     stmt->deleteFromCache = 1;
@@ -1197,13 +1200,25 @@ int dpiStmt_executeMany(dpiStmt *stmt, dpiExecMode mode, uint32_t numIters)
         return dpiGen__endPublicFn(stmt, DPI_FAILURE, &error);
     }
 
+    // batch errors and array DML row counts are only supported with DML
+    // statements (insert, update, delete and merge)
+    if ((mode & DPI_MODE_EXEC_BATCH_ERRORS ||
+                mode & DPI_MODE_EXEC_ARRAY_DML_ROWCOUNTS) &&
+            stmt->statementType != DPI_STMT_TYPE_INSERT &&
+            stmt->statementType != DPI_STMT_TYPE_UPDATE &&
+            stmt->statementType != DPI_STMT_TYPE_DELETE &&
+            stmt->statementType != DPI_STMT_TYPE_MERGE) {
+        dpiError__set(&error, "check mode", DPI_ERR_EXEC_MODE_ONLY_FOR_DML);
+        return dpiGen__endPublicFn(stmt, DPI_FAILURE, &error);
+    }
+
     // ensure that all bind variables have a big enough maxArraySize to
     // support this operation
     for (i = 0; i < stmt->numBindVars; i++) {
-        if (stmt->bindVars[i].var->maxArraySize < numIters) {
+        if (stmt->bindVars[i].var->buffer.maxArraySize < numIters) {
             dpiError__set(&error, "check array size",
                     DPI_ERR_ARRAY_SIZE_TOO_SMALL,
-                    stmt->bindVars[i].var->maxArraySize);
+                    stmt->bindVars[i].var->buffer.maxArraySize);
             return dpiGen__endPublicFn(stmt, DPI_FAILURE, &error);
         }
     }
@@ -1564,15 +1579,16 @@ int dpiStmt_getQueryValue(dpiStmt *stmt, uint32_t pos,
         return dpiGen__endPublicFn(stmt, DPI_FAILURE, &error);
     }
     *nativeTypeNum = var->nativeTypeNum;
-    *data = &var->externalData[stmt->bufferRowIndex - 1];
+    *data = &var->buffer.externalData[stmt->bufferRowIndex - 1];
     return dpiGen__endPublicFn(stmt, DPI_SUCCESS, &error);
 }
 
 
 //-----------------------------------------------------------------------------
 // dpiStmt_getRowCount() [PUBLIC]
-//   Return the number of rows affected by the last SQL executed (for insert,
-// update or delete) or the number of rows fetched (for queries).
+//   Return the number of rows affected by the last DML executed (for insert,
+// update, delete and merge) or the number of rows fetched (for queries). In
+// all other cases, 0 is returned.
 //-----------------------------------------------------------------------------
 int dpiStmt_getRowCount(dpiStmt *stmt, uint64_t *count)
 {
@@ -1584,7 +1600,12 @@ int dpiStmt_getRowCount(dpiStmt *stmt, uint64_t *count)
     DPI_CHECK_PTR_NOT_NULL(stmt, count)
     if (stmt->statementType == DPI_STMT_TYPE_SELECT)
         *count = stmt->rowCount;
-    else if (stmt->env->versionInfo->versionNum < 12) {
+    else if (stmt->statementType != DPI_STMT_TYPE_INSERT &&
+            stmt->statementType != DPI_STMT_TYPE_UPDATE &&
+            stmt->statementType != DPI_STMT_TYPE_DELETE &&
+            stmt->statementType != DPI_STMT_TYPE_MERGE) {
+        *count = 0;
+    } else if (stmt->env->versionInfo->versionNum < 12) {
         if (dpiOci__attrGet(stmt->handle, DPI_OCI_HTYPE_STMT, &rowCount32, 0,
                 DPI_OCI_ATTR_ROW_COUNT, "get row count", &error) < 0)
             return dpiGen__endPublicFn(stmt, DPI_FAILURE, &error);
@@ -1703,7 +1724,7 @@ int dpiStmt_scroll(dpiStmt *stmt, dpiFetchMode mode, int32_t offset,
     }
 
     // perform any pre-fetch activities required
-    if (dpiStmt__preFetch(stmt, &error) < 0)
+    if (dpiStmt__beforeFetch(stmt, &error) < 0)
         return dpiGen__endPublicFn(stmt, DPI_FAILURE, &error);
 
     // perform fetch; when fetching the last row, only fetch a single row
@@ -1767,7 +1788,7 @@ int dpiStmt_setFetchArraySize(dpiStmt *stmt, uint32_t arraySize)
         arraySize = DPI_DEFAULT_FETCH_ARRAY_SIZE;
     for (i = 0; i < stmt->numQueryVars; i++) {
         var = stmt->queryVars[i];
-        if (var && var->maxArraySize < arraySize) {
+        if (var && var->buffer.maxArraySize < arraySize) {
             dpiError__set(&error, "check array size",
                     DPI_ERR_ARRAY_SIZE_TOO_BIG, arraySize);
             return dpiGen__endPublicFn(stmt, DPI_FAILURE, &error);

package/odpi/src/dpiSubscr.c

@@ -50,6 +50,7 @@ static void dpiSubscr__callback(dpiSubscr *subscr, UNUSED void *handle,
         dpiError__getInfo(&error, &errorInfo);
         message.errorInfo = &errorInfo;
     }
+    message.registered = subscr->registered;
 
     // invoke user callback
     (*subscr->callback)(subscr->callbackContext, &message);
@@ -60,6 +61,23 @@ static void dpiSubscr__callback(dpiSubscr *subscr, UNUSED void *handle,
 }
 
 
+//-----------------------------------------------------------------------------
+// dpiSubscr__checkOpen() [INTERNAL]
+//   Determine if the subscription is open and available for use.
+//-----------------------------------------------------------------------------
+static int dpiSubscr__checkOpen(dpiSubscr *subscr, const char *fnName,
+        dpiError *error)
+{
+    if (dpiGen__startPublicFn(subscr, DPI_HTYPE_SUBSCR, fnName, 1, error) < 0)
+        return DPI_FAILURE;
+    if (!subscr->handle)
+        return dpiError__set(error, "check closed", DPI_ERR_SUBSCR_CLOSED);
+    if (!subscr->conn->handle || subscr->conn->closing)
+        return dpiError__set(error, "check connection", DPI_ERR_NOT_CONNECTED);
+    return DPI_SUCCESS;
+}
+
+
 //-----------------------------------------------------------------------------
 // dpiSubscr__create() [INTERNAL]
 //   Create a new subscription structure and return it. In case of error NULL
@@ -69,6 +87,7 @@ int dpiSubscr__create(dpiSubscr *subscr, dpiConn *conn,
         dpiSubscrCreateParams *params, uint64_t *subscrId, dpiError *error)
 {
     uint32_t qosFlags;
+    int32_t int32Val;
     int rowids;
 
     // retain a reference to the connection
@@ -76,6 +95,7 @@ int dpiSubscr__create(dpiSubscr *subscr, dpiConn *conn,
     subscr->conn = conn;
     subscr->callback = params->callback;
     subscr->callbackContext = params->callbackContext;
+    subscr->subscrNamespace = params->subscrNamespace;
     subscr->qos = params->qos;
 
     // create the subscription handle
@@ -101,6 +121,13 @@ int dpiSubscr__create(dpiSubscr *subscr, dpiConn *conn,
             DPI_OCI_ATTR_SUBSCR_TIMEOUT, "set timeout", error) < 0)
         return DPI_FAILURE;
 
+    // set the IP address used on the client to listen for events
+    if (params->ipAddress && params->ipAddressLength > 0 &&
+            dpiOci__attrSet(subscr->env->handle, DPI_OCI_HTYPE_ENV,
+                    (void*) params->ipAddress, params->ipAddressLength,
+                    DPI_OCI_ATTR_SUBSCR_IPADDR, "set IP address", error) < 0)
+        return DPI_FAILURE;
+
     // set the port number used on the client to listen for events
     if (params->portNumber > 0 && dpiOci__attrSet(subscr->env->handle,
             DPI_OCI_HTYPE_ENV, (void*) &params->portNumber, 0,
@@ -163,9 +190,44 @@ int dpiSubscr__create(dpiSubscr *subscr, dpiConn *conn,
             DPI_OCI_ATTR_CHNF_OPERATIONS, "set operations", error) < 0)
         return DPI_FAILURE;
 
+    // set grouping information, if applicable
+    if (params->groupingClass) {
+
+        // set grouping class
+        if (dpiOci__attrSet(subscr->handle, DPI_OCI_HTYPE_SUBSCRIPTION,
+                (void*) &params->groupingClass, 0,
+                DPI_OCI_ATTR_SUBSCR_NTFN_GROUPING_CLASS, "set grouping class",
+                error) < 0)
+            return DPI_FAILURE;
+
+        // set grouping value
+        if (dpiOci__attrSet(subscr->handle, DPI_OCI_HTYPE_SUBSCRIPTION,
+                (void*) &params->groupingValue, 0,
+                DPI_OCI_ATTR_SUBSCR_NTFN_GROUPING_VALUE, "set grouping value",
+                error) < 0)
+            return DPI_FAILURE;
+
+        // set grouping type
+        if (dpiOci__attrSet(subscr->handle, DPI_OCI_HTYPE_SUBSCRIPTION,
+                (void*) &params->groupingType, 0,
+                DPI_OCI_ATTR_SUBSCR_NTFN_GROUPING_TYPE, "set grouping type",
+                error) < 0)
+            return DPI_FAILURE;
+
+        // set grouping repeat count
+        int32Val = DPI_SUBSCR_GROUPING_FOREVER;
+        if (dpiOci__attrSet(subscr->handle, DPI_OCI_HTYPE_SUBSCRIPTION,
+                (void*) &int32Val, 0,
+                DPI_OCI_ATTR_SUBSCR_NTFN_GROUPING_REPEAT_COUNT,
+                "set grouping repeat count", error) < 0)
+            return DPI_FAILURE;
+
+    }
+
     // register the subscription
     if (dpiOci__subscriptionRegister(conn, &subscr->handle, error) < 0)
         return DPI_FAILURE;
+    subscr->registered = 1;
 
     // get the registration id, if applicable
     if (subscrId && dpiOci__attrGet(subscr->handle, DPI_OCI_HTYPE_SUBSCRIPTION,
@@ -184,7 +246,9 @@ int dpiSubscr__create(dpiSubscr *subscr, dpiConn *conn,
 void dpiSubscr__free(dpiSubscr *subscr, dpiError *error)
 {
     if (subscr->handle) {
-        dpiOci__subscriptionUnRegister(subscr, error);
+        if (subscr->registered)
+            dpiOci__subscriptionUnRegister(subscr->conn, subscr, error);
+        dpiOci__handleFree(subscr->handle, DPI_OCI_HTYPE_SUBSCRIPTION);
         subscr->handle = NULL;
     }
     if (subscr->conn) {
@@ -230,6 +294,41 @@ static void dpiSubscr__freeMessage(dpiSubscrMessage *message)
 }
 
 
+//-----------------------------------------------------------------------------
+// dpiSubscr__populateAQMessage() [INTERNAL]
+//   Populate message with details.
+//-----------------------------------------------------------------------------
+static int dpiSubscr__populateAQMessage(dpiSubscr *subscr,
+        dpiSubscrMessage *message, void *descriptor, dpiError *error)
+{
+    uint32_t flags = 0;
+
+    // determine if message is a deregistration message
+    if (dpiOci__attrGet(descriptor, DPI_OCI_DTYPE_AQNFY_DESCRIPTOR, &flags,
+            NULL, DPI_OCI_ATTR_NFY_FLAGS, "get flags", error) < 0)
+        return DPI_FAILURE;
+    message->eventType = (flags == 1) ? DPI_EVENT_DEREG : DPI_EVENT_AQ;
+    if (message->eventType == DPI_EVENT_DEREG) {
+        subscr->registered = 0;
+        return DPI_SUCCESS;
+    }
+
+    // determine the name of the queue which spawned the event
+    if (dpiOci__attrGet(descriptor, DPI_OCI_DTYPE_AQNFY_DESCRIPTOR,
+            (void*) &message->queueName, &message->queueNameLength,
+            DPI_OCI_ATTR_QUEUE_NAME, "get queue name", error) < 0)
+        return DPI_FAILURE;
+
+    // determine the consumer name for the queue that spawned the event
+    if (dpiOci__attrGet(descriptor, DPI_OCI_DTYPE_AQNFY_DESCRIPTOR,
+            (void*) &message->consumerName, &message->consumerNameLength,
+            DPI_OCI_ATTR_CONSUMER_NAME, "get consumer name", error) < 0)
+        return DPI_FAILURE;
+
+    return DPI_SUCCESS;
+}
+
+
 //-----------------------------------------------------------------------------
 // dpiSubscr__populateObjectChangeMessage() [INTERNAL]
 //   Populate object change message with details.
@@ -284,6 +383,17 @@ static int dpiSubscr__populateMessage(dpiSubscr *subscr,
 {
     void *rawValue;
 
+    // if quality of service flag indicates that deregistration should take
+    // place when the first notification is received, mark the subscription
+    // as no longer registered
+    if (subscr->qos & DPI_SUBSCR_QOS_DEREG_NFY)
+        subscr->registered = 0;
+
+    // handle AQ messages, if applicable
+    if (subscr->subscrNamespace == DPI_SUBSCR_NAMESPACE_AQ)
+        return dpiSubscr__populateAQMessage(subscr, message, descriptor,
+                error);
+
     // determine the type of event that was spawned
     if (dpiOci__attrGet(descriptor, DPI_OCI_DTYPE_CHDES, &message->eventType,
             NULL, DPI_OCI_ATTR_CHDES_NFYTYPE, "get event type", error) < 0)
@@ -311,7 +421,7 @@ static int dpiSubscr__populateMessage(dpiSubscr *subscr,
             return dpiSubscr__populateQueryChangeMessage(subscr, message,
                     descriptor, error);
         case DPI_EVENT_DEREG:
-            subscr->handle = NULL;
+            subscr->registered = 0;
             break;
         default:
             return dpiError__set(error, "event type", DPI_ERR_NOT_SUPPORTED);
@@ -543,13 +653,12 @@ int dpiSubscr_close(dpiSubscr *subscr)
 {
     dpiError error;
 
-    if (dpiGen__startPublicFn(subscr, DPI_HTYPE_SUBSCR, __func__, 1,
-            &error) < 0)
+    if (dpiSubscr__checkOpen(subscr, __func__, &error) < 0)
         return dpiGen__endPublicFn(subscr, DPI_FAILURE, &error);
-    if (subscr->handle) {
-        if (dpiOci__subscriptionUnRegister(subscr, &error) < 0)
+    if (subscr->registered) {
+        if (dpiOci__subscriptionUnRegister(subscr->conn, subscr, &error) < 0)
             return dpiGen__endPublicFn(subscr, DPI_FAILURE, &error);
-        subscr->handle = NULL;
+        subscr->registered = 0;
     }
 
     return dpiGen__endPublicFn(subscr, DPI_SUCCESS, &error);
@@ -566,8 +675,7 @@ int dpiSubscr_prepareStmt(dpiSubscr *subscr, const char *sql,
     dpiStmt *tempStmt;
     dpiError error;
 
-    if (dpiGen__startPublicFn(subscr, DPI_HTYPE_SUBSCR, __func__, 1,
-            &error) < 0)
+    if (dpiSubscr__checkOpen(subscr, __func__, &error) < 0)
         return dpiGen__endPublicFn(subscr, DPI_FAILURE, &error);
     DPI_CHECK_PTR_NOT_NULL(subscr, sql)
     DPI_CHECK_PTR_NOT_NULL(subscr, stmt)