Welcome back to the next thoroughly thrilling installment of our series on transforming RPGLE into modern web services on IBM i.
Thus far we have built the robust backend: Physical File (FOODFILE) for data and an RPGLE module (WEBFOOD) handling customer read/add/update/delete logic with validation and error codes.
Now, we'll bridge the gap to the web by wrapping that module in JavaScript endpoints using the itoolkit library. This lets you serve RESTful APIs over HTTP, callable from any client browsers, Postman, or mobile apps.
By the end of this lesson, you'll deploy a lightweight Node.js server on IBM i, test your endpoints, and have a full-stack API ready for production. We'll keep it simple: no heavy frameworks, just itoolkit for XML-RPC calls to your RPGLE.
Prerequisites:
- Completed Part 1: RPGLE program WEBFOOD compiled in FOODLIB.
- IBM i with PASE (PASE for Node.js) and access to install Node.js (via yum or ACS Run SQL Scripts).
- Basic Node.js knowledge (we'll provide full code).
- Tools: Postman (or curl) for testing; a web browser.
If you're new to Node on IBM i, no sweat!
IBM's PASE makes it feel native. Let's get your API live!
Why JavaScript + itoolkit for RPGLE Web Services?
Your RPGLE is the rock-solid core, but clients expect JSON over HTTP.
Enter itoolkit: a lightweight JS library that generates XML Program Call Markup Language (PCML) to invoke IBM i programs via XMLSERVICE. It's efficient, secure (uses IBM i auth), and handles the RPGLE-to-JSON translation seamlessly.
What is iToolKit for IBM i
iToolKit is a client library that lets modern languages call IBM i native services (RPG/CL programs, commands, SQL, and QSYS APIs) through the XMLSERVICE interface. It abstracts parameter marshalling, transport details, and result parsing so JavaScript/Node.js apps can treat IBM i business logic as remote procedure calls or microservice endpoints.
Key features and benefits
Calls RPG/COBOL/CL programs and program-described parameters without hand‑packing buffers.
Executes CL commands and embedded SQL and returns structured results.
Supports multiple transports: HTTP(S) gateway, SSH, and direct DB connections (where applicable).
Parses XML/JSON responses into plain JavaScript objects for easy handling.
Simplifies modern web/API front ends accessing existing IBM i logic, enabling safe modernization without rewriting core business code.
What is express for IBM i
The IBM i express open source package is the Node.js Express web framework packaged and made available for the IBM i PASE environment so developers can run Express applications natively on the system.
How it helps iToolKit integrations
Lets you host a local HTTP endpoint that receives requests, runs middleware, and forwards calls to IBM i through iToolKit.
Provides routing and body parsing so you can map HTTP payloads to RPGLE program parameters before invoking iToolKit.
Enables a simple, maintainable wrapper layer that converts RPG return structures into JSON responses.
Makes it straightforward to add auth, logging, rate limiting, TLS termination, and other API concerns before or after iToolKit calls.
What is fast-xml-parser for IBM i
fast-xml-parser is a fast, pure‑JavaScript XML parser commonly installed via npm and usable in the PASE/Node environment on IBM i to parse XML into JavaScript objects or JSON and to build XML from objects.
How it helps iToolKit integrations
iToolKit often returns XML (XMLSERVICE); fast-xml-parser converts those XML payloads into plain JavaScript objects for routing, validation, and HTTP response generation.
Using it removes the need to hand-parse XML, simplifies parameter extraction, and speeds development of JavaScript wrappers around RPGLE services.
Benefits:
- RESTful by Default: Map POST requests to your module's params.
- Zero Overhead: Runs in PASE; no Java EE servers needed.
- Scalable: Handles concurrent calls; integrate with Express for routing.
- Debug-Friendly: Logs XML payloads for troubleshooting.
IBM i 7.3+ supports Node.js natively via the open-source package manager.
We'll install, verify, and grab itoolkit.
Install NodeJS using IBM i ACS
To install open-source software on IBM i, you’ll need the appropriate authority and follow the right steps.
IBM i Node.js SDK
If you’re installing Node.js (or any other open-source package) using the IBM i Node.js SDK, you’ll need sufficient authority to install software on your system. Obviously you will need to ensure you have the necessary permissions to install RPM packages.
PASE (Portable Application Solutions Environment):
When working with open-source software via PASE, you’ll need the following authority:
IBM i Access Client Solutions (ACS):
If you’re using ACS to manage open-source packages, you’ll need the necessary authority to:
- Download software (such as RPM packages) using ACS.
- Install the downloaded packages.
- Update existing packages.
Ensure you have the appropriate permissions to perform these actions.
Community Support:
- For community-supported open-source projects (e.g., Node.js packages), you can raise defects or seek assistance on community channels like GitHub.
- While IBM provides some level of free community support for specific integration pieces, it’s essential to engage with the relevant open-source community for assistance.
For more information on installing open-source packages, visit the IBM i RPM Packages page.
Launch IBM i ACS Open Source Package Management
Logon with a Profile with authority
Open Open Source Package Management in ACS
You will now see a screen that lists all the open source packages already installed on your system.
If you scroll down and find node.js is installed, then you are good to go.
If it is not installed then simply click the AVAILABLE PACKAGE heading and scroll down to find nodejs20 (or your preferred version).
You will see several different versions of node.js available for ibm i systems:
Let’s explore the differences between Node.js versions 14, 16, 18, and 20. Each of these versions brings its own set of features and improvements:
- End-of-Life: Node.js 14 will go End-of-Life in April 2023.
- Stability: It’s an LTS (Long-Term Support) version, which means it’s stable and well-supported.
- Recommended for Production: Ideal for production environments where reliability is crucial.
- Features: Node.js 14 introduced features like worker threads, V8 engine updates, and improved diagnostics.
- Considerations: If you’re currently on Node.js 14, plan to upgrade to either Node.js 18 (LTS) or Node.js 20 (soon to be LTS).
- End-of-Life: Node.js 16 will go End-of-Life in September 2023 (brought forward from April 2024 due to OpenSSL 1.1.1 support).
- Stability: Another LTS version with stability and long-term support.
- Features: Node.js 16 introduced ECMAScript modules (ESM), V8 updates, and performance improvements.
- Use Cases: Suitable for applications that benefit from ESM and need long-term support.
- Preferred LTS Version: As of now, Node.js 18.14.0 is the preferred LTS version.
- Stability: Provides stability and long-term support.
- Features: Node.js 18 includes enhancements like URL, fetch(), and EventTarget improvements.
- Considerations: If you’re looking for a stable LTS version, Node.js 18 is a good choice.
- Not Yet LTS: Node.js 20 is the current release and will enter LTS in October.
- Features: Node.js 20 introduces the Permission Model (restricting access to resources), synchronous import.meta.resolve, and other improvements.
- Performance: Leverages V8 Fast API calls for better performance.
- Evaluation: Explore the new features and evaluate their impact on your applications.
In summary, choose the LTS versions (14, 16, or 18) for production systems, and consider Node.js 20 for experimentation and feature exploration.
Life on the modern edge is fun.
Choose Node.js 2.0 🙂
Enter a 'Y', sit back and sip your cup of tea (either ASSAM or EARL GRAY is acceptable) and watch Node.JS install on your IBM i System.
HUZZAH! node.js is installed on my IBM i System
Create WEBSERVICE-FOOD Project Directory
The webserver information will be stored in the IFS so let's create af older off your personal IFS folder and call it 'webservice-food' (e.g., /home/youruser/webservice-food/):
Initialize this Node project
Initializing a Node project means creating the basic files and structure that let Node.js and npm manage your app: a package.json manifest, a place for source code, and an initial set of dependencies and scripts so you can run, test, and publish the project.
Quick one-line
Run npm init (or npm init -y) in an empty folder to create and start your project.
Why do it
records project name, version, entry point, scripts, and dependencies.
npm/yarn can install and track packages your code needs.
Consistent scripts let you run the app the same way on every machine.
It makes the project shareable, reproducible, and ready for CI/CD.
Now from the QSH command line we are going to confirm we are in the correct directory, we have access to NODE and NPM and then initialize:
which node
Initialize our Node Project in Project Folder
Use your QSHELL terminal and run NPM INIT
For this example, and screen shots, I will be using a PASE TERMINAL from VS-Code
You want to answer the prompts as they come up:
Hopefully this works and you will find a package.json file in your project folder:
Install itoolkit and express and fast-xml-parser:
Your package.json now has dependencies. Pro tip: Add .npmrc with engine-strict=true for version pinning.
Verify Setup
The echo command writes a single-line Node.js script into a file named test.js; the redirection operator (>) creates or overwrites that file. The node command at /QOpenSys/pkgs/opt/nodejs/bin/node runs the Node.js interpreter and executes the script.
This writes the text console.log('Node on IBM i!'); into test.js in your default IFS folder.
If test.js already exists it will be replaced; if not, it will be created.
echo "console.log('Hello from your IBM i Node');" > /home/youruser/webservice-food/test.js
Calls the Node binary directly (full path) to execute test.js.. Node loads the file, runs console.log, and writes Node on IBM i! to stdout.
Expected result is the command prints: Hello from your IBM i Node
No additional output means Node executed the script successfully.
If nothing prints or you get errors, check file permissions, ensure you’re in the same directory as test.js, and that you’re running a PASE/bash shell where that Node binary is usable.
