IBM SDK for Node.js – z/OS Trial

IBM SDK for Node.js – z/OS Trial

This trial version is based on Version 6 of the SDK for Node.js, but might not be updated in line with Node.js community updates.

Last update: 04 April 2019



These instructions are specific to this trial; for more information about the full IBM SDK for Node.js – z/OS product, see the user guides in IBM Knowledge Center.


The content is available subject to the following disclaimer:

The code and application programming interfaces herein are trial information that may not be made generally available by IBM as or in a product. You are permitted to use the information only for internal use for evaluation purposes and not for use in a production environment. IBM provides the information without obligation of support and “as is” without warranty of any kind.

Hardware and software requirements


  • IBM zEnterprise® 196 (z196) or newer
    • Software:

      • z/OS V2R2 with PTF UI46658 or z/OS V2R3, z/OS UNIX System Services enabled, and Integrated Cryptographic Service Facility (ICSF) configured and started.
      • Perl 5.6.x or later, required for installation of the provided C/C++ runtime and compiler.
      • To compile native add-ons, Python 2.7.13 and Make 4.1 must be installed and available on your PATH.


      If you are upgrading from the previous beta level, uninstall that level first, by following the instructions in the uninstallation section.

      Installing and uninstalling

      The pax.Z file contains an updated C/C++ runtime and compiler, which has the following additional storage requirements:

      • 2 GB free space on HFS.
      • 400 MB free space for the MVS dataset under the high-level qualifier (HLQ) where the compiler will be installed. The default HLQ will be your user ID.

      To install:

      1. Download the pax.Z file from the Download section to a z/OS machine.
      2. Extract the pax.Z file inside an installation directory of your choice. For example:
        pax -rf <path_to_pax.Z_file> -x pax
      3. If required, export the following environment variables before you install the C/C++ compiler:

        The compiler installation tool requires an appropriate MSGCLASS parameter that logs the output of a dependent JCL job to the HELD OUTPUT QUEUE. The default MSGCLASS value is “s”. You can override this value by using the COMPILER_INSTALL_MSGCLASS environment variable:
        Failure to set an appropriate MSGCLASS can result in XMIT errors, as described in Troubleshooting.

        By default, the compiler installation script creates datasets under your user ID’s HLQ. You can specify a custom HLQ for the datasets by setting the COMPILER_INSTALL_HLQ environment variable:
        export COMPILER_INSTALL_HLQ=<custom_HLQ>

      4. Run the following command to install the C/C++ compiler:
        The script unpacks the compiler into the current working directory then loads the compiler datasets under your user ID’s HLQ or the custom HLQ that you specified earlier. The script then runs a “Hello world” application to verify the installation.

        Note: If problems occur during process, you can optionally run the following command before running for extra diagnostic information during the installation:

      5. Add the full path of your installation directory to your PATH environment variable:
        export PATH=<installation_directory>/bin/:$PATH
      6. Run the node and npm commands from the command line.

      To uninstall:

      1. Uninstall the C/C++ compiler by running the following command from the installation directory:
        ./ -uninstall
      2. Delete the installation directory.

      API documentation

      Node.js v6.16.0 API reference documentation


      • Node.js uses z/OS UNIX System Services semaphores. If the Node.js runtime ends unexpectedly, stale semaphores might be left on the system, potentially resulting in a lack of available semaphores for invoking additional Node.js instances. Currently, you must manually clean up stale semaphores, by using the ipcrm command. Too many stale semaphores results in the following assert:
        # Fatal error in ../src/base/platform/, line 85
        # CHECK_EQ(0, result) failed
        #   Expected: 0
        #   Found: -1
      • If the node process hangs without any output check, confirm whether /dev/random is functional, by entering the following command:
        cat /dev/random | od | head
        If /dev/random is not available, ensure that ICSF is started.
      • During the compiler installation, you might see an error message that is similar to the following example:

        An error occurred while receiving temporary dataset ... to dataset ... at ./ line 147.
        cannot receive ... to ... at ./ line 61.

        To resolve this problem, make sure that you have exported the COMPILER_INSTALL_MSGCLASS variable as described in the Installation section.

      Fix list

      For the information about all the APAR fixes made available for the product, see Fix list for IBM SDK for Node.js – z/OS.

      Known issues and limitations

      • For v6.14.1 or earlier, the Node.js runtime requires an address space of at least 700 MB. Use the ulimit -A command to set or display the maximum size of the address space.
      • The Node.js API on subdirectories is not supported on z/OS.
      • You cannot use IBM Monitoring and Diagnostic Tools – Interactive Diagnostic Data Explorer.
      • There is no Node Application Metrics component in this release, so you cannot use IBM Monitoring and Diagnostic Tools – Health Center to monitor your applications.
      • A common way of boosting performance on z/OS is to load common or reusable modules into the dynamic link pack area (DLPA).


      We want to hear your feedback – you can add comments or issues in Github: