Add oracledb.initOracleClient() for Oracle Client initialization

Author: cjbj

CHANGELOG.md

@@ -4,6 +4,13 @@
 
 **This release is under development**
 
+- Added a
+  [`oracledb.initOracleClient()`](https://oracle.github.io/node-oracledb/doc/api.html#odbinitoracleclient)
+  function to specify the directory that the Oracle Client libraries and
+  optional configuration files should be located from, and to specify other
+  configuration values, see [Initializing
+  Node-oracledb](https://oracle.github.io/node-oracledb/doc/api.html#initnodeoracledb).
+
 - Added database instance startup and shutdown functions
 [`oracledb.startup()`](https://oracle.github.io/node-oracledb/doc/api.html#odbstartup),
 [`oracledb.shutdown()`](https://oracle.github.io/node-oracledb/doc/api.html#odbshutdown),

INSTALL.md

@@ -35,6 +35,12 @@ process.env.ORA_SDTZ = 'UTC';
 const oracledb = require('oracledb');
 const dbConfig = require('./dbconfig.js');
 
+// On Windows and macOS, you can specify the directory containing your Oracle
+// Client Libraries.  If this is not done, then a standard search heuristic is
+// used, see the node-oracledb documentation.
+// oracledb.initOracleClient({ libDir: 'C:\instantclient_19_3' });             // Windows
+// oracledb.initOracleClient({ libDir: '/Users/myname/instantclient_19_3' });  // macOS
+
 async function run() {
   let connection;
 

doc/api.md

@@ -132,6 +132,16 @@ class OracleDb {
     return pool;
   }
 
+  initOracleClient(arg1) {
+    let options = {};
+    nodbUtil.checkArgCount(arguments, 0, 1);
+    if (arg1 !== undefined) {
+      nodbUtil.assert(nodbUtil.isObject(arg1), 'NJS-005', 1);
+      options = arg1;
+    }
+    this._initOracleClient(options);
+  }
+
 }
 
 // Oracledb functions and classes

examples/example.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2017, 2019, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2017, 2020, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -22,10 +22,6 @@
  *   This script is included in the npm bundle of node-oracledb.  It
  *   is invoked by package.json during npm install.
  *
- *   The node-oracledb npm package bundles all available pre-built
- *   binaries, so this script is really just a check to see if an
- *   appropriate pre-built binary is available.
- *
  * MAINTENANCE NOTES
  *   This file should only ever 'require' packages included in core Node.js.
  *
@@ -50,7 +46,7 @@ function error(message) { // eslint-disable-line
   console.error.apply(console, args);
 }
 
-// Print a concluding messages and quits
+// Print concluding messages and quit
 function done(err) {
   let installUrl = 'https://oracle.github.io/node-oracledb/INSTALL.html';
 
@@ -64,58 +60,28 @@ function done(err) {
     process.exit(87);
   } else { // Successfully installed
     let arch;
-    let clientUrl;
 
     if (process.arch === 'x64') {
       arch = '64-bit';
     } else {
       arch = '32-bit';
     }
 
-    log('********************************************************************************');
-
-    log('** Node-oracledb ' + nodbUtil.PACKAGE_JSON_VERSION + ' installed for Node.js ' + process.versions.node + ' (' + process.platform + ', ' + process.arch +')');
-
-    log('**');
-    log('** To use node-oracledb:');
-
     if (process.platform === 'linux') {
-      if (process.arch === 'x64') {
-        clientUrl = 'https://www.oracle.com/database/technologies/instant-client/linux-x86-64-downloads.html';
-      } else {
-        clientUrl = 'https://www.oracle.com/database/technologies/instant-client/linux-x86-32-downloads.html';
-      }
-
-      log('** - Oracle Client libraries (' + arch + ') must be configured with ldconfig or LD_LIBRARY_PATH');
-      log('** - To get libraries, install an Instant Client Basic or Basic Light package from');
-      log('**   ' + clientUrl);
+      installUrl += '#linuxinstall';
     } else if (process.platform === 'darwin') {
-      clientUrl = 'https://www.oracle.com/database/technologies/instant-client/macos-intel-x86-downloads.html';
-      installUrl = 'https://oracle.github.io/node-oracledb/INSTALL.html#instosx';
-
-      log('** - Oracle Instant Client Basic or Basic Light package libraries must be in ~/lib or /usr/local/lib');
-      log('**   Download from ' + clientUrl);
+      installUrl += '#instosx';
     } else if (process.platform === 'win32') {
-      if (process.arch === 'x64') {
-        clientUrl = 'https://www.oracle.com/database/technologies/instant-client/winx64-64-downloads.html';
-      } else {
-        clientUrl = 'https://www.oracle.com/database/technologies/instant-client/microsoft-windows-32-downloads.html';
-      }
-
-      log('** - Oracle Client libraries (' + arch + ') must be in your PATH environment variable');
-      log('** - To get libraries, install an Instant Client Basic or Basic Light package from');
-      log('**   ' + clientUrl);
-      log('** - A Microsoft Visual Studio Redistributable suitable for your Oracle Client library version must be available');
-      log('**   See ' + installUrl + ' for details');
-    } else {
-      clientUrl = 'https://www.oracle.com/technetwork/database/database-technologies/instant-client/overview/index.html';
-      log('** - Oracle Client libraries (' + arch + ') must be in your operating system library search path');
-      log('** - To get libraries, install an Instant Client Basic or Basic Light package from:');
-      log('**   ' + clientUrl);
+      installUrl += '#windowsinstallation';
     }
 
+    log('********************************************************************************');
+    log('** Node-oracledb ' + nodbUtil.PACKAGE_JSON_VERSION + ' installed for Node.js ' + process.versions.node + ' (' + process.platform + ', ' + process.arch +')');
     log('**');
-    log('** Installation instructions: ' + installUrl);
+    log('** To use node-oracledb:');
+    log('** - Oracle Client libraries (' + arch + ') must be available.');
+    log('** - Follow the installation instructions:');
+    log('**   ' + installUrl);
     log('********************************************************************************\n');
   }
 }

lib/oracledb.js

@@ -83,6 +83,7 @@ static const char *njsErrorMessages[] = {
     "NJS-074: cannot convert from JavaScript value to attribute \"%.*s\" of type \"%.*s\"", // errConvertToObjAttr
     "NJS-075: only one of connectString and connectionString can be used", // errDblConnectionString
     "NJS-076: connection request rejected. Pool queue length queueMax %d reached", // errQueueMax
+    "NJS-077: Oracle Client library has already been initialized", // errClientLibAlreadyInitialized
 };
 
 

odpi

@@ -113,6 +113,9 @@
 // fetchInfo
 #define NJS_MAX_FETCH_AS_STRING_SIZE    200
 
+// encoding name to use for all strings
+#define NJS_ENCODING                    "UTF-8"
+
 
 //-----------------------------------------------------------------------------
 // enumerations
@@ -195,7 +198,7 @@ typedef enum {
     errConvertToObjAttr,
     errDblConnectionString,
     errQueueMax,
-
+    errClientLibAlreadyInitialized,
 
     // New ones should be added here
 

package/install.js

@@ -28,6 +28,7 @@
 // class methods
 static NJS_NAPI_METHOD(njsOracleDb_createPool);
 static NJS_NAPI_METHOD(njsOracleDb_getConnection);
+static NJS_NAPI_METHOD(njsOracleDb_initOracleClient);
 
 // asynchronous methods
 static NJS_ASYNC_METHOD(njsOracleDb_createPoolAsync);
@@ -95,7 +96,7 @@ static NJS_NAPI_FINALIZE(njsOracleDb_finalize);
 static bool njsOracleDb_initCommonCreateParams(njsBaton *baton,
         dpiCommonCreateParams *params);
 static bool njsOracleDb_initDPI(njsOracleDb *oracleDb, napi_env env,
-        njsBaton *baton);
+        dpiContextCreateParams *params, njsBaton *baton);
 
 // define constants exposed to JS
 static njsConstant njsClassConstants[] = {
@@ -324,6 +325,8 @@ static const napi_property_descriptor njsClassProperties[] = {
             napi_default, NULL },
     { "_getConnection", NULL, njsOracleDb_getConnection, NULL, NULL, NULL,
             napi_default, NULL },
+    { "_initOracleClient", NULL, njsOracleDb_initOracleClient, NULL, NULL,
+            NULL, napi_default, NULL },
     { NULL, NULL, NULL, NULL, NULL, NULL, napi_default, NULL }
 };
 
@@ -437,7 +440,7 @@ static bool njsOracleDb_createPoolProcessArgs(njsBaton *baton, napi_env env,
     bool connStrFound, connStrFound1;
 
     // initialize ODPI-C library, if necessary
-    if (!njsOracleDb_initDPI(baton->oracleDb, env, baton))
+    if (!njsOracleDb_initDPI(baton->oracleDb, env, NULL, baton))
         return false;
 
     // set defaults on baton
@@ -656,7 +659,7 @@ static bool njsOracleDb_getConnectionProcessArgs(njsBaton *baton,
     bool connStrFound, connStrFound1;
 
     // initialize ODPI-C library, if necessary
-    if (!njsOracleDb_initDPI(baton->oracleDb, env, baton))
+    if (!njsOracleDb_initDPI(baton->oracleDb, env, NULL, baton))
         return false;
 
     // copy items used from the OracleDb class since they may change after
@@ -884,7 +887,7 @@ static napi_value njsOracleDb_getOracleClientVersion(napi_env env,
 
     if (!njsUtils_validateGetter(env, info, (njsBaseInstance**) &oracleDb))
         return NULL;
-    if (!njsOracleDb_initDPI(oracleDb, env, NULL))
+    if (!njsOracleDb_initDPI(oracleDb, env, NULL, NULL))
         return NULL;
     if (dpiContext_getClientVersion(oracleDb->context, &versionInfo) < 0) {
         njsUtils_throwErrorDPI(env, oracleDb);
@@ -907,7 +910,7 @@ static napi_value njsOracleDb_getOracleClientVersionString(napi_env env,
 
     if (!njsUtils_validateGetter(env, info, (njsBaseInstance**) &oracleDb))
         return NULL;
-    if (!njsOracleDb_initDPI(oracleDb, env, NULL))
+    if (!njsOracleDb_initDPI(oracleDb, env, NULL, NULL))
         return NULL;
     if (dpiContext_getClientVersion(oracleDb->context, &versionInfo) < 0) {
         njsUtils_throwErrorDPI(env, oracleDb);
@@ -1074,6 +1077,84 @@ static napi_value njsOracleDb_getVersionSuffix(napi_env env,
 }
 
 
+//-----------------------------------------------------------------------------
+// njsOracleDb_initOracleClientHelper()
+//   Helper method that performs the work of njsOracleDb_initOracleClient().
+//-----------------------------------------------------------------------------
+static bool njsOracleDb_initOracleClientHelper(napi_env env,
+        napi_callback_info info)
+{
+    size_t libDirLength, configDirLength, errorUrlLength, driverNameLength;
+    char *libDir, *configDir, *errorUrl, *driverName;
+    njsBaseInstance *callingInstance;
+    napi_value callingObj, args[1];
+    dpiContextCreateParams params;
+    njsOracleDb *oracleDb;
+    bool ok;
+
+    // process arguments
+    libDir = configDir = errorUrl = driverName = NULL;
+    libDirLength = configDirLength = errorUrlLength = driverNameLength = 0;
+    if (!njsUtils_validateArgs(env, info, 1, args, &callingObj,
+            &callingInstance))
+        return false;
+    if (!njsUtils_getStringFromArg(env, args, 0, "libDir", &libDir,
+            &libDirLength, NULL, NULL))
+        return false;
+    if (!njsUtils_getStringFromArg(env, args, 0, "configDir", &configDir,
+            &configDirLength, NULL, NULL))
+        return false;
+    if (!njsUtils_getStringFromArg(env, args, 0, "errorUrl", &errorUrl,
+            &errorUrlLength, NULL, NULL))
+        return false;
+    if (!njsUtils_getStringFromArg(env, args, 0, "driverName", &driverName,
+            &driverNameLength, NULL, NULL))
+        return false;
+
+    // initialize library
+    memset(&params, 0, sizeof(params));
+    if (libDirLength > 0)
+        params.oracleClientLibDir = libDir;
+    if (configDirLength > 0)
+        params.oracleClientConfigDir = configDir;
+    if (errorUrlLength > 0)
+        params.loadErrorUrl = errorUrl;
+    if (driverNameLength > 0)
+        params.defaultDriverName = driverName;
+    oracleDb = (njsOracleDb*) callingInstance;
+    ok = njsOracleDb_initDPI(oracleDb, env, &params, NULL);
+
+    // cleanup
+    if (libDir)
+        free(libDir);
+    if (configDir)
+        free(configDir);
+    if (errorUrl)
+        free(errorUrl);
+    if (driverName)
+        free(driverName);
+    return ok;
+}
+
+
+//-----------------------------------------------------------------------------
+// njsOracleDb_initOracleClient()
+//   Initialize the Oracle Client library now, rather than when the first pool
+// or standalone connection is created, or a request is made to determine the
+// Oracle Client version. If the Oracle Client library has already been
+// initialized, an exception is raised.
+//
+// PARAMETERS
+//   - options
+//-----------------------------------------------------------------------------
+static napi_value njsOracleDb_initOracleClient(napi_env env,
+        napi_callback_info info)
+{
+    njsOracleDb_initOracleClientHelper(env, info);
+    return NULL;
+}
+
+
 //-----------------------------------------------------------------------------
 // njsOracleDb_initCommonCreateParams()
 //   Initialize common creation parameters for pools and standalone
@@ -1089,10 +1170,6 @@ static bool njsOracleDb_initCommonCreateParams(njsBaton *baton,
     if (baton->events)
         params->createMode = (dpiCreateMode)
                 (params->createMode | DPI_MODE_CREATE_EVENTS);
-    params->encoding = "UTF-8";
-    params->nencoding = "UTF-8";
-    params->driverName = NJS_DRIVER_NAME;
-    params->driverNameLength = (uint32_t) strlen(params->driverName);
     return true;
 }
 
@@ -1106,27 +1183,47 @@ static bool njsOracleDb_initCommonCreateParams(njsBaton *baton,
 // errors that can take place when the module is imported.
 //-----------------------------------------------------------------------------
 static bool njsOracleDb_initDPI(njsOracleDb *oracleDb, napi_env env,
-        njsBaton *baton)
+        dpiContextCreateParams *params, njsBaton *baton)
 {
+    dpiContextCreateParams localParams;
     napi_value error, message;
     dpiErrorInfo errorInfo;
 
-    // if already initialized, nothing needs to be done
-    if (oracleDb->context)
-        return true;
+    // if already initialized and parameters were passed, raise an exception;
+    // otherwise do nothing as this is implicitly called when creating a
+    // standalone connection or session pool and when getting the Oracle Client
+    // library version
+    if (oracleDb->context) {
+        if (!params)
+            return true;
+        return njsUtils_throwError(env, errClientLibAlreadyInitialized);
+    }
+
+    // set up parameters used for initializing ODPI-C
+    if (params) {
+        memcpy(&localParams, params, sizeof(dpiContextCreateParams));
+    } else {
+        memset(&localParams, 0, sizeof(dpiContextCreateParams));
+    }
+    localParams.defaultEncoding = NJS_ENCODING;
+    if (!localParams.defaultDriverName)
+        localParams.defaultDriverName = NJS_DRIVER_NAME;
+    if (!localParams.loadErrorUrl)
+        localParams.loadErrorUrl =
+                "https://oracle.github.io/node-oracledb/INSTALL.html";
 
     // create global DPI context (with baton available)
     if (baton) {
-        if (dpiContext_create(DPI_MAJOR_VERSION, DPI_MINOR_VERSION,
-                &oracleDb->context, &baton->errorInfo) < 0) {
+        if (dpiContext_createWithParams(DPI_MAJOR_VERSION, DPI_MINOR_VERSION,
+                &localParams, &oracleDb->context, &baton->errorInfo) < 0) {
             baton->dpiError = true;
             return false;
         }
 
     // create global DPI context (no baton available, throw error immediately)
     } else {
-        if (dpiContext_create(DPI_MAJOR_VERSION, DPI_MINOR_VERSION,
-                &oracleDb->context, &errorInfo) < 0) {
+        if (dpiContext_createWithParams(DPI_MAJOR_VERSION, DPI_MINOR_VERSION,
+                &localParams, &oracleDb->context, &errorInfo) < 0) {
             NJS_CHECK_NAPI(env, napi_create_string_utf8(env, errorInfo.message,
                     errorInfo.messageLength, &message))
             NJS_CHECK_NAPI(env, napi_create_error(env, NULL, message, &error))