Skip to content
/ vsam.js Public
forked from ibmruntimes/vsam.js

Reading and writing vsam files using NodeJS

License

Notifications You must be signed in to change notification settings

gabylb/vsam.js

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

76 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

vsam

This NodeJS module enables you to read and modify VSAM datasets on z/OS

Installation

Before installing, download and install Node.js. Node.js 8.16.2 or higher is required.

Simple to use

Vsam.js is designed to be a bare bones vsam I/O module.

  if (vsam.exist("sample.test.vsam.ksds"))
    dataset = vsam.openSync("sample.test.vsam.ksds",
                            JSON.parse(fs.readFileSync('schema.json')));

  // find using a string as key:
  dataset.find("0321", (record, err) => {
    if (err != null)
      console.log("Not found!");
    else {
      assert(record.key, "0321");
      console.log(`Current details: Name(${record.name}), Amount(${record.amount})`);
      record.name = "KEVIN";
      record.quantity = Buffer.from([0xe5, 0xf6, 0x78, 0x9a]).toString('hex');
      dataset.update(record, (err) => {
        dataset.close();
      });
    }
  });

  // or find using binary data as key (type must be set to "hexadecimal"):
  const keybuf = Buffer.from([0xa1, 0xb2, 0xc3, 0xd4]);
  dataset.find(keybuf, keybuf.length, (record, err) => {
    ...

  // or:
  dataset.find("0xa1b2c3d4", (record, err) => {
    ...

schema.json looks like this:

{
  "key": {
    "type": "string",
    "maxLength": 5
  },
  "name": {
    "type": "string",
    "maxLength": 10
  },
  "quantity": {
    "type": "hexadecimal",
    "maxLength": 4
  }
}

Table of contents


Allocating a vsam dataset for I/O

const vsam = require('vsam');
const fs = require('fs');
var vsamObj = vsam.allocSync("VSAM.DATASET.NAME", JSON.parse(fs.readFileSync('schema.json')));
  • The first argument is the VSAM dataset name to allocate.
  • The second argument is the JSON object derived from the schema file.
  • The value returned is a vsam dataset handle. The rest of this readme describes the operations that can be performed on this object.
  • Usage notes:
    • If the dataset already exists, this function will throw an exception.
    • On any error, this function with throw an exception.

Opening a vsam dataset for I/O

const vsam = require('vsam');
const fs = require('fs');
var vsamObj = vsam.openSync("VSAM.DATASET.NAME", JSON.parse(fs.readFileSync('schema.json')));
  • The first argument is the name of an existing VSAM dataset.
  • The second argument is the JSON object derived from the schema file.
  • The optional third argument, if specified, is the fopen() mode; default is 'ab+,type=record' if none is specified.
  • The value returned is a VSAM dataset handle. The rest of this readme describes the operations that can be performed on this object.
  • Usage notes:
    • If the third argument is specified, it is passed as-is to C/C++ library function fopen().
    • To open a non-empty VSAM dataset in read-only mode, specify 'rb,type=record' as the third argument.
    • On error, this function with throw an exception.

Check if VSAM dataset exists

const vsam = require('vsam');
const fs = require('fs');
if (vsam.exist("VSAM.DATASET.NAME")) {
  /* Open the vsam file. */
}
  • The first argument is the name of an existing VSAM dataset.
  • Boolean value is returned indicating whether dataset exists or not.

Closing a VSAM dataset

vsamObj.close((err) => { /* Handle error. */ });
  • The first argument is a callback function containing an error object if the close operation failed.

Reading a record from a VSAM dataset

vsamObj.read((record, err) => { 
  /* Use the record object. */
});
  • The first argument is a callback function whose arguments are as follows:
    • The first argument is an object that contains the information from the read record.
    • The second argument will contain an error object in case the read operation failed.
  • Usage notes:
    • The read operation retrievs the record under the current cursor and advances the cursor by one record length.

Data Types

The following data types are currently supported:

  • string
    • find and write data stored as a string (character array)
  • hexadecimal
    • find binary data using Buffer or hexadecimal string, write using a hexadecimal string representation of the binary data

See test/test2.json and test/ksds2.js for an example covering both types.

Writing a record to a VSAM dataset

vsamObj.write(record, (err) => { 
  /* Make sure err is null. */
});
  • The first argument is record object that will be written.
  • The second argument is a callback to notify of any error in case the write operation failed.
  • Usage notes:
    • The write operation advances the cursor by one record length after the newly written record.
    • The write operation will overwrite any existing record with the same key.

Finding a record in a VSAM dataset

vsamObj.find(recordKey, (record, err) => { 
  /* Use record information. */
});
vsamObj.findeq(recordKey, (record, err) => { 
  /* Use record information. */
});
vsamObj.findge(recordKey, (record, err) => { 
  /* Use record information. */
});
vsamObj.findlast(recordKey, (record, err) => { 
  /* Use record information. */
});
vsamObj.findfirst(recordKey, (record, err) => { 
  /* Use record information. */
});
  • The first argument is record key (usually a string) (except for findlast and findfirst).
  • The second argument is a callback (this is the first argument for findlast and findfirst)
    • The first argument is a record object retrieved using the key provided.
    • The second argument is an error object in case the operation failed.
  • Usage notes:
    • The find operation will place the cursor at the queried record (if found).
    • The record object in the callback will by null if the query failed to retrieve a record.

Updating a record in a VSAM dataset

vsamObj.update(record, (err) => { 
   ...
});
  • The first argument is record object.
  • The second argument is a callback
    • The first argument is an error object in case the operation failed.
  • Usage notes:
    • The update operation will write over the record currently under the cursor.

Deleting a record from a VSAM dataset

vsamObj.delete((err) => { /* Handle error. */ });
  • The first argument is a callback function containing an error object if the delete operation failed.
  • Usage notes:
    • The record under the current position of the dataset cursor gets deleted.
    • This will usually be placed inside the callback of a find operation. The find operation places the cursor on the desired record and the subsequent delete operation deletes it.

Deallocating a VSAM dataset

vsamObj.dealloc((err) => { /* Handle error. */ });
  • The first argument is a callback function containing an error object if the deallocation operation failed.

About

Reading and writing vsam files using NodeJS

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • C++ 69.9%
  • JavaScript 27.3%
  • Python 2.8%