Working with VSAM Data Sets in Node.js on z/OS

In the previous blog Building Native Node.js Add-ons on z/OS, we have built a simple native add-on for Node.js.

Now we will use a real and useful add-on called vsam.js. This Node.js module enables you to read and modify VSAM datasets on z/OS.

VSAM is a mainframe data set type that is used by many business applications on z/OS. We will use Git on z/OS as well to get the code to z/OS UNIX file-system.

Required Tooling

We need a few additional tools that will make getting the code to the z/OS UNIX easier. We will keep using Zowe CLI to simplify the interaction with z/OS. You can install Zowe CLI by following the instructions on https://zowe.github.io/docs-site/latest/user-guide/cli-installcli.html#installing-zowe-cli-from-an-online-registry including setting up the z/OSMF profile.

Git for z/OS and cURL

  1. Go to https://my.rocketsoftware.com/RocketCommunity#/downloads
  2. Log in or sign up to the Rocket Community
  3. Search for git and download git-2.14.4_b09.181107.tar.gz

We will use the same home directory on z/OS as in the previous blog:

export ROCKET_HOME=${rocket_home}

Let’s copy the files to z/OS using Zowe CLI:

zowe zos-files upload file-to-uss --binary git-2.14.4_b09.181107.tar.gz ${ROCKET_HOME}/download/git-2.14.4_b09.181107.tar.gz

Go back to the z/OS shell session and unpack these packages:

export ROCKET_HOME=${rocket_home}. ${ROCKET_HOME}/rocket_activate.sh${ROCKET_HOME}/bin/gunzip --stdout ${ROCKET_HOME}/download/git-2.14.4_b09.181107.tar.gz | tar xoUXf -${ROCKET_HOME}/bin/gunzip --stdout ${ROCKET_HOME}/download/curl-7.52.1_b006.170926.tar.gz | tar xoUXf -

Now is the time to assign correct access rights:

chmod -R 755 ${ROCKET_HOME}/bin/*
find ${ROCKET_HOME}/lib -type f -exec chmod 644 {} \\;
find ${ROCKET_HOME}/lib -type f -name '*.so' -exec chmod 755 {} \\;

Your environment variables should be already set correctly by rocket_activate.sh.

You need to set up the certificates for Git:

mkdir ${ROCKET_HOME}/etc
curl -s -k https://curl.haxx.se/ca/cacert.pem -o ${ROCKET_HOME}/etc/cacert.pem

And then update the rocket_activate.sh script by adding:

# Git:
export RSUSR=$ROCKET_HOME
export GIT_SHELL=$RSUSR/bin/bash
export GIT_EXEC_PATH=$RSUSR/libexec/git-core
export GIT_TEMPLATE_DIR=$RSUSR/share/git-core/templates
export GIT_MAN_PATH=$RSUSR/man
export GIT_SSL_CAINFO=$RSUSR/etc/cacert.pem

Clone vsam.js repository

After running . ${ROCKET_HOME}/rocket_activate.sh once more you can finally clone the GitHub repository to your z/OS system by:

git clone https://github.com/ibmruntimes/vsam.js.git
cd vsam.js

You can build it by and test:

npm install --nodedir=$NODE_HOME && npm test

You know that the vsam.js works well on your system and you can start using it. If you want to use it in your applications you do not need to clone its code you can just add as a dependency.

It can be useful to have the project on your system. You can add new functionality to the source code and contribute it back using GitHub Pull Requests.

Vsam.js example

We will create new Node.js program from scratch.

mkdir vsam-example
cd vsam-example
npm init

The npm init command initializes a new JavaScript application based on the values that you enter:

This utility will walk you through creating a package.json file.
It only covers the most common items, and tries to guess sensible defaults.
See `npm help json` for definitive documentation on these fields
and exactly what they do.
Use `npm install <pkg> --save` afterwards to install a package and
save it as a dependency in the package.json file.
Press ^C at any time to quit.
name: (vsam-example)
version: (1.0.0)
description: Example of VSAM program
entry point: (index.js)
test command:
git repository:
keywords:
author:
license: (ISC)
About to write to ~/workspace/vsam-example/package.json:
{
"name": "vsam-example",
"version": "1.0.0",
"description": "Example of VSAM program",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "",
"license": "ISC"
}
Is this ok? (yes) yes

To add vsam.js as a dependency you need to issue the following command:

npm install vsam.js --save --nodedir=$NODE_HOME

Let’s create index.js with the following contents:

You can run by issuing node index.js. If you run it for the first time, it will create a new VSAM KSDS dataset and insert one record into it. You should see:

userid.TEST.VSAM.KSDS does not exist
userid.TEST.VSAM.KSDS allocated
Creating record

When you run it next time, it will just print what is there:

Record read { key: '00001', name: 'Petr', gender: 'male' }

What next?

This has been a simple application that wrote and read from a VSAM dataset.

For an example of a REST API service that works with VSAM data sets, have a look at https://github.com/irisbaron/vsam-express-demo.

Petr’s main areas of expertise are mainframes and automation, and using modern development tools and languages such as Java, Python, and Node.js on z/OS.