Ensure prefetchRows is used for REF CURSORS

Author: Christopher Jones

CHANGELOG.md

@@ -17,6 +17,9 @@
   `oracledb.OUT_FORMAT_OBJECT` mode, allowing all columns to be represented in
   the JavaScript object.
 
+- The value of `prefetchRows` set when getting a REF CURSOR as a BIND_OUT
+  parameter is now used in the subsequent data retrieval from that cursor.
+
 - Fixed a compatibility regression affecting SODA "get" operations using older
   Oracle Client releases.
 

doc/api.md

@@ -1798,10 +1798,11 @@ to return query results, see [Tuning Fetch Performance](#rowfetching).
 The `prefetchRows` value is ignored in some cases, such as when the query
 involves a LOB.
 
-If you fetch a REF CURSOR and subsequently pass it back to a PL/SQL block, then
-set `prefetchRows` to 0 during the initial query to ensure that rows are not
-internally fetched from the REF CURSOR by node-oracledb thus making them
-unavailable in the PL/SQL code.
+If you fetch a REF CURSOR, retrieve rows from that cursor, and then pass it back
+to a PL/SQL block, you should set `prefetchRows` to 0 during the initial
+statement that gets the REF CURSOR.  This ensures that rows are not internally
+fetched from the REF CURSOR by node-oracledb thus making them unavailable in the
+final PL/SQL code.
 
 The default value is 2.
 

src/njsVariable.c

@@ -44,6 +44,9 @@ static bool njsVariable_setInvalidBind(njsVariable *var, uint32_t pos,
 bool njsVariable_createBuffer(njsVariable *var, njsConnection *conn,
         njsBaton *baton)
 {
+    dpiData *data;
+    uint32_t i;
+
     // if the variable is not an array use the bind array size
     if (!var->isArray)
         var->maxArraySize = baton->bindArraySize;
@@ -116,6 +119,20 @@ bool njsVariable_createBuffer(njsVariable *var, njsConnection *conn,
             &var->buffer->dpiVarData) < 0)
         return njsBaton_setErrorDPI(baton);
 
+    // for cursors, set the prefetch value, if it differs from the default;
+    // also mark the variable as not null in order for the prefetch rows to
+    // take effect
+    if (var->nativeTypeNum == DPI_NATIVE_TYPE_STMT &&
+            baton->prefetchRows != DPI_DEFAULT_PREFETCH_ROWS) {
+        for (i = 0; i < var->maxArraySize; i++) {
+            data = &var->buffer->dpiVarData[i];
+            data->isNull = 0;
+            if (dpiStmt_setPrefetchRows(data->value.asStmt,
+                    baton->prefetchRows) < 0)
+                return njsBaton_setErrorDPI(baton);
+        }
+    }
+
     return true;
 }
 

test/list.txt

@@ -3760,6 +3760,9 @@ oracledb.OUT_FORMAT_OBJECT and resultSet =  true
     147.12 Negative - null
     147.13 Negative - random string
     147.14 Negative - Boolean
+    147.15 Query round-trips with no prefetch
+    147.16 Query round-trips with prefetch equal to row count
+    147.17 Query round-trips with prefetch larger than row count
 
 148. fetchArraySize1.js
     148.1 oracledb.fetchArraySize
@@ -4737,6 +4740,8 @@ oracledb.OUT_FORMAT_OBJECT and resultSet =  true
     239.2 prefetchRows is enabled with default value
     239.3 cursor bind OUT then bind IN
     239.4 implicit binding type
+    239.5 check REF CURSOR round-trips with no prefetching
+    239.6 check REF CURSOR round-trips with prefetching
 
 240. errorOffset.js
     240.1 checks the offset value of the error
@@ -4780,7 +4785,7 @@ oracledb.OUT_FORMAT_OBJECT and resultSet =  true
         243.1.1 OUT bind DB Object
         243.1.2 IN OUT bind DB Object
     243.2 set dbObjectAsPojo in BIND_OUT and BIND_INOUT options
-        243.2.1 OUT bind DB Object 
+        243.2.1 OUT bind DB Object
         243.2.2 IN OUT bind DB Object
     243.3 set dbObjectAsPojo in bind variables doesn't work
         243.3.1 OUT bind DB Object

test/plsqlBindCursorsIN.js

@@ -50,6 +50,7 @@ describe('239. plsqlBindCursorsIN.js', () => {
     select 4, 'String 4' from dual
     union all
     select 5, 'String 5' from dual
+    order by 1
   `;
 
   before(async () => {
@@ -99,7 +100,8 @@ describe('239. plsqlBindCursorsIN.js', () => {
                 union all
                 select 4, 'String 4' from dual
                 union all
-                select 5, 'String 5' from dual;
+                select 5, 'String 5' from dual
+                order by 1;
         end;
       `;
       await conn.execute(plsql);
@@ -235,4 +237,64 @@ describe('239. plsqlBindCursorsIN.js', () => {
       should.not.exist(error);
     }
   }); // 239.4
-});
+
+  it('239.5 check REF CURSOR round-trips with no prefetching', async () => {
+    if (!dbconfig.test.DBA_PRIVILEGE) {
+      it.skip('');
+      return;
+    }
+    try {
+      const sid = await testsUtil.getSid(conn);
+      let rt = await testsUtil.getRoundTripCount(sid);
+      let result = await conn.execute(
+        `begin ${procName2}(:bv); end;`,
+        {
+          bv: {dir: oracledb.BIND_OUT, type: oracledb.CURSOR }
+        },
+        {
+          prefetchRows: 0
+        }
+      );
+      const rc = result.outBinds.bv;
+      await rc.getRows(2);
+      await rc.getRows(2);
+      rt = await testsUtil.getRoundTripCount(sid) - rt;
+
+      should.strictEqual(rt, 3);
+
+    } catch (error) {
+      should.not.exist(error);
+    }
+  }); // 239.5
+
+  it('239.6 check REF CURSOR round-trips with prefetching', async () => {
+    if (!dbconfig.test.DBA_PRIVILEGE) {
+      it.skip('');
+      return;
+    }
+    try {
+      const sid = await testsUtil.getSid(conn);
+      let rt = await testsUtil.getRoundTripCount(sid);
+
+      let result = await conn.execute(
+        `begin ${procName2}(:bv); end;`,
+        {
+          bv: {dir: oracledb.BIND_OUT, type: oracledb.CURSOR }
+        },
+        {
+          prefetchRows: 100
+        }
+      );
+      const rc = result.outBinds.bv;
+      await rc.getRows(2);
+      await rc.getRows(2);
+      rt = await testsUtil.getRoundTripCount(sid) - rt;
+
+      should.strictEqual(rt, 2);
+
+    } catch (error) {
+      should.not.exist(error);
+    }
+  }); // 239.6
+
+});

test/prefetchRows.js

@@ -28,11 +28,24 @@ const oracledb = require('oracledb');
 const should   = require('should');
 const assert   = require('assert');
 const dbconfig = require('./dbconfig.js');
+const testsUtil = require('./testsUtil.js');
 
 describe("147. prefetchRows.js", function() {
 
   let conn;
 
+  const sql = `
+    select 1, 'String 1' from dual
+    union all
+    select 2, 'String 2' from dual
+    union all
+    select 3, 'String 3' from dual
+    union all
+    select 4, 'String 4' from dual
+    union all
+    select 5, 'String 5' from dual
+    order by 1`;
+
   const DefaultPrefetchRows = oracledb.prefetchRows;
   before(async () => {
     try {
@@ -236,4 +249,58 @@ describe("147. prefetchRows.js", function() {
     }
   });
 
-});
+  it('147.15 Query round-trips with no prefetch', async () => {
+    if (!dbconfig.test.DBA_PRIVILEGE) {
+      return;
+    }
+    try {
+      const sid = await testsUtil.getSid(conn);
+      let rt = await testsUtil.getRoundTripCount(sid);
+
+      await conn.execute(sql, [], { prefetchRows: 0 });
+      rt = await testsUtil.getRoundTripCount(sid) - rt;
+
+      should.strictEqual(rt, 2);
+
+    } catch (error) {
+      should.not.exist(error);
+    }
+  });
+
+  it('147.16 Query round-trips with prefetch equal to row count', async () => {
+    if (!dbconfig.test.DBA_PRIVILEGE) {
+      return;
+    }
+    try {
+      const sid = await testsUtil.getSid(conn);
+      let rt = await testsUtil.getRoundTripCount(sid);
+
+      await conn.execute(sql, [], { prefetchRows: 5 });
+      rt = await testsUtil.getRoundTripCount(sid) - rt;
+
+      should.strictEqual(rt, 2);
+
+    } catch (error) {
+      should.not.exist(error);
+    }
+  });
+
+  it('147.16 Query round-trips with prefetch larger than row count', async () => {
+    if (!dbconfig.test.DBA_PRIVILEGE) {
+      return;
+    }
+    try {
+      const sid = await testsUtil.getSid(conn);
+      let rt = await testsUtil.getRoundTripCount(sid);
+
+      await conn.execute(sql, [], { prefetchRows: 6 });
+      rt = await testsUtil.getRoundTripCount(sid) - rt;
+
+      should.strictEqual(rt, 1);
+
+    } catch (error) {
+      should.not.exist(error);
+    }
+  });
+
+});

test/testsUtil.js

@@ -212,11 +212,43 @@ testsUtil.measureNetworkRoundTripTime = async function() {
   return new Date() - startTime;
 };
 
+testsUtil.getSid = async function(conn) {
+  const sql = `select sys_context('userenv','sid') from dual`;
+  const result = await conn.execute(sql);
+  return result.rows[0][0];  // session id
+};
+
+testsUtil.getRoundTripCount = async function(sid) {
+  if (!dbconfig.test.DBA_PRIVILEGE) {
+    let msg = "Note: DBA privilege environment variable is not true!\n";
+    msg += "Without DBA privilege the test cannot get the current round trip count!";
+    throw new Error(msg);
+  } else {
+    let dbaCredential = {
+      user:          dbconfig.test.DBA_user,
+      password:      dbconfig.test.DBA_password,
+      connectString: dbconfig.connectString,
+      privilege:     oracledb.SYSDBA
+    };
+
+    const sql = `
+      select ss.value
+      from v$sesstat ss, v$statname sn
+      where ss.sid = :sid
+        and ss.statistic# = sn.statistic#
+        and sn.name like '%roundtrip%client%'`;
+    const conn = await oracledb.getConnection(dbaCredential);
+    const result = await conn.execute(sql, [sid]);
+    await conn.close();
+    return result.rows[0][0];  // number of round-trips executed so far in the session
+  }
+};
+
 testsUtil.createAQtestUser = async function(AQ_USER, AQ_USER_PWD) {
 
   if (!dbconfig.test.DBA_PRIVILEGE) {
-    let msg = "Note: DBA privilege environment variable is false!\n";
-    msg += "Without DBA privilege, it could not create schema!";
+    let msg = "Note: DBA privilege environment variable is not true!\n";
+    msg += "Without DBA privilege, the test cannot create the schema!";
     throw new Error(msg);
   } else {
     let dbaCredential = {
@@ -265,7 +297,8 @@ testsUtil.createAQtestUser = async function(AQ_USER, AQ_USER_PWD) {
 
 testsUtil.dropAQtestUser = async function(AQ_USER) {
   if (!dbconfig.test.DBA_PRIVILEGE) {
-    let msg = "Without DBA privilege, it could not drop schema!\n";
+    let msg = "Note: DBA privilege environment variable is not true!\n";
+    msg += "Without DBA privilege, the test cannot drop the schema!\n";
     throw new Error(msg);
   } else {
     let dbaCredential = {