Install and Use Node.js iToolkit for IBM i
Node.js has joined other popular IBM i open-source technologies, such as PHP and Python, for web application and API development. A server-side runtime for JavaScript, Node.js can run both on IBM i and on other platforms such as Linux.
The Node.js iToolkit lets you leverage your company’s investment in RPG and COBOL business logic while developing front ends and APIs with Node.js. As with Node.js itself, iToolkit can run on your IBM i or can connect to IBM i from your PC or an external web server.
This post explains how to install Node.js and its iToolkit on your IBM i, then use iToolkit to call an RPG service program.
Install Node.js
First, make sure you’ve set up the open source environment on your IBM i.
Then, before proceeding with these instructions, make sure you have set up the open source path.
To install Node.js, see IBM’s documentation and use the yum approach: https://ibmi-oss-docs.readthedocs.io/en/latest/nodejs/README.html.
Note: To run the example given in this post, you will have to install the ODBC driver as well.
Once you have open source and Node.js installed, it’s time to install the iToolkit.
Install iToolkit
Node has a robust package manager called npm that can install iToolkit and other npm-enabled modules.
If you are creating a new project, we recommend installing Node packages (called modules) in your project directory, rather than in the global package area. That way, you can later upgrade your Node modules located in individual projects without unintentionally affecting your other projects.
If you don’t have a project directory yet, create it now. For example, let’s say you wanted to create a project directory in your IBM i home directory (/home/aseiden in my case). From a PASE terminal (SSH preferred):
|
1 2 |
cd ~ mkdir toolkit-test |
Now, go into your project directory:
|
1 |
cd ~/toolkit-test |
Then (only if this is a new project) initialize the npm environment with a new package.json file by typing:
|
1 |
npm init --yes |
This initialization command will create the package.json file under your project.
Verify that package.json was created by running ls:
|
1 |
ls |
You should see one file: package.json.
Now install the iToolkit module:
|
1 |
npm install itoolkit |
See the results of your npm command by running ls again:
|
1 |
ls |
You should see three names: node_modules package-lock.json package.json.
Let’s list the contents of the node_modules directory:
|
1 |
ls node_modules |
You should see a large list of modules, including itoolkit and its dependent modules fast-xml-parser and odbc.
If any modules are missing, or if you saw module installation errors, try updating npm to the latest stable version (npm install npm@latest -g), then install the modules again.
Use iToolkit to call a service program
IBM’s documentation provides an example script for calling a service program using the iToolkit.
The example shows how to call the cos (cosine) procedure in service program QSYS/QC2UTIL2 and get its return value. (Service program QC2UTIL2 comes preinstalled with the IBM i operating system.)
I’ve modified IBM’s example in several ways:
- Connect using ODBC instead of SSH
- Add parameter names for easier reading
- Add comments and more descriptive console.log text
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 |
const { Connection, ProgramCall } = require('itoolkit'); const { XMLParser } = require('fast-xml-parser'); const conn = new Connection({ transport: 'odbc', transportOptions: { dsn: '*LOCAL'} }); const program = new ProgramCall('QC2UTIL2', { lib: 'QSYS', func: 'cos' }); program.addParam({ name: 'angle', type: '8f', value: '0', by: 'val' }); program.addReturn({ name: 'cos', type: '8f', value: '' }); conn.add(program); conn.run((error, xmlOutput) => { if (error) { throw error; } // uncomment next line if you want to see raw XML output // console.log(xmlOutput); // parse XML into JSON const XmlToJsonParser = new XMLParser(); const result = XmlToJsonParser.parse(xmlOutput); // demonstrate how to extract parameter and return value console.log('Angle input: ' + result.myscript.pgm.parm.data + ' Cosine result: ' + result.myscript.pgm.return.data); }); |
Use your favorite IFS file editor or uploader to save this cosine.js script in the toolkit-test project directory you created earlier.
Run the script from your terminal like so:
|
1 |
node cosine.js |
You should see this output: Angle input: 0 Cosine result: 1, from the ‘0’ passed in to addParam().
To test this script with a different angle value, change the ‘0’ to another radian angle, such as ‘3.14159’, which should return -1.
A note about fast-xml-parser: This example uses the fast-xml-parser module to convert iToolkit’s raw XML output to JSON, which the Node script can read natively. The latest iToolkit package installs fast-xml-parser automatically as a dependency.
Getting started with Node.js
Take advantage of our 1-on-1 support as you build and maintain your Node.js APIs or web applications. Check out our SmartSupport program and its Developer Productivity Package.
If you need an even faster start, let us implement your pilot project. You’ll learn Node.js development techniques as we focus on completing your project. Or not. The choice is entirely yours.
Great article! We are pushing the bounds of the known 400 universe here!
Verify values passed. Not sure what QC2UTIL2 is expecting, but I think sin/cos are best calculated with several decimals. (8f3)?
Thanks, Martin! The 8f type is the one expected by the ‘cos’ procedure of QC2UTIL2. I believe in floating point types, the decimal places are implied even if not given explicitly.
Alan,
I’ve followed the instructions in this article. After performing the
npm install itoolkit command, my node_modules contains contains itoolkit and fast-xml-parser, but does not contain odbc.
I have also followed your article on how to install the ODBC driver, and can execute the SQL statement using /QOpenSys/pkgs/bin/isql -v *LOCAL.
I’m on V7R4, and am also using the latest stable version of npm: (9.3.1)
Any suggestions?
Try updating your npm again using “npm install npm@latest -g”. My npm shows version 9.6.0. (I tested the installation and successfully got the odbc module.) Let me know how it goes.