page-brochureware.php

IBM SDK for Node.js – z/OS beta


IBM SDK for Node.js – z/OS Beta 4

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

The full version of IBM® SDK for Node.js is available for purchase from IBM Marketplace.

Last update: 8 September 2017


Download



Documentation


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

Disclaimer

The content is available subject to the following disclaimer:

The code and application programming interfaces herein are beta 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

Hardware:
IBM zEnterprise® 196 (z196) or newer

Software:

  • z/OS V2R2 or later, with PTF UI46658, 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.6 and Make 4.1 must be installed and available on your PATH.

Upgrading

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:

    COMPILER_INSTALL_MSGCLASS
    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:
    export COMPILER_INSTALL_MSGCLASS=<custom MSGCLASS>
    Failure to set an appropriate MSGCLASS can result in XMIT errors, as described in Troubleshooting.

    COMPILER_INSTALL_HLQ
    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:
    ./unpack.pl
    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.
  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:
    ./unpack.pl -uninstall
  2. Delete the installation directory.

Running

If you did not apply PTF UI46658, Node.js applications require that you add the following dataset to the STEPLIB environment variable:
<UHLQ>.CEEZ230.D170510.RT22.SCEERUN2
Where UHLQ is the high-level qualifier of the user ID that you used to install the compiler.

Otherwise, run your Node.js applications in the same way as for other versions of the IBM SDK for Node.js. For more information, see IBM Knowledge Center.

API documentation

Node.js v6.11.2 API reference documentation

Troubleshooting

  • 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/semaphore.cc, 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 ./unpack.pl line 147.
    cannot receive ... to ... at ./unpack.pl line 61.


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

Known issues and limitations

  • The current release 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 fs.watch 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). However, do not load the C/C++ compiler provided with the SDK into DLPA if the z/OS V2R2 XL C/C++ compiler is already loaded in DLPA. Loading both compilers into DLPA will cause unexpected compiler behavior. This restriction is a limitation of the current beta version of the C/C++ compiler that is provided with the SDK.

Feedback

We want to hear your feedback – you can add comments or issues in Github: https://github.com/ibmruntimes/node/issues