diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 00000000..05a8e0c6 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,16 @@ +# .readthedocs.yml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/conf.py + +# Optionally set the version of Python and requirements required to build your docs +python: + version: 3.7 + install: + - requirements: docs/requirements.txt diff --git a/docs/CommandCall.rst b/docs/CommandCall.rst new file mode 100644 index 00000000..a04ec430 --- /dev/null +++ b/docs/CommandCall.rst @@ -0,0 +1,22 @@ +.. _CommandCall: + +Calling a Command +----------------- + +CommandCall API +^^^^^^^^^^^^^^^ +.. autoclass:: CommandCall + :members: + +.. autofunction:: clOptions +.. autofunction:: shOptions +.. autofunction:: commandCallConfig + +Example +^^^^^^^^ + +Call the RTVJOBA CL command +"""""""""""""""""""""""""""" + +.. literalinclude:: examples/rtvjoba.js + :language: javascript diff --git a/docs/Connection.rst b/docs/Connection.rst new file mode 100644 index 00000000..038cddf5 --- /dev/null +++ b/docs/Connection.rst @@ -0,0 +1,135 @@ +.. _Connection: + +Creating a Connection +===================== + +Transports +---------- + +The ``Connection`` Class uses ``ODBC``, ``SSH``, ``idb``, and ``REST`` transports to access ``XMLSERVICE``. +Some transports require prerequisite setup. Learn morre about each transport below. + +ODBC +^^^^ +.. _guide: https://github.com/IBM/ibmi-oss-examples/blob/master/odbc/odbc.md#table-of-contents + +The ODBC transport establishes a database connection and calls XMLSERVICE stored procedure. +Refer to the odbc guide_ for setup instructions. + +SSH +^^^ +The SSH transport executes ``xmlservice-cli`` program via ssh. +Install ``xmlservice-cli`` before using the ``SSH`` transport. + +.. code-block:: bash + + $ yum install itoolkit-utils + +idb +^^^^ + +The idb transport establishes a database connection and calls the XMLSERVICE stored procedure. + +**NOTE** the idb transport is only supported on an IBM i system. + +REST +^^^^ +The REST transport makes an HTTP request to an endpoint that process the XML input and returns XML output. + +Initial configuration is required for the endpoint. + +A quick example is to add the following to ``/www/apachedft/conf/httpd.conf``. + + +.. code-block:: apache + + ScriptAlias /cgi-bin/ /QSYS.LIB/XMLSERVICE.LIB/ + + AllowOverride None + Require all granted + SetHandler cgi-script + Options +ExecCGI + + +Connection API +-------------- + +.. autoclass:: Connection + :members: + +.. autofunction:: connectionConfig +.. autofunction:: odbcOptions +.. autofunction:: sshOptions +.. autofunction:: idbOptions +.. autofunction:: restOptions +.. autofunction:: runCallback + +Examples +-------- + +Creating a ``Connection`` using the ``ODBC`` tranport. + +.. code-block:: js + + const connection = new Connection({ + transport: 'odbc', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword'} + }); + +Creating a ``Connection`` using the ``ODBC`` tranport with a ``DSN``. + +.. code-block:: js + + const connection = new Connection({ + transport: 'odbc', + transportOptions: { dsn: '*LOCAL'} + }); + +Creating a ``Connection`` with ``ssh`` tranport using private key to authenticate. + +.. code-block:: js + + const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' } + }); + +Creating a ``Connection`` using the ``ssh`` tranport with a private key to authenticate. + +.. code-block:: js + + const { readFileSync } = require('fs'); + + const privateKey = readFileSync('path/to/privateKey', 'utf-8'); + + // NOTE if your privateKey also requires a passphrase provide it + + const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', privateKey, passphrase: 'myphrase' } + }); + +Creating a ``Connection`` using the ``idb`` tranport. + +.. code-block:: js + + const connection = new Connection({ + transport: 'idb', + transportOptions: { database: '*LOCAL', username: 'myuser', password: 'mypass' } + }); + +Creating a ``Connection`` using the ``REST`` tranport. + +.. code-block:: js + + const connection = new Connection({ + transport: 'rest', + transportOptions: { + host: 'myhost', + database: '*LOCAL', + username: 'myuser', + password: 'mypass' + port: 80, + path:'/cgi-bin/xmlcgi.pgm', + } + }); diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/ProgramCall.rst b/docs/ProgramCall.rst new file mode 100644 index 00000000..9b74299e --- /dev/null +++ b/docs/ProgramCall.rst @@ -0,0 +1,23 @@ +.. _ProgramCall: + +Calling a Program or Service Program +------------------------------------ + +ProgramCall API +^^^^^^^^^^^^^^^ +.. autoclass:: ProgramCall + :members: + +.. autofunction:: programCallConfig +.. autofunction:: parameterConfig +.. autofunction:: returnConfig +.. autofunction:: data + +Example +^^^^^^^^ + +Call the QUSROBJD Program +""""""""""""""""""""""""" + +.. literalinclude:: examples/qusrobjd.js + :language: javascript diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..37c66359 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,63 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) +import json + +js_source_path = '../lib' +primary_domain = 'js' + +# -- Project information ----------------------------------------------------- + +project = 'nodejs-itoolkit' +copyright = '2020, IBM' +author = 'IBM' + +# The full version, including alpha/beta/rc tags +# read the version from package.json +with open('../package.json', 'r') as read_file: + package = json.load(read_file) + release = package['version'] + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx_js', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The master toctree document. +master_doc = 'index' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# 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 +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] diff --git a/docs/deprecated.rst b/docs/deprecated.rst new file mode 100644 index 00000000..96029d36 --- /dev/null +++ b/docs/deprecated.rst @@ -0,0 +1,21 @@ +.. _deprecated: + + +Deprecated Classes and Functions +================================ + +.. toctree:: + :maxdepth: 1 + + deprecated/iConn + deprecated/iCmd + deprecated/iDataQueue + deprecated/iNetwork + deprecated/iObj + deprecated/iPgm + deprecated/iProd + deprecated/iQsh + deprecated/iSh + deprecated/iSql + deprecated/iUserSpace + deprecated/iWork diff --git a/docs/deprecated/examples/addQuery.js b/docs/deprecated/examples/addQuery.js new file mode 100644 index 00000000..d9ed04ed --- /dev/null +++ b/docs/deprecated/examples/addQuery.js @@ -0,0 +1,27 @@ +const { Connection, iSql } = require('itoolkit'); +const { parseString } = require('xml2js'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const sql = new iSql(); + +sql.addQuery('SELECT LSTNAM, STATE FROM QIWS.QCUSTCDT'); +sql.fetch(); +sql.free(); + +connection.add(sql); + +connection.run((error, xmlOutput) => { + if (error) { + throw error; + } + parseString(xmlOutput, (parseError, result) => { + if (parseError) { + throw parseError; + } + console.log(JSON.stringify(result)); + }); +}); diff --git a/docs/deprecated/examples/addToLibraryList.js b/docs/deprecated/examples/addToLibraryList.js new file mode 100644 index 00000000..73680822 --- /dev/null +++ b/docs/deprecated/examples/addToLibraryList.js @@ -0,0 +1,15 @@ +const { Connection, iObj } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const obj = new iObj(connection); + +obj.addToLibraryList('QHTTPSVR', (error, output) => { + if (error) { + throw error; + } + console.log(output); +}); diff --git a/docs/deprecated/examples/callProcedure.js b/docs/deprecated/examples/callProcedure.js new file mode 100644 index 00000000..3ba434ab --- /dev/null +++ b/docs/deprecated/examples/callProcedure.js @@ -0,0 +1,28 @@ +const { Connection, iSql } = require('itoolkit'); +const { parseString } = require('xml2js'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const sql = new iSql(); + +sql.prepare('call qsys2.tcpip_info()'); +sql.execute(); +sql.fetch(); +sql.free(); + +connection.add(sql); + +connection.run((error, xmlOutput) => { + if (error) { + throw error; + } + parseString(xmlOutput, (parseError, result) => { + if (parseError) { + throw parseError; + } + console.log(JSON.stringify(result)); + }); +}); diff --git a/docs/deprecated/examples/clearDataQueue.js b/docs/deprecated/examples/clearDataQueue.js new file mode 100644 index 00000000..975408f9 --- /dev/null +++ b/docs/deprecated/examples/clearDataQueue.js @@ -0,0 +1,15 @@ +const { Connection, iDataQueue } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const dq = new iDataQueue(connection); + +dq.clearDataQueue('mydq', 'mylib', (error, output) => { + if (error) { + throw error; + } + console.log(output); +}); diff --git a/docs/deprecated/examples/createUserSpace.js b/docs/deprecated/examples/createUserSpace.js new file mode 100644 index 00000000..45b55cd6 --- /dev/null +++ b/docs/deprecated/examples/createUserSpace.js @@ -0,0 +1,15 @@ +const { Connection, iUserSpace } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const userSpace = new iUserSpace(connection); + +userSpace.createUserSpace('myuserspace', 'mylib', 'LOG', 50, 'EXCLUDE', 'Example User Space', (error, output) => { + if (error) { + throw error; + } + console.log(output); +}); diff --git a/docs/deprecated/examples/deleteUserSpace.js b/docs/deprecated/examples/deleteUserSpace.js new file mode 100644 index 00000000..d35430d6 --- /dev/null +++ b/docs/deprecated/examples/deleteUserSpace.js @@ -0,0 +1,15 @@ +const { Connection, iUserSpace } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const userSpace = new iUserSpace(connection); + +userSpace.deleteUserSpace('myuserspace', 'mylib', (error, output) => { + if (error) { + throw error; + } + console.log(output); +}); diff --git a/docs/deprecated/examples/getDataArea.js b/docs/deprecated/examples/getDataArea.js new file mode 100644 index 00000000..56e1971e --- /dev/null +++ b/docs/deprecated/examples/getDataArea.js @@ -0,0 +1,15 @@ +const { Connection, iWork } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const work = new iWork(connection); + +work.getDataArea('mylibrary', 'mydataarea', 100, (error, output) => { + if (error) { + throw error; + } + console.log(output); +}); diff --git a/docs/deprecated/examples/getInstalledProducts.js b/docs/deprecated/examples/getInstalledProducts.js new file mode 100644 index 00000000..6911b5f8 --- /dev/null +++ b/docs/deprecated/examples/getInstalledProducts.js @@ -0,0 +1,15 @@ +const { Connection, iProd } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const prod = new iProd(connection); + +prod.getInstalledProducts((error, output) => { + if (error) { + throw error; + } + console.log(output); +}); diff --git a/docs/deprecated/examples/getJobInfo.js b/docs/deprecated/examples/getJobInfo.js new file mode 100644 index 00000000..66b773de --- /dev/null +++ b/docs/deprecated/examples/getJobInfo.js @@ -0,0 +1,15 @@ +const { Connection, iWork } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const work = new iWork(connection); + +work.getJobInfo('jobname', 'user', 'jobnumber', (error, output) => { + if (error) { + throw error; + } + console.log(output); +}); diff --git a/docs/deprecated/examples/getJobStatus.js b/docs/deprecated/examples/getJobStatus.js new file mode 100644 index 00000000..b9abda42 --- /dev/null +++ b/docs/deprecated/examples/getJobStatus.js @@ -0,0 +1,15 @@ +const { Connection, iWork } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const work = new iWork(connection); + +work.getJobStatus('jobid', (error, output) => { + if (error) { + throw error; + } + console.log(output); +}); diff --git a/docs/deprecated/examples/getNetInterfaceData.js b/docs/deprecated/examples/getNetInterfaceData.js new file mode 100644 index 00000000..f1abb442 --- /dev/null +++ b/docs/deprecated/examples/getNetInterfaceData.js @@ -0,0 +1,15 @@ +const { Connection, iNetwork } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const net = new iNetwork(connection); + +net.getNetInterfaceData('127.0.0.1', (error, output) => { + if (error) { + throw error; + } + console.log(output); +}); diff --git a/docs/deprecated/examples/getPTFInfo.js b/docs/deprecated/examples/getPTFInfo.js new file mode 100644 index 00000000..e5c73bee --- /dev/null +++ b/docs/deprecated/examples/getPTFInfo.js @@ -0,0 +1,15 @@ +const { Connection, iProd } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const prod = new iProd(connection); + +prod.getPTFInfo('SI54708', (error, output) => { + if (error) { + throw error; + } + console.log(output); +}); diff --git a/docs/deprecated/examples/getProductInfo.js b/docs/deprecated/examples/getProductInfo.js new file mode 100644 index 00000000..45f0e862 --- /dev/null +++ b/docs/deprecated/examples/getProductInfo.js @@ -0,0 +1,15 @@ +const { Connection, iProd } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const prod = new iProd(connection); + +prod.getProductInfo('5770DG1', (error, output) => { + if (error) { + throw error; + } + console.log(output); +}); diff --git a/docs/deprecated/examples/getSysStatus.js b/docs/deprecated/examples/getSysStatus.js new file mode 100644 index 00000000..086e30f1 --- /dev/null +++ b/docs/deprecated/examples/getSysStatus.js @@ -0,0 +1,15 @@ +const { Connection, iWork } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const work = new iWork(connection); + +work.getSysStatus((error, output) => { + if (error) { + throw error; + } + console.log((output)); +}); diff --git a/docs/deprecated/examples/getSysStatusExt.js b/docs/deprecated/examples/getSysStatusExt.js new file mode 100644 index 00000000..e8e8b06c --- /dev/null +++ b/docs/deprecated/examples/getSysStatusExt.js @@ -0,0 +1,15 @@ +const { Connection, iWork } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const work = new iWork(connection); + +work.getSysStatusExt((error, output) => { + if (error) { + throw error; + } + console.log(output); +}); diff --git a/docs/deprecated/examples/getSysValue.js b/docs/deprecated/examples/getSysValue.js new file mode 100644 index 00000000..cb4fd43f --- /dev/null +++ b/docs/deprecated/examples/getSysValue.js @@ -0,0 +1,15 @@ +const { Connection, iWork } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const work = new iWork(connection); + +work.getSysValue('QCCSID', (error, output) => { + if (error) { + throw error; + } + console.log(`QCCSID = ${output}`); +}); diff --git a/docs/deprecated/examples/getTCPIPAttr.js b/docs/deprecated/examples/getTCPIPAttr.js new file mode 100644 index 00000000..063b7c62 --- /dev/null +++ b/docs/deprecated/examples/getTCPIPAttr.js @@ -0,0 +1,15 @@ +const { Connection, iNetwork } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const net = new iNetwork(connection); + +net.getTCPIPAttr((error, output) => { + if (error) { + throw error; + } + console.log((output)); +}); diff --git a/docs/deprecated/examples/getUserSpaceData.js b/docs/deprecated/examples/getUserSpaceData.js new file mode 100644 index 00000000..782218ed --- /dev/null +++ b/docs/deprecated/examples/getUserSpaceData.js @@ -0,0 +1,15 @@ +const { Connection, iUserSpace } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const userSpace = new iUserSpace(connection); + +userSpace.getUserSpaceData('myuserspace', 'mylib', 20, (error, output) => { + if (error) { + throw error; + } + console.log(output); +}); diff --git a/docs/deprecated/examples/receiveFromDataQueue.js b/docs/deprecated/examples/receiveFromDataQueue.js new file mode 100644 index 00000000..fdaf47f4 --- /dev/null +++ b/docs/deprecated/examples/receiveFromDataQueue.js @@ -0,0 +1,15 @@ +const { Connection, iDataQueue } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const dq = new iDataQueue(connection); + +dq.receiveFromDataQueue('mydq', 'mylib', 20, (error, output) => { + if (error) { + throw error; + } + console.log(output); +}); diff --git a/docs/deprecated/examples/retrCmdInfo.js b/docs/deprecated/examples/retrCmdInfo.js new file mode 100644 index 00000000..5f942858 --- /dev/null +++ b/docs/deprecated/examples/retrCmdInfo.js @@ -0,0 +1,15 @@ +const { Connection, iObj } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const obj = new iObj(connection); + +obj.retrCmdInfo('CRTLIB', '*LIBL', (error, output) => { + if (error) { + throw error; + } + console.log(output); +}); diff --git a/docs/deprecated/examples/retrPgmInfo.js b/docs/deprecated/examples/retrPgmInfo.js new file mode 100644 index 00000000..4a60b123 --- /dev/null +++ b/docs/deprecated/examples/retrPgmInfo.js @@ -0,0 +1,15 @@ +const { Connection, iObj } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const obj = new iObj(connection); + +obj.retrPgmInfo('XMLCGI', 'QXMLSERV', (error, output) => { + if (error) { + throw error; + } + console.log(output); +}); diff --git a/docs/deprecated/examples/retrSrvPgmInfo.js b/docs/deprecated/examples/retrSrvPgmInfo.js new file mode 100644 index 00000000..22b463b5 --- /dev/null +++ b/docs/deprecated/examples/retrSrvPgmInfo.js @@ -0,0 +1,16 @@ + +const { Connection, iObj } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const obj = new iObj(connection); + +obj.retrSrvPgmInfo('QZSRVSSL', 'QHTTPSVR', (error, output) => { + if (error) { + throw error; + } + console.log(output); +}); diff --git a/docs/deprecated/examples/retrUserAuthToObj.js b/docs/deprecated/examples/retrUserAuthToObj.js new file mode 100644 index 00000000..a61ad1de --- /dev/null +++ b/docs/deprecated/examples/retrUserAuthToObj.js @@ -0,0 +1,15 @@ +const { Connection, iObj } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const obj = new iObj(connection); + +obj.retrUserAuthToObj('/home', (error, output) => { + if (error) { + throw error; + } + console.log(output); +}); diff --git a/docs/deprecated/examples/retrUserInfo.js b/docs/deprecated/examples/retrUserInfo.js new file mode 100644 index 00000000..b3dd3a97 --- /dev/null +++ b/docs/deprecated/examples/retrUserInfo.js @@ -0,0 +1,15 @@ +const { Connection, iObj } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const obj = new iObj(connection); + +obj.retrUserInfo('QSYS', (error, output) => { + if (error) { + throw error; + } + console.log(output); +}); diff --git a/docs/deprecated/examples/retrUsrAuth.js b/docs/deprecated/examples/retrUsrAuth.js new file mode 100644 index 00000000..2034e5d7 --- /dev/null +++ b/docs/deprecated/examples/retrUsrAuth.js @@ -0,0 +1,15 @@ +const { Connection, iObj } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const obj = new iObj(connection); + +obj.retrUsrAuth('*PUBLIC', '*PGM', 'XMLCGI', 'QXMLSERV', (error, output) => { + if (error) { + throw error; + } + console.log(output); +}); diff --git a/docs/deprecated/examples/sendToDataQueue.js b/docs/deprecated/examples/sendToDataQueue.js new file mode 100644 index 00000000..7c3d930f --- /dev/null +++ b/docs/deprecated/examples/sendToDataQueue.js @@ -0,0 +1,15 @@ +const { Connection, iDataQueue } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const dq = new iDataQueue(connection); + +dq.sendToDataQueue('TESTQ', 'TEST', 'Hello World!', (error, output) => { + if (error) { + throw error; + } + console.log(output); +}); diff --git a/docs/deprecated/examples/setUserSpaceData.js b/docs/deprecated/examples/setUserSpaceData.js new file mode 100644 index 00000000..abd37d7d --- /dev/null +++ b/docs/deprecated/examples/setUserSpaceData.js @@ -0,0 +1,15 @@ +const { Connection, iUserSpace } = require('itoolkit'); + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const userSpace = new iUserSpace(connection); + +userSpace.setUserSpaceData('myuserspace', 'mylib', 20, 'Hello!', (error, output) => { + if (error) { + throw error; + } + console.log(output); +}); diff --git a/docs/deprecated/iCmd.rst b/docs/deprecated/iCmd.rst new file mode 100644 index 00000000..3ff138dd --- /dev/null +++ b/docs/deprecated/iCmd.rst @@ -0,0 +1,7 @@ +.. _iCmd: + +iCmd +---- + +.. autofunction:: iCmd +.. autofunction:: clOptionsDeprecated diff --git a/docs/deprecated/iConn.rst b/docs/deprecated/iConn.rst new file mode 100644 index 00000000..7e278580 --- /dev/null +++ b/docs/deprecated/iConn.rst @@ -0,0 +1,9 @@ +.. _iConn: + +iConn +----- +.. autoclass:: iConn + :members: + +.. autofunction:: restConfig +.. autofunction:: runCallbackDeprecated diff --git a/docs/deprecated/iDataQueue.rst b/docs/deprecated/iDataQueue.rst new file mode 100644 index 00000000..79f39d55 --- /dev/null +++ b/docs/deprecated/iDataQueue.rst @@ -0,0 +1,33 @@ +.. _iDataQueue: + +iDataQueue +---------- + +.. autoclass:: iDataQueue + :members: + +.. autofunction:: sendToDataQueueCallback +.. autofunction:: receiveFromDataQueueCallback +.. autofunction:: clearDataQueueCallback + +Examples +^^^^^^^^ + +Send data to the data queue +""""""""""""""""""""""""""" + +.. literalinclude:: examples/sendToDataQueue.js + :language: javascript + + +Retrieve data from the data queue +""""""""""""""""""""""""""""""""" + +.. literalinclude:: examples/receiveFromDataQueue.js + :language: javascript + +Clear the data queue +"""""""""""""""""""" + +.. literalinclude:: examples/clearDataQueue.js + :language: javascript diff --git a/docs/deprecated/iNetwork.rst b/docs/deprecated/iNetwork.rst new file mode 100644 index 00000000..a2c2d4e3 --- /dev/null +++ b/docs/deprecated/iNetwork.rst @@ -0,0 +1,27 @@ +.. _iNetwork: + +iNetwork +-------- + +.. autoclass:: iNetwork + :members: + +.. autofunction:: getTCPIPAttrCallback +.. autofunction:: getTCPIPAttrOutput +.. autofunction:: getNetInterfaceDataCallback +.. autofunction:: getNetInterfaceDataOutput + +Examples +^^^^^^^^ + +Retrieve TCP / IP attributes +"""""""""""""""""""""""""""" + +.. literalinclude:: examples/getTCPIPAttr.js + :language: javascript + +Retrieve network interface data +""""""""""""""""""""""""""""""" + +.. literalinclude:: examples/getNetInterfaceData.js + :language: javascript diff --git a/docs/deprecated/iObj.rst b/docs/deprecated/iObj.rst new file mode 100644 index 00000000..9bb77b9e --- /dev/null +++ b/docs/deprecated/iObj.rst @@ -0,0 +1,64 @@ +.. _iObj: + +iObj +---- + +.. autoclass:: iObj + :members: + +.. autofunction:: addToLibraryListCallback +.. autofunction:: retrUsrAuthCallback +.. autofunction:: retrUsrAuthOutput +.. autofunction:: retrCmdInfoCallback +.. autofunction:: retrCmdInfoOutput +.. autofunction:: retrPgmInfoCallback +.. autofunction:: retrPgmInfoOutput +.. autofunction:: retrSrvPgmInfoCallback +.. autofunction:: retrSrvPgmInfoOutput +.. autofunction:: retrUserInfoCallback +.. autofunction:: retrUserInfoOutput +.. autofunction:: retrUserAuthToObjCallback +.. autofunction:: retrUserAuthToObjOutput + +Examples +^^^^^^^^ + +Retrieve a user's authority to an object +"""""""""""""""""""""""""""""""""""""""" +.. literalinclude:: examples/retrUsrAuth.js + :language: javascript + +Retrieve command information +"""""""""""""""""""""""""""" + +.. literalinclude:: examples/retrCmdInfo.js + :language: javascript + +Retrieve program information +"""""""""""""""""""""""""""" + +.. literalinclude:: examples/retrPgmInfo.js + :language: javascript + +Retrieve service program information + +.. literalinclude:: examples/retrSrvPgmInfo.js + :language: javascript + +Retrieve user information +""""""""""""""""""""""""" + +.. literalinclude:: examples/retrUserInfo.js + :language: javascript + +Retrieve users authorized to an object +"""""""""""""""""""""""""""""""""""""" + +.. literalinclude:: examples/retrUserAuthToObj.js + :language: javascript + +Add a library to the library list +""""""""""""""""""""""""""""""""" + +.. literalinclude:: examples/addToLibraryList.js + :language: javascript diff --git a/docs/deprecated/iPgm.rst b/docs/deprecated/iPgm.rst new file mode 100644 index 00000000..73466911 --- /dev/null +++ b/docs/deprecated/iPgm.rst @@ -0,0 +1,9 @@ +.. _ipgm: + +iPgm +---- + +.. autoclass:: iPgm + :members: + +.. autofunction:: iPgmOptions diff --git a/docs/deprecated/iProd.rst b/docs/deprecated/iProd.rst new file mode 100644 index 00000000..728df205 --- /dev/null +++ b/docs/deprecated/iProd.rst @@ -0,0 +1,36 @@ +.. _iProd: + +iProd +----- + +.. autoclass:: iProd + :members: + +.. autofunction:: getPTFInfoCallback +.. autofunction:: getPTFInfoOutput +.. autofunction:: getProductInfoCallback +.. autofunction:: getProductInfoOutput +.. autofunction:: getInstalledProductsCallback +.. autofunction:: getInstalledProductsOutput + +Examples +^^^^^^^^ + +Retrieve basic PTF info +""""""""""""""""""""""" + +.. literalinclude:: examples/getPTFInfo.js + :language: javascript + + +Retrieve basic information about the product load +""""""""""""""""""""""""""""""""""""""""""""""""" + +.. literalinclude:: examples/getProductInfo.js + :language: javascript + +Retrieve the list of all installed products +""""""""""""""""""""""""""""""""""""""""""" + +.. literalinclude:: examples/getInstalledProducts.js + :language: javascript diff --git a/docs/deprecated/iQsh.rst b/docs/deprecated/iQsh.rst new file mode 100644 index 00000000..ebeaa226 --- /dev/null +++ b/docs/deprecated/iQsh.rst @@ -0,0 +1,7 @@ +.. _iQsh: + +iQsh +---- + +.. autofunction:: iQsh +.. autofunction:: qshOptionsDeprecated diff --git a/docs/deprecated/iSh.rst b/docs/deprecated/iSh.rst new file mode 100644 index 00000000..2482af37 --- /dev/null +++ b/docs/deprecated/iSh.rst @@ -0,0 +1,7 @@ +.. _iSh: + +iSh +--- + +.. autofunction:: iSh +.. autofunction:: shOptionsDeprecated diff --git a/docs/deprecated/iSql.rst b/docs/deprecated/iSql.rst new file mode 100644 index 00000000..9b214d30 --- /dev/null +++ b/docs/deprecated/iSql.rst @@ -0,0 +1,30 @@ +.. _iSql: + +iSql +---- + +.. autoclass:: iSql + :members: + +.. autofunction:: iSqlOptions +.. autofunction:: commitOptions +.. autofunction:: describeOptions +.. autofunction:: countOptions +.. autofunction:: executeParams +.. autofunction:: fetchOptions + +Examples +^^^^^^^^ + +Run a query +""""""""""" + +.. literalinclude:: examples/addQuery.js + :language: javascript + + +Call a procedure +"""""""""""""""" + +.. literalinclude:: examples/callProcedure.js + :language: javascript diff --git a/docs/deprecated/iUserSpace.rst b/docs/deprecated/iUserSpace.rst new file mode 100644 index 00000000..194690b8 --- /dev/null +++ b/docs/deprecated/iUserSpace.rst @@ -0,0 +1,38 @@ +.. _iUserSpace: + +iUserSpace +---------- + +.. autoclass:: iUserSpace + :members: + +.. autofunction:: createUserSpaceCallback +.. autofunction:: setUserSpaceDataCallback +.. autofunction:: getUserSpaceDataCallback +.. autofunction:: deleteUserSpaceCallback + +Examples +^^^^^^^^ + +Create a new user space +""""""""""""""""""""""" + +.. literalinclude:: examples/createUserSpace.js + :language: javascript + +Set the content of the user space +""""""""""""""""""""""""""""""""" +.. literalinclude:: examples/setUserSpaceData.js + :language: javascript + +Retrieve the content of the user space +"""""""""""""""""""""""""""""""""""""" + +.. literalinclude:: examples/getUserSpaceData.js + :language: javascript + +Delete the user space +""""""""""""""""""""" + +.. literalinclude:: examples/deleteUserSpace.js + :language: javascript diff --git a/docs/deprecated/iWork.rst b/docs/deprecated/iWork.rst new file mode 100644 index 00000000..576f7c24 --- /dev/null +++ b/docs/deprecated/iWork.rst @@ -0,0 +1,58 @@ +.. _iWork: + +iWork +----- + +.. autoclass:: iWork + :members: + +.. autofunction:: getSysValueCallback +.. autofunction:: getSysStatusCallback +.. autofunction:: getSysStatusOutput +.. autofunction:: getSysStatusExtCallback +.. autofunction:: getSysStatusExtOutput +.. autofunction:: getJobStatusCallback +.. autofunction:: getJobStatusOutput +.. autofunction:: getJobInfoCallback +.. autofunction:: getJobInfoOutput +.. autofunction:: getDataAreaCallback +.. autofunction:: getDataAreaOutput + +Examples +^^^^^^^^ + +Retrieve a system value +""""""""""""""""""""""" + +.. literalinclude:: examples/getSysValue.js + :language: javascript + +Retrieve basic system status +"""""""""""""""""""""""""""" + +.. literalinclude:: examples/getSysStatus.js + :language: javascript + +Retrieve extended system status +""""""""""""""""""""""""""""""" + +.. literalinclude:: examples/getSysStatusExt.js + :language: javascript + +Retrieve job status +""""""""""""""""""" + +.. literalinclude:: examples/getJobStatus.js + :language: javascript + +Retrieve job info +""""""""""""""""" + +.. literalinclude:: examples/getJobInfo.js + :language: javascript + +Retrieve the contents of a data area +""""""""""""""""""""""""""""""""""""" + +.. literalinclude:: examples/getDataArea.js + :language: javascript diff --git a/docs/examples/qusrobjd.js b/docs/examples/qusrobjd.js new file mode 100644 index 00000000..bf05209d --- /dev/null +++ b/docs/examples/qusrobjd.js @@ -0,0 +1,80 @@ +const { Connection, ProgramCall } = require('itoolkit'); +const { parseString } = require('xml2js'); + +const conn = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const receiver = { + name: 'receiver', + type: 'ds', + io: 'out', + len: 'rec1', + fields: [ + { name: 'bytes_returned', type: '10i0', value: '0' }, + { name: 'bytes_available', type: '10i0', value: '0' }, + { name: 'object_name', type: '10A', value: '' }, + { name: 'object_library_name', type: '10A', value: '' }, + { name: 'object_type', type: '10A', value: '' }, + { name: 'return_library', type: '10A', value: '0' }, + { name: 'storage_pool_number', type: '10i0', value: '0' }, + { name: 'object_owner', type: '10A', value: '' }, + { name: 'object_domain', type: '2A', value: '' }, + { name: 'creation_datetime', type: '13A', value: '' }, + { name: 'object_change_datetime', type: '13A', value: '' }, + ], +}; + +const errno = { + name: 'error_code', + type: 'ds', + io: 'both', + len: 'rec2', + fields: [ + { + name: 'bytes_provided', + type: '10i0', + value: 0, + setlen: 'rec2', + }, + { name: 'bytes_available', type: '10i0', value: 0 }, + { name: 'msgid', type: '7A', value: '' }, + { type: '1A', value: '' }, + ], +}; + +const objectAndLibrary = { + type: 'ds', + fields: [ + { name: 'object', type: '10A', value: 'QCSRC' }, + { name: 'lib', type: '10A', value: '*LIBL' }, + ], +}; + +const program = new ProgramCall('QUSROBJD', { lib: 'QSYS' }); +program.addParam(receiver); +program.addParam({ + name: 'length_of_receiver', + type: '10i0', + setlen: 'rec1', + value: '0', +}); +program.addParam({ name: 'format_name', type: '8A', value: 'OBJD0100' }); +program.addParam(objectAndLibrary); +program.addParam({ name: 'object_type', type: '10A', value: '*FILE' }); +program.addParam(errno); + +conn.add(program); + +conn.run((error, xmlOutput) => { + if (error) { + throw error; + } + parseString(xmlOutput, (parseError, result) => { + if (parseError) { + throw parseError; + } + console.log(JSON.stringify(result)); + }); +}); diff --git a/docs/examples/rtvjoba.js b/docs/examples/rtvjoba.js new file mode 100644 index 00000000..26240db9 --- /dev/null +++ b/docs/examples/rtvjoba.js @@ -0,0 +1,24 @@ +const { Connection, CommandCall } = require('itoolkit'); +const { parseString } = require('xml2js'); + + +const connection = new Connection({ + transport: 'ssh', + transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' }, +}); + +const command = new CommandCall({ type: 'cl', command: 'RTVJOBA USRLIBL(?) SYSLIBL(?)' }); + +connection.add(command); + +connection.run((error, xmlOutput) => { + if (error) { + throw error; + } + parseString(xmlOutput, (parseError, result) => { + if (parseError) { + throw parseError; + } + console.log(JSON.stringify(result)); + }); +}); diff --git a/docs/features.rst b/docs/features.rst new file mode 100644 index 00000000..2a6b2610 --- /dev/null +++ b/docs/features.rst @@ -0,0 +1,12 @@ +.. _features: + + +Features +======== + +.. toctree:: + :maxdepth: 1 + + Connection + CommandCall + ProgramCall diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..0bce6df9 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,67 @@ +.. nodejs-itoolkit documentation master file, created by + sphinx-quickstart on Tue Mar 31 16:50:35 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to nodejs-itoolkit's documentation! +=========================================== + +Introduction +============ + +.. _XMLSERVICE: https://github.com/IBM/xmlservice#xmlservice + +``itoolkit`` is a Node.js interface to XMLSERVICE_ to access all things IBM i. + +XMLSERVICE provides interfaces to interact with IBM i resources such as programs and commands. + +XMLSERVICE receives xml input and returns xml output. + +For example we can execute a CL command by sending the following XML input to XMLSERVICE. + +.. code-block:: xml + + + + RTVJOBA USRLIBL(?) SYSLIBL(?) + + +XMLSERVICE will run the command and respond with XML output. + +.. code-block:: xml + + + + + +++ success RTVJOBA USRLIBL(?) SYSLIBL(?) + + QGPL QTEMP + + + QSYS QSYS2 QHLPSYS QUSRSYS + + + + +The purpose of this package is to simplify the process of creating XMLSERVICE input, invoking XMLSERVICE, and returning XMLSERVICE output from Node.js. + +Installation +^^^^^^^^^^^^ + +.. code-block:: bash + + $ npm install itoolkit + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + features + deprecated + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..cd157bc6 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +sphinx-js>=2.8