Node Js

Yep, you heard correct, IBM i supports node.js via PTF.

API documentation

New db2a asynchronous APIs

The db2a designers were very good users creating two different types of APIs. All asynchronous related APIs have counterpart synchronous versions like db.prepare (asynchronous) and db.prepareSync (synchronous).

Synchronous APIs: execSync, prepareSync, executeSync, fetchSync, etc.

If you are uncomfortable with asynchronous callback programming, or you find your application is behaving erratically, please consider using ‘Sync’ versions of db2a APIs.

  • Pro: The db2a ‘Sync’ APIs are familiar synchronous programming model, similar to php, python, RPG, etc.
  • Con: The db2a ‘Sync’ APIs will halt the nodejs event loop to process DB2 requests. While ‘halt’ obviously sounds bad, overall performance may actually run faster with ‘Sync’ db2 workload if relatively simple queries (most queries). However, if you have many requests per second, or, longer running db2 operations, ‘async’ operations may be best.

Asynchronous APIs: exec, prepare, execute, fetch, etc.

You MUST use a DB2 connection pool to effectively use db2a APIs. Basically, rule of effective DB2 is never share a resource (connection, statement), across threads. Yes, technically nodejs interpreter NOT threaded. However, asynchronous APIs are implemented by using child threads. That is, prepare, execute, etc., are placed in a worker thread while doing DB2 operation (I/O), then return to the event loop on completion (callback). Therefore, threads are used, and, the DB2 ‘no share resource across threads’ rules must be followed. There is a sample connection pool with the bears example below.

  • Pro: Web server application may handle more requests using ‘async’ APIs (trade off of simpler ‘Sync’).
  • Con: However, you must use connection pools to avoid random failures of sharing resources across threads (previous db2 rule bullet). You must also be very careful to nest db2 operational callbacks to avoid errors like deleting a statement before occurs, etc.

nodejs toolkit

The nodejs tool kit has multiple transports:

  • http rest request - iConn using ‘host’ keyword to XMLSERVICE configured as a RPG CGI.
    • Pro: This interface allows for best asynchronous behaviour for node toolkit. Http rest is an easy interface for 2 tier node toolkit applications (client/server). You may copy IBM i node toolkit code to client and call IBM i from anywhere. The Bluemix toolkit sample below demonstrates using rest calls to IBM i XMLSERVICE configured Apache using node toolkit (copied from IBM i os400/xstoolkit/lib).
    • Con: The http interface is obviously slower than DB2 below.
  • db2 stored procedure - iConn default without ‘host’ keyword to XMLSERVICE via stored procedure call.
    • Pro: Simple model to code. That is, DB2 usually already working in node application, so toolkit is added simply.
    • Con: Current node toolkit istoredp.js class uses full open/close. This is very slow, and, can stall or fail depending on workload. Similar to db2a discussion above, the toolkit needs a new design of connection pools to work better under heavy loads (TBD — source: https://github.com/IBM/nodejs-itoolkit )
      • Debug (minimum): If you are experiencing SQL errors from node toolkit, problem is most likely db2 or db2a driver. To verify, please consider switching to http rest method to see if the problem simply goes away (often will work). The db2a driver has some years to grow, so please let the IBM owners know of SQL errors (not toolkit).

Some better examples

IBM i examples running on Yips use following conf files

  • httpd.conf — Apache configuration
  • fastcgi.conf — Apache fastcgi configuration (PHP, mama, etc.)
  • mama.conf — FastCGI tool to start stand-alone servers (node, python, etc.)

Follow links for extended conversation about setting up a ‘safer’ Apache, xmlservice with *NONE uid/pwd, mama, etc. A new tool ‘mama’ has been created as fastcgi extension to start/stop your standalone applications. Mama is designed to work with Apache FastCGI as additional configuration files (mama.conf).

  • XMLSERVICEInstall — see xmlservice crtxml3 with *NONE uid/pwd (localhost/127.0.0.1 xmlservice)
  • litmis git mama - mama source code, multiple Apache configurations for different machine environments (useful patterns).
  • Mama - mama pre-compiled version

IBM i db2a bears example for new db2a ‘async’ interfaces (ported to node 6) …

IBM i toolkit flight 400 interfaces node 6 (yes, calling flight 400 RPG programs).

IBM i toolkit silly hat example (ported to node 6) …

IBM i hats.savf

  • hats.zip (latest)
    • programs and db2 files for hats demo (remember to allow web access RWX *PUBLIC)

Original bluemix silly hat example (bluemix obsolete)…

Our friends at Litmis/Krengel made a bitbucket repository for Node.js on IBM i …

CCSID issues

Have CCSID issues? Junk characters? Nothing works?

  • IBM i actions, see CCSID