Updated Python & Node.js examples for cx_Oracle 8.2 and node-oracledb 5.2

javascript/node-oracledb/README.md

@@ -1,14 +1,15 @@
 # Node-oracledb Examples
 
-This directory contains [node-oracledb](https://www.npmjs.com/package/oracledb) examples.
+This directory contains [node-oracledb](https://www.npmjs.com/package/oracledb)
+examples.  Documentation is [here
+](https://oracle.github.io/node-oracledb/doc/api.html).
 
 To run the examples:
 
 - [Install node-oracledb](https://oracle.github.io/node-oracledb/INSTALL.html#quickstart).
 
-
-- Edit `dbconfig.js` and set your username, password and the database
-connection string, for example:
+- Edit `dbconfig.js` and set your username and the database connection string,
+for example:
 
   ```
   module.exports = {
@@ -19,9 +20,8 @@ connection string, for example:
 
   ```
 
-  This reads the password from the environment variable
-  `NODE_ORACLEDB_PASSWORD`, which you must set before running
-  examples.
+- In a terminal window, set the environment variable `NODE_ORACLEDB_PASSWORD` to
+  the value of your database password.
 
 - Review the samples and then run them like:
 
@@ -58,8 +58,7 @@ File Name                                                 | Description
 [`dbmsoutputpipe.js`](dbmsoutputpipe.js)                  | Show fetching DBMS_OUTPUT by using a pipelined table
 [`demodrop.js`](demodrop.js)                              | Drops the schema objects created by the examples
 [`demosetup.js`](demosetup.js)                            | Used to create common schema objects for the examples
-[`dmlrupd1.js`](dmlrupd1.js)                              | Example of DML RETURNING with a single row match
-[`dmlrupd2.js`](dmlrupd2.js)                              | Example of DML RETURNING where multiple rows are matched
+[`dmlrupd.js`](dmlrupd.js)                                | Example of DML RETURNING where multiple rows are matched
 [`em_batcherrors.js`](em_batcherrors.js)                  | `executeMany()` example showing handling data errors
 [`em_dmlreturn1.js`](em_dmlreturn1.js)                    | `executeMany()` example of DML RETURNING that returns single values
 [`em_dmlreturn2.js`](em_dmlreturn2.js)                    | `executeMany()` example of DML RETURNING that returns multiple values
@@ -73,6 +72,7 @@ File Name                                                 | Description
 [`impres.js`](impres.js)                                  | Shows PL/SQL 'Implict Results' returning multiple query results from PL/SQL code.
 [`insert1.js`](insert1.js)                                | Basic example creating a table and inserting data.  Shows DDL and DML
 [`insert2.js`](insert2.js)                                | Basic example showing auto commit behavior
+[`lastinsertid.js`](lastinsertid.js)                      | Shows inserting a row and getting its ROWID.
 [`lobbinds.js`](lobbinds.js)                              | Demonstrates how to bind and query LOBs
 [`lobinsert1.js`](lobinsert1.js)                          | Shows inserting a file into a CLOB column
 [`lobinsert2.js`](lobinsert2.js)                          | Inserts text into a CLOB column using the RETURNING INTO method.
@@ -97,7 +97,7 @@ File Name                                                 | Description
 [`select1.js`](select1.js)                                | Executes a basic query without using a connection pool or ResultSet
 [`select2.js`](select2.js)                                | Executes queries to show array and object output formats
 [`selectgeometry.js`](selectgeometry.js)                  | Insert and query Oracle Spatial geometries
-[`selectjson.js`](selectjson.js)                          | Shows some JSON features of Oracle Database
+[`selectjson.js`](selectjson.js)                          | Shows some JSON features of Oracle Database 21c
 [`selectjsonblob.js`](selectjsonblob.js)                  | Shows how to use a BLOB as a JSON column store
 [`selectobject.js`](selectobject.js)                      | Insert and query a named Oracle database object
 [`selectnestedcursor.js`](selectnestedcursor.js)          | Shows selecting from a nested cursor
@@ -108,4 +108,4 @@ File Name                                                 | Description
 [`sessiontagging2.js`](sessiontagging2.js)                | More complex example of pooled connection tagging for setting session state
 [`soda1.js`](soda1.js)                                    | Basic Simple Oracle Document Access (SODA) example
 [`version.js`](version.js)                                | Shows the node-oracledb version attributes
-[`webappawait.js`](webappawait.js)                        | A simple web application using a connection pool
+[`webapp.js`](webapp.js)                                  | A simple web application using a connection pool

javascript/node-oracledb/aqmulti.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2019, 2021, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -33,6 +33,17 @@
 const oracledb = require('oracledb');
 const dbConfig = require('./dbconfig.js');
 
+// On Windows and macOS, you can specify the directory containing the Oracle
+// Client Libraries at runtime, or before Node.js starts.  On other platforms
+// the system library search path must always be set before Node.js is started.
+// See the node-oracledb installation documentation.
+// If the search path is not correct, you will get a DPI-1047 error.
+if (process.platform === 'win32') { // Windows
+  oracledb.initOracleClient({ libDir: 'C:\\oracle\\instantclient_19_11' });
+} else if (process.platform === 'darwin') { // macOS
+  oracledb.initOracleClient({ libDir: process.env.HOME + '/Downloads/instantclient_19_8' });
+}
+
 const queueName = "DEMO_RAW_QUEUE";
 
 async function enq() {

javascript/node-oracledb/aqobject.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2019, 2021, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -34,6 +34,17 @@
 const oracledb = require('oracledb');
 const dbConfig = require('./dbconfig.js');
 
+// On Windows and macOS, you can specify the directory containing the Oracle
+// Client Libraries at runtime, or before Node.js starts.  On other platforms
+// the system library search path must always be set before Node.js is started.
+// See the node-oracledb installation documentation.
+// If the search path is not correct, you will get a DPI-1047 error.
+if (process.platform === 'win32') { // Windows
+  oracledb.initOracleClient({ libDir: 'C:\\oracle\\instantclient_19_11' });
+} else if (process.platform === 'darwin') { // macOS
+  oracledb.initOracleClient({ libDir: process.env.HOME + '/Downloads/instantclient_19_8' });
+}
+
 const queueName = "ADDR_QUEUE";
 
 async function enq() {

javascript/node-oracledb/aqoptions.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2019, 2021, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -33,6 +33,17 @@
 const oracledb = require('oracledb');
 const dbConfig = require('./dbconfig.js');
 
+// On Windows and macOS, you can specify the directory containing the Oracle
+// Client Libraries at runtime, or before Node.js starts.  On other platforms
+// the system library search path must always be set before Node.js is started.
+// See the node-oracledb installation documentation.
+// If the search path is not correct, you will get a DPI-1047 error.
+if (process.platform === 'win32') { // Windows
+  oracledb.initOracleClient({ libDir: 'C:\\oracle\\instantclient_19_11' });
+} else if (process.platform === 'darwin') { // macOS
+  oracledb.initOracleClient({ libDir: process.env.HOME + '/Downloads/instantclient_19_8' });
+}
+
 const queueName = "DEMO_RAW_QUEUE";
 
 async function enq() {

javascript/node-oracledb/aqraw.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2019, 2021, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -33,6 +33,17 @@
 const oracledb = require('oracledb');
 const dbConfig = require('./dbconfig.js');
 
+// On Windows and macOS, you can specify the directory containing the Oracle
+// Client Libraries at runtime, or before Node.js starts.  On other platforms
+// the system library search path must always be set before Node.js is started.
+// See the node-oracledb installation documentation.
+// If the search path is not correct, you will get a DPI-1047 error.
+if (process.platform === 'win32') { // Windows
+  oracledb.initOracleClient({ libDir: 'C:\\oracle\\instantclient_19_11' });
+} else if (process.platform === 'darwin') { // macOS
+  oracledb.initOracleClient({ libDir: process.env.HOME + '/Downloads/instantclient_19_8' });
+}
+
 const queueName = "DEMO_RAW_QUEUE";
 
 async function enq() {

javascript/node-oracledb/blobhttp.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2015, 2020, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2015, 2021, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -35,6 +35,17 @@ const oracledb = require('oracledb');
 const dbConfig = require('./dbconfig.js');
 const demoSetup = require('./demosetup.js');
 
+// On Windows and macOS, you can specify the directory containing the Oracle
+// Client Libraries at runtime, or before Node.js starts.  On other platforms
+// the system library search path must always be set before Node.js is started.
+// See the node-oracledb installation documentation.
+// If the search path is not correct, you will get a DPI-1047 error.
+if (process.platform === 'win32') { // Windows
+  oracledb.initOracleClient({ libDir: 'C:\\oracle\\instantclient_19_11' });
+} else if (process.platform === 'darwin') { // macOS
+  oracledb.initOracleClient({ libDir: process.env.HOME + '/Downloads/instantclient_19_8' });
+}
+
 const httpPort = 7000;
 
 // Main entry point.  Creates a connection pool which becomes the
@@ -140,7 +151,7 @@ async function closePoolAndExit() {
     await oracledb.getPool().close(2);
     console.log('Pool closed');
     process.exit(0);
-  } catch(err) {
+  } catch (err) {
     console.error(err.message);
     process.exit(1);
   }

javascript/node-oracledb/calltimeout.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2018, 2019, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2018, 2021, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -32,6 +32,17 @@
 const oracledb = require("oracledb");
 const dbConfig = require('./dbconfig.js');
 
+// On Windows and macOS, you can specify the directory containing the Oracle
+// Client Libraries at runtime, or before Node.js starts.  On other platforms
+// the system library search path must always be set before Node.js is started.
+// See the node-oracledb installation documentation.
+// If the search path is not correct, you will get a DPI-1047 error.
+if (process.platform === 'win32') { // Windows
+  oracledb.initOracleClient({ libDir: 'C:\\oracle\\instantclient_19_11' });
+} else if (process.platform === 'darwin') { // macOS
+  oracledb.initOracleClient({ libDir: process.env.HOME + '/Downloads/instantclient_19_8' });
+}
+
 const dboptime = 4; // seconds the simulated database operation will take
 const timeout  = 2; // seconds the application will wait for the database operation
 

javascript/node-oracledb/connect.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2015, 2021, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -33,6 +33,17 @@
 const oracledb = require('oracledb');
 const dbConfig = require('./dbconfig.js');
 
+// On Windows and macOS, you can specify the directory containing the Oracle
+// Client Libraries at runtime, or before Node.js starts.  On other platforms
+// the system library search path must always be set before Node.js is started.
+// See the node-oracledb installation documentation.
+// If the search path is not correct, you will get a DPI-1047 error.
+if (process.platform === 'win32') { // Windows
+  oracledb.initOracleClient({ libDir: 'C:\\oracle\\instantclient_19_11' });
+} else if (process.platform === 'darwin') { // macOS
+  oracledb.initOracleClient({ libDir: process.env.HOME + '/Downloads/instantclient_19_8' });
+}
+
 async function run() {
 
   let connection;

javascript/node-oracledb/connectionpool.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2018, 2020, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2018, 2021, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -22,7 +22,7 @@
  *   Shows connection pool usage.  Connection pools are recommended
  *   for applications that use a lot of connections for short periods.
  *
- *   Other connection pool examples are in sessionfixup.js and webappawait.js.
+ *   Other connection pool examples are in sessionfixup.js and webapp.js.
  *   For a standalone connection example, see connect.js
  *
  *   In some networks forced pool termination may hang unless you have
@@ -38,11 +38,24 @@
 // If you increase poolMax, you must increase UV_THREADPOOL_SIZE before Node.js
 // starts its thread pool.  If you set UV_THREADPOOL_SIZE too late, the value is
 // ignored and the default size of 4 is used.
+// Note on Windows you must set the UV_THREADPOOL_SIZE environment variable before
+// running your application.
 // process.env.UV_THREADPOOL_SIZE = 4;
 
 const oracledb = require('oracledb');
 const dbConfig = require('./dbconfig.js');
 
+// On Windows and macOS, you can specify the directory containing the Oracle
+// Client Libraries at runtime, or before Node.js starts.  On other platforms
+// the system library search path must always be set before Node.js is started.
+// See the node-oracledb installation documentation.
+// If the search path is not correct, you will get a DPI-1047 error.
+if (process.platform === 'win32') { // Windows
+  oracledb.initOracleClient({ libDir: 'C:\\oracle\\instantclient_19_11' });
+} else if (process.platform === 'darwin') { // macOS
+  oracledb.initOracleClient({ libDir: process.env.HOME + '/Downloads/instantclient_19_8' });
+}
+
 async function init() {
   try {
     // Create a connection pool which will later be accessed via the
@@ -64,8 +77,9 @@ async function init() {
       // queueMax: 500, // don't allow more than 500 unsatisfied getConnection() calls in the pool queue
       // queueTimeout: 60000, // terminate getConnection() calls queued for longer than 60000 milliseconds
       // sessionCallback: myFunction, // function invoked for brand new connections or by a connection tag mismatch
+      // sodaMetaDataCache: false, // Set true to improve SODA collection access performance
       // stmtCacheSize: 30, // number of statements that are cached in the statement cache of each connection
-      // _enableStats: false // record pool usage statistics that can be output with pool._logStats()
+      // enableStatistics: false // record pool usage for oracledb.getPool().getStatistics() and logStatistics()
     });
     console.log('Connection pool started');
 
@@ -89,7 +103,7 @@ async function dostuff() {
     const options = { outFormat: oracledb.OUT_FORMAT_OBJECT };
     const result = await connection.execute(sql, binds, options);
     console.log(result);
-    // oracledb.getPool()._logStats(); // show pool statistics.  _enableStats must be true
+    // oracledb.getPool().logStatistics(); // show pool statistics.  pool.enableStatistics must be true
   } catch (err) {
     console.error(err);
   } finally {
@@ -115,7 +129,7 @@ async function closePoolAndExit() {
     await oracledb.getPool().close(10);
     console.log('Pool closed');
     process.exit(0);
-  } catch(err) {
+  } catch (err) {
     console.error(err.message);
     process.exit(1);
   }

javascript/node-oracledb/cqn1.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2018, 2019, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2018, 2021, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -39,14 +39,24 @@
 const oracledb = require("oracledb");
 const dbConfig = require('./dbconfig.js');
 
+// On Windows and macOS, you can specify the directory containing the Oracle
+// Client Libraries at runtime, or before Node.js starts.  On other platforms
+// the system library search path must always be set before Node.js is started.
+// See the node-oracledb installation documentation.
+// If the search path is not correct, you will get a DPI-1047 error.
+if (process.platform === 'win32') { // Windows
+  oracledb.initOracleClient({ libDir: 'C:\\oracle\\instantclient_19_11' });
+} else if (process.platform === 'darwin') { // macOS
+  oracledb.initOracleClient({ libDir: process.env.HOME + '/Downloads/instantclient_19_8' });
+}
+
 dbConfig.events = true;  // CQN needs events mode
 
 const interval = setInterval(function() {
   console.log("waiting...");
 }, 5000);
 
-function myCallback(message)
-{
+function myCallback(message) {
   // message.type is one of the oracledb.SUBSCR_EVENT_TYPE_* values
   console.log("Message type:", message.type);
   if (message.type == oracledb.SUBSCR_EVENT_TYPE_DEREG) {
@@ -100,7 +110,7 @@ async function setup(connection) {
   for (const s of stmts) {
     try {
       await connection.execute(s);
-    } catch(e) {
+    } catch (e) {
       if (e.errorNum != 942)
         console.error(e);
     }

javascript/node-oracledb/cqn2.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2018, 2019, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2018, 2021, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -40,14 +40,24 @@
 const oracledb = require("oracledb");
 const dbConfig = require('./dbconfig.js');
 
+// On Windows and macOS, you can specify the directory containing the Oracle
+// Client Libraries at runtime, or before Node.js starts.  On other platforms
+// the system library search path must always be set before Node.js is started.
+// See the node-oracledb installation documentation.
+// If the search path is not correct, you will get a DPI-1047 error.
+if (process.platform === 'win32') { // Windows
+  oracledb.initOracleClient({ libDir: 'C:\\oracle\\instantclient_19_11' });
+} else if (process.platform === 'darwin') { // macOS
+  oracledb.initOracleClient({ libDir: process.env.HOME + '/Downloads/instantclient_19_8' });
+}
+
 dbConfig.events = true;  // CQN needs events mode
 
 const interval = setInterval(function() {
   console.log("waiting...");
 }, 5000);
 
-function myCallback(message)
-{
+function myCallback(message) {
   // message.type is one of the oracledb.SUBSCR_EVENT_TYPE_* values
   console.log("Message type:", message.type);
   if (message.type == oracledb.SUBSCR_EVENT_TYPE_DEREG) {
@@ -100,7 +110,7 @@ async function setup(connection) {
   for (const s of stmts) {
     try {
       await connection.execute(s);
-    } catch(e) {
+    } catch (e) {
       if (e.errorNum != 942)
         console.error(e);
     }