Skip to content

docs: Simplify main README to contain basic info #260

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Apr 24, 2020
Merged

docs: Simplify main README to contain basic info #260

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e853908
docs: Simplify main README to contain basic info
abmusse Apr 22, 2020
7733c32
fixup! docs: Simplify main README to contain basic info
abmusse Apr 22, 2020
177e4f0
fixup! fixup! docs: Simplify main README to contain basic info
abmusse Apr 23, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
244 changes: 47 additions & 197 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,199 +1,68 @@
# Node.js iToolkit <!-- omit in toc -->
# Node.js itoolkit <!-- omit in toc -->

[![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)
[![ryver-chat](https://img.shields.io/badge/Ryver-Chat-blue)](https://ibmioss.ryver.com/index.html#forums/1000127)
[![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 <!-- omit in toc -->
- [Introduction](#introduction)
- [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)
- [Tests](#tests)
- [Contributing](#contributing)
- [License](#license)

# Installation

Before installing, download and install Node.js

```sh
$ npm i itoolkit@alpha
```
# Introduction

## Main Classes
[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.

### Connection
The Connection class is used to transport xml input and return xml output.
For example run a CL command by sending the following XML input to XMLSERVICE.

#### 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' }
});
```xml
<?xml version="1.0" encoding="UTF-8"?>
<myscript>
<cmd exec="rexx">RTVJOBA USRLIBL(?) SYSLIBL(?)</cmd>
</myscript>
```

##### 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/
<Directory /QSYS.LIB/XMLSERVICE.LIB/>
AllowOverride None
Require all granted
SetHandler cgi-script
Options +ExecCGI
</Directory>
```

- 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' }
});
XMLSERVICE will run the command and respond with XML output.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<myscript>
<cmd exec="rexx">
<success>+++ success RTVJOBA USRLIBL(?) SYSLIBL(?)</success>
<row>
<data desc="USRLIBL">QGPL QTEMP</data>
</row>
<row>
<data desc="SYSLIBL">QSYS QSYS2 QHLPSYS QUSRSYS</data>
</row>
</cmd>
</myscript>
```

##### 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');
`itoolkit` can run the same CL command with:

const privateKey = readFileSync('path/to/privateKey', 'utf-8');

// NOTE if your privateKey also requires a passphrase provide it
```js
const { Connection, CommandCall } = require('itoolkit');
const { parseString } = require('xml2js');

const connection = new Connection({
transport: 'ssh',
transportOptions: { host: 'myhost', username: 'myuser', privateKey, passphrase: 'myphrase' }
transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' },
});
```

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' }
});
```
const command = new CommandCall({ type: 'cl', command: 'RTVJOBA USRLIBL(?) SYSLIBL(?)' });

##### ODBC
The [ODBC](https://github.com/wankdanker/node-odbc/tree/v2.0) transport establishes a database connection and calls XMLSERVICE stored procedure.
connection.add(command);

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) => {
connection.run((error, xmlOutput) => {
if (error) {
throw error;
}
Expand All @@ -203,47 +72,28 @@ conn.run((error, xmlOutput) => {
}
console.log(JSON.stringify(result));
});
});
```
### CommandCall
CommandCall is used to execute a CL, QSH, or PASE command.

#### Example
```javascript
const {
Connection, CommandCall,
} = require('itoolkit');
The purpose of this package is to simplify the process of creating XMLSERVICE input, invoking XMLSERVICE, and returning XMLSERVICE output from Node.js.

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' }));
# Installation

conn.run((error, xmlOutput) => {
if (error) {
throw error;
}
parseString(xmlOutput, (parseError, result) => {
if (parseError) {
throw parseError;
}
console.log(JSON.stringify(result));
});
});
```sh
$ npm install itoolkit
```

# Features
- [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
Refer to the [README](test/README.md)
# Tests
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)