Add DML RETURNING support

Author: cjbj

doc/api.md

@@ -936,7 +936,7 @@ Callback function parameter | Description
 ##### Prototype
 
 ```
-void execute(String sql, [Object bindParams, [Object options,]] function(Error error, [Object result]){});
+void execute(String sql [, Object bindParams [, Object options]], function(Error error [, Object result]){});
 ```
 
 ##### Return Value
@@ -1013,7 +1013,7 @@ Options Property | Description
 *String outFormat* | Overrides *Oracledb* [`outFormat`](#propdboutformat)
 
 ```
-function(Error error, [Object result])
+function(Error error [, Object result])
 ```
 
 The parameters of the callback function are:

examples/demo.sql

@@ -41,3 +41,10 @@ SHOW ERRORS
 DROP TABLE j_purchaseorder;
 CREATE TABLE j_purchaseorder
     (po_document VARCHAR2(4000) CONSTRAINT ensure_json CHECK (po_document IS JSON));
+
+-- DML RETURNING
+DROP TABLE dmlrupdtab;
+CREATE TABLE dmlrupdtab (id NUMBER, name VARCHAR2(40));
+INSERT INTO dmlrupdtab VALUES (1001, 'Venkat');
+INSERT INTO dmlrupdtab VALUES (1002, 'Neeharika');
+COMMIT;

examples/dmlrupd1.js

@@ -0,0 +1,67 @@
+/* Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. */
+
+/******************************************************************************
+ *
+ * You may not use the identified files except in compliance with the Apache
+ * License, Version 2.0 (the "License.")
+ *
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * NAME
+ *   dmlrupd1.js
+ *
+ * DESCRIPTION
+ *   Example of 'DML Returning' with a single row match
+ *   Use demo.sql to create the required table or do:
+ *     DROP TABLE dmlrupdtab;
+ *     CREATE TABLE dmlrupdtab (id NUMBER, name VARCHAR2(40));
+ *     INSERT INTO dmlrupdtab VALUES (1001, 'Venkat');
+ *     INSERT INTO dmlrupdtab VALUES (1002, 'Neeharika');
+ *     COMMIT;
+ *
+ *****************************************************************************/
+
+var oracledb = require( 'oracledb' );
+var dbConfig = require('./dbconfig.js');
+
+oracledb.getConnection(
+  {
+    user          : dbConfig.user,
+    password      : dbConfig.password,
+    connectString : dbConfig.connectString
+  },
+  function(err, connection)
+  {
+    if (err)
+    {
+      console.error(err);
+      return;
+    }
+
+    connection.execute(
+      "UPDATE DMLRUPDTAB SET NAME = :name WHERE ID = :id RETURNING ID, NAME INTO :RID, :RNAME",
+      {
+        id:    1001,
+        name:  "Krishna",
+        rid:   { type: oracledb.NUMBER, dir: oracledb.BIND_OUT },
+        rname: { type: oracledb.STRING, dir: oracledb.BIND_OUT }
+      },
+      { isAutoCommit: true },
+      function(err, result)
+      {
+        if (err)
+        {
+          console.error(err);
+          return;
+        }
+        console.log(result.outBinds);
+      });
+  });

examples/dmlrupd2.js

@@ -0,0 +1,66 @@
+/* Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. */
+
+/******************************************************************************
+ *
+ * You may not use the identified files except in compliance with the Apache
+ * License, Version 2.0 (the "License.")
+ *
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * NAME
+ *   dmlrupd2.js
+ *
+ * DESCRIPTION
+ *   Example of 'DML Returning' with multiple rows matched
+ *   Use demo.sql to create the required table or do:
+ *     DROP TABLE dmlrupdtab;
+ *     CREATE TABLE dmlrupdtab (id NUMBER, name VARCHAR2(40));
+ *     INSERT INTO dmlrupdtab VALUES (1001, 'Venkat');
+ *     INSERT INTO dmlrupdtab VALUES (1002, 'Neeharika');
+ *     COMMIT;
+ *
+ *****************************************************************************/
+
+var oracledb = require( 'oracledb' );
+var dbConfig = require('./dbconfig.js');
+
+oracledb.getConnection(
+  {
+    user          : dbConfig.user,
+    password      : dbConfig.password,
+    connectString : dbConfig.connectString
+  },
+  function(err, connection)
+  {
+    if (err)
+    {
+      console.error(err);
+      return;
+    }
+
+    connection.execute(
+      "UPDATE DMLRUPDTAB SET NAME = :name RETURNING ID, NAME INTO :RID, :RNAME",
+      {
+        name:  "Chris",
+        rid:   { type: oracledb.NUMBER, dir: oracledb.BIND_OUT },
+        rname: { type: oracledb.STRING, dir: oracledb.BIND_OUT }
+      },
+      { isAutoCommit: true },
+      function(err, result)
+      {
+        if (err)
+        {
+          console.error(err);
+          return;
+        }
+        console.log(result.outBinds);
+      });
+  });

src/dpi/include/dpiStmt.h

@@ -131,6 +131,11 @@ typedef struct
 } MetaData;
 
 
+// Application (Driver) level callback function prototype
+typedef int (*cbtype) (void *ctx, DPI_SZ_TYPE nRows, unsigned long iter,
+                       unsigned long index, dvoid **bufpp, void **alenp,
+                       dvoid **indpp, unsigned short **rcodepp,
+                       unsigned char *piecep );
 
 class Stmt
 {
@@ -141,17 +146,23 @@ class Stmt
                                 // properties
   virtual DpiStmtType stmtType() const = 0;
 
+  virtual bool        isDML() const = 0 ;
+
+  virtual bool        isReturning() = 0 ;
+
   virtual DPI_SZ_TYPE  rowsAffected() const = 0;
 
   virtual unsigned int numCols() = 0;
 
                                 // methods
   virtual void bind(unsigned int pos, unsigned short type, void  *buf,
-                    DPI_SZ_TYPE bufSize, short *ind, DPI_BUFLEN_TYPE *bufLen) = 0;
+                    DPI_SZ_TYPE bufSize, short *ind, DPI_BUFLEN_TYPE *bufLen,
+                    void *data, cbtype cb = NULL ) = 0;
 
   virtual void bind(const unsigned char *name, int nameLen,
                     unsigned short type,  void *buf, DPI_SZ_TYPE  bufSize,
-                    short *ind, DPI_BUFLEN_TYPE *bufLen) = 0;
+                    short *ind, DPI_BUFLEN_TYPE *bufLen,
+                    void *data, cbtype cb = NULL ) = 0;
 
   virtual void execute ( int numIterations, bool isAutoCommit = false) = 0;