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 optionreturnError
to behave likeiConn.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()
¶
Create an instance of Connection with
returnError
set to false. This is a compatabilty option to behave likeiConn.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) => {
...
})
Test your application still works as expected using this instance of
Connection
.Update
Connection.run()
callbacks to expect an error as the first parameter.
conn.run((error, xmlOutput) => {
if (error) { throw error; }
});
Remove
returnError
property from theConnection
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
.