Add Success With Info Warnings support

Author: sharadraju

doc/src/release_notes.rst

@@ -13,6 +13,13 @@ node-oracledb `v6.3.0 <https://github.com/oracle/node-oracledb/compare/v6.2.0...
 Common Changes
 ++++++++++++++
 
+#)  Added a ``warning`` property to the ``result`` object for database
+    warnings (such as PL/SQL compilation warnings) generated by calls to
+    :meth:`connection.execute()` or :meth:`connection.executeMany()`.
+
+#)  Added property :attr:`connection.warning` for warnings (such as the
+    password being in the grace period) generated during connection.
+
 #)  VARCHAR2 and LOB columns which contain JSON, and have the "IS JSON" check
     constraint enabled, can now be fetched in the same way as columns of type
     JSON. In node-oracledb :ref:`Thick mode <enablingthick>` this requires

lib/connection.js

@@ -865,6 +865,11 @@ class Connection extends EventEmitter {
       throw err;
     }
 
+    // convert ORA errors to NJS
+    if (result.warning) {
+      result.warning = errors.transformErr(result.warning);
+    }
+
     // process queries; if a result set is not desired, fetch all of the rows
     // from the result set and then destroy the result set
     if (result.resultSet !== undefined) {
@@ -1107,6 +1112,21 @@ class Connection extends EventEmitter {
     return this._impl && this._impl.getMaxOpenCursors();
   }
 
+  //---------------------------------------------------------------------------
+  // warning
+  //
+  // Returns warningInfo.
+  //---------------------------------------------------------------------------
+  get warning() {
+    let warning = this._impl.getWarning();
+    if (warning) {
+      // Make sure that warning code attribute is populated and ORA error
+      // is converted to NJS, if required
+      warning = errors.transformErr(warning);
+    }
+    return this._impl && warning;
+  }
+
   //---------------------------------------------------------------------------
   // module
   //

lib/errors.js

@@ -162,6 +162,9 @@ const ERR_INVALID_SID = 519;
 const ERR_TNS_NAMES_FILE_MISSING = 520;
 const ERR_CONNECTION_EOF = 521;
 
+// Oracle SUCCESS_WITH_INFO warning start from 700
+const WRN_COMPILATION_CREATE = 700;
+
 // define mapping for ODPI-C, OCI & ORA errors that need to be wrapped
 // with NJS errors
 const adjustErrorXref = new Map();
@@ -180,6 +183,7 @@ adjustErrorXref.set("ORA-00028", ERR_CONNECTION_CLOSED);
 adjustErrorXref.set("ORA-00600", ERR_CONNECTION_CLOSED);
 adjustErrorXref.set("ORA-24338", ERR_INVALID_REF_CURSOR);
 adjustErrorXref.set("ORA-25708", ERR_TOKEN_HAS_EXPIRED);
+adjustErrorXref.set("ORA-24344", WRN_COMPILATION_CREATE);
 
 // define mapping for error messages
 const messages = new Map();
@@ -445,6 +449,11 @@ messages.set(ERR_TNS_NAMES_FILE_MISSING,                // NJS-520
 messages.set(ERR_CONNECTION_EOF,                        // NJS-521
   'connection to host %s port %d received end-of-file on communication channel. (CONNECTION_ID=%s)');
 
+// Oracle SUCCESS_WITH_INFO warning
+
+messages.set(WRN_COMPILATION_CREATE,                           // NJS-700
+  'creation succeeded with compilation errors');
+
 //-----------------------------------------------------------------------------
 // assert()
 //
@@ -781,6 +790,7 @@ module.exports = {
   ERR_UNEXPECTED_XML_TYPE,
   ERR_WRONG_USER_FORMAT_EXTAUTH_PROXY,
   ERR_CONNECTION_CLOSED_CODE: `${ERR_PREFIX}-${ERR_CONNECTION_CLOSED}`,
+  WRN_COMPILATION_CREATE,
   assert,
   assertArgCount,
   assertParamPropBool,

lib/impl/connection.js

@@ -354,6 +354,15 @@ class ConnectionImpl {
       " on the connection");
   }
 
+  //---------------------------------------------------------------------------
+  // getWarning()
+  //
+  // Returns a warning on a connection
+  //---------------------------------------------------------------------------
+  getWarning() {
+    errors.throwNotImplemented("getting information about warning");
+  }
+
   //---------------------------------------------------------------------------
   // isHealthy()
   //

lib/thin/connection.js

@@ -206,6 +206,9 @@ class ThinConnectionImpl extends ConnectionImpl {
 
     // process results
     const result = {};
+    if (message.warning) {
+      result.warning = message.warning;
+    }
     if (statement.numQueryVars > 0) {
       result.resultSet = message.resultSet;
     } else {
@@ -1120,5 +1123,12 @@ class ThinConnectionImpl extends ConnectionImpl {
   getTransactionInProgress() {
     return this._protocol.txnInProgress === constants.TNS_TXN_IN_PROGRESS;
   }
+
+  //---------------------------------------------------------------------------
+  // Returns the warning object.
+  //---------------------------------------------------------------------------
+  getWarning() {
+    return this.warning;
+  }
 }
 module.exports = ThinConnectionImpl;

lib/thin/pool.js

@@ -541,6 +541,7 @@ class ThinPoolImpl extends PoolImpl {
 
   // release connection to connection pool
   release(conn) {
+    conn.warning = undefined;
     this._usedConnectionList.delete(conn);
     if (conn.nscon.connected) {
       conn._lastTimeUsed = Date.now();

lib/thin/protocol/constants.js

@@ -757,6 +757,9 @@ module.exports = {
   TNS_ERR_NO_DATA_FOUND: 1403,
   TNS_ERR_SESSION_SHUTDOWN: 12572,
 
+  // warnings
+  TNS_WARN_COMPILATION_CREATE: 0x20,
+
   // other constants
   PACKET_HEADER_SIZE: 8,
   NUMBER_AS_TEXT_CHARS: 172,

lib/thin/protocol/messages/auth.js

@@ -327,6 +327,7 @@ class AuthMessage extends Message {
       this.conn.instanceName = this.sessionData['AUTH_INSTANCENAME'];
       const fullVersionNum = Number(this.sessionData['AUTH_VERSION_NO']);
       const versionNum = (fullVersionNum >> 24) & 0xFF;
+      this.conn.warning = this.warning;
       if (buf.caps.ttcFieldVersion >= constants.TNS_CCAP_FIELD_VERSION_18_1_EXT_1) {
         releaseNum = (fullVersionNum >> 16) & 0xFF;
         updateNum = (fullVersionNum >> 12) & 0x0F;

lib/thin/protocol/messages/base.js

@@ -44,9 +44,9 @@ class Message {
     this.flushOutBinds = false;
     this.endToEndSeqNum = 0;
     this.errorOccurred = false;
-    this.isWarning = false;
     this.flushOutBinds = false;
     this.processedError = false;
+    this.warning = undefined;
   }
 
   preProcess() { }
@@ -75,7 +75,10 @@ class Message {
     buf.skipUB1();                              // flags
     buf.skipUB1();                              // user cursor options
     buf.skipUB1();                              // UPI parameter
-    buf.skipUB1();                              // warning flag
+    const warnFlag = buf.readUInt8();           // warning flag
+    if (warnFlag & constants.TNS_WARN_COMPILATION_CREATE) {
+      this.warning = errors.getErr(errors.WRN_COMPILATION_CREATE);
+    }
     this.errorInfo.rowID = buf.readRowID();     // rowid
     buf.skipUB4();                              // OS error
     buf.skipUB1();                              // statement error
@@ -149,22 +152,23 @@ class Message {
       /*
        * Remove ending newline from ORA error message
        */
-      this.errorInfo.message = this.errorInfo.message.replace(/\n+$/, "");
+      this.errorInfo.message = this.errorInfo.message.trim();
     }
-    this.errorInfo.isWarning = false;
     this.processedError = true;
   }
 
   processReturnParameter() { }
 
   processWarningInfo(buf) {
-    this.errorInfo.num = buf.readUB2();         // error number
-    const numBytes = buf.readUB2();             // length of error message
-    buf.skipUB2();                              // flags
-    if (this.errorInfo.num != 0 && numBytes > 0) {
-      this.errorInfo.message = buf.readStr(constants.CSFRM_IMPLICIT);
+    const errNum = buf.readUB2();              // warning number
+    const numBytes = buf.readUB2();            // length of warning message
+    buf.skipUB2();                             // flags
+    if (errNum != 0 && numBytes > 0) {
+      // get message string and remove the ending newline.
+      const message = buf.readStr(constants.CSFRM_IMPLICIT).trim();
+      this.warning = new Error(message);
+      this.warning.errorNum = errNum;
     }
-    this.errorInfo.isWarning = true;
   }
 
   hasMoreData(buf) {

src/njsConnection.c

@@ -58,6 +58,7 @@ NJS_NAPI_METHOD_DECL_ASYNC(njsConnection_getStatementInfo);
 NJS_NAPI_METHOD_DECL_SYNC(njsConnection_getStmtCacheSize);
 NJS_NAPI_METHOD_DECL_SYNC(njsConnection_getTag);
 NJS_NAPI_METHOD_DECL_SYNC(njsConnection_getTransactionInProgress);
+NJS_NAPI_METHOD_DECL_SYNC(njsConnection_getWarning);
 NJS_NAPI_METHOD_DECL_SYNC(njsConnection_isHealthy);
 NJS_NAPI_METHOD_DECL_ASYNC(njsConnection_ping);
 NJS_NAPI_METHOD_DECL_ASYNC(njsConnection_rollback);
@@ -175,6 +176,8 @@ static const napi_property_descriptor njsClassProperties[] = {
             NULL },
     { "getTransactionInProgress", NULL, njsConnection_getTransactionInProgress,
             NULL, NULL, NULL, napi_default, NULL },
+    { "getWarning", NULL, njsConnection_getWarning, NULL, NULL, NULL,
+            napi_default, NULL },
     { "isHealthy", NULL, njsConnection_isHealthy, NULL, NULL, NULL,
             napi_default, NULL },
     { "ping", NULL, njsConnection_ping, NULL, NULL, NULL, napi_default,
@@ -483,6 +486,9 @@ static bool njsConnection_connectAsync(njsBaton *baton)
             &baton->dpiConnHandle) < 0)
         return njsBaton_setErrorDPI(baton);
 
+    // handle warnings if any
+    dpiContext_getError(baton->globals->context, &baton->warningInfo);
+
     return true;
 }
 
@@ -496,6 +502,11 @@ static bool njsConnection_connectPostAsync(njsBaton *baton, napi_env env,
 {
     njsConnection *conn = (njsConnection*) baton->callingInstance;
 
+    // process warnings if any
+    if (baton->warningInfo.isWarning) {
+        conn->warningInfo = baton->warningInfo;
+    }
+
     // transfer the ODPI-C connection handle to the new object
     conn->handle = baton->dpiConnHandle;
     baton->dpiConnHandle = NULL;
@@ -662,6 +673,9 @@ static bool njsConnection_executeAsync(njsBaton *baton)
     if (dpiStmt_execute(baton->dpiStmtHandle, mode, &baton->numQueryVars) < 0)
         return njsBaton_setErrorDPI(baton);
 
+    // handle warnings if any
+    dpiContext_getError(baton->globals->context, &baton->warningInfo);
+
     // for queries, initialize query variables
     if (baton->numQueryVars > 0) {
 
@@ -698,7 +712,7 @@ static bool njsConnection_executeAsync(njsBaton *baton)
 static bool njsConnection_executePostAsync(njsBaton *baton, napi_env env,
         napi_value *result)
 {
-    napi_value resultSet, rowsAffected, outBinds, lastRowid;
+    napi_value resultSet, rowsAffected, outBinds, lastRowid, error;
     napi_value implicitResults;
     uint32_t rowidValueLength;
     const char *rowidValue;
@@ -711,6 +725,14 @@ static bool njsConnection_executePostAsync(njsBaton *baton, napi_env env,
     // create result object
     NJS_CHECK_NAPI(env, napi_create_object(env, result))
 
+    // process warnings if any
+    if (baton->warningInfo.isWarning) {
+        if (!njsUtils_getError(env, &baton->warningInfo, NULL, &error))
+            return false;
+        NJS_CHECK_NAPI(env, napi_set_named_property(env, *result, "warning",
+                error))
+    }
+
     // handle queries
     if (baton->queryVars) {
 
@@ -1700,6 +1722,25 @@ NJS_NAPI_METHOD_IMPL_SYNC(njsConnection_getTransactionInProgress, 0, NULL)
 }
 
 
+//-----------------------------------------------------------------------------
+// njsConnection_getWarning()
+//  Get the warning set on connection object. This is set at connection
+//  creation time. The only warning expected is password-will-expire-soon
+//-----------------------------------------------------------------------------
+NJS_NAPI_METHOD_IMPL_SYNC(njsConnection_getWarning, 0, NULL)
+{
+    njsConnection *conn = (njsConnection*) callingInstance;
+
+    if (conn->handle) {
+        if (conn->warningInfo.isWarning) {
+            if (!njsUtils_getError(env, &conn->warningInfo, NULL, returnValue))
+                return njsUtils_throwErrorDPI(env, globals);
+        }
+    }
+    return true;
+}
+
+
 //-----------------------------------------------------------------------------
 // njsConnection_newFromBaton()
 //   Called when a connection is being created from the baton.
@@ -1727,6 +1768,10 @@ bool njsConnection_newFromBaton(njsBaton *baton, napi_env env,
         baton->tagLength = 0;
     }
 
+    // transfer any warning information to the connection
+    if (baton->warningInfo.isWarning) {
+        conn->warningInfo = baton->warningInfo;
+    }
     return true;
 }