From e853908798e8e608f2b65cfbfa25677ae25d3af1 Mon Sep 17 00:00:00 2001 From: Abdirahim Musse <33973272+abmusse@users.noreply.github.com> Date: Wed, 22 Apr 2020 11:21:55 -0500 Subject: [PATCH 1/3] docs: Simplify main README to contain basic info --- README.md | 224 ++---------------------------------------------------- 1 file changed, 7 insertions(+), 217 deletions(-) diff --git a/README.md b/README.md index a3f7bf58..55d7c275 100644 --- a/README.md +++ b/README.md @@ -10,17 +10,7 @@ # Table of Contents - [Installation](#installation) -- [Main Classes](#main-classes) - - [Connection](#connection) - - [Transports](#transports) - - [idb-connector](#idb-connector) - - [REST](#rest) - - [SSH](#ssh) - - [ODBC](#odbc) - - [ProgramCall](#programcall) - - [Example](#example) - - [CommandCall](#commandcall) - - [Example](#example-1) +- [Features](#features) - [Documentation](#documentation) - [Testing](#testing) - [Contributing](#contributing) @@ -28,222 +18,22 @@ # Installation -Before installing, download and install Node.js - ```sh - $ npm i itoolkit@alpha -``` - -## Main Classes - -### Connection -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, 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. - -**NOTE** the `idb-connector` transport is only supported on an IBM i system. - -To use the `idb-connector` transport create an instance of Connection with: - -```javascript -const connection = new Connection({ - transport: 'idb', - transportOptions: { database: '*LOCAL', username: 'myuser', password: 'mypass' } -}); -``` - -##### REST -The REST transport makes an HTTP request to an endpoint that process the XML input and returns XML output. - -Initial configuration is required for the endpoint. - -A quick example is to add the following to `/www/apachedft/conf/httpd.conf` - -```apache -ScriptAlias /cgi-bin/ /QSYS.LIB/XMLSERVICE.LIB/ - - AllowOverride None - Require all granted - SetHandler cgi-script - Options +ExecCGI - -``` - -- start the server - - ` STRTCPSVR SERVER(*HTTP) HTTPSVR(APACHEDFT)` - -- go to `http://HOSTNAME:PORT/cgi-bin/xmlcgi.pgm` - -you should see an XML document - -To use the `REST` transport create an instance of Connection with: - -```javascript -const connection = new Connection({ - transport: 'rest', - transportOptions: { host: 'myhost', port: 80, path:'/cgi-bin/xmlcgi.pgm' database: '*LOCAL', username: 'myuser', password: 'mypass' } -}); + $ npm install itoolkit ``` -##### SSH -The SSH transport executes `xmlservice-cli` program via ssh. - -Ensure you have OpenSSH installed on your IBM i system. - -Also `xmlservice-cli` is required on the IBM i host with: - -`yum install itoolkit-utils` - -The [ssh2](https://www.npmjs.com/package/ssh2#client-methods) client module is used to connect and supports both private key and password authentication. - -To use the `SSH` transport with private key authentication create an instance of Connection with: - -```javascript -const { readFileSync } = require('fs'); - -const privateKey = readFileSync('path/to/privateKey', 'utf-8'); - -// NOTE if your privateKey also requires a passphrase provide it - -const connection = new Connection({ - transport: 'ssh', - transportOptions: { host: 'myhost', username: 'myuser', privateKey, passphrase: 'myphrase' } -}); -``` - -To use the `SSH` transport with password authentication create an instance of Connection with: - -```javascript - -const connection = new Connection({ - transport: 'ssh', - transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' } -}); -``` - -##### ODBC -The [ODBC](https://github.com/wankdanker/node-odbc/tree/v2.0) transport establishes a database connection and calls XMLSERVICE stored procedure. - -Refer to the [odbc setup guide](https://github.com/IBM/ibmi-oss-examples/blob/master/odbc/odbc.md#table-of-contents) for setup instructions. - -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://github.com/IBM/ibmi-oss-examples/blob/master/odbc/odbc.md#dsns) to use. - -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. - -#### Example -```javascript -const { - Connection, ProgramCall, -} = require('itoolkit'); - -const { parseString } = require('xml2js'); - -const conn = new Connection({ - transport: 'ssh', - transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' } -}); - -const program = new ProgramCall('QWCRSVAL', { lib: 'QSYS' }); -const outBuf = [ - [0, '10i0'], - [0, '10i0'], - ['', '36h'], - ['', '10A'], - ['', '1A'], - ['', '1A'], - [0, '10i0'], - [0, '10i0'], -]; -const errno = [ - [0, '10i0'], - [0, '10i0', { setlen: 'rec2' }], - ['', '7A'], - ['', '1A'], -]; - -program.addParam(outBuf, { io: 'out' }); -program.addParam(66, '10i0'); -program.addParam(1, '10i0'); -program.addParam('QCCSID', '10A'); -program.addParam(errno, { io: 'both', len: 'rec2' }); - -conn.add(program); - - -conn.run((error, xmlOutput) => { - if (error) { - throw error; - } - parseString(xmlOutput, (parseError, result) => { - if (parseError) { - throw parseError; - } - console.log(JSON.stringify(result)); - }); -}); -``` -### CommandCall -CommandCall is used to execute a CL, QSH, or PASE command. - -#### Example -```javascript -const { - Connection, CommandCall, -} = require('itoolkit'); - -const { parseString } = require('xml2js'); - -const conn = new Connection({ - transport: 'ssh', - transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' } -}); - -conn.add(new CommandCall({ command: 'RTVJOBA USRLIBL(?) SYSLIBL(?)', type: 'cl' })); - -conn.run((error, xmlOutput) => { - if (error) { - throw error; - } - parseString(xmlOutput, (parseError, result) => { - if (parseError) { - throw parseError; - } - console.log(JSON.stringify(result)); - }); -}); -``` +# Features +- Call ILE programs and service programs +- Call CL, QSH, and PASE shell commands # Documentation Please read the [docs](https://nodejs-itoolkit.readthedocs.io/en/latest/). # Testing -Refer to the [README](test/README.md) +Refer to the [README](test/README.md). # Contributing Please read the [contribution guidelines](https://github.com/IBM/nodejs-itoolkit/blob/master/CONTRIBUTING.md). # License -[`MIT`](https://github.com/IBM/nodejs-itoolkit/blob/master/LICENSE) +[MIT](https://github.com/IBM/nodejs-itoolkit/blob/master/LICENSE) From 7733c3230689b9bc31d68b2eb85227d94295d1a4 Mon Sep 17 00:00:00 2001 From: Abdirahim Musse <33973272+abmusse@users.noreply.github.com> Date: Wed, 22 Apr 2020 11:36:36 -0500 Subject: [PATCH 2/3] fixup! docs: Simplify main README to contain basic info --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 55d7c275..9a6db228 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ # Installation ```sh - $ npm install itoolkit +$ npm install itoolkit ``` # Features From 177e4f07506d0164fe719ca8400c7005ea43cd5d Mon Sep 17 00:00:00 2001 From: Abdirahim Musse <33973272+abmusse@users.noreply.github.com> Date: Thu, 23 Apr 2020 12:15:50 -0500 Subject: [PATCH 3/3] fixup! fixup! docs: Simplify main README to contain basic info --- README.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 66 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 9a6db228..d833cb04 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Node.js iToolkit +# Node.js itoolkit [![npm](https://img.shields.io/npm/v/itoolkit?logo=npm)](https://www.npmjs.com/package/itoolkit) ![Supported Node Versions](https://img.shields.io/node/v-lts/itoolkit) @@ -6,16 +6,76 @@ [![ryver-signup](https://img.shields.io/badge/Ryver-Signup-blue)](https://ibmioss.ryver.com/application/signup/members/9tJsXDG7_iSSi1Q) [![Documentation Status](https://readthedocs.org/projects/nodejs-itoolkit/badge/?version=latest)](https://nodejs-itoolkit.readthedocs.io/en/latest/?badge=latest) -`itoolkit` is a Node.js interface to [XMLSERVICE](https://github.com/IBM/xmlservice) to access all things IBM i. +`itoolkit` is a Node.js interface to [XMLSERVICE](https://github.com/IBM/xmlservice) to access all things [IBM i](https://en.wikipedia.org/wiki/IBM_i). # Table of Contents +- [Introduction](#introduction) - [Installation](#installation) - [Features](#features) - [Documentation](#documentation) -- [Testing](#testing) +- [Tests](#tests) - [Contributing](#contributing) - [License](#license) +# Introduction + +[XMLSERVICE](https://github.com/IBM/xmlservice) provides interfaces to interact with IBM i resources such as programs and commands. XMLSERVICE receives xml input and returns xml output. + +For example run a CL command by sending the following XML input to XMLSERVICE. + +```xml + + + RTVJOBA USRLIBL(?) SYSLIBL(?) + +``` + +XMLSERVICE will run the command and respond with XML output. + +```xml + + + + +++ success RTVJOBA USRLIBL(?) SYSLIBL(?) + + QGPL QTEMP + + + QSYS QSYS2 QHLPSYS QUSRSYS + + + +``` + +`itoolkit` can run the same CL command with: + +```js +const { Connection, CommandCall } = require('itoolkit'); +const { parseString } = require('xml2js'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const command = new CommandCall({ type: 'cl', command: 'RTVJOBA USRLIBL(?) SYSLIBL(?)' }); + +connection.add(command); + +connection.run((error, xmlOutput) => { + if (error) { + throw error; + } + parseString(xmlOutput, (parseError, result) => { + if (parseError) { + throw parseError; + } + console.log(JSON.stringify(result)); + }); +``` + +The purpose of this package is to simplify the process of creating XMLSERVICE input, invoking XMLSERVICE, and returning XMLSERVICE output from Node.js. + # Installation ```sh @@ -23,13 +83,13 @@ $ npm install itoolkit ``` # Features -- Call ILE programs and service programs -- Call CL, QSH, and PASE shell commands +- [Call ILE programs and service programs](https://nodejs-itoolkit.readthedocs.io/en/latest/ProgramCall.html) +- [Call CL, QSH, and PASE shell commands](https://nodejs-itoolkit.readthedocs.io/en/latest/CommandCall.html) # Documentation Please read the [docs](https://nodejs-itoolkit.readthedocs.io/en/latest/). -# Testing +# Tests Refer to the [README](test/README.md). # Contributing