Migrating from itoolkit v0.x to v1.x

If you are upgrading an existing application its a great idea to have good test coverage before upgrading.

Most applications applications using a version < 1.0.0 should continue to work but it’s still highly recommended to test your application first.

Warning

BREAKING CHANGES

BREAKING CHANGES

Sync Mode Operations

iConn.run() no longer supports sync mode. Sync mode is not reccommended and since it did not work properly it was removed. See (#32) for more details.

iConn.setTimeout() is removed. This function was used to set the timeout for iConn.run sync mode.

iSql Authentication

iSql.connect() and iSql.setOptions() are removed. These functions were used in conjunction for XMLSERVICE user authentication. The transports already handle user authentication.

New Features

SSH and ODBC transports

Users can now use ssh and odbc transports. This will allow users more ways to use itoolkit on their local machine.

Support error first callbacks

  • iConn.run() did not return errors to the run callback. Connection.run() follows Node.js convention of error first callbacks. Connection still has a compatability option returnError to behave like iConn.run() and return the xml output as the first parameter of the run callback. See the Migrating from iConn.run() to Connection.run() section.

Support DS types within addReturn

  • iPgm.addReturn did not support the DS data type, ProgramCall.addReturn added support.

Deprecated Classes and Functions

iConn

The iConn class was replaced with the Connection class and it will be removed in v2.x.

Differences

  • Connection constructor accepts single object parameter.

  • Connection.run() follows Node.js convention of error first error first callbacks.

Migrating from iConn to Connection

Warning

Beware that the Connection and iConn classes differ in how they call the callbacks passed to their run methods. You cannot simply replace iConn with Connection without adjusting your callbacks. See the Migrating from iConn.run() to Connection.run() section.

When connecting using idb-connector, iConn takes 3 arguments: database, username, and password. These can be passed as attributes on the transportOptions attribute of the object passed to Connection and specify the transport is idb. eg.

// const conn = new iConn('*LOCAL', 'myuser', 'mypassword');

const conn = new Connection({
  transport: 'idb',
  transportOptions: { database: '*LOCAL', username: 'myuser', password: 'mypassword' }
});

When connecting using rest, iConn takes 4 arguments: database, username, password, and options. The options object included host, port, and path to generate the url string. Instead specify database, username, password, and url on the transportOptions attribute of the object passed to Connection and specify the transport is rest. eg.

// const restConfig = { host: 'myhost.example.com', port: 80, path: '/cgi-bin/xmlcgi.pgm' }
// const conn = new iConn('*LOCAL', 'myuser', 'mypassword', restConfig);

const conn = new Connection({
  transport: 'rest',
  transportOptions: {
    database: '*LOCAL',
    username: 'myuser',
    password: 'mypassword',
    url: 'http://myhost.example.com/cgi-bin/xmlcgi.pgm',
  }
});

Migrating from iConn.run() to Connection.run()

  1. Create an instance of Connection with returnError set to false. This is a compatabilty option to behave like iConn.run() and return the xml output as the first parameter of the run callback.

// const conn = new iConn("*LOCAL", "myuser", "mypassword");

const conn = new Connection({
  transport: 'idb',
  returnError: false,
  transportOptions: { database: '*LOCAL', username: 'myuser', password: 'mypassword' }
});

conn.add(...)

conn.run((xmlOutput) => {
    ...
})

  1. Test your application still works as expected using this instance of Connection.

  2. Update Connection.run() callbacks to expect an error as the first parameter.

conn.run((error, xmlOutput) => {
    if (error) { throw error; }
});

  1. Remove returnError property from the Connection constructor. The default behavior is to return error first callbacks.

const conn = new Connection({
  transport: 'idb',
  transportOptions: { database: '*LOCAL', username: 'myuser', password: 'mypassword' }
});

iPgm

iPgm was replaced by the ProgramCall and will be removed in v2.x.

Differences

  • Data and data structures and are now defined as objects.

  • ProgramCall.addParam() now accepts a single object parameter.

  • ProgramCall.addReturn() now accepts a single object parameter,

  • ProgramCall.addReturn() now supports DS as return type.

Migrating from iPgm.addParam() to ProgramCall.addParam()

Parameter and data options are passed with the object parameter. Ensure the data type is specified; defaulting to use 1024a is deprecated.

// iPgm.addParam('0', '10i0', { io: 'in', setlen: 'rec1' })

ProgramCall.addParam({ type: '10i0', io: 'in', setlen: 'rec1', value: 0 })

Data structures have type ds and an additional fields property which is an array of data or ds objects.

/*
 const ds = [
   [0, '10i0'],
   [0, '10i0', { setlen: 'rec2' }],
   ['', '36h'],
   ['', '10A'],
   ['', '1A'],
   ['', '1A'],
   [0, '10i0'],
   [0, '10i0'],
 ];
*/

// iPgm.addParam(ds, { io: 'out', dim: '1' });

const ds = {
  type: 'ds',
  dim: '1',
  io: 'out',
  fields: [
    { type: '10i0', value: 0 },
    { type: '10i0', value: 0, setlen: 'rec2' },
    { type: '36h', value: '' },
    { type: '10A', value: '' },
    { type: '1A', value: ''},
    { type: '1A', value: ''},
    { type: '10i0', value: 0 },
    { type: '10i0', value: 0 },
  ]
};

ProgramCall.addParam(ds);

Migrating from iPgm.addReturn() to ProgramCall.addReturn()

Data previously defined as:

addReturn('', '10A', { varying: '4' })

Will now be defined as:

addReturn({type: '10A', value: '', varying: '4' })

iCmd

iCmd is replaced by CommandCall and will be removed in v2.x.

A command previously generated with:

const command = iCmd('RTVJOBA USRLIBL(?) SYSLIBL(?)')

Will now be generated with:

const command = new CommandCall({type: 'cl', command: 'RTVJOBA USRLIBL(?) SYSLIBL(?)' })

iQsh

iQsh is replaced by CommandCall and will be removed in v2.x.

A command previously generated with:

const command = iQsh('system wrksyssts')

Will now be generated with:

const command = new CommandCall({type: 'qsh', command: 'system wrksyssts' })

iSh

iSh is replaced by CommandCall and will be removed in v2.x.

A command previously generated with:

const command = iSh('ls /home')

Will now be generated with:

const command = new CommandCall({type: 'sh', command: 'ls /home' })

iSql

iSql class is deprecated and will be removed in v2.x. The odbc, idb-connector, and idb-pconnector npm packages are much better SQL interfaces for IBM i and should be used instead.

iSql.connect and iSql.setOptions are no longer available.

xmlToJson

xmlToJson is deprecated and will be removed in v2.x. Use an external XML parser such as fast-xml-parser.

iDataQueue

The iDataQueue class is deprecated and will be removed in v2.x.

iNetwork

The iNetwork class is deprecated and will be removed in v2.x.

iObj

The iObj class is deprecated and will be removed in v2.x.

iProd

The iProd class is deprecated and will be removed in v2.x.

iUserSpace

The iUserSpace class is deprecated and will be removed in v2.x.

iWork

The iWork class is deprecated and will be removed in v2.x.