Skip to content

Commit f51438e

Browse files
abmusseabmusse
committed
[README.md] Update Readme for v1.0.0
- Document Classes, transports, examples
1 parent 15ec42d commit f51438e

File tree

1 file changed

+251
-62
lines changed

1 file changed

+251
-62
lines changed

‎README.md

+251-62
Original file line numberDiff line numberDiff line change
@@ -1,84 +1,273 @@
1-
# Node.js Toolkit
2-
3-
#### The toolkit is a Node.js wrapper over the XMLSERVICE open source project from IBM.
1+
# Node.js iToolkit <!-- omit in toc -->
42

53
[![NPM](https://nodei.co/npm/itoolkit.png?downloads=true&downloadRank=true)](https://nodei.co/npm/itoolkit/)
64

7-
# Installation
85

9-
Installation is done from a PASE shell.
6+
`itoolkit` is a Node.js interface to [XMLSERVICE](https://github.com/IBM/xmlservice) to access all things IBM i.
7+
8+
# Table of Contents <!-- omit in toc -->
9+
- [Installation](#installation)
10+
- [Main Classes](#main-classes)
11+
- [Connection](#connection)
12+
- [Transports](#transports)
13+
- [idb-connector](#idb-connector)
14+
- [REST](#rest)
15+
- [SSH](#ssh)
16+
- [ProgramCall](#programcall)
17+
- [Example](#example)
18+
- [CommandCall](#commandcall)
19+
- [Example](#example-1)
20+
- [SqlCall](#sqlcall)
21+
- [Example](#example-2)
22+
- [Utility Toolkit Functions](#utility-toolkit-functions)
23+
- [Documentation](#documentation)
24+
- [Testing](#testing)
25+
- [Contributing](#contributing)
26+
- [License](#license)
27+
28+
# Installation
29+
30+
Before installing, download and install Node.js
1031

1132
```sh
1233
$ npm i itoolkit
1334
```
1435

15-
# Quick Example
36+
## Main Classes
1637

17-
## Example 1: Basic APIs
18-
```js
19-
var xt = require("itoolkit");
20-
var conn = new xt.iConn("*LOCAL", "USERNAME", "PASSWORD");
21-
22-
function cbJson(str) {
23-
var result = xt.xmlToJson(str);
24-
console.log(JSON.stringify(result, " ", 2))
25-
}
26-
27-
conn.add(xt.iCmd("RTVJOBA USRLIBL(?) SYSLIBL(?)")); /* Test iCmd */
28-
conn.add(xt.iSh("system -i wrksyssts")); /* Test iSh */
29-
var pgm = new xt.iPgm("QWCRSVAL", {"lib":"QSYS"}); /* Test iPgm */
30-
var outBuf = [
31-
[0, "10i0"],
32-
[0, "10i0"],
33-
["", "36h"],
34-
["", "10A"],
35-
["", "1A"],
36-
["", "1A"],
37-
[0, "10i0"],
38-
[0, "10i0"]
39-
];
40-
pgm.addParam(outBuf, {"io":"out"});
41-
pgm.addParam(66, "10i0");
42-
pgm.addParam(1, "10i0");
43-
pgm.addParam("QCCSID", "10A");
44-
pgm.addParam(this.errno, {"io":"both", "len" : "rec2"});
45-
conn.add(pgm);
46-
47-
var sql = new xt.iSql(); /* Test iSql Class */
48-
sql.prepare("call qsys2.tcpip_info()");
49-
sql.execute();
50-
sql.fetch();
51-
sql.free();
52-
conn.add(sql);
53-
conn.run(cbJson);
38+
### Connection
39+
The Connection class is used to transport xml input and return xml output.
40+
41+
#### Transports
42+
Supported transports include [idb-connector](https://github.com/IBM/nodejs-idb-connector), REST, and SSH.
43+
44+
##### idb-connector
45+
The [idb-connector](https://github.com/IBM/nodejs-idb-connector) transport establishes a database connection and calls XMLSERVICE stored procedure.
46+
47+
**NOTE** the `idb-connector` transport is only supported on an IBM i system.
48+
49+
To use the `idb-connector` transport create an instance of Connection with:
50+
51+
```javascript
52+
const connection = new Connection({
53+
transport: 'idb',
54+
transportOptions: { database: '*LOCAL', username: 'myuser', password: 'mypass' }
55+
});
5456
```
5557

56-
## Example 2: Toolkit classes
57-
```js
58-
var xt = require("itoolkit");
59-
var wk = require('itoolkit/lib/iwork');
60-
var nt = require('itoolkit/lib/inetwork');
58+
##### REST
59+
The REST transport makes an HTTP request to an endpoint that process the XML input and returns XML output.
60+
61+
Initial configuration is required for the endpoint.
62+
63+
A quick example is to add the following to `/www/apachedft/conf/httpd.conf`
64+
65+
```
66+
ScriptAlias /cgi-bin/ /QSYS.LIB/XMLSERVICE.LIB/
67+
<Directory /QSYS.LIB/XMLSERVICE.LIB/>
68+
AllowOverride None
69+
order allow,deny
70+
allow from all
71+
SetHandler cgi-script
72+
Options +ExecCGI
73+
</Directory>
74+
```
6175

62-
var conn = new xt.iConn("*LOCAL", "USERNAME", "PASSWORD");
76+
- start the server
6377

64-
var work = new wk.iWork(conn);
65-
var net = new nt.iNetwork(conn);
78+
` STRTCPSVR SERVER(*HTTP) HTTPSVR(APACHEDFT)`
6679

67-
work.getSysValue("QCCSID", (output) => {
68-
console.log("QCCSID = " + output);
69-
});
80+
- go to `http://HOSTNAME:PORT/cgi-bin/xmlcgi.pgm`
7081

71-
net.getTCPIPAttr((output) => {
72-
console.log(JSON.stringify(output, " ", 2));
73-
});
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+
});
7491
```
7592

76-
# API Reference
77-
* https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/wiki/IBM%20i%20Technology%20Updates/page/Toolkit%20for%20i%20APIs
93+
##### SSH
94+
The SSH transport executes `xmlservice-cli` program via ssh.
7895

79-
# Contributions
80-
Please read the [contribution guidelines](https://github.com/IBM/nodejs-itoolkit/blob/master/CONTRIBUTING.md).
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');
108+
109+
const privateKey = readFileSync('path/to/privateKey', 'utf-8');
110+
111+
// NOTE if your privateKey also requires a passphrase provide it
112+
113+
const connection = new Connection({
114+
transport: 'ssh',
115+
transportOptions: { host: 'myhost', username: 'myuser', privateKey, passphrase: 'myphrase' }
116+
});
117+
```
118+
119+
To use the `SSH` transport with password authentication create an instance of Connection with:
120+
121+
```javascript
122+
123+
const connection = new Connection({
124+
transport: 'ssh',
125+
transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }
126+
});
127+
```
81128

129+
### ProgramCall
130+
The ProgramCall class is used to call IBM i programs and service programs.
131+
132+
#### Example
133+
```javascript
134+
const {
135+
Connection, ProgramCall, xmlToJson,
136+
} = require('itoolkit');
137+
138+
const conn = new Connection({
139+
transport: 'ssh',
140+
transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }
141+
});
142+
143+
const program = new ProgramCall('QWCRSVAL', { lib: 'QSYS' });
144+
const outBuf = [
145+
[0, '10i0'],
146+
[0, '10i0'],
147+
['', '36h'],
148+
['', '10A'],
149+
['', '1A'],
150+
['', '1A'],
151+
[0, '10i0'],
152+
[0, '10i0'],
153+
];
154+
const errno = [
155+
[0, '10i0'],
156+
[0, '10i0', { setlen: 'rec2' }],
157+
['', '7A'],
158+
['', '1A'],
159+
];
160+
161+
program.addParam(outBuf, { io: 'out' });
162+
program.addParam(66, '10i0');
163+
program.addParam(1, '10i0');
164+
program.addParam('QCCSID', '10A');
165+
program.addParam(errno, { io: 'both', len: 'rec2' });
166+
167+
conn.add(program);
168+
169+
170+
conn.run((error, xmlOutput) => {
171+
if (error) {
172+
throw error;
173+
}
174+
const result = xmlToJson(xmlOutput);
175+
console.log(result);
176+
});
177+
```
178+
### CommandCall
179+
CommandCall is used to execute a CL, QSH, or PASE command.
180+
181+
#### Example
182+
```javascript
183+
const {
184+
Connection, CommandCall, xmlToJson,
185+
} = require('itoolkit');
186+
187+
const conn = new Connection({
188+
transport: 'ssh',
189+
transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }
190+
});
191+
192+
conn.add(new CommandCall({ command: 'RTVJOBA USRLIBL(?) SYSLIBL(?)', type: 'cl' }));
193+
194+
conn.run((error, xmlOutput) => {
195+
if (error) {
196+
throw error;
197+
}
198+
const result = xmlToJson(xmlOutput);
199+
console.log(result);
200+
});
201+
```
202+
203+
### SqlCall
204+
SqlCall is used to make an SQL query.
205+
206+
#### Example
207+
208+
```javascript
209+
const {
210+
Connection, SqlCall, xmlToJson,
211+
} = require('itoolkit');
212+
213+
const conn = new Connection({
214+
transport: 'ssh',
215+
transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }
216+
});
217+
218+
const sql = new SqlCall();
219+
sql.prepare('call qsys2.tcpip_info()');
220+
sql.execute();
221+
sql.fetch();
222+
sql.free();
223+
224+
conn.add(sql);
225+
226+
conn.run((error, xmlOutput) => {
227+
if (error) {
228+
throw error;
229+
}
230+
const result = xmlToJson(xmlOutput);
231+
console.log(result);
232+
});
233+
```
234+
## Utility Toolkit Functions
235+
236+
Aside from the main classes this toolkit also provides helper functions to access:
237+
- Data Queues
238+
- User Space objects
239+
- Object info
240+
- Product info
241+
- Network info
242+
243+
```js
244+
const {
245+
Connection, Toolkit, xmlToJson,
246+
} = require('itoolkit');
247+
248+
const conn = new Connection({
249+
transport: 'ssh',
250+
transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }
251+
});
252+
253+
const toolkit = new Toolkit(conn);
254+
255+
toolkit.getSysValue('QCCSID', (error, value) => {
256+
if (error) {
257+
throw error;
258+
}
259+
console.log(`QCCSID = ${value}`);
260+
});
261+
```
262+
263+
# Documentation
264+
TODO port and update Docs from [developer works](https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/wiki/IBM%20i%20Technology%20Updates/page/Toolkit%20for%20i%20APIs)
265+
266+
# Testing
267+
Refer to the [README](test/README.md)
268+
269+
# Contributing
270+
Please read the [contribution guidelines](https://github.com/IBM/nodejs-itoolkit/blob/master/CONTRIBUTING.md).
82271

83272
# License
84-
[`MIT`](https://github.com/IBM/nodejs-itoolkit/blob/master/LICENSE) file.
273+
[`MIT`](https://github.com/IBM/nodejs-itoolkit/blob/master/LICENSE)

0 commit comments

Comments
 (0)