Skip to content

Commit 85c860b

Browse files
abmusseabmusse
authored
docs: Simplify main README to contain basic info (#260)
1 parent 727b6c4 commit 85c860b

File tree

1 file changed

+47
-197
lines changed

1 file changed

+47
-197
lines changed

‎README.md‎

Lines changed: 47 additions & 197 deletions
Original file line numberDiff line numberDiff line change
@@ -1,199 +1,68 @@
1-
# Node.js iToolkit <!-- omit in toc -->
1+
# Node.js itoolkit <!-- omit in toc -->
22

33
[![npm](https://img.shields.io/npm/v/itoolkit?logo=npm)](https://www.npmjs.com/package/itoolkit)
44
![Supported Node Versions](https://img.shields.io/node/v-lts/itoolkit)
55
[![ryver-chat](https://img.shields.io/badge/Ryver-Chat-blue)](https://ibmioss.ryver.com/index.html#forums/1000127)
66
[![ryver-signup](https://img.shields.io/badge/Ryver-Signup-blue)](https://ibmioss.ryver.com/application/signup/members/9tJsXDG7_iSSi1Q)
77
[![Documentation Status](https://readthedocs.org/projects/nodejs-itoolkit/badge/?version=latest)](https://nodejs-itoolkit.readthedocs.io/en/latest/?badge=latest)
88

9-
`itoolkit` is a Node.js interface to [XMLSERVICE](https://github.com/IBM/xmlservice) to access all things IBM i.
9+
`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).
1010

1111
# Table of Contents <!-- omit in toc -->
12+
- [Introduction](#introduction)
1213
- [Installation](#installation)
13-
- [Main Classes](#main-classes)
14-
- [Connection](#connection)
15-
- [Transports](#transports)
16-
- [idb-connector](#idb-connector)
17-
- [REST](#rest)
18-
- [SSH](#ssh)
19-
- [ODBC](#odbc)
20-
- [ProgramCall](#programcall)
21-
- [Example](#example)
22-
- [CommandCall](#commandcall)
23-
- [Example](#example-1)
14+
- [Features](#features)
2415
- [Documentation](#documentation)
25-
- [Testing](#testing)
16+
- [Tests](#tests)
2617
- [Contributing](#contributing)
2718
- [License](#license)
2819

29-
# Installation
30-
31-
Before installing, download and install Node.js
32-
33-
```sh
34-
$ npm i itoolkit@alpha
35-
```
20+
# Introduction
3621

37-
## Main Classes
22+
[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.
3823

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

42-
#### Transports
43-
Supported transports include [idb-connector](https://github.com/IBM/nodejs-idb-connector), REST, SSH, and ODBC.
44-
45-
##### idb-connector
46-
The [idb-connector](https://github.com/IBM/nodejs-idb-connector) transport establishes a database connection and calls XMLSERVICE stored procedure.
47-
48-
**NOTE** the `idb-connector` transport is only supported on an IBM i system.
49-
50-
To use the `idb-connector` transport create an instance of Connection with:
51-
52-
```javascript
53-
const connection = new Connection({
54-
transport: 'idb',
55-
transportOptions: { database: '*LOCAL', username: 'myuser', password: 'mypass' }
56-
});
26+
```xml
27+
<?xml version="1.0" encoding="UTF-8"?>
28+
<myscript>
29+
<cmd exec="rexx">RTVJOBA USRLIBL(?) SYSLIBL(?)</cmd>
30+
</myscript>
5731
```
5832

59-
##### REST
60-
The REST transport makes an HTTP request to an endpoint that process the XML input and returns XML output.
61-
62-
Initial configuration is required for the endpoint.
63-
64-
A quick example is to add the following to `/www/apachedft/conf/httpd.conf`
65-
66-
```apache
67-
ScriptAlias /cgi-bin/ /QSYS.LIB/XMLSERVICE.LIB/
68-
<Directory /QSYS.LIB/XMLSERVICE.LIB/>
69-
AllowOverride None
70-
Require all granted
71-
SetHandler cgi-script
72-
Options +ExecCGI
73-
</Directory>
74-
```
75-
76-
- start the server
77-
78-
` STRTCPSVR SERVER(*HTTP) HTTPSVR(APACHEDFT)`
79-
80-
- go to `http://HOSTNAME:PORT/cgi-bin/xmlcgi.pgm`
81-
82-
you should see an XML document
83-
84-
To use the `REST` transport create an instance of Connection with:
85-
86-
```javascript
87-
const connection = new Connection({
88-
transport: 'rest',
89-
transportOptions: { host: 'myhost', port: 80, path:'/cgi-bin/xmlcgi.pgm' database: '*LOCAL', username: 'myuser', password: 'mypass' }
90-
});
33+
XMLSERVICE will run the command and respond with XML output.
34+
35+
```xml
36+
<?xml version="1.0" encoding="UTF-8"?>
37+
<myscript>
38+
<cmd exec="rexx">
39+
<success>+++ success RTVJOBA USRLIBL(?) SYSLIBL(?)</success>
40+
<row>
41+
<data desc="USRLIBL">QGPL QTEMP</data>
42+
</row>
43+
<row>
44+
<data desc="SYSLIBL">QSYS QSYS2 QHLPSYS QUSRSYS</data>
45+
</row>
46+
</cmd>
47+
</myscript>
9148
```
9249

93-
##### SSH
94-
The SSH transport executes `xmlservice-cli` program via ssh.
95-
96-
Ensure you have OpenSSH installed on your IBM i system.
97-
98-
Also `xmlservice-cli` is required on the IBM i host with:
99-
100-
`yum install itoolkit-utils`
101-
102-
The [ssh2](https://www.npmjs.com/package/ssh2#client-methods) client module is used to connect and supports both private key and password authentication.
103-
104-
To use the `SSH` transport with private key authentication create an instance of Connection with:
105-
106-
```javascript
107-
const { readFileSync } = require('fs');
50+
`itoolkit` can run the same CL command with:
10851

109-
const privateKey = readFileSync('path/to/privateKey', 'utf-8');
110-
111-
// NOTE if your privateKey also requires a passphrase provide it
52+
```js
53+
const { Connection, CommandCall } = require('itoolkit');
54+
const { parseString } = require('xml2js');
11255

11356
const connection = new Connection({
11457
transport: 'ssh',
115-
transportOptions: { host: 'myhost', username: 'myuser', privateKey, passphrase: 'myphrase' }
58+
transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' },
11659
});
117-
```
118-
119-
To use the `SSH` transport with password authentication create an instance of Connection with:
120-
121-
```javascript
12260

123-
const connection = new Connection({
124-
transport: 'ssh',
125-
transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }
126-
});
127-
```
61+
const command = new CommandCall({ type: 'cl', command: 'RTVJOBA USRLIBL(?) SYSLIBL(?)' });
12862

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

132-
Refer to the [odbc setup guide](https://github.com/IBM/ibmi-oss-examples/blob/master/odbc/odbc.md#table-of-contents) for setup instructions.
133-
134-
To use the `ODBC` transport create an instance of Connection with:
135-
136-
```javascript
137-
const connection = new Connection({
138-
transport: 'odbc',
139-
transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword'}
140-
});
141-
```
142-
143-
Alternatively you can specify a [DSN](https://github.com/IBM/ibmi-oss-examples/blob/master/odbc/odbc.md#dsns) to use.
144-
145-
To use the `ODBC` transport with a DSN create an instance of Connection with:
146-
147-
```javascript
148-
const connection = new Connection({
149-
transport: 'odbc',
150-
transportOptions: { dsn: '*LOCAL'}
151-
});
152-
```
153-
### ProgramCall
154-
The ProgramCall class is used to call IBM i programs and service programs.
155-
156-
#### Example
157-
```javascript
158-
const {
159-
Connection, ProgramCall,
160-
} = require('itoolkit');
161-
162-
const { parseString } = require('xml2js');
163-
164-
const conn = new Connection({
165-
transport: 'ssh',
166-
transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }
167-
});
168-
169-
const program = new ProgramCall('QWCRSVAL', { lib: 'QSYS' });
170-
const outBuf = [
171-
[0, '10i0'],
172-
[0, '10i0'],
173-
['', '36h'],
174-
['', '10A'],
175-
['', '1A'],
176-
['', '1A'],
177-
[0, '10i0'],
178-
[0, '10i0'],
179-
];
180-
const errno = [
181-
[0, '10i0'],
182-
[0, '10i0', { setlen: 'rec2' }],
183-
['', '7A'],
184-
['', '1A'],
185-
];
186-
187-
program.addParam(outBuf, { io: 'out' });
188-
program.addParam(66, '10i0');
189-
program.addParam(1, '10i0');
190-
program.addParam('QCCSID', '10A');
191-
program.addParam(errno, { io: 'both', len: 'rec2' });
192-
193-
conn.add(program);
194-
195-
196-
conn.run((error, xmlOutput) => {
65+
connection.run((error, xmlOutput) => {
19766
if (error) {
19867
throw error;
19968
}
@@ -203,47 +72,28 @@ conn.run((error, xmlOutput) => {
20372
}
20473
console.log(JSON.stringify(result));
20574
});
206-
});
20775
```
208-
### CommandCall
209-
CommandCall is used to execute a CL, QSH, or PASE command.
21076
211-
#### Example
212-
```javascript
213-
const {
214-
Connection, CommandCall,
215-
} = require('itoolkit');
77+
The purpose of this package is to simplify the process of creating XMLSERVICE input, invoking XMLSERVICE, and returning XMLSERVICE output from Node.js.
21678
217-
const { parseString } = require('xml2js');
218-
219-
const conn = new Connection({
220-
transport: 'ssh',
221-
transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }
222-
});
223-
224-
conn.add(new CommandCall({ command: 'RTVJOBA USRLIBL(?) SYSLIBL(?)', type: 'cl' }));
79+
# Installation
22580
226-
conn.run((error, xmlOutput) => {
227-
if (error) {
228-
throw error;
229-
}
230-
parseString(xmlOutput, (parseError, result) => {
231-
if (parseError) {
232-
throw parseError;
233-
}
234-
console.log(JSON.stringify(result));
235-
});
236-
});
81+
```sh
82+
$ npm install itoolkit
23783
```
23884
85+
# Features
86+
- [Call ILE programs and service programs](https://nodejs-itoolkit.readthedocs.io/en/latest/ProgramCall.html)
87+
- [Call CL, QSH, and PASE shell commands](https://nodejs-itoolkit.readthedocs.io/en/latest/CommandCall.html)
88+
23989
# Documentation
24090
Please read the [docs](https://nodejs-itoolkit.readthedocs.io/en/latest/).
24191
242-
# Testing
243-
Refer to the [README](test/README.md)
92+
# Tests
93+
Refer to the [README](test/README.md).
24494
24595
# Contributing
24696
Please read the [contribution guidelines](https://github.com/IBM/nodejs-itoolkit/blob/master/CONTRIBUTING.md).
24797
24898
# License
249-
[`MIT`](https://github.com/IBM/nodejs-itoolkit/blob/master/LICENSE)
99+
[MIT](https://github.com/IBM/nodejs-itoolkit/blob/master/LICENSE)

0 commit comments

Comments
 (0)