Add ODBC Transport

README.md

@@ -13,6 +13,7 @@
         - [idb-connector](#idb-connector)
         - [REST](#rest)
         - [SSH](#ssh)
+        - [ODBC](#odbc)
     - [ProgramCall](#programcall)
       - [Example](#example)
     - [CommandCall](#commandcall)
@@ -39,7 +40,7 @@ Before installing, download and install Node.js
 The Connection class is used to transport xml input and return xml output.
 
 #### Transports
-Supported transports include [idb-connector](https://github.com/IBM/nodejs-idb-connector), REST, and SSH.
+Supported transports include [idb-connector](https://github.com/IBM/nodejs-idb-connector), REST, SSH, and ODBC.
 
 ##### idb-connector
 The [idb-connector](https://github.com/IBM/nodejs-idb-connector) transport establishes a database connection and calls XMLSERVICE stored procedure.
@@ -126,6 +127,59 @@ const connection = new Connection({
 });
 ```
 
+##### ODBC
+The [ODBC](https://github.com/wankdanker/node-odbc/tree/v2.0) transport establishes a database connection and calls XMLSERVICE stored procedure.
+
+Before using the ODBC transport ensure all dependencies are installed.
+
+Ensure the IBM i Access ODBC driver is installed where you will be running Node.js.
+
+`TODO document installation`
+
+On the client side ensure `unixODBC` and `unixODBC-devel` are both installed.
+
+On IBM i this can be done with:
+
+`yum install unixODBC unixODBC-devel`
+
+Refer to [node-odbc](https://github.com/wankdanker/node-odbc/tree/v2.0#installation) for how this is done your OS.
+
+Also on the client side ensure the `IBM i Access ODBC Driver` is installed.
+
+`TODO document installation`
+
+To use the `ODBC` transport create an instance of Connection with:
+
+```javascript
+const connection = new Connection({
+  transport: 'odbc',
+  transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword'}
+});
+```
+
+Alternatively you can specify a [DSN](https://support.microsoft.com/en-us/help/966849/what-is-a-dsn-data-source-name) to use.
+
+Create an `.odbc.ini` file within your home directory and add additional configuration options.
+
+Refer to the [knowledge center](https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_73/rzaik/connectkeywords.htm) for a list of valid options.
+
+A simple .odbc.ini file:
+
+```
+[*LOCAL]
+Driver=IBM i Access ODBC Driver
+UserID=myuser
+Password=mypass
+System=localhost
+```
+To use the `ODBC` transport with a DSN create an instance of Connection with:
+
+```javascript
+const connection = new Connection({
+  transport: 'odbc',
+  transportOptions: { dsn: '*LOCAL'}
+});
+```
 ### ProgramCall
 The ProgramCall class is used to call IBM i programs and service programs.
 

lib/Connection.js

@@ -23,11 +23,13 @@ const {
 const { iRestHttp } = require('./transports/irest');
 const { db2Call } = require('./transports/istoredp');
 const { sshCall } = require('./transports/sshTransport');
+const { odbcCall } = require('./transports/odbcTransport');
 
 const availableTransports = {
   idb: db2Call,
   rest: iRestHttp,
   ssh: sshCall,
+  odbc: odbcCall,
 };
 
 class Connection {

lib/transports/odbcTransport.js

@@ -0,0 +1,92 @@
+// Copyright (c) International Business Machines Corp. 2019
+// All Rights Reserved
+
+// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+// associated documentation files (the "Software"), to deal in the Software without restriction,
+// including without limitation the rights to use, copy, modify, merge, publish, distribute,
+// sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+
+// The above copyright notice and this permission notice shall be included in all copies or
+// substantial portions of the Software.
+
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+// NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+function odbcCall(config, xmlInput, done) {
+  // eslint-disable-next-line global-require
+  const { Connection } = require('odbc');
+
+  const {
+    host = 'localhost',
+    username = null,
+    password = null,
+    ipc = '*NA',
+    ctl = '*here',
+    xslib = 'QXMLSERV',
+    verbose = false,
+    dsn = null,
+  } = config;
+
+  const sql = `call ${xslib}.iPLUGR512K(?,?,?)`;
+  const driver = 'IBM i Access ODBC Driver';
+  let connectionString;
+
+  if (dsn && typeof dsn === 'string') {
+    connectionString = `DSN=${dsn}`;
+  } else {
+    connectionString = `DRIVER=${driver};SYSTEM=${host};`;
+
+    if (username && typeof username === 'string') {
+      connectionString += `UID=${username};`;
+    }
+    if (password && typeof password === 'string') {
+      connectionString += `PWD=${password};`;
+    }
+  }
+
+  if (verbose) {
+    console.log(`SQL to run is ${sql}`);
+  }
+
+  let connection;
+
+  // potentially throws an error with invalid SYSTEM, UID, PWD
+  try {
+    connection = new Connection(connectionString);
+  } catch (error) {
+    done(error, null);
+  }
+
+  connection.query(sql, [ipc, ctl, xmlInput], (queryError, results) => {
+    if (queryError) {
+      done(queryError, null);
+      return;
+    }
+
+    connection.close((closeError) => {
+      if (closeError) {
+        done(closeError, null);
+        return;
+      }
+
+      if (!results) {
+        done('Empty result set was returned', null);
+        return;
+      }
+
+      let xmlOutput = '';
+
+      results.forEach((chunk) => {
+        xmlOutput += chunk.OUT151;
+      });
+
+      done(null, xmlOutput);
+    });
+  });
+}
+
+exports.odbcCall = odbcCall;

lib/utils.js

@@ -221,7 +221,7 @@ const xmlToJson = (xml) => {
 function returnTransports(transportOptions) {
   // eslint-disable-next-line global-require
   const { Connection } = require('./Connection');
-  const availableTransports = ['idb', 'rest', 'ssh'];
+  const availableTransports = ['idb', 'rest', 'ssh', 'odbc'];
   const transports = [];
 
   const options = {

package.json

@@ -50,6 +50,7 @@
   "optionalDependencies": {
     "idb-connector": "^1.1.8",
     "idb-pconnector": "^1.0.2",
-    "ssh2": "0.8.2"
+    "ssh2": "0.8.2",
+    "odbc": "^2.0.0-beta.1"
   }
 }

test/functional/CommandCallFunctional.js

@@ -38,6 +38,7 @@ const opt = {
   privateKey,
   passphrase: process.env.TKPHRASE,
   verbose: !!process.env.TKVERBOSE,
+  dsn: process.env.TKDSN,
 };
 
 const transports = returnTransports(opt);

test/functional/ProgramCallFunctional.js

@@ -39,6 +39,7 @@ const opt = {
   privateKey,
   passphrase: process.env.TKPHRASE,
   verbose: !!process.env.TKVERBOSE,
+  dsn: process.env.TKDSN,
 };
 
 const transports = returnTransports(opt);

test/functional/SqlCallFunctional.js

@@ -39,6 +39,7 @@ const opt = {
   privateKey,
   passphrase: process.env.TKPHRASE,
   verbose: !!process.env.TKVERBOSE,
+  dsn: process.env.TKDSN,
 };
 
 const transports = returnTransports(opt);

test/functional/ToolkitFunctional.js

@@ -39,6 +39,7 @@ const opt = {
   privateKey,
   passphrase: process.env.TKPHRASE,
   verbose: !!process.env.TKVERBOSE,
+  dsn: process.env.TKDSN,
 };
 
 const lib = 'NODETKTEST';