From ab6f592feba9b0d0109aac31b4e11e62ec3add4c Mon Sep 17 00:00:00 2001 From: Abdirahim Musse <33973272+abmusse@users.noreply.github.com> Date: Mon, 23 Mar 2020 15:12:36 -0500 Subject: [PATCH 01/14] docs: Add migration guide --- docs/migratation.md | 177 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 docs/migratation.md diff --git a/docs/migratation.md b/docs/migratation.md new file mode 100644 index 00000000..0ed88ad3 --- /dev/null +++ b/docs/migratation.md @@ -0,0 +1,177 @@ +# Migrating from itoolkit 0.x.x to 1.0.0 + +### Deprecated Classes and Functions + +#### iConn +The `iConn` class is deprecated and will be removed at a later time. + +You should migrate to use the `Connection` class instead. + +The `Connection` class supports multiple trnasports. + +The transport and transport options are specified during object construction. + +`Connection.run()` returns error first callback to indicate a transport error. + +`Connection.run()` does not support sync mode and always runs asynchronously. + + +For example creating a `Connection` using ssh transport: + +```js +const conn = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' } +}); + +conn.add(new CommandCall({ command: 'RTVJOBA USRLIBL(?) SYSLIBL(?)', type: 'cl' })); + +conn.run((error, xmlOutput) => { + if (error) { + throw error; + } +}); +``` +#### iPgm +The `iPgm` class is deprecated and will be removed at a later time. + +You should migrate to use the `ProgramCall` class instead. + +`ProgramCall.addParam()` now accepts a single object parameter. + +Data and data structures and are now defined as objects. + +Data previously defined as: + +`addParam('0', '10i0', { setlen: 'rec1' })` + +Will now be defined as: + +`addParam({ type: '10i0', value: 0, setlen: 'rec1' })` + +Notice that the data options are passed with the object parameter. + +A data structure previously defined as: + +```js +const ds = [ + [0, '10i0'], + [0, '10i0', { setlen: 'rec2' }], + ['', '36h'], + ['', '10A'], + ['', '1A'], + ['', '1A'], + [0, '10i0'], + [0, '10i0'], +]; + +progam.addParam(ds, { dim: '1' }); +``` + +Will now be defined as: + +```js +const ds = { + type: 'ds', + dim: '1', + 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 }, + ] +}; + +progam.addParam(ds); +``` + +Data structures have type `ds` and `fields` property which is an array of data objects. + +`ProgramCall.addReturn()` now accepts a single object parameter. + +Data previously defined as: + +`addReturn('', '10A', { varying: '4' })` + +Will now be defined as: + +`addReturn({type: '10A', value: '', varying: '4' })` + +`ProgramCall.addReturn()` now supports DS as return type. + +#### iCmd +The `iCmd` class is deprecated and will be removed at a later time. + +You should migrate to use the `CommandCall` class instead using type `cl`. + +A command previously generated with: + +`iCmd('RTVJOBA USRLIBL(?) SYSLIBL(?)')` + +Will now be generated with: + +`const command = new CommandCall({type: 'cl', command: 'RTVJOBA USRLIBL(?) SYSLIBL(?)' })` + +#### iQsh +The `iQsh` class is deprecated and will be removed at a later time. + +You should migrate to use the `CommandCall` class instead using type `qsh`. + +A command previously generated with: + +`iQsh('system wrksyssts')` + +Will now be generated with: + +`const command = new CommandCall({type: 'qsh', command: 'system wrksyssts' })` + +#### iSh +The `iSh` class is deprecated and will be removed at a later time. + +You should migrate to use the `CommandCall` class instead using type `sh`. + +A command previously generated with: + +`iSh('ls /home')` + +Will now be generated with: + +`const command = new CommandCall({type: 'sh', command: 'ls /home' })` + +#### iSql + +The `iSql` class is deprecated and will be removed at a later time. + +Instead of using `iSql` you should migrate to use `odbc`, `idb-connector`, or `idb-pconnector` npm package. + +`iSql.connect` and `iSql.setOptions` are now disabled. + +#### xmlToJson + +The `xmlToJson` function is deprecated and will be removed at a later time. + +You should migrate to use `xml2js` npm package. + +#### iDataQueue +The `iDataQueue` class is deprecated and will be removed at a later time. + +#### iNetwork +The `iNetwork` class is deprecated and will be removed at a later time. + +#### iObj +The `iObj` class is deprecated and will be removed at a later time. + +#### iProd +The `iProd` class is deprecated and will be removed at a later time. + +#### iUserSpace + +The `iUserSpace` class is deprecated and will be removed at a later time. + +#### iWork + +The `iWork` class is deprecated and will be removed at a later time. From 2470e10a15bf1f148995d452b3b9871ea89e2d82 Mon Sep 17 00:00:00 2001 From: Abdirahim Musse <33973272+abmusse@users.noreply.github.com> Date: Mon, 30 Mar 2020 14:58:54 -0500 Subject: [PATCH 02/14] fixup! docs: Add migration guide --- docs/migratation.md | 152 ++++++++++++++++++++++++++++++-------------- 1 file changed, 103 insertions(+), 49 deletions(-) diff --git a/docs/migratation.md b/docs/migratation.md index 0ed88ad3..1d4adc6b 100644 --- a/docs/migratation.md +++ b/docs/migratation.md @@ -1,20 +1,37 @@ -# Migrating from itoolkit 0.x.x to 1.0.0 +# Migrating from itoolkit v0 to v1 -### Deprecated Classes and Functions +If you upgrading an existing application its a great idea to have good test coverage before upgrading. -#### iConn -The `iConn` class is deprecated and will be removed at a later time. +Most applications applications using a version < 1.0.0 should continue to work but it is still highly recommended to test your application first. -You should migrate to use the `Connection` class instead. +## Major Features -The `Connection` class supports multiple trnasports. +### Added ssh and odbc transports -The transport and transport options are specified during object construction. +In addition to the existing `idb` and `rest` transports users can now use `ssh` and `odbc` transports. -`Connection.run()` returns error first callback to indicate a transport error. +These transports will allow users more ways to use itoolkit on their local machine. -`Connection.run()` does not support sync mode and always runs asynchronously. +### Support error first callbacks + +Using `Connection.run()` users now have access to an error first callback to check if a transport error occured. + +### Support DS types within return node + +Previously `iPgm.addReturn` did not support DS as return types. + +This feature was added to `ProgramCall.addReturn`. + +## Deprecated Classes and Functions + +### iConn +The `iConn` class is deprecated and will be removed in the next major version. + +Use the `Connection` class instead. +The `Connection` class supports multiple transports. + +The transport and transport options are specified during object construction. For example creating a `Connection` using ssh transport: @@ -23,19 +40,57 @@ const conn = new Connection({ transport: 'ssh', transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' } }); +``` -conn.add(new CommandCall({ command: 'RTVJOBA USRLIBL(?) SYSLIBL(?)', type: 'cl' })); +Migrating from `iConn` to `Connection` constructor -conn.run((error, xmlOutput) => { - if (error) { - throw error; +`iConn` with idb transport: + +```js +const conn = new iConn("*LOCAL", "myuser", "mypassword"); +``` + +`Connection` with `idb` transport: + +```js +const conn = new Connection({ + transport: 'idb', + transportOptions: { database: '*LOCAL', username: 'myuser', password: 'mypassword' } +}); + +``` + +`iConn` with `rest` transport: + +```js +const restConfig = { host: 'myhost', port: 80, path: '/' } +const conn = new iConn('*LOCAL', 'myuser', 'mypassword', restConfig); +``` + +`Connection` with `rest` transport: + +```js +const conn = new Connection({ + transport: 'idb', + transportOptions: { + database: '*LOCAL', + username: 'myuser', + password: 'mypassword', + host: 'myhost', + port: 80, + path: '/', } }); ``` -#### iPgm -The `iPgm` class is deprecated and will be removed at a later time. -You should migrate to use the `ProgramCall` class instead. +`Connection.run()` returns error first callback to indicate a transport error. + +`Connection.run()` does not support sync mode and always runs asynchronously. + +### iPgm +The `iPgm` class is deprecated and will be removed in the next major version. + +Use the `ProgramCall` class instead. `ProgramCall.addParam()` now accepts a single object parameter. @@ -89,9 +144,9 @@ const ds = { progam.addParam(ds); ``` -Data structures have type `ds` and `fields` property which is an array of data objects. +Data structures have type `ds` and an additional `fields` property which is an array of data or ds objects. -`ProgramCall.addReturn()` now accepts a single object parameter. +`ProgramCall.addReturn()` now accepts a single object parameter, with the same format as `ProgramCall.addParam()`. Data previously defined as: @@ -104,74 +159,73 @@ Will now be defined as: `ProgramCall.addReturn()` now supports DS as return type. #### iCmd -The `iCmd` class is deprecated and will be removed at a later time. +The `iCmd` class is deprecated and will be removed in the next major version. -You should migrate to use the `CommandCall` class instead using type `cl`. +Use the `CommandCall` class instead with type set to `cl` instead. A command previously generated with: -`iCmd('RTVJOBA USRLIBL(?) SYSLIBL(?)')` +`const command = iCmd('RTVJOBA USRLIBL(?) SYSLIBL(?)')` Will now be generated with: `const command = new CommandCall({type: 'cl', command: 'RTVJOBA USRLIBL(?) SYSLIBL(?)' })` -#### iQsh -The `iQsh` class is deprecated and will be removed at a later time. +### iQsh +The `iQsh` class is deprecated and will be removed in the next major version. -You should migrate to use the `CommandCall` class instead using type `qsh`. +Use the `CommandCall` class instead with type set to `qsh` instead. A command previously generated with: -`iQsh('system wrksyssts')` +`const command = iQsh('system wrksyssts')` Will now be generated with: `const command = new CommandCall({type: 'qsh', command: 'system wrksyssts' })` -#### iSh -The `iSh` class is deprecated and will be removed at a later time. +### iSh +The `iSh` class is deprecated and will be removed in the next major version. -You should migrate to use the `CommandCall` class instead using type `sh`. +Use the `CommandCall` class instead with type set to `sh` instead. A command previously generated with: -`iSh('ls /home')` +`const command = iSh('ls /home')` Will now be generated with: `const command = new CommandCall({type: 'sh', command: 'ls /home' })` -#### iSql - -The `iSql` class is deprecated and will be removed at a later time. +### iSql -Instead of using `iSql` you should migrate to use `odbc`, `idb-connector`, or `idb-pconnector` npm package. +The `iSql` class is deprecated and will be removed in the next major version. -`iSql.connect` and `iSql.setOptions` are now disabled. +The `odbc`, `idb-connector`, and `idb-pconnector` npm packages are much better SQL interfaces for IBM i and should be used instead. -#### xmlToJson +`iSql.connect` and `iSql.setOptions` are no longer available. -The `xmlToJson` function is deprecated and will be removed at a later time. +### xmlToJson -You should migrate to use `xml2js` npm package. +The `xmlToJson` function is deprecated and will be removed in the next major version. -#### iDataQueue -The `iDataQueue` class is deprecated and will be removed at a later time. +Use `xml2js` npm package. -#### iNetwork -The `iNetwork` class is deprecated and will be removed at a later time. +### iDataQueue +The `iDataQueue` class is deprecated and will be removed in the next major version. -#### iObj -The `iObj` class is deprecated and will be removed at a later time. +### iNetwork +The `iNetwork` class is deprecated and will be removed in the next major version. -#### iProd -The `iProd` class is deprecated and will be removed at a later time. +### iObj +The `iObj` class is deprecated and will be removed in the next major version. -#### iUserSpace +### iProd +The `iProd` class is deprecated and will be removed in the next major version. -The `iUserSpace` class is deprecated and will be removed at a later time. +### iUserSpace +The `iUserSpace` class is deprecated and will be removed in the next major version. -#### iWork +### iWork -The `iWork` class is deprecated and will be removed at a later time. +The `iWork` class is deprecated and will be removed in the next major version. From 743d77ed38e8ea17a8672e66fe1347c642ad0335 Mon Sep 17 00:00:00 2001 From: Abdirahim Musse <33973272+abmusse@users.noreply.github.com> Date: Mon, 30 Mar 2020 15:01:32 -0500 Subject: [PATCH 03/14] fixup! fixup! docs: Add migration guide --- docs/migratation.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/migratation.md b/docs/migratation.md index 1d4adc6b..0103ae40 100644 --- a/docs/migratation.md +++ b/docs/migratation.md @@ -198,7 +198,6 @@ Will now be generated with: `const command = new CommandCall({type: 'sh', command: 'ls /home' })` ### iSql - The `iSql` class is deprecated and will be removed in the next major version. The `odbc`, `idb-connector`, and `idb-pconnector` npm packages are much better SQL interfaces for IBM i and should be used instead. @@ -206,7 +205,6 @@ The `odbc`, `idb-connector`, and `idb-pconnector` npm packages are much better S `iSql.connect` and `iSql.setOptions` are no longer available. ### xmlToJson - The `xmlToJson` function is deprecated and will be removed in the next major version. Use `xml2js` npm package. @@ -227,5 +225,4 @@ The `iProd` class is deprecated and will be removed in the next major version. The `iUserSpace` class is deprecated and will be removed in the next major version. ### iWork - The `iWork` class is deprecated and will be removed in the next major version. From e086bf84eab8b3a83c6c88fa3bc5b1652f728893 Mon Sep 17 00:00:00 2001 From: Abdirahim Musse <33973272+abmusse@users.noreply.github.com> Date: Mon, 30 Mar 2020 15:31:49 -0500 Subject: [PATCH 04/14] fixup! fixup! fixup! docs: Add migration guide --- docs/migratation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migratation.md b/docs/migratation.md index 0103ae40..28a45a13 100644 --- a/docs/migratation.md +++ b/docs/migratation.md @@ -1,6 +1,6 @@ # Migrating from itoolkit v0 to v1 -If you upgrading an existing application its a great idea to have good test coverage before upgrading. +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 is still highly recommended to test your application first. From c09c14f051cdd946509cdd913a56665d294d4188 Mon Sep 17 00:00:00 2001 From: Abdirahim Musse <33973272+abmusse@users.noreply.github.com> Date: Wed, 1 Apr 2020 19:41:22 -0500 Subject: [PATCH 05/14] fixup! fixup! fixup! fixup! docs: Add migration guide --- docs/migratation.md | 202 +++++++++++++++++++++++--------------------- 1 file changed, 105 insertions(+), 97 deletions(-) diff --git a/docs/migratation.md b/docs/migratation.md index 28a45a13..67b45da9 100644 --- a/docs/migratation.md +++ b/docs/migratation.md @@ -1,134 +1,155 @@ -# Migrating from itoolkit v0 to v1 +# 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 is still highly recommended to test your application first. +Most applications applications using a version < 1.0.0 should continue to work but it's still highly recommended to test your application first. -## Major Features +## :rotating_light: BREAKING CHANGES :rotating_light: -### Added ssh and odbc transports +### `iConn.run()` no longer supports sync mode +Sync mode did not work properly to begin with see ([#32](https://github.com/IBM/nodejs-itoolkit/issues/32)). -In addition to the existing `idb` and `rest` transports users can now use `ssh` and `odbc` transports. +### `iConn.setTimeout()` is removed +This function was used to set timeout for `iConn.run` sync mode. -These transports will allow users more ways to use itoolkit on their local machine. +### `iSql.connect()` and `iSql.setOptions()` are removed -### Support error first callbacks +These functions were used in conjunction for XMLSERVICE user authentication. The transports already handle user authentication. + +## New Features -Using `Connection.run()` users now have access to an error first callback to check if a transport error occured. +### 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 DS types within return node +### Support error first callbacks +`iConn.run()` did not return errors to the run callback. `Connection.run()` follows Node.js convention of [error first callbacks](https://nodejs.org/api/errors.html#errors_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. -Previously `iPgm.addReturn` did not support DS as return types. +### Support DS types within addReturn -This feature was added to `ProgramCall.addReturn`. +- `iPgm.addReturn` did not support the DS data type, `ProgramCall.addReturn` added support. ## Deprecated Classes and Functions - ### iConn -The `iConn` class is deprecated and will be removed in the next major version. +The `iConn` class was replaced with the `Connection` class and it will be removed in `v2.x`. -Use the `Connection` class instead. +### Differences -The `Connection` class supports multiple transports. +- `Connection` constructor accepts single object parameter. +- `Connection.run()` follows Node.js convention of error first [error first callbacks](https://nodejs.org/api/errors.html#errors_error_first_callbacks). -The transport and transport options are specified during object construction. - -For example creating a `Connection` using ssh transport: +#### Migrating from `iConn` to `Connection` Constructor ```js +// using idb transport + +// const conn = new iConn("*LOCAL", "myuser", "mypassword"); + const conn = new Connection({ - transport: 'ssh', - transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' } + transport: 'idb', + transportOptions: { database: '*LOCAL', username: 'myuser', password: 'mypassword' } }); -``` -Migrating from `iConn` to `Connection` constructor +// using rest transport -`iConn` with idb transport: +// const restConfig = { host: 'myhost', port: 80, path: '/' } +// const conn = new iConn('*LOCAL', 'myuser', 'mypassword', restConfig); -```js -const conn = new iConn("*LOCAL", "myuser", "mypassword"); +const conn = new Connection({ + transport: 'rest', + transportOptions: { + database: '*LOCAL', + username: 'myuser', + password: 'mypassword', + host: 'myhost', + port: 80, + path: '/', + } +}); ``` -`Connection` with `idb` transport: +#### 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. ```js +// 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) => { + ... +}) ``` -`iConn` with `rest` transport: +2. Test your application still works as expected using this instance of `Connection`. + +3. Update `Connection.run()` callbacks to expect an error as the first parameter. ```js -const restConfig = { host: 'myhost', port: 80, path: '/' } -const conn = new iConn('*LOCAL', 'myuser', 'mypassword', restConfig); +conn.run((error, xmlOutput) => { + if (error) { throw error; } +}); ``` -`Connection` with `rest` transport: +4. Remove `returnError` property from the `Connection` constructor. The default behavior is to return error first callbacks. ```js const conn = new Connection({ transport: 'idb', - transportOptions: { - database: '*LOCAL', - username: 'myuser', - password: 'mypassword', - host: 'myhost', - port: 80, - path: '/', - } + transportOptions: { database: '*LOCAL', username: 'myuser', password: 'mypassword' } }); -``` -`Connection.run()` returns error first callback to indicate a transport error. - -`Connection.run()` does not support sync mode and always runs asynchronously. +``` ### iPgm -The `iPgm` class is deprecated and will be removed in the next major version. +`iPgm` was replaced by the `ProgramCall` and will be removed in `v2.x`. -Use the `ProgramCall` class instead. +### Differences -`ProgramCall.addParam()` now accepts a single object parameter. +- 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. -Data and data structures and are now defined as objects. - -Data previously defined as: - -`addParam('0', '10i0', { setlen: 'rec1' })` - -Will now be defined as: +#### Migrating from `iPgm.addParam()` to `ProgramCall.addParam()` -`addParam({ type: '10i0', value: 0, setlen: 'rec1' })` +Parameter and data options are passed with the object parameter. Ensure you specify the data type odefaulting to use `1024a` is deprecated. -Notice that the data options are passed with the object parameter. +```js +// iPgm.addParam('0', '10i0', { io: 'in', setlen: 'rec1' }) -A data structure previously defined as: +ProgramCall.addParam({ type: '10i0', io: 'in', setlen: 'rec1', value: 0 }) -```js -const ds = [ - [0, '10i0'], - [0, '10i0', { setlen: 'rec2' }], - ['', '36h'], - ['', '10A'], - ['', '1A'], - ['', '1A'], - [0, '10i0'], - [0, '10i0'], -]; - -progam.addParam(ds, { dim: '1' }); ``` -Will now be defined as: +Data structures have type `ds` and an additional `fields` property which is an array of data or ds objects. ```js +/* + 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' }, @@ -141,13 +162,10 @@ const ds = { ] }; -progam.addParam(ds); +ProgramCall.addParam(ds); ``` -Data structures have type `ds` and an additional `fields` property which is an array of data or ds objects. - -`ProgramCall.addReturn()` now accepts a single object parameter, with the same format as `ProgramCall.addParam()`. - +#### Migrating from `iPgm.addReturn()` to `ProgramCall.addReturn()` Data previously defined as: `addReturn('', '10A', { varying: '4' })` @@ -156,12 +174,8 @@ Will now be defined as: `addReturn({type: '10A', value: '', varying: '4' })` -`ProgramCall.addReturn()` now supports DS as return type. - #### iCmd -The `iCmd` class is deprecated and will be removed in the next major version. - -Use the `CommandCall` class instead with type set to `cl` instead. +`iCmd` is replaced by `CommandCall` and will be removed in `v2.x`. A command previously generated with: @@ -172,9 +186,7 @@ Will now be generated with: `const command = new CommandCall({type: 'cl', command: 'RTVJOBA USRLIBL(?) SYSLIBL(?)' })` ### iQsh -The `iQsh` class is deprecated and will be removed in the next major version. - -Use the `CommandCall` class instead with type set to `qsh` instead. +`iQsh` is replaced by `CommandCall` and will be removed in `v2.x`. A command previously generated with: @@ -185,9 +197,7 @@ Will now be generated with: `const command = new CommandCall({type: 'qsh', command: 'system wrksyssts' })` ### iSh -The `iSh` class is deprecated and will be removed in the next major version. - -Use the `CommandCall` class instead with type set to `sh` instead. +`iSh` is replaced by `CommandCall` and will be removed in `v2.x`. A command previously generated with: @@ -198,31 +208,29 @@ Will now be generated with: `const command = new CommandCall({type: 'sh', command: 'ls /home' })` ### iSql -The `iSql` class is deprecated and will be removed in the next major version. - -The `odbc`, `idb-connector`, and `idb-pconnector` npm packages are much better SQL interfaces for IBM i and should be used instead. +`iSql` class is deprecated and will be removed in `v2.x`. +The [odbc](https://www.npmjs.com/package/odbc), [idb-connector](https://www.npmjs.com/package/idb-connector), and [idb-pconnector](https://www.npmjs.com/package/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 -The `xmlToJson` function is deprecated and will be removed in the next major version. - -Use `xml2js` npm package. +`xmlToJson` is deprecated and will be removed in `v2.x`. +Use [xml2js](https://www.npmjs.com/package/xml2js) instead. ### iDataQueue -The `iDataQueue` class is deprecated and will be removed in the next major version. +The `iDataQueue` class is deprecated and will be removed in `v2.x`. ### iNetwork -The `iNetwork` class is deprecated and will be removed in the next major version. +The `iNetwork` class is deprecated and will be removed in `v2.x`. ### iObj -The `iObj` class is deprecated and will be removed in the next major version. +The `iObj` class is deprecated and will be removed in `v2.x`. ### iProd -The `iProd` class is deprecated and will be removed in the next major version. +The `iProd` class is deprecated and will be removed in `v2.x`. ### iUserSpace -The `iUserSpace` class is deprecated and will be removed in the next major version. +The `iUserSpace` class is deprecated and will be removed in `v2.x`. ### iWork -The `iWork` class is deprecated and will be removed in the next major version. +The `iWork` class is deprecated and will be removed in `v2.x`. From c6c96c1747e6a7f2148c5e71195273835707199e Mon Sep 17 00:00:00 2001 From: Abdirahim Musse <33973272+abmusse@users.noreply.github.com> Date: Fri, 3 Apr 2020 13:05:30 -0500 Subject: [PATCH 06/14] refactor: Rename to migratation-guide-v1.0.md --- docs/{migratation.md => migratation-guide-v1.0.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{migratation.md => migratation-guide-v1.0.md} (100%) diff --git a/docs/migratation.md b/docs/migratation-guide-v1.0.md similarity index 100% rename from docs/migratation.md rename to docs/migratation-guide-v1.0.md From 9b8ce1f73942387a65e168f2497e843a807367c6 Mon Sep 17 00:00:00 2001 From: Abdirahim Musse <33973272+abmusse@users.noreply.github.com> Date: Wed, 22 Apr 2020 14:35:49 -0500 Subject: [PATCH 07/14] docs: Add migration guide to sphinx docs --- docs/conf.py | 4 ++++ docs/index.rst | 3 +++ docs/migratation-guide-v1.0.md | 2 +- 3 files changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 37c66359..ce47a7b1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -37,6 +37,7 @@ # ones. extensions = [ 'sphinx_js', + 'recommonmark', ] # Add any paths that contain templates here, relative to this directory. @@ -50,6 +51,9 @@ # This pattern also affects html_static_path and html_extra_path. exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +# The suffix of source filenames. +source_suffix = ['.rst', '.md'] + # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for diff --git a/docs/index.rst b/docs/index.rst index 0bce6df9..c687f94f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -52,12 +52,15 @@ Installation $ npm install itoolkit +**NOTE:** If you are upgrading from ``0.1.x`` be sure to read the :doc:`migration guide `. + .. toctree:: :maxdepth: 1 :caption: Contents: features deprecated + migratation-guide-v1.0 Indices and tables diff --git a/docs/migratation-guide-v1.0.md b/docs/migratation-guide-v1.0.md index 67b45da9..d50eec8d 100644 --- a/docs/migratation-guide-v1.0.md +++ b/docs/migratation-guide-v1.0.md @@ -4,7 +4,7 @@ If you are upgrading an existing application its a great idea to have good test Most applications applications using a version < 1.0.0 should continue to work but it's still highly recommended to test your application first. -## :rotating_light: BREAKING CHANGES :rotating_light: +## 🚨 BREAKING CHANGES 🚨 ### `iConn.run()` no longer supports sync mode Sync mode did not work properly to begin with see ([#32](https://github.com/IBM/nodejs-itoolkit/issues/32)). From 3f7f5d83bfca7ec48870d6974d7ec297dc5da6ee Mon Sep 17 00:00:00 2001 From: Abdirahim Musse <33973272+abmusse@users.noreply.github.com> Date: Wed, 22 Apr 2020 19:32:59 -0500 Subject: [PATCH 08/14] fixup! docs: Add migration guide to sphinx docs --- docs/migratation-guide-v1.0.md | 236 ------------------------ docs/migratation-guide-v1.0.rst | 311 ++++++++++++++++++++++++++++++++ 2 files changed, 311 insertions(+), 236 deletions(-) delete mode 100644 docs/migratation-guide-v1.0.md create mode 100644 docs/migratation-guide-v1.0.rst diff --git a/docs/migratation-guide-v1.0.md b/docs/migratation-guide-v1.0.md deleted file mode 100644 index d50eec8d..00000000 --- a/docs/migratation-guide-v1.0.md +++ /dev/null @@ -1,236 +0,0 @@ -# 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. - -## 🚨 BREAKING CHANGES 🚨 - -### `iConn.run()` no longer supports sync mode -Sync mode did not work properly to begin with see ([#32](https://github.com/IBM/nodejs-itoolkit/issues/32)). - -### `iConn.setTimeout()` is removed -This function was used to set timeout for `iConn.run` sync mode. - -### `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](https://nodejs.org/api/errors.html#errors_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. - -### 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](https://nodejs.org/api/errors.html#errors_error_first_callbacks). - -#### Migrating from `iConn` to `Connection` Constructor - -```js -// using idb transport - -// const conn = new iConn("*LOCAL", "myuser", "mypassword"); - -const conn = new Connection({ - transport: 'idb', - transportOptions: { database: '*LOCAL', username: 'myuser', password: 'mypassword' } -}); - -// using rest transport - -// const restConfig = { host: 'myhost', port: 80, path: '/' } -// const conn = new iConn('*LOCAL', 'myuser', 'mypassword', restConfig); - -const conn = new Connection({ - transport: 'rest', - transportOptions: { - database: '*LOCAL', - username: 'myuser', - password: 'mypassword', - host: 'myhost', - port: 80, - path: '/', - } -}); -``` - -#### 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. - -```js -// 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) => { - ... -}) -``` - -2. Test your application still works as expected using this instance of `Connection`. - -3. Update `Connection.run()` callbacks to expect an error as the first parameter. - -```js -conn.run((error, xmlOutput) => { - if (error) { throw error; } -}); -``` - -4. Remove `returnError` property from the `Connection` constructor. The default behavior is to return error first callbacks. - -```js -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 you specify the data type odefaulting to use `1024a` is deprecated. - -```js -// 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. - -```js -/* - 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](https://www.npmjs.com/package/odbc), [idb-connector](https://www.npmjs.com/package/idb-connector), and [idb-pconnector](https://www.npmjs.com/package/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 [xml2js](https://www.npmjs.com/package/xml2js) instead. - -### 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`. diff --git a/docs/migratation-guide-v1.0.rst b/docs/migratation-guide-v1.0.rst new file mode 100644 index 00000000..675e9973 --- /dev/null +++ b/docs/migratation-guide-v1.0.rst @@ -0,0 +1,311 @@ +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 +================ + +``iConn.run()`` no longer supports sync mode +-------------------------------------------- + +Sync mode did not work properly to begin with see +(`#32 `__). + +``iConn.setTimeout()`` is removed +---------------------------------- + +This function was used to set timeout for ``iConn.run`` sync mode. + +``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. + + +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`` Constructor +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code:: js + + // using idb transport + + // const conn = new iConn("*LOCAL", "myuser", "mypassword"); + + const conn = new Connection({ + transport: 'idb', + transportOptions: { database: '*LOCAL', username: 'myuser', password: 'mypassword' } + }); + + // using rest transport + + // const restConfig = { host: 'myhost', port: 80, path: '/' } + // const conn = new iConn('*LOCAL', 'myuser', 'mypassword', restConfig); + + const conn = new Connection({ + transport: 'rest', + transportOptions: { + database: '*LOCAL', + username: 'myuser', + password: 'mypassword', + url: 'http://myhost:80/', + } + }); + +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. + +.. code:: js + + // 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) => { + ... + }) + +2. Test your application still works as expected using this instance of + ``Connection``. + +3. Update ``Connection.run()`` callbacks to expect an error as the first + parameter. + +.. code:: js + + conn.run((error, xmlOutput) => { + if (error) { throw error; } + }); + +4. Remove ``returnError`` property from the ``Connection`` constructor. + The default behavior is to return error first callbacks. + +.. code:: js + + 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 +you specify the data type odefaulting to use ``1024a`` is deprecated. + +.. code:: js + + // 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. + +.. code:: js + + /* + 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 +`xml2js `__ instead. + +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``. From 599869d6e16857ebbb1b3dd819a3792fa29e27e6 Mon Sep 17 00:00:00 2001 From: Abdirahim Musse <33973272+abmusse@users.noreply.github.com> Date: Fri, 24 Apr 2020 11:13:49 -0500 Subject: [PATCH 09/14] fixup! fixup! docs: Add migration guide to sphinx docs --- docs/conf.py | 3 --- docs/migratation-guide-v1.0.rst | 21 ++++++++++++++------- 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index ce47a7b1..125bb59a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -37,7 +37,6 @@ # ones. extensions = [ 'sphinx_js', - 'recommonmark', ] # Add any paths that contain templates here, relative to this directory. @@ -51,8 +50,6 @@ # This pattern also affects html_static_path and html_extra_path. exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] -# The suffix of source filenames. -source_suffix = ['.rst', '.md'] # -- Options for HTML output ------------------------------------------------- diff --git a/docs/migratation-guide-v1.0.rst b/docs/migratation-guide-v1.0.rst index 675e9973..177790ac 100644 --- a/docs/migratation-guide-v1.0.rst +++ b/docs/migratation-guide-v1.0.rst @@ -8,12 +8,14 @@ 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 ================ +.. 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 :ref:`iconn-to-connection-run` section. + ``iConn.run()`` no longer supports sync mode -------------------------------------------- @@ -48,7 +50,7 @@ Support error first callbacks 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. + parameter of the run callback. See the :ref:`iconn-to-connection-run` section. Support DS types within addReturn @@ -90,7 +92,7 @@ Migrating from ``iConn`` to ``Connection`` Constructor // using rest transport - // const restConfig = { host: 'myhost', port: 80, path: '/' } + // 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({ @@ -99,12 +101,17 @@ Migrating from ``iConn`` to ``Connection`` Constructor database: '*LOCAL', username: 'myuser', password: 'mypassword', - url: 'http://myhost:80/', + url: 'http://myhost.example.com/cgi-bin/xmlcgi.pgm', } }); +.. _iconn-to-connection-run: + Migrating from ``iConn.run()`` to ``Connection.run()`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +You should be able to figure out how to connect using Connection from the docs, however you may not +realize that iConn -> Connection implies a change in behavior of the callbacks. Follow the steps +below to migrate 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 @@ -166,7 +173,7 @@ Migrating from ``iPgm.addParam()`` to ``ProgramCall.addParam()`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Parameter and data options are passed with the object parameter. Ensure -you specify the data type odefaulting to use ``1024a`` is deprecated. +the data type is specified; defaulting to use ``1024a`` is deprecated. .. code:: js From e5caf07b1085a137eb589b4bf05a9449f3849d39 Mon Sep 17 00:00:00 2001 From: Abdirahim Musse <33973272+abmusse@users.noreply.github.com> Date: Fri, 24 Apr 2020 12:58:40 -0500 Subject: [PATCH 10/14] fixup! fixup! fixup! docs: Add migration guide to sphinx docs --- docs/conf.py | 1 - docs/migratation-guide-v1.0.rst | 16 ++++++++-------- 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 125bb59a..37c66359 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -50,7 +50,6 @@ # This pattern also affects html_static_path and html_extra_path. exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] - # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for diff --git a/docs/migratation-guide-v1.0.rst b/docs/migratation-guide-v1.0.rst index 177790ac..ebf5e123 100644 --- a/docs/migratation-guide-v1.0.rst +++ b/docs/migratation-guide-v1.0.rst @@ -8,14 +8,12 @@ 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 ================ -.. 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 :ref:`iconn-to-connection-run` section. - ``iConn.run()`` no longer supports sync mode -------------------------------------------- @@ -76,6 +74,11 @@ Differences first callbacks `__. +.. 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 :ref:`iconn-to-connection-run` section. + Migrating from ``iConn`` to ``Connection`` Constructor ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -109,9 +112,6 @@ Migrating from ``iConn`` to ``Connection`` Constructor Migrating from ``iConn.run()`` to ``Connection.run()`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -You should be able to figure out how to connect using Connection from the docs, however you may not -realize that iConn -> Connection implies a change in behavior of the callbacks. Follow the steps -below to migrate 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 From 5218bdf5216097c08a5773ec39aafd5b947236f1 Mon Sep 17 00:00:00 2001 From: Abdirahim Musse <33973272+abmusse@users.noreply.github.com> Date: Fri, 24 Apr 2020 15:45:41 -0500 Subject: [PATCH 11/14] fixup! fixup! fixup! fixup! docs: Add migration guide to sphinx docs --- docs/migratation-guide-v1.0.rst | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/docs/migratation-guide-v1.0.rst b/docs/migratation-guide-v1.0.rst index ebf5e123..2b2a557e 100644 --- a/docs/migratation-guide-v1.0.rst +++ b/docs/migratation-guide-v1.0.rst @@ -74,32 +74,42 @@ Differences 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 :ref:`iconn-to-connection-run` section. -Migrating from ``iConn`` to ``Connection`` Constructor -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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. .. code:: js - // using idb transport - - // const conn = new iConn("*LOCAL", "myuser", "mypassword"); + // const conn = new iConn('*LOCAL', 'myuser', 'mypassword'); const conn = new Connection({ transport: 'idb', + returnError: false, transportOptions: { database: '*LOCAL', username: 'myuser', password: 'mypassword' } }); - // using rest transport +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. + +.. code:: js // 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', + returnError: false, transportOptions: { database: '*LOCAL', username: 'myuser', From ee2a1c81d1d29990f86152e6ddf0cc7e196d5b86 Mon Sep 17 00:00:00 2001 From: Abdirahim Musse <33973272+abmusse@users.noreply.github.com> Date: Fri, 24 Apr 2020 15:58:00 -0500 Subject: [PATCH 12/14] fixup! fixup! fixup! fixup! fixup! docs: Add migration guide to sphinx docs --- docs/migratation-guide-v1.0.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migratation-guide-v1.0.rst b/docs/migratation-guide-v1.0.rst index 2b2a557e..b3fcffdc 100644 --- a/docs/migratation-guide-v1.0.rst +++ b/docs/migratation-guide-v1.0.rst @@ -75,7 +75,7 @@ Differences callbacks `__. Migrating from ``iConn`` to ``Connection`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. WARNING:: Beware that the Connection and iConn classes differ in how they call the callbacks From bf799409699556eddeca3c492744a05315ad4637 Mon Sep 17 00:00:00 2001 From: Abdirahim Musse <33973272+abmusse@users.noreply.github.com> Date: Fri, 24 Apr 2020 18:10:35 -0500 Subject: [PATCH 13/14] fixup! fixup! fixup! fixup! fixup! fixup! docs: Add migration guide to sphinx docs --- docs/index.rst | 3 ++- docs/migratation-guide-v1.0.rst | 23 ++++++++++------------- 2 files changed, 12 insertions(+), 14 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index c687f94f..5523daf3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -52,7 +52,8 @@ Installation $ npm install itoolkit -**NOTE:** If you are upgrading from ``0.1.x`` be sure to read the :doc:`migration guide `. +.. NOTE:: + If you are upgrading from ``0.1.x`` be sure to read the :doc:`migration guide `. .. toctree:: :maxdepth: 1 diff --git a/docs/migratation-guide-v1.0.rst b/docs/migratation-guide-v1.0.rst index b3fcffdc..266a90e9 100644 --- a/docs/migratation-guide-v1.0.rst +++ b/docs/migratation-guide-v1.0.rst @@ -14,21 +14,20 @@ first. BREAKING CHANGES ================ -``iConn.run()`` no longer supports sync mode --------------------------------------------- +Sync Mode Operations +--------------------- -Sync mode did not work properly to begin with see -(`#32 `__). +``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 ----------------------------------- +``iConn.setTimeout()`` is removed. This function was used to set the timeout for ``iConn.run`` +sync mode. -This function was used to set timeout for ``iConn.run`` sync mode. +iSql Authentication +------------------- -``iSql.connect()`` and ``iSql.setOptions()`` are removed --------------------------------------------------------- - -These functions were used in conjunction for XMLSERVICE user +``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 @@ -92,7 +91,6 @@ object passed to ``Connection`` and specify the transport is ``idb``. eg. const conn = new Connection({ transport: 'idb', - returnError: false, transportOptions: { database: '*LOCAL', username: 'myuser', password: 'mypassword' } }); @@ -109,7 +107,6 @@ transport is ``rest``. eg. const conn = new Connection({ transport: 'rest', - returnError: false, transportOptions: { database: '*LOCAL', username: 'myuser', From 49a9f0179a51386a956e887120f9b0b6b7c8fab8 Mon Sep 17 00:00:00 2001 From: Abdirahim Musse <33973272+abmusse@users.noreply.github.com> Date: Fri, 24 Apr 2020 18:12:00 -0500 Subject: [PATCH 14/14] fixup! fixup! fixup! fixup! fixup! fixup! fixup! docs: Add migration guide to sphinx docs --- docs/migratation-guide-v1.0.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migratation-guide-v1.0.rst b/docs/migratation-guide-v1.0.rst index 266a90e9..168e2d49 100644 --- a/docs/migratation-guide-v1.0.rst +++ b/docs/migratation-guide-v1.0.rst @@ -15,7 +15,7 @@ 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.