From 400cb13166b2b779a72b773fa657967dc4125c79 Mon Sep 17 00:00:00 2001 From: Abdirahim Musse <33973272+abmusse@users.noreply.github.com> Date: Wed, 1 Apr 2020 00:19:08 -0500 Subject: [PATCH 1/6] docs: Update jsdoc for Deprecated.js --- lib/Deprecated.js | 1347 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 1163 insertions(+), 184 deletions(-) diff --git a/lib/Deprecated.js b/lib/Deprecated.js index 12f7f0f7..3847a8f2 100644 --- a/lib/Deprecated.js +++ b/lib/Deprecated.js @@ -49,10 +49,23 @@ const { Connection } = require('./Connection'); // DEPRECATED: For now, routes call to ProgramCall, but will be removed at a later time. class iPgm { /** - * @description Creates a new iPgm object + * iPgm Options + * @typedef {object} iPgmOptions + * @property {string} lib - The library where the program exists. + * @property {string} [error=fast] - Determines action when an error is encountered. + * Valid options are ``on``, ``off``, or ``fast``. Default is ``fast``. Using ``on`` + * will cause the script execution to stop and log a full error report. + * Using ``off`` or ``fast`` continues executing the script. The Difference is that ``fast`` + * will log a brief error report and ``off`` will not. + * @property {string} [func] - The target function of the service program. + */ + + /** + * @deprecated Replaced by ``ProgramCall`` and will be removed in the next major version. + * @description Creates a new iPgm object. * @constructor - * @param {string} pgm - * @param {object} [options] + * @param {string} pgm - The program or service program name. + * @param {iPgmOptions} [options] */ constructor(pgm, options) { iPgmDeprecate('As of v1.0, class \'iPgm\' is deprecated. Please use \'ProgramCall\' instead.'); @@ -60,11 +73,12 @@ class iPgm { } /** - * @description adds a parameter to the program XML - * @param {string | array} data - * @param {string} [type] - * @param {object} options - */ + * @deprecated Replaced by ``ProgramCall.addParam()`` and will be removed in the next major version. + * @description Adds a parameter to the program. + * @param {string|array} data - The value of the the data or 2D array ds definition. + * @param {string|object} [type] - The XMLSERVICE data type or ds options. + * @param {object} [options] - The parm or data options. + */ addParam(data, type, options) { const parameter = {}; @@ -107,10 +121,12 @@ class iPgm { } /** - * @description adds a return element to the program XML - * @param {string} value - * @param {string} type - * @param {object} [options] + * @deprecated Replaced by ``ProgramCall.addReturn()`` and will be removed in the + * next major version. + * @description Specifies the type of the return value from the service program function. + * @param {string} data - The value of the data. + * @param {string} type - The xmlservice data type. + * @param {object} [options] - The data options. */ addReturn(value, type = '1024a', options) { const data = {}; @@ -130,8 +146,8 @@ class iPgm { } /** - * @description returns the current program XML - * @returns {string} the generated program XML + * @deprecated Replaced by ``ProgramCall.toXML()`` and will be removed in the next major version. + * @returns {string} The generated program XML. */ toXML() { iPgmDeprecate('As of v1.0, \'iPgm.toXML()\' is deprecated. Please use \'ProgramCall.toXML()\' instead.'); @@ -142,7 +158,8 @@ class iPgm { // DEPRECATED: will be removed at a later time. class iSql { /** - * @description Creates a new iSql object + * @deprecated Will be removed in the next major version. + * @description Creates a new iSql object. * @constructor */ constructor() { @@ -151,27 +168,46 @@ class iSql { } /** - * @description adds sql query XML - * @param {string} stmt - * @param {object} [options] + * iSql Options + * @typedef {object} iSqlOptions + * @property {string} [error=fast] - Determines action when an error is encountered. + * Valid options are ``on``, ``off``, or ``fast``. Default is ``fast``. Using ``on`` + * will cause the script execution to stop and log a full error report. + * Using ``off`` or ``fast`` continues executing the script. The Difference is that ``fast`` + * will log a brief error report and ``off`` will not. + */ + + /** + * @deprecated Will be removed in the next major version. + * @description Specifies an sql query. + * @param {string} stmt - The sql staetment. + * @param {iSqlOptions} [options] */ addQuery(stmt, options = {}) { this.xml += `${stmt}`; } /** - * @description adds sql prepare XML - * @param {string} stmt - * @param {object} [options] + * @deprecated Will be removed in the next major version. + * @description Prepares a sql statement. + * @param {string} stmt - The sql statement. + * @param {iSqlOptions} [options] */ prepare(stmt, options = {}) { this.xml += `${stmt}`; } /** - * @description adds sql execute XML - * @param {array} params - * @param {object} [options] + * execute parameters + * @typedef {array} executeParams - 2D array for parameters. + * @property {string[]} subArray - Each sub element is [value, io] of the parameter. + */ + + /** + * @deprecated Will be removed in the next major version. + * @description Executes a prepared statement. + * @param {executeParams} params - 2D array for parameters. + * @param {iSqlOptions} [options] */ execute(params, options = {}) { this.xml += ``; @@ -186,9 +222,14 @@ class iSql { } /** - * @description adds sql table XML - * @param {array} params - * @param {object} [options] + * @deprecated Will be removed in the next major version. + * @description Retrieves table metadata. + * @param {string[]} params - + * The first element is the qualifer or catalog for the table. This may be an empty string. + * The second element is the schema name for the table. + * The third element is the name of the table. + * The fourth element is the type of the table. This may be an empty string. + * @param {iSqlOptions} [options] */ tables(params, options = {}) { this.xml += ``; @@ -199,9 +240,13 @@ class iSql { } /** - * @description adds sql table priv XML - * @param {array} params - * @param {object} [options] + * @deprecated Will be removed in the next major version. + * @description Retrieves table privledge metadata. + * @param {string[]} params - + * The first element is the qualifer or catalog for the table. This may be an empty string. + * The second element is the schema name for the table. + * The third element is the name of the table. + * @param {iSqlOptions} [options] */ tablePriv(params, options = {}) { this.xml += ``; @@ -214,9 +259,14 @@ class iSql { } /** - * @description adds sql columns XML - * @param {array} params - * @param {object} [options] + * @deprecated Will be removed in the next major version. + * @description Retrieves column metadata. + * @param {string[]} params - + * The first element is the qualifer or catalog for the table. This may be an empty string. + * The second element is the schema name for the column. + * The third element is the name of the table. + * The fourth element is the name of the column. + * @param {iSqlOptions} [options] */ columns(params, options = {}) { this.xml += ``; @@ -228,9 +278,14 @@ class iSql { } /** - * @description adds sql special XML - * @param {array} params - * @param {object} [options] + * @deprecated Will be removed in the next major version. + * @description Retrieves special column metadata. + * @param {string[]} params - + * The first element is the qualifer or catalog for the table. This may be an empty string. + * The second element is the schema name for the column. + * The third element is 'row', 'transaction', or 'session'. + * The fourth element is 'no' or 'nullable'. + * @param {iSqlOptions} [options] */ special(params, options = {}) { this.xml += ``; @@ -242,9 +297,14 @@ class iSql { } /** - * @description adds sql column priv XML - * @param {array} params - * @param {object} [options] + * @deprecated Will be removed in the next major version. + * @description Retrieves column privledge metadata. + * @param {string[]} params - + * The first element is the qualifer or catalog for the table. This may be an empty string. + * The second element is the schema name for the column. + * The third element is the name of the table. + * The fourth element is the name of the column. + * @param {iSqlOptions} [options] */ columnPriv(params, options = {}) { this.xml += ``; @@ -256,9 +316,14 @@ class iSql { } /** - * @description adds sql procedures XML - * @param {*} params - * @param {*} [options] + * @deprecated Will be removed in the next major version. + * @description Retrieves procedure metadata. + * @param {string[]} params - + * The first element is the qualifer or catalog for the procedure. + * This may be an empty string. + * The second element is the schema name for the procedure. + * The third element is the name of the procedure. + * @param {iSqlOptions} [options] */ procedures(params, options = {}) { this.xml += ``; @@ -270,9 +335,14 @@ class iSql { } /** - * @description adds sql pcolumns XML - * @param {array} params - * @param {object} [options] + * @deprecated Will be removed in the next major version. + * @description Retrieves procedure columns metadata. + * @param {string[]} params - + * The first element is the qualifer or catalog for the procedure. + * This may be an empty string. + * The second element is the schema name for the procedure. + * The third element is the name of the procedure. + * @param {iSqlOptions} [options] */ pColumns(params, options = {}) { this.xml += ``; @@ -284,9 +354,13 @@ class iSql { } /** - * @description adds sql primary keys XML - * @param {array} params - * @param {object} [options] + * @deprecated Will be removed in the next major version. + * @description Retrieves primary key metadata. + * @param {string[]} params - + * The first element is the qualifer or catalog for the table. This may be an empty string. + * The second element is the schema name for the table. + * The third element is the name of the table. + * @param {iSqlOptions} [options] */ primaryKeys(params, options = {}) { this.xml += ``; @@ -298,9 +372,18 @@ class iSql { } /** - * @description adds sql foriegn keys XML - * @param {array} params - * @param {object} [options] + * @deprecated Will be removed in the next major version. + * @description Retrieves foreign key metadata. + * @param {string[]} params - + * The first element is the qualifer or catalog for the primary key table. + * This may be an empty string. + * The second element is the schema name for the primary key table. + * The third element is the name of the primary key table. + * The fourth element is the qualifer or catalog for the foreign key table. + * This may be an empty string. + * The fifth element is the schema name for the foreign key table. + * The sixth element is the name of the foreign key table. + * @param {iSqlOptions} [options] */ foreignKeys(params, options = {}) { this.xml += ``; @@ -312,9 +395,15 @@ class iSql { } /** - * @description adds sql stats XML - * @param {array} params - * @param {object} [options] + * @deprecated Will be removed in the next major version. + * @description Retrieves metadata statistics for a table. + * @param {string[]} params - + * The first element is the qualifer or catalog for the table. + * This may be an empty string. + * The second element is the schema name for the table. + * The third element is the name of the table. + * The fourth element is 'all' or 'unique' to specify the level of stats returned. + * @param {iSqlOptions} [options] */ statistics(params, options = {}) { this.xml += ``; @@ -326,55 +415,109 @@ class iSql { } /** - * @description adds sql commit XML - * @param {object} options + * commit options + * @typedef {object} commitOptions + * @property {string} [action=commit] - The commit action either 'commit' or 'rollback'. + * Default is 'commit'. + * @property {string} [error=fast] - Determines action when an error is encountered. + * Valid options are ``on``, ``off``, or ``fast``. Default is ``fast``. Using ``on`` + * will cause the script execution to stop and log a full error report. + * Using ``off`` or ``fast`` continues executing the script. The Difference is that ``fast`` + * will log a brief error report and ``off`` will not. + */ + + /** + * @deprecated Will be removed in the next major version. + * @description Commits or rollsback a transaction. + * @param {commitOptions} [options] */ commit(options = {}) { this.xml += ``; } /** - * @description adds sql row count XML - * @param {object} options + * @deprecated Will be removed in the next major version. + * @description Retrieves the number of rows affected by a change. + * @param {iSqlOptions} [options] */ rowCount(options = {}) { this.xml += ``; } /** - * @description adds sql row count XML - * @param {object} options + * count options + * @typedef {object} countOptions + * @property {string} [desc=both] - The desc can be 'col', 'parm', or 'both'. Default is 'both'. + * @property {string} [error=fast] - Determines action when an error is encountered. + * Valid options are ``on``, ``off``, or ``fast``. Default is ``fast``. Using ``on`` + * will cause the script execution to stop and log a full error report. + * Using ``off`` or ``fast`` continues executing the script. The Difference is that ``fast`` + * will log a brief error report and ``off`` will not. + */ + + /** + * @deprecated Will be removed in the next major version. + * @description Retireves the number of column results, parameters, or both. + * @param {countOptions} [options] */ count(options = {}) { this.xml += ``; } /** - * @description adds sql describe XML - * @param {object} options + * describe options + * @typedef {object} describeOptions + * @property {string} [desc=both] - The desc option can be 'col', 'parm', or 'both'. + * Default is 'both'. + * @property {string} [error=fast] - Determines action when an error is encountered. + * Valid options are ``on``, ``off``, or ``fast``. Default is ``fast``. Using ``on`` + * will cause the script execution to stop and log a full error report. + * Using ``off`` or ``fast`` continues executing the script. The Difference is that ``fast`` + * will log a brief error report and ``off`` will not. + */ + + /** + * @deprecated Will be removed in the next major version. + * @description Retireves the description of a column, parameter, or both. + * @param {describeOptions} [options] */ describe(options = {}) { this.xml += ``; } /** - * @description adds sql fetch XML - * @param {object} options + * fetch options + * @typedef {object} fetchOptions + * @property {string} [block=all] - The block option can be 'all' or number of rows to fetch 'n'. + * Default is 'all'. + * @property {string} [desc=on] - The desc option can be 'on' or 'off'. Default is 'on'. + * @property {string} [error=fast] - Determines action when an error is encountered. + * Valid options are ``on``, ``off``, or ``fast``. Default is ``fast``. Using ``on`` + * will cause the script execution to stop and log a full error report. + * Using ``off`` or ``fast`` continues executing the script. The Difference is that ``fast`` + * will log a brief error report and ``off`` will not. + */ + + /** + * @deprecated Will be removed in the next major version. + * @description Frees Resources. + * @param {fetchOptions} [options] */ fetch(options = {}) { this.xml += ``; } /** - * @description adds sql free XML + * @deprecated Will be removed in the next major version. + * @description Adds sql free XML. */ free() { this.xml += ''; } /** - * @description returns the current sql XML - * @returns {string} - the generted sql XML + * @deprecated Will be removed in the next major version. + * @returns {string} - The generted sql XML. */ toXML() { return `${this.xml}`; @@ -384,12 +527,24 @@ class iSql { // DEPRECATED: For now, routes call to Connection, but will be removed at a later time. class iConn { /** - * @description Creates a new iConn object + * Deprecated rest transport configuration + * @typedef {object} restConfig + * @property {string} host=localhost - The hostname of the server. Default is 'localhost'. + * @property {string} [ipc=*NA] - The key name/security route to XMLSERVICE job. + * Default is '*NA'. + * @property {string} [ctl=*here] - The control options for XMLSERVICE jobs. Defaults is '*here'. + * @property {number} port=80 - The port on the server. Default is 80. + * @property {string} path=/ - The path to xmlcgi endpoint. Default is '/'. + */ + + /** + * @deprecated Replaced by ``Connection`` and will be removed in the next major version. + * @description Creates a new iConn object. * @constructor - * @param {string} db - * @param {string} user - * @param {string} pwd - * @param {object} [option] + * @param {string} db - The database to connect to. + * @param {string} user - The user to connect as. + * @param {string} pwd - The user's password. + * @param {restConfig} [restConfig] - The rest transport config. */ constructor(db, user, pwd, option) { iConnDeprecate('As of v1.0, class \'iConn\' is deprecated. Please use \'Connection\' instead.'); @@ -417,11 +572,10 @@ class iConn { } /** - * @description - * enables or disables the verbose mode for debugging - * returns the current state of debug flag - * @param {boolean} [flag] - * @returns {boolean} the current state of the debug flag + * @deprecated Replaced by ``Connection.debug()`` and will be removed in the next major version. + * @description Enables or disables the verbose mode for debugging. + * @param {boolean} [flag] - Whether to enable verbose output. + * @returns {boolean} The current state of the debug flag. */ debug(flag) { iConnDeprecate('As of v1.0, \'iConn.debug()\' is deprecated. Please use \'Connection.debug()\' instead'); @@ -430,7 +584,9 @@ class iConn { /** - * @description returns conn property from iConn object. + * @deprecated Replaced by ``Connection.getTransportOptions()`` and will be removed in the + * next major version. + * @description Returns conn property from iConn object. * @returns {object} the conn property from iConn object. */ getConnection() { @@ -439,8 +595,10 @@ class iConn { } /** - * @description adds XML request to command list - * @param {string | object} xml + * @deprecated Replaced by ``Connection.add()`` and will be removed in the next major version. + * @description Adds XML to the command list. When an instance of iPgm or iSql is passed + * ``.toXML()`` is invoked to return the underlying xml. + * @param {string|object} xml - The xml to add to the command list. */ add(xml) { iConnDeprecate('As of v1.0, \'iConn.add()\' is deprecated. Please use \'Connection.add()\' instead'); @@ -448,11 +606,16 @@ class iConn { } /** - * @description - * Invokes transport with XML input from command list - * Calls user provided callback with the XML output - * @param {fuction} callback - * @param {boolean} sync + * @callback runCallbackDeprecated + * @param {string} xmlOutput - the xml output. + */ + + /** + * @deprecated Replaced by ``Connection.run()`` and will be removed in the next major version. + * @description Invokes transport with XML generated from joining the command list. + * Note the command list is cleared after calling this function. + * Once the transport is complete the user provided callback function is called. + * @param {runCallbackDeprecated} callback - The callback function. */ run(callback) { iConnDeprecate('As of v1.0, \'iConn.run()\' is deprecated. Please use \'Connection.run()\' instead'); @@ -462,8 +625,9 @@ class iConn { class iDataQueue { /** + * @deprecated Will be removed in the next major version. * @constructor - * @param {Connection} conn + * @param {Connection} conn - The Connection object. */ constructor(conn = {}) { iDataQueueDeprecate('As of v1.0, class \'iDataQueue\' is deprecated and will be removed at a later time.'); @@ -494,10 +658,19 @@ class iDataQueue { } /** - * @param {string} name - * @param {string} lib - * @param {string} data - * @param {function} cb + * @callback sendToDataQueueCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {boolean|null} output - This is true if successful or null when an error occurs. + */ + + /** + * @description Sends data to the data queue. + * IBM i API: QSNDDTAQ + * @deprecated Will be removed in the next major version. + * @param {string} name - The data queue name. + * @param {string} lib - The library containing the data queue. + * @param {string} data -The data to send to the data queue. + * @param {sendToDataQueueCallback} cb - The callback function. */ sendToDataQueue(name, lib, data, cb) { iDataQueueDeprecate('As of v1.0, \'iDataQueue.sendToDataQueue()\' is deprecated and will be removed at a later time.'); @@ -544,10 +717,20 @@ class iDataQueue { } /** - * @param {string} name - * @param {string} lib - * @param {string} length - * @param {function} cb + * @callback receiveFromDataQueueCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {string|null} output - This is the output from the data queue if successful + * or null when an error occurs. + */ + + /** + * @description Receives data from the data queue. + * IBM i API: QRCVDTAQ + * @deprecated Will be removed in the next major version. + * @param {string} name - The data queue name. + * @param {string} lib - The library containing the data queue. + * @param {string} length - The length of the data to retrieve. + * @param {receiveFromDataQueueCallback} cb - The callback function. */ receiveFromDataQueue(name, lib, length, cb) { iDataQueueDeprecate('As of v1.0, \'iDataQueue.receiveFromDataQueue()\' is deprecated and will be removed at a later time.'); @@ -596,9 +779,18 @@ class iDataQueue { } /** - * @param {string} name - * @param {string} lib - * @param {function} cb + * @callback clearDataQueueCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {boolean|null} output - This is true if successful or null when an error occurs. + */ + + /** + * @description Clears the data queue. + * IBM i API: QCLRDTAQ + * @deprecated Will be removed in the next major version. + * @param {string} name - the data queue name. + * @param {string} lib - The library containing the data queue. + * @param {clearDataQueueCallback} cb - The callback function. */ clearDataQueue(name, lib, cb) { iDataQueueDeprecate('As of v1.0, \'iDataQueue.clearDataQueue()\' is deprecated and will be removed at a later time.'); @@ -646,8 +838,9 @@ class iDataQueue { class iNetwork { /** + * @deprecated Will be removed in the next major version. * @constructor - * @param {Connection} conn + * @param {Connection} conn - The Connection object. */ constructor(conn) { iNetworkDeprecate('As of v1.0, class \'iNetwork\' is deprecated and will be removed at a later time.'); @@ -694,7 +887,52 @@ class iNetwork { } /** - * @param {function} cb + * getTCPIPAttr Output Object + * @typedef {object} getTCPIPAttrOutput + * @property {string} TCP/IPv4_stack_status + * @property {string} How_long_active + * @property {string} When_last_started_-_date + * @property {string} When_last_started_-_time + * @property {string} When_last_ended_-_date + * @property {string} When_last_ended_-_time + * @property {string} Who_last_started_-_job_name + * @property {string} Who_last_started_-_job_user_name + * @property {string} Who_last_started_-_job_number + * @property {string} Who_last_started_-_internal_job_identifier + * @property {string} Who_last_ended_-_job_name + * @property {string} Who_last_ended_-_job_user_name + * @property {string} Who_last_ended_-_job_number + * @property {string} Who_last_ended_-_internal_job_identifier + * @property {string} Offset_to_additional_information + * @property {string} Length_of_additional_information + * @property {string} Limited_mode + * @property {string} Offset_to_list_of_Internet_addresses + * @property {string} Number_of_Internet_addresses + * @property {string} Entry_length_for_list_of_Internet_addresses + * @property {string} DNS_protocol + * @property {string} Retries + * @property {string} Time_interval + * @property {string} Search_order + * @property {string} Initial_domain_name_server + * @property {string} DNS_listening_port + * @property {string} Host_name + * @property {string} Domain_name + * @property {string} Reserved + * @property {string} Domain_search_list + */ + + /** + * @callback getTCPIPAttrCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {getTCPIPAttrOutput|null} output - This is an object if successful + * or null when an error occurs. + */ + + /** + * @description Retrieve TCP/IP Attributes. + * IBM i API: QTOCNETSTS/QtocRtvTCPA + * @deprecated Will be removed in the next major version. + * @param {getTCPIPAttrCallback} cb - The callback function. */ getTCPIPAttr(cb) { iNetworkDeprecate('As of v1.0, \'iNetwork.getTCPIPAttr()\' is deprecated and will be removed at a later time.'); @@ -812,8 +1050,69 @@ class iNetwork { } /** - * @param {string} ipaddr - * @param {function} cb + * getNetInterfaceData Output Object + * @typedef {object} getNetInterfaceDataOutput + * @property {string} Internet_address + * @property {string} Internet_address_binary + * @property {string} Network_address + * @property {string} Network_address_binary + * @property {string} Line_description + * @property {string} Interface_status + * @property {string} Interface_type_of_service + * @property {string} Interface_MTU + * @property {string} Interface_line_type + * @property {string} Host_address + * @property {string} Host_address_binary + * @property {string} Interface_subnet_mask + * @property {string} Interface_subnet_mask_binary + * @property {string} Directed_broadcast_address + * @property {string} Directed_broadcast_address_binary + * @property {string} Change_date + * @property {string} Change_time + * @property {string} Associated_local_interface + * @property {string} Associated_local_interface_binary + * @property {string} Change_status + * @property {string} Packet_rules + * @property {string} Automatic_start + * @property {string} TRLAN_bit_sequencing + * @property {string} Interface_type + * @property {string} Proxy_ARP_allowed + * @property {string} Proxy_ARP_enabled + * @property {string} Configured_MTU + * @property {string} Network_name + * @property {string} Interface_name + * @property {string} Alias_name + * @property {string} Interface_description + * @property {string} Offset_to_preferred_interface_list + * @property {string} Number_of_entries_in_preferred_interface_list + * @property {string} Length_of_one_preferred_interface_list_entry + * @property {string} DHCP_created + * @property {string} DHCP_dynamic_DNS_updates + * @property {string} DHCP_lease_expiration + * @property {string} DHCP_lease_expiration_-_date + * @property {string} DHCP_lease_expiration_-_time + * @property {string} DHCP_lease_obtained + * @property {string} DHCP_lease_obtained_-_date + * @property {string} DHCP_lease_obtained_-_time + * @property {string} Use_DHCP_unique_identifier + * @property {string} DHCP_server_IP_address + * @property {string} Preferred_interface_Internet_address + * @property {string} Preferred_interface_Internet_address_binary + */ + + /** + * @callback getNetInterfaceDataCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {getNetInterfaceDataOutput|null} output - This is an object if successful + * or null when an error occurs. + */ + + /** + * @deprecated Will be removed in the next major version. + * @description Retrieves detailed information about a specified IPv4 network interface. + * IBM i API: QTOCNETSTS/QtocRtvNetIfcDta + * @param {string} ipaddr - The IP address. + * @param {getNetInterfaceDataCallback} cb - The callback function. */ getNetInterfaceData(ipaddr, cb) { iNetworkDeprecate('As of v1.0, \'iNetwork.getNetInterfaceData()\' is deprecated and will be removed at a later time.'); @@ -1001,8 +1300,9 @@ class iNetwork { class iObj { /** + * @deprecated Will be removed in the next major version. * @constructor - * @param {Connection} conn + * @param {Connection} conn - The Connection object. */ constructor(conn) { iObjDeprecate('As of v1.0, class \'iObj\' is deprecated and will be removed at a later time.'); @@ -1049,8 +1349,17 @@ class iObj { } /** - * @param {string} lib - * @param {function} cb + * @callback addToLibraryListCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {boolean|null} output - This is true if successful or null when an error occurs. + */ + + /** + * @description Adds a library to the library list. + * IBM i API: QLICHGLL + * @deprecated Will be removed in the next major version. + * @param {string} lib - The library to add. + * @param {addToLibraryListCallback} cb - The callback function. */ addToLibraryList(lib, cb) { iObjDeprecate('As of v1.0, \'iObj.addToLibraryList()\' is deprecated and will be removed at a later time.'); @@ -1101,11 +1410,58 @@ class iObj { } /** - * @param {string} usr - * @param {string} type - * @param {string} obj - * @param {string} lib - * @param {function} cb + * retrUsrAuth Output Object + * @typedef {object} retrUsrAuthOutput + * @property {string} Object_authority_/_Data_authority + * @property {string} Authorization_list_management + * @property {string} Object_operational + * @property {string} Object_management + * @property {string} Object_existence + * @property {string} Data_read + * @property {string} Data_add + * @property {string} Data_update + * @property {string} Data_delete + * @property {string} Authorization_list + * @property {string} Authority_source + * @property {string} Some_adopted_authority + * @property {string} Adopted_object_authority + * @property {string} Adopted_authorization_list_management + * @property {string} Adopted_object_operational + * @property {string} Adopted_object_management + * @property {string} Adopted_object_existence + * @property {string} Adopted_data_read + * @property {string} Adopted_data_add + * @property {string} Adopted_data_update + * @property {string} Adopted_data_delete + * @property {string} Adopted_data_execute + * @property {string} Reserved + * @property {string} Adopted_object_alter + * @property {string} Adopted_object_reference + * @property {string} Data_execute + * @property {string} Object_alter + * @property {string} Object_reference + * @property {string} ASP_device_name_of_library + * @property {string} ASP_device_name_of_object + * @property {string} Offset_to_group_information_table + * @property {string} Number_of_group_table_entries_returned + */ + + /** + * @callback retrUsrAuthCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {retrUsrAuthOutput|null} output - This is an object if successful or + * null when an error occurs. + */ + + /** + * Retrieves a specific user's authority for an object. + * IBM i API: QSYRUSRA + * @deprecated Will be removed in the next major version. + * @param {string} usr - The name of the user whose object authority is returned. + * @param {string} type - The type of object for which authority information is returned. + * @param {string} obj - The object name. + * @param {string} lib - The library name. + * @param {retrUsrAuthCallback} cb - The callback function. */ retrUsrAuth(usr, type, obj, lib = '*LIBL', cb) { iObjDeprecate('As of v1.0, \'iObj.retrUsrAuth()\' is deprecated and will be removed at a later time.'); @@ -1245,9 +1601,64 @@ class iObj { } /** - * @param {string} cmd - * @param {string} lib - * @param {function} cb + * retrCmdInfo Output Object + * @typedef {object} retrCmdInfoOutput + * @property {string} Command_name + * @property {string} Command_library_name + * @property {string} Command_processing_program_or_proxy_target_command + * @property {string} Command_processing_program's_or_proxy_target_command's_library name + * @property {string} Source_file_name + * @property {string} Source_file_library_name + * @property {string} Source_file_member_name + * @property {string} Validity_check_program_name + * @property {string} Validity_check_program_library_name + * @property {string} Mode_information + * @property {string} Where_allowed_to_run + * @property {string} Allow_limited_user + * @property {string} Maximum_positional_parameters + * @property {string} Prompt_message_file_name + * @property {string} Prompt_message_file_library_name + * @property {string} Message_file_name + * @property {string} Message_file_library_name + * @property {string} Help_panel_group_name + * @property {string} Help_panel_group_library_name + * @property {string} Help_identifier + * @property {string} Search_index_name + * @property {string} Search_index_library_name + * @property {string} Current_library + * @property {string} Product_library + * @property {string} Prompt_override_program_name + * @property {string} Prompt_override_program_library name + * @property {string} Restricted_to_target_release + * @property {string} Text_description + * @property {string} Command_processing_program_call_state + * @property {string} Validity_check_program_call_state + * @property {string} Prompt_override_program_call_state + * @property {string} Offset_to_help_bookshelf_information + * @property {string} Length_of_help_bookshelf_information + * @property {string} Coded_character_set_ID_(CCSID) + * @property {string} Enabled_for_GUI_indicator + * @property {string} Threadsafe_indicator + * @property {string} Multithreaded_job_action + * @property {string} Proxy_command_indicator + * @property {string} Prompt_message_file_text_indicator + * @property {string} Object_authority_/_Data_authority + */ + + /** + * @callback retrCmdInfoCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {retrCmdInfoOutput|null} output - This is an object if successful or + * null when an error occurs. + */ + + /** + * @description Retrieves information from a command definition object. + * IBM i API: QCDRCMDI + * @deprecated Will be removed in the next major version. + * @param {string} cmd - The command name. + * @param {string} lib - The library name. + * @param {retrCmdInfoCallback} cb - The callback function. */ retrCmdInfo(cmd, lib = '*LIBL', cb) { iObjDeprecate('As of v1.0, \'iObj.retrCmdInfo()\' is deprecated and will be removed at a later time.'); @@ -1394,9 +1805,86 @@ class iObj { } /** - * @param {string} _pgm - * @param {string} lib - * @param {function} cb + * retrPgmInfo Output Object + * @typedef {object} retrPgmInfoOutput + * @property {string} Program_name + * @property {string} Program_library_name + * @property {string} Program_owner + * @property {string} Program_attribute + * @property {string} Creation_date_and_time + * @property {string} Source_file_name + * @property {string} Source_file_library_name + * @property {string} Source_file_member_name + * @property {string} Source_file_updated_date_and_time + * @property {string} Observable_information + * @property {string} User_profile_option + * @property {string} Use_adopted_authority + * @property {string} Log_commands + * @property {string} Allow_RTVCLSRC + * @property {string} Fix_decimal_data + * @property {string} Text description + * @property {string} Type_of_program + * @property {string} Teraspace_storage-enabled_program + * @property {string} Reserved + * @property {string} Minimum_number_of_parameters + * @property {string} Maximum_number_of_parameters + * @property {string} Program_size + * @property {string} Associated_space_size + * @property {string} Static_storage_size + * @property {string} Automatic_storage_size + * @property {string} Number_of_MI_instructions + * @property {string} Number_of_MI_ODT_entries + * @property {string} Program_state + * @property {string} Compiler_identification + * @property {string} Earliest_release_program_can_run + * @property {string} Sort_sequence_table_name + * @property {string} Sort_sequence_table_library name + * @property {string} Language_identifier + * @property {string} Program_domain + * @property {string} Conversion_required + * @property {string} Conversion_details + * @property {string} Optimization + * @property {string} Paging_pool + * @property {string} Update_program_automatic_storage_area_(PASA) + * @property {string} Clear_program_automatic_storage_area_(PASA) + * @property {string} Paging_amount + * @property {string} Program_entry_procedure_module + * @property {string} Program_entry_procedure_module_library + * @property {string} Activation_group_attribute + * @property {string} Observable_information_compressed + * @property {string} Run-time_information_compressed + * @property {string} Release_program_created_on + * @property {string} Shared_activation_group + * @property {string} Allow_update + * @property {string} Program_CCSID + * @property {string} Number_of_modules + * @property {string} Number_of_service_programs + * @property {string} Number_of_copyrights + * @property {string} Number_of_unresolved_references + * @property {string} Release_program_created_for + * @property {string} Allow_static_storage_reinitialization + * @property {string} All_creation_data + * @property {string} Allow_bound_*SRVPGM_library_name_update + * @property {string} Profiling_data + * @property {string} Teraspace_storage_enabled_modules + * @property {string} Storage_model + * @property {string} Uses_argument_optimization_(ARGOPT) + */ + + /** + * @callback retrPgmInfoCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {retrPgmInfoOutput|null} output - This is an object if successful or + * null when an error occurs. + */ + + /** + * @description Retrieves information from a program object. + * IBM i API: QCLRPGMI + * @deprecated Will be removed in the next major version. + * @param {string} _pgm - The program name. + * @param {string} lib - The library name. + * @param {retrPgmInfoCallback} cb - The callback function. */ retrPgmInfo(_pgm, lib = '*LIBL', cb) { iObjDeprecate('As of v1.0, \'iObj.retrPgmInfo()\' is deprecated and will be removed at a later time.'); @@ -1591,9 +2079,67 @@ class iObj { } /** - * @param {string} srvpgm - * @param {string} lib - * @param {function} cb + * retrSrvPgmInfo Output Object + * @typedef {object} retrSrvPgmInfoOutput + * @property {string} Service_program_name + * @property {string} Service_program_library_name + * @property {string} Service_program_owner + * @property {string} Service_program_attribute + * @property {string} Creation_date_and_time + * @property {string} Export_source_file_name + * @property {string} Export_source_file_library_name + * @property {string} Export_source_file_member_name + * @property {string} Activation_group_attribute + * @property {string} Current_export_signature + * @property {string} User_profile + * @property {string} Observable_information_compressed + * @property {string} Run-time_information_compressed + * @property {string} Service_program_CCSID + * @property {string} Number_of_modules + * @property {string} Number_of_service_programs + * @property {string} Number_of_copyrights + * @property {string} Text_description + * @property {string} Shared_activation_group + * @property {string} Allow_update + * @property {string} Number_of_unresolved_references + * @property {string} Use_adopted_authority + * @property {string} Allow_bound_*SRVPGM_library_name_update + * @property {string} Profiling_data + * @property {string} Teraspace_storage_enabled_modules + * @property {string} Storage_model + * @property {string} Uses_argument_optimization_(ARGOPT) + * @property {string} Reserved_'00'X + * @property {string} Service_program_state + * @property {string} Service program_domain + * @property {string} Associated_space_size + * @property {string} Static_storage_size + * @property {string} Service_program_size + * @property {string} Release_service_program_created_on + * @property {string} Earliest_release_service_program_can_run + * @property {string} Release_service_program_created_for + * @property {string} Allow_static_storage_reinitialization + * @property {string} Conversion_required + * @property {string} All_creation_data + * @property {string} Conversion_details + * @property {string} Reserved + * @property {string} Paging_pool + * @property {string} Paging_amount + */ + + /** + * @callback retrSrvPgmInfoCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {retrSrvPgmInfoOutput|null} output - This is an object if successful or + * null when an error occurs. + */ + + /** + * Retrieves information from a service program object. + * IBM i API: QBNRSPGM + * @deprecated Will be removed in the next major version. + * @param {string} srvpgm - The service program name. + * @param {string} lib - The library name. + * @param {retrSrvPgmInfoCallback} cb - THe callback function. */ retrSrvPgmInfo(srvpgm, lib = '*LIB', cb) { iObjDeprecate('As of v1.0, \'iObj.retrSrvPgmInfo()\' is deprecated and will be removed at a later time.'); @@ -1746,8 +2292,37 @@ class iObj { } /** - * @param {string} user - * @param {function} cb + * retrUserInfo Output Object + * @typedef {object} retrUserInfoOutput + * @property {string} User_profile_name + * @property {string} Previous_sign-on_date_and_time + * @property {string} Sign-on_attempts_not_valid + * @property {string} Status + * @property {string} Password_change_date + * @property {string} No_password_indicator + * @property {string} Reserved + * @property {string} Password_expiration_interval + * @property {string} Date_password_expires + * @property {string} Days_until_password_expires + * @property {string} Set_password_to_expire + * @property {string} Display_sign-on_information + * @property {string} Local_password_management + * @property {string} Block_password_change + */ + + /** + * @callback retrUserInfoCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {retrUserInfoOutput|null} output - This is an object if successful or + * null when an error occurs. + */ + + /** + * Retrieves information about a user profile. + * IBM i API: QSYRUSRI + * @deprecated Will be removed in the next major version. + * @param {string} user - The user profile. + * @param {retrUserInfoCallback} cb - The callback function. */ retrUserInfo(user, cb) { iObjDeprecate('As of v1.0, \'iObj.retrUserInfo()\' is deprecated and will be removed at a later time.'); @@ -1836,8 +2411,38 @@ class iObj { } /** - * @param {string} path - * @param {function} cb + * retrUserAuthToObj Output Object + * @typedef {object} retrUserAuthToObjOutput + * @property {string} Profile_name + * @property {string} User_or_group indicator + * @property {string} Data_authority + * @property {string} Authorization_list_management + * @property {string} Object_management + * @property {string} Object_existence + * @property {string} Object_alter + * @property {string} Object_reference + * @property {string} Reserved + * @property {string} Object_operational + * @property {string} Data_read + * @property {string} Data_add + * @property {string} Data_update + * @property {string} Data_delete + * @property {string} Data_execute + */ + + /** + * @callback retrUserAuthToObjCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {retrUserAuthToObjOutput|null} output - This is an object if successful or + * null when an error occurs. + */ + + /** + * Retrieves information about the users who are authorized to an object. + * IBM i API: QSYRTVUA + * @deprecated Will be removed in the next major version. + * @param {string} path - The absolute path to the object. + * @param {retrUserAuthToObjCallback} cb - The callback function. */ retrUserAuthToObj(path, cb) { iObjDeprecate('As of v1.0, \'iObj.retrUserAuthToObj()\' is deprecated and will be removed at a later time.'); @@ -1948,8 +2553,9 @@ class iObj { class iProd { /** + * @deprecated Will be removed in the next major version. * @constructor - * @param {Connection} conn + * @param {Connection} conn - The Connection object. */ constructor(conn) { iProdDeprecate('As of v1.0, class \'iProd\' is deprecated and will be removed at a later time.'); @@ -1997,8 +2603,53 @@ class iProd { } /** - * @param {string} PTFID - * @param {function} cb + * getPTFInfo Output Object + * @typedef {object} getPTFInfoOutput + * @property {string} Product_ID + * @property {string} PTF_ID + * @property {string} Release_level + * @property {string} Product_option + * @property {string} Load_ID + * @property {string} Loaded_status + * @property {string} Cover_letter_status + * @property {string} On-order_status + * @property {string} Save_file_status + * @property {string} File_name + * @property {string} File_library_name + * @property {string} PTF_type + * @property {string} IPL_action + * @property {string} Action_pending + * @property {string} Action_required + * @property {string} PTF_is_released + * @property {string} Target_release + * @property {string} Superseding_PTF + * @property {string} Current_IPL_source + * @property {string} Minimum_level + * @property {string} Maximum_level + * @property {string} Format_information_available + * @property {string} Status_date_and_time + * @property {string} Licensed_Internal_Code_group + * @property {string} Superseded_by_PTF_ID + * @property {string} Current_server_IPL_source + * @property {string} Server_IPL_required + * @property {string} Creation_date_and_time + * @property {string} Technology_refresh_PTF + * @property {string} Reserved + */ + + /** + * @callback getPTFInfoCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {getPTFInfoOutput|null} output - This is an object if successful or + * null when an error occurs. + */ + + /** + * @description Retrieve the load status of specified PTF. + * IBM i API: QPZRTVFX + * @deprecated Will be removed in the next major version. + * @param {string} PTFID - The PTF number to be queried + * @param {getPTFInfoCallback} cb - The callback function. */ getPTFInfo(PTFID, cb) { iProdDeprecate('As of v1.0, \'iProd.getPTFInfo()\' is deprecated and will be removed at a later time'); @@ -2132,9 +2783,42 @@ class iProd { } /** - * @param {string} prodID - * @param {number} [option] - * @param {function} cb + * getProductInfo Output Object + * @typedef {object} getProductInfoOutput + * @property {string} Product_ID + * @property {string} Release_level + * @property {string} Product_option + * @property {string} Load_ID + * @property {string} Loaded_type + * @property {string} Symbolic_load_state + * @property {string} Load_error_indicator + * @property {string} Load_state + * @property {string} Supported_flag + * @property {string} Registration_type + * @property {string} Registration_value + * @property {string} Offset_to_additional_information + * @property {string} Primary_language_load_identifier + * @property {string} Minimum_target_release + * @property {string} Minimum_VRM_of_*BASE_required_by_option + * @property {string} Requirements_met_between_base_and_option_value + * @property {string} Level + * @property {string} Reserved + */ + + /** + * @callback getProductInfoCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {getProductInfoOutput|null} output - This is an object if successful or + * null when an error occurs. + */ + + /** + * @description Retrieve the status of the specified product. + * IBM i API: QSZRTVPR + * @deprecated Will be removed in the next major version. + * @param {string} prodID - The product id. + * @param {number} [option] - The product option. + * @param {getProductInfoCallback} cb - The callback function. */ getProductInfo(prodID, option, cb) { iProdDeprecate('As of v1.0, \'iProd.getProductInfo()\' is deprecated and will be removed at a later time'); @@ -2267,7 +2951,33 @@ class iProd { } /** - * @param {function} cb + * getInstalledProducts Output Object + * @typedef {object} getInstalledProductsOutput + * @property {string} Product_ID + * @property {string} Product_option + * @property {string} Release_level + * @property {string} Description_text_message_ID + * @property {string} Description_text_object_name + * @property {string} Description_text_library_name + * @property {string} Installed_flag + * @property {string} Supported_flag + * @property {string} Registration_type + * @property {string} Registration_value + * @property {string} Description_text + */ + + /** + * @callback getInstalledProductsCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {getInstalledProductsOutput|null} output - This is an object if successful or + * null when an error occurs. + */ + + /** + * @description Retrieve the list of all installed products. + * IBM i API: QSZSLTPR + * @deprecated Will be removed in the next major version. + * @param {getInstalledProductsCallback} cb - the callback function */ getInstalledProducts(cb) { iProdDeprecate('As of v1.0, \'iProd.getInstalledProducts()\' is deprecated and will be removed at a later time'); @@ -2384,8 +3094,9 @@ class iProd { class iUserSpace { /** + * @deprecated Will be removed in the next major version. * @constructor - * @param {Connection} conn + * @param {Connection} conn - The Connection object. */ constructor(conn) { iUserSpaceDeprecate('As of v1.0, class \'iUserSpace\' is deprecated and will be removed at a later time.'); @@ -2429,13 +3140,22 @@ class iUserSpace { } /** - * @param {string} name - * @param {string} lib - * @param {string} attr - * @param {number} size - * @param {string} auth - * @param {string} desc - * @param {function} cb + * @callback createUserSpaceCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {boolean|null} output - This is true if successful or null when an error occurs. + */ + + /** + * @deprecated Will be removed in the next major version. + * @description Create a new user space. + * IBM i API: QUSCRTUS + * @param {string} name - The user space name. (10 characters max). + * @param {string} lib - The library name. + * @param {string} attr - The extended attribute of the user space (11 characters max). + * @param {number} size - The initial size of the user space. + * @param {string} auth - The authority to the user space. + * @param {string} desc - The description of the user space (50 characters max). + * @param {createUserSpaceCallback} cb */ createUserSpace(name, lib, attr, size, auth, desc, cb) { iUserSpaceDeprecate('As of v1.0, \'iUserSpace.createUserSpace()\' is deprecated and will be removed at a later time.'); @@ -2495,11 +3215,20 @@ class iUserSpace { } /** - * @param {string} name - * @param {string} lib - * @param {string} length - * @param {string} msg - * @param {function} cb + * @callback setUserSpaceDataCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {boolean|null} output - This is true if successful or null when an error occurs. + */ + + /** + * @deprecated Will be removed in the next major version. + * @description Set the content of the user space. + * IBM i API: QUSCHGUS + * @param {string} name - The user space name. + * @param {string} lib - The library name. + * @param {string} length -Tthe length of the data to set. + * @param {string} msg - The data to set. + * @param {setUserSpaceDataCallback} cb - The callback function. */ setUserSpaceData(name, lib, length, msg, cb) { iUserSpaceDeprecate('As of v1.0, \'iUserSpace.setUserSpaceData()\' is deprecated and will be removed at a later time.'); @@ -2557,10 +3286,20 @@ class iUserSpace { } /** - * @param {string} name - * @param {string} lib - * @param {string} length - * @param {function} cb + * @callback getUserSpaceDataCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {string|null} output - This is the output from the user space if successful + * or null when an error occurs. + */ + + /** + * @deprecated Will be removed in the next major version. + * @description Retrieves the content of the user space. + * IBM i API: QUSRTVUS + * @param {string} name - The user space name. + * @param {string} lib - The library name. + * @param {string} length - The length of the data to retrieve. + * @param {getUserSpaceDataCallback} cb - The callback function. */ getUserSpaceData(name, lib, length, cb) { iUserSpaceDeprecate('As of v1.0, \'iUserSpace.getUserSpaceData()\' is deprecated ad will be removed at a later time.'); @@ -2618,9 +3357,18 @@ class iUserSpace { } /** - * @param {string} name - * @param {string} lib - * @param {function} cb + * @callback deleteUserSpaceCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {boolean|null} output - This is true if successful or null when an error occurs. + */ + + /** + * @deprecated Will be removed in the next major version. + * @description Delete the user space. + * IBM i API: QUSDLTUS + * @param {string} name - The user space name. + * @param {string} lib - The library name. + * @param {deleteUserSpaceCallback} cb - The callback function. */ deleteUserSpace(name, lib, cb) { iUserSpaceDeprecate('As of v1.0, \'iUserSpace.deleteUserSpace()\' is deprecated and will be removed at a later time'); @@ -2675,8 +3423,9 @@ class iUserSpace { class iWork { /** + * @deprecated Will be removed in the next major version. * @constructor - * @param {Connection} conn + * @param {Connection} conn - The Connection object. */ constructor(conn) { iWorkDeprecate('As of v1.0, class \'iWork\' is deprecated and will be removed at a later time.'); @@ -2720,8 +3469,18 @@ class iWork { } /** - * @param {string} sysValue - * @param {function} cb + * @callback getSysValueCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {string|null} output - This is the system value if successful + * or null when an error occurs. + */ + + /** + * @deprecated Will be removed in the next major version. + * @description Retrieves the specified system value. + * IBM i API: QWCRSVAL + * @param {string} sysValue - The system value. + * @param {getSysValueCallback} cb - The callback function. */ getSysValue(sysValue, cb) { iWorkDeprecate('As of v1.0, \'iWork.getSysValue()\' is deprecated and will be removed at a later time.'); @@ -2835,7 +3594,38 @@ class iWork { } /** - * @param {function} cb + * getSysStatus Output Object + * @typedef {object} getSysStatusOutput + * @property {string} Current_date_and_time + * @property {string} System_name + * @property {string} Users_currently_signed_on + * @property {string} Users_temporarily_signed_off_(disconnected) + * @property {string} Users_suspended_by_system_request + * @property {string} Users_suspended_by_group_jobs + * @property {string} Users_signed_off_with_printer_output_waiting_to_print + * @property {string} Batch_jobs_waiting_for_messages + * @property {string} Batch_jobs_running + * @property {string} Batch_jobs_held_while_running + * @property {string} Batch_jobs_ending + * @property {string} Batch_jobs_waiting_to_run_or_already_scheduled + * @property {string} Batch_jobs_held_on_a_job_queue + * @property {string} Batch_jobs_on_a_held_job_queue + * @property {string} Batch_jobs_on_an_unassigned_job_queue + * @property {string} Batch_jobs_ended_with_printer_output_waiting_to_print + */ + + /** + * @callback getSysStatusCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {getSysStatusOutput|null} output - This is an object if successful or + * null when an error occurs. + */ + + /** + * @deprecated Will be removed in the next major version. + * @description Retrieves basic system status. + * IBM i API: QWCRSSTS + * @param {getSysStatusCallback} cb - The callback function. */ getSysStatus(cb) { iWorkDeprecate('As of v1.0, \'iWork.getSysStatus()\' is deprecated and will be removed at a later time.'); @@ -2926,7 +3716,53 @@ class iWork { } /** - * @param {function} cb + * getSysStatusExt Output Object + * @typedef {object} getSysStatusExtOutput + * @property {string} Current_date_and_time + * @property {string} System_name + * @property {string} Elapsed_time + * @property {string} Restricted_state_flag + * @property {string} %_processing_unit_used + * @property {string} Jobs_in_system + * @property {string} %_permanent_addresses + * @property {string} %_temporary_addresses + * @property {string} System_ASP + * @property {string} %_system_ASP_used + * @property {string} Total_auxiliary_storage + * @property {string} Current_unprotected_storage_used + * @property {string} Maximum_unprotected_storage_used + * @property {string} %_DB_capability + * @property {string} Main_storage_size + * @property {string} Number_of_partitions + * @property {string} Partition_identifier + * @property {string} Current_processing_capacity + * @property {string} Processor_sharing_attribute + * @property {string} Number_of_processors + * @property {string} Active_jobs_in_system + * @property {string} Active_threads_in_system + * @property {string} Maximum_jobs_in_system + * @property {string} %_temporary_256MB_segments_used + * @property {string} %_temporary_4GB_segments_used + * @property {string} %_permanent_256MB_segments_used + * @property {string} %_permanent_4GB_segments_used + * @property {string} %_current_interactive_performance + * @property {string} %_uncapped_CPU_capacity_used + * @property {string} %_shared_processor_pool_used + * @property {string} Main_storage_size_(long) + */ + + /** + * @callback getSysStatusExtCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {getSysStatusExtOutput|null} output - This is an object if successful or + * null when an error occurs. + */ + + /** + * @deprecated Will be removed in the next major version. + * @description Retrieves detailed system status. + * IBM i API: QWCRSSTS + * @param {getSysStatusExtCallback} cb - The callback function. */ getSysStatusExt(cb) { iWorkDeprecate('As of v1.0, \'iWork.getSysStatusExt()\' is deprecated and will be removed at a later time.'); @@ -3051,8 +3887,25 @@ class iWork { } /** - * @param {string} jobId - * @param {function} cb + * getJobStatus Output Object + * @typedef {object} getJobStatusOutput + * @property {string} Job_status + * @property {string} Fully_qualified_job_name + */ + + /** + * @callback getJobStatusCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {getJobStatusOutput|null} output - This is an object if successful or + * null when an error occurs. + */ + + /** + * @deprecated Will be removed in the next major version. + * @description Retrieves the status of the specified job. + * IBM i API: QWCRJBST + * @param {string} jobId - The job id. + * @param {getJobStatusCallback} cb - The callback function. */ getJobStatus(jobId, cb) { iWorkDeprecate('As of v1.0, \'iWork.getJobStatus()\' is deprecated and will be removed at a later time.'); @@ -3118,10 +3971,60 @@ class iWork { } /** - * @param {string} jobName - * @param {string} userName - * @param {string} jobNumber - * @param {function} cb + * getJobInfo Output Object + * @typedef {object} getJobInfoOutput + * @property {string} Job_name + * @property {string} User_name + * @property {string} Job_number + * @property {string} Job_status + * @property {string} Job_type + * @property {string} Job_subtype + * @property {string} Subsystem_description_name + * @property {string} Run_priority_(job) + * @property {string} System_pool_identifier + * @property {string} Processing_unit_time_used,_if_less_than_2,147,483,647_milliseconds + * @property {string} Number_of_auxiliary_I/O_requests,_if_less_than_2,147,483,647 + * @property {string} Number_of_interactive_transactions + * @property {string} Response_time_total + * @property {string} Function_type + * @property {string} Function_name + * @property {string} Active_job_status + * @property {string} Number_of_database_lock_waits + * @property {string} Number_of_internal_machine_lock_waits + * @property {string} Number_of_nondatabase_lock_waits + * @property {string} Time_spent_on_database_lock_waits + * @property {string} Time_spent_on_internal_machine_lock_waits + * @property {string} Time_spent_on_nondatabase_lock_waits + * @property {string} Current_system_pool_identifier + * @property {string} Thread_count + * @property {string} Processing_unit_time_used_-_total_for_the_job + * @property {string} Number_of_auxiliary_I/O_requests + * @property {string} Processing_unit_time_used_for_database_-_total_for_the_job + * @property {string} Page_faults + * @property {string} Active_job_status_for_jobs_ending + * @property {string} Memory_pool_name + * @property {string} Message_reply + * @property {string} Message_key,_when_active_job_waiting_for_a_message + * @property {string} Message_queue_name,_when_active_job_waiting_for_a_message + * @property {string} Message_queue_library_name,_when_active_job_waiting_for_a_message + * @property {string} Message_queue_library_ASP_device_name,_when_active_job_waiting_for_a_message + */ + + /** + * @callback getJobInfoCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {getJobInfoOutput|null} output - This is an object if successful or + * null when an error occurs. + */ + + /** + * @deprecated Will be removed in the next major version. + * @description Retrieves info about the specified job. + * IBM i API: QUSRJOBI + * @param {string} jobName - The job name. + * @param {string} userName - The username. + * @param {string} jobNumber - The job number. + * @param {getJobInfoCallback} cb - The callback function. */ getJobInfo(jobName, userName, jobNumber, cb) { iWorkDeprecate('As of v1.0, \'iWork.getJobInfo()\' is deprecated and will be removed at a later time.'); @@ -3263,10 +4166,30 @@ class iWork { } /** - * @param {string} lib - * @param {string} area - * @param {string} length - * @param {function} cb + * getDataArea Output Object + * @typedef {object} getDataAreaOutput + * @property {string} Type_of_value_returned + * @property {string} Library_name + * @property {string} Length_of_value_returned + * @property {string} Number_of_decimal_positions + * @property {string} Value + */ + + /** + * @callback getDataAreaCallback + * @param {Error|null} error - the error object if an error occured or null. + * @param {getDataAreaOutput|null} output - This is an object if successful or + * null when an error occurs. + */ + + /** + * @deprecated Will be removed in the next major version. + * @description Retrieves the contents of a data area. + * IBM i API: QWCRDTAA + * @param {string} lib - The library name. + * @param {string} area - The data area name. + * @param {string} length - The length of the data to retrieve. + * @param {getDataAreaCallback} cb - The callback function. */ getDataArea(lib, area, length, cb) { iWorkDeprecate('As of v1.0, \'iWork.getDataArea()\' is deprecated and will be removed at a later time.'); @@ -3345,42 +4268,98 @@ class iWork { // DEPRECATED FUNCTIONS BELOW. WILL BE REMOVED SOMETIME AFTER v1.0 /** - * @description creates cmd XML - * @param {string} cmd - * @param {object} [options] - * @returns {string} - the generated XML for the CL command + * CL Command Options + * @typedef {object} clOptionsDeprecated + * @property {string} [exec=cmd] - How to run the command. + * Valid options: 'cmd', 'system', or 'rexx'. Default is 'cmd'. + * @property {string} [error=fast] - Determines action when an error is encountered. + * Valid options are ``on``, ``off``, or ``fast``. Default is ``fast``. Using ``on`` + * will cause the script execution to stop and log a full error report. + * Using ``off`` or ``fast`` continues executing the script. The Difference is that ``fast`` + * will log a brief error report and ``off`` will not. + * @property {string} [hex=off] - Whether to output data in hex format. + * Valid options are 'on' or 'off'. Default is 'off'. + * @property {string} [before] - The CCSID to convert to before command call. + * @property {string} [after] - The CCSID to convert to after command call. */ -const iCmd = (cmd, options) => { + +/** + * @deprecated Replaced by ``CommandCall`` and will be removed in the next major version. + * @description Generates a CL command. + * @param {string} cmd - The command to string run. + * @param {clOptionsDeprecated} [options] - The command options. + * @returns {string} The generated XML for the CL command. + */ +function iCmd(cmd, options) { iCmdDeprecate('As of v1.0, class \'iCmd()\' is deprecated. Please use \'CommandCall\' instead.'); const command = new CommandCall({ command: cmd, type: 'cl', options }); return command.toXML(); -}; +} + +/** + * QSH Command Options + * @typedef {object} qshOptionsDeprecated + * @property {string} [rows] - Whether to split the output row by row. + * Valid options are 'on' or 'off'. Default is 'off'. + * @property {string} [error=fast] - Determines action when an error is encountered. + * Valid options are ``on``, ``off``, or ``fast``. Default is ``fast``. Using ``on`` + * will cause the script execution to stop and log a full error report. + * Using ``off`` or ``fast`` continues executing the script. The Difference is that ``fast`` + * will log a brief error report and ``off`` will not. + * @property {string} [hex=off] - Whether to output data in hex format. + * Valid options are 'on' or 'off'. Default is 'off'. + * @property {string} [before] - The CCSID to convert to before command call. + * @property {string} [after] - The CCSID to convert to after command call. + */ /** - * @description creates qsh XML - * @param {string} qsh - * @param {object} [options] - * @returns {string} - the generated XML for the qsh command + * @deprecated Replaced by ``CommandCall`` and will be removed in the next major version. + * @description Generates a qsh command. + * @param {string} qsh - The command to string run. + * @param {qshOptionsDeprecated} [options] - The command options. + * @returns {string} The generated command. */ -const iQsh = (qsh, options) => { +function iQsh(qsh, options) { iQshDeprecate('As of v1.0, class \'iQsh()\' is deprecated. Please use \'CommandCall\' instead.'); const command = new CommandCall({ command: qsh, type: 'qsh', options }); return command.toXML(); -}; +} + +/** + * SH Command Options + * @typedef {object} shOptionsDeprecated + * @property {string} [rows] - Whether to split the output row by row. + * Valid options are `on` or `off`. Default is `off`. + * @property {string} [error=fast] - Determines action when an error is encountered. + * Valid options are ``on``, ``off``, or ``fast``. Default is ``fast``. Using ``on`` + * will cause the script execution to stop and log a full error report. + * Using ``off`` or ``fast`` continues executing the script. The Difference is that ``fast`` + * will log a brief error report and ``off`` will not. + * @property {string} [hex=off] - Whether to output data in hex format. + * Valid options are 'on' or 'off'. Default is 'off'. + * @property {string} [before] - The CCSID to convert to before command call. + * @property {string} [after] - The CCSID to convert to after command call. + */ /** - * @description creates sh XML - * @param {string} sh - * @param {object} [options] - * @returns {string} - the generated XML for the sh command + * @deprecated Replaced by ``CommandCall`` and will be removed in the next major version. + * @description Generates a PASE shell command. + * @param {string} sh - The command to string run. + * @param {shOptionsDeprecated} [options] - The command options. + * @returns {string} The generated command. */ -const iSh = (sh, options) => { +function iSh(sh, options) { iShDeprecate('As of v1.0, class \'iSh()\' is deprecated. Please use \'CommandCall\' instead.'); const command = new CommandCall({ command: sh, type: 'sh', options }); return command.toXML(); -}; +} -const xmlToJson = (xml) => { +/** + * @deprecated Will be removed in the next major version. + * @param {string} xml - The XMLSERVICE output. + * @returns {object[]} - The array of result objects. + */ +function xmlToJson(xml) { xmlToJsonDeprecate('As of v1.0, \'xmlToJson\' is deprecated. Use xml2js npm package instead.'); const cmdRegG = /[\s\S]+?<\/cmd>/g; @@ -3582,7 +4561,7 @@ const xmlToJson = (xml) => { }); } return ResultArr; -}; +} module.exports.iPgm = iPgm; module.exports.iSql = iSql; From 6126b67c83ea40840b834fa4ede70d18ece25916 Mon Sep 17 00:00:00 2001 From: Abdirahim Musse <33973272+abmusse@users.noreply.github.com> Date: Mon, 6 Apr 2020 16:24:19 -0500 Subject: [PATCH 2/6] fixup! docs: Update jsdoc for Deprecated.js --- lib/Deprecated.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/Deprecated.js b/lib/Deprecated.js index 3847a8f2..f54fa5c3 100644 --- a/lib/Deprecated.js +++ b/lib/Deprecated.js @@ -4329,7 +4329,7 @@ function iQsh(qsh, options) { * SH Command Options * @typedef {object} shOptionsDeprecated * @property {string} [rows] - Whether to split the output row by row. - * Valid options are `on` or `off`. Default is `off`. + * Valid options are ``on`` or ``off``. Default is ``off``. * @property {string} [error=fast] - Determines action when an error is encountered. * Valid options are ``on``, ``off``, or ``fast``. Default is ``fast``. Using ``on`` * will cause the script execution to stop and log a full error report. From 20465fc89046c3170ccd894e8b3986958cb02713 Mon Sep 17 00:00:00 2001 From: Abdirahim Musse <33973272+abmusse@users.noreply.github.com> Date: Mon, 6 Apr 2020 16:30:46 -0500 Subject: [PATCH 3/6] fixup! fixup! docs: Update jsdoc for Deprecated.js --- lib/Deprecated.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/Deprecated.js b/lib/Deprecated.js index f54fa5c3..18a2db94 100644 --- a/lib/Deprecated.js +++ b/lib/Deprecated.js @@ -4307,7 +4307,7 @@ function iCmd(cmd, options) { * Using ``off`` or ``fast`` continues executing the script. The Difference is that ``fast`` * will log a brief error report and ``off`` will not. * @property {string} [hex=off] - Whether to output data in hex format. - * Valid options are 'on' or 'off'. Default is 'off'. + * Valid options are ``on`` or 'off'. Default is ``off``. * @property {string} [before] - The CCSID to convert to before command call. * @property {string} [after] - The CCSID to convert to after command call. */ @@ -4336,7 +4336,7 @@ function iQsh(qsh, options) { * Using ``off`` or ``fast`` continues executing the script. The Difference is that ``fast`` * will log a brief error report and ``off`` will not. * @property {string} [hex=off] - Whether to output data in hex format. - * Valid options are 'on' or 'off'. Default is 'off'. + * Valid options are ``on`` or ``off``. Default is ``off``. * @property {string} [before] - The CCSID to convert to before command call. * @property {string} [after] - The CCSID to convert to after command call. */ From a3098469ecac9097dc70b34c749ad562a1918310 Mon Sep 17 00:00:00 2001 From: Abdirahim Musse <33973272+abmusse@users.noreply.github.com> Date: Wed, 8 Apr 2020 11:08:48 -0500 Subject: [PATCH 4/6] fixup! fixup! fixup! docs: Update jsdoc for Deprecated.js --- lib/Deprecated.js | 9 --------- 1 file changed, 9 deletions(-) diff --git a/lib/Deprecated.js b/lib/Deprecated.js index 18a2db94..3f639116 100644 --- a/lib/Deprecated.js +++ b/lib/Deprecated.js @@ -917,7 +917,6 @@ class iNetwork { * @property {string} DNS_listening_port * @property {string} Host_name * @property {string} Domain_name - * @property {string} Reserved * @property {string} Domain_search_list */ @@ -1434,7 +1433,6 @@ class iObj { * @property {string} Adopted_data_update * @property {string} Adopted_data_delete * @property {string} Adopted_data_execute - * @property {string} Reserved * @property {string} Adopted_object_alter * @property {string} Adopted_object_reference * @property {string} Data_execute @@ -1825,7 +1823,6 @@ class iObj { * @property {string} Text description * @property {string} Type_of_program * @property {string} Teraspace_storage-enabled_program - * @property {string} Reserved * @property {string} Minimum_number_of_parameters * @property {string} Maximum_number_of_parameters * @property {string} Program_size @@ -2108,7 +2105,6 @@ class iObj { * @property {string} Teraspace_storage_enabled_modules * @property {string} Storage_model * @property {string} Uses_argument_optimization_(ARGOPT) - * @property {string} Reserved_'00'X * @property {string} Service_program_state * @property {string} Service program_domain * @property {string} Associated_space_size @@ -2121,7 +2117,6 @@ class iObj { * @property {string} Conversion_required * @property {string} All_creation_data * @property {string} Conversion_details - * @property {string} Reserved * @property {string} Paging_pool * @property {string} Paging_amount */ @@ -2300,7 +2295,6 @@ class iObj { * @property {string} Status * @property {string} Password_change_date * @property {string} No_password_indicator - * @property {string} Reserved * @property {string} Password_expiration_interval * @property {string} Date_password_expires * @property {string} Days_until_password_expires @@ -2421,7 +2415,6 @@ class iObj { * @property {string} Object_existence * @property {string} Object_alter * @property {string} Object_reference - * @property {string} Reserved * @property {string} Object_operational * @property {string} Data_read * @property {string} Data_add @@ -2634,7 +2627,6 @@ class iProd { * @property {string} Server_IPL_required * @property {string} Creation_date_and_time * @property {string} Technology_refresh_PTF - * @property {string} Reserved */ /** @@ -2802,7 +2794,6 @@ class iProd { * @property {string} Minimum_VRM_of_*BASE_required_by_option * @property {string} Requirements_met_between_base_and_option_value * @property {string} Level - * @property {string} Reserved */ /** From 934faf31ab18343e80e2d12ecc65359e6ffa7024 Mon Sep 17 00:00:00 2001 From: Kevin Adler Date: Fri, 17 Apr 2020 12:07:44 -0500 Subject: [PATCH 5/6] Update lib/Deprecated.js --- lib/Deprecated.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/Deprecated.js b/lib/Deprecated.js index 3f639116..a9d4ceef 100644 --- a/lib/Deprecated.js +++ b/lib/Deprecated.js @@ -241,7 +241,7 @@ class iSql { /** * @deprecated Will be removed in the next major version. - * @description Retrieves table privledge metadata. + * @description Retrieves table priviledge metadata. * @param {string[]} params - * The first element is the qualifer or catalog for the table. This may be an empty string. * The second element is the schema name for the table. From d1e0c8cf8db610151156625bad76ac2f880302ff Mon Sep 17 00:00:00 2001 From: Kevin Adler Date: Fri, 17 Apr 2020 12:07:51 -0500 Subject: [PATCH 6/6] Update lib/Deprecated.js --- lib/Deprecated.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/Deprecated.js b/lib/Deprecated.js index a9d4ceef..001d63f1 100644 --- a/lib/Deprecated.js +++ b/lib/Deprecated.js @@ -428,7 +428,7 @@ class iSql { /** * @deprecated Will be removed in the next major version. - * @description Commits or rollsback a transaction. + * @description Commits or rolls back a transaction. * @param {commitOptions} [options] */ commit(options = {}) {