API Reference¶
Toolkit Object¶
-
class
itoolkit.
iToolKit
(iparm=0, iret=0, ids=1, irow=1)¶ Main iToolKit XMLSERVICE collector and output parser.
Parameters: - iparm (num) – include xml node parm output (0-no, 1-yes).
- iret (num) – include xml node return output (0-no, 1-yes).
- ids (num) – include xml node ds output (0-no, 1-yes).
- irow (num) – include xml node row output (0-no, 1-yes).
Returns: iToolKit (obj)
-
add
(obj)¶ Add additional child object.
Parameters: none – Returns: none Notes
<?xml version=’1.0’?> <xmlservice>
-
call
(itrans)¶ Call xmlservice with accumulated input XML.
Parameters: itrans (obj) – XMLSERVICE transport object Returns: none Raises: TransportClosedException
– If the transport has been closed.
-
clear
()¶ Clear collecting child objects.
Parameters: none – Returns: (void) Notes
<?xml version=’1.0’?> <xmlservice>
-
dict_out
(ikey=0)¶ return dict output.
Parameters: ikey (str) – select ‘key’ from {‘key’:’value’}. Returns: ‘value’} Return type: dict {‘key’
-
hybrid_out
(ikey=0)¶ return hybrid output.
Parameters: ikey (str) – select ‘key’ from {‘key’:’value’}. Returns: {‘data’:[list]}} Return type: hybrid {key
-
list_out
(ikey=-1)¶ return list output.
Parameters: ikey (num) – select list from index [[0],[1],,,,]. Returns: list [value]
-
trace_close
()¶ End trace (1.2+)
Parameters: none – Returns: (void)
-
trace_hexdump
(itext)¶ Write trace hexdump (1.2+) :param itext: trace text :type itext: str
Returns: (void)
-
trace_open
(iname='*terminal')¶ Open trace *terminal or file /tmp/python_toolkit_(iname).log (1.2+)
Parameters: iname (str) – trace *terminal or file /tmp/python_toolkit_(iname).log Returns: (void)
-
trace_write
(itext)¶ Write trace text (1.2+)
Parameters: itext (str) – trace text Returns: (void)
-
xml_in
()¶ return raw xml input.
Parameters: none – Returns: xml
-
xml_out
()¶ return raw xml output.
Parameters: none – Returns: xml
Toolkit Operations¶
-
class
itoolkit.
iPgm
(ikey, iname, iopt={})¶ IBM i XMLSERVICE call *PGM.
Parameters: - ikey (str) – XML <ikey>…operation …</ikey> for parsing output.
- iname (str) – IBM i *PGM or *SRVPGM name
- iopt (dict) – option - dictionay of options (below) {‘error’:’on|off|fast’} : XMLSERVICE error choice {‘error’:’fast’} {‘func’:’MYFUNC’} : IBM i *SRVPGM function export. {‘lib’:’mylib’} : IBM i library name {‘mode’:’opm|ile’} : XMLSERVICE error choice {‘mode’:’ile’}
Example
iPgm(‘zzcall’,’ZZCALL’) .addParm(iData(‘var1’,’1a’,’a’)) .addParm(iData(‘var2’,’1a’,’b’)) .addParm(iData(‘var3’,’7p4’,’32.1234’)) .addParm(iData(‘var4’,’12p2’,’33.33’)) .addParm(
iDS(‘var5’) .addData(iData(‘d5var1’,’1a’,’a’)) .addData(iData(‘d5var2’,’1a’,’b’)) .addData(iData(‘d5var3’,’7p4’,’32.1234’)) .addData(iData(‘d5var4’,’12p2’,’33.33’)) )Returns: iPgm (obj) Notes
- pgm:
- <pgm name=’’
- [lib=’’
- func=’’ mode=’opm|ile’ error=’on|off|fast’ (1.7.6) ]> … </pgm>
-
add
(obj)¶ Additional mini dom xml child nodes.
Parameters: obj (iBase) – additional child object Example
itool = iToolKit() itool.add(
iPgm(‘zzcall’,’ZZCALL’) <— child of iToolkit .addParm(iData(‘INCHARA’,’1a’,’a’)) <— child of iPgm )Returns: (void)
-
addParm
(obj, iopt={})¶ Add a parameter child node.
Parameters: - obj (obj) – iData object or iDs object.
- iopt (dict) – options to pass to iParm constructor
Returns: (void)
-
make
()¶ Assemble coherent mini dom xml, including child nodes.
Parameters: none – Returns: xml.dom.minidom (obj)
-
xml_in
()¶ Return XML string of collected mini dom xml child nodes.
Parameters: none – Returns: XML (str)
-
class
itoolkit.
iSrvPgm
(ikey, iname, ifunc, iopt={})¶ IBM i XMLSERVICE call *SRVPGM.
Parameters: - ikey (str) – XML <ikey>…operation …</ikey> for parsing output.
- iname (str) – IBM i *PGM or *SRVPGM name
- ifunc (str) – IBM i *SRVPGM function export.
- iopt (dict) – option - dictionay of options (below) {‘error’:’on|off|fast’} : XMLSERVICE error choice {‘error’:’fast’} {‘lib’:’mylib’} : IBM i library name {‘mode’:’opm|ile’} : XMLSERVICE error choice {‘mode’:’ile’}
Example
see iPgm
Returns: iSrvPgm (obj) Notes
- pgm:
- <pgm name=’’
- [lib=’’
- func=’’ mode=’opm|ile’ error=’on|off|fast’ (1.7.6) ]> … </pgm>
-
add
(obj)¶ Additional mini dom xml child nodes.
Parameters: obj (iBase) – additional child object Example
itool = iToolKit() itool.add(
iPgm(‘zzcall’,’ZZCALL’) <— child of iToolkit .addParm(iData(‘INCHARA’,’1a’,’a’)) <— child of iPgm )Returns: (void)
-
addParm
(obj, iopt={})¶ Add a parameter child node.
Parameters: - obj (obj) – iData object or iDs object.
- iopt (dict) – options to pass to iParm constructor
Returns: (void)
-
addRet
(obj)¶ Add a return structure child node.
Parameters: obj (obj) – iData object or iDs object. Returns: (void)
-
make
()¶ Assemble coherent mini dom xml, including child nodes.
Parameters: none – Returns: xml.dom.minidom (obj)
-
xml_in
()¶ Return XML string of collected mini dom xml child nodes.
Parameters: none – Returns: XML (str)
-
class
itoolkit.
iCmd
(ikey, icmd, iopt={})¶ IBM i XMLSERVICE call *CMD not returning *OUTPUT.
Parameters: - ikey (str) – XML <ikey>…operation …</ikey> for parsing output.
- icmd (str) – IBM i command no output (see 5250 command prompt).
- iopt (dict) –
option - dictionay of options (below) {‘error’:’on|off|fast’} : XMLSERVICE error option {‘exec’:cmd|system|rexx’} : XMLSERVICE command type {‘exec’:’cmd’}
RTVJOBA CCSID(?N) {‘exec’:’rex’}
Example
iCmd(‘chglibl’, ‘CHGLIBL LIBL(XMLSERVICE) CURLIB(XMLSERVICE)’) iCmd(‘rtvjoba’, ‘RTVJOBA CCSID(?N) OUTQ(?)’)
Returns: iCmd (obj) Notes
- Special commands returning output parameters are allowed.
- (?) - indicate string return (?N) - indicate numeric return
- <cmd [exec=’cmd|system|rexx’ (default exec=’cmd’)
- hex=’on’ before=’cc1/cc2/cc3/cc4’ after=’cc4/cc3/cc2/cc1’ (1.6.8) error=’on|off|fast’ (1.7.6) ]>IBM i command</cmd>
-
add
(obj)¶ Additional mini dom xml child nodes.
Parameters: obj (iBase) – additional child object Example
itool = iToolKit() itool.add(
iPgm(‘zzcall’,’ZZCALL’) <— child of iToolkit .addParm(iData(‘INCHARA’,’1a’,’a’)) <— child of iPgm )Returns: (void)
-
make
()¶ Assemble coherent mini dom xml, including child nodes.
Parameters: none – Returns: xml.dom.minidom (obj)
-
xml_in
()¶ Return XML string of collected mini dom xml child nodes.
Parameters: none – Returns: XML (str)
-
class
itoolkit.
iCmd5250
(ikey, icmd, iopt={})¶ IBM i XMLSERVICE call 5250 *CMD returning *OUTPUT.
Parameters: - ikey (str) – XML <ikey>…operation …</ikey> for parsing output.
- icmd (str) – IBM i PASE script/utility (see call qp2term).
- iopt (dict) – option - dictionay of options (below) {‘error’:’on|off|fast’} : XMLSERVICE error choice {‘error’:’fast’} {‘row’:’on|off’} : XMLSERVICE wrap line in row tag? {‘row’:’off’}
Example
iCmd5250(‘dsplibl’,’dsplibl’) iCmd5250(‘wrkactjob’,’wrkactjob’)
Returns: iCmd5250 (obj) Notes
This is a subclass of iSh, therefore XMLSERVICE perfoms standard PASE shell popen fork/exec calls.
/QOpenSys/usr/bin/system ‘wrkactjob’
Please note, this is a relatively slow operation, use sparingly on high volume web sites.
- <sh [rows=’on|off’
- hex=’on’ before=’cc1/cc2/cc3/cc4’ after=’cc4/cc3/cc2/cc1’ (1.7.4) error=’on|off|fast’ (1.7.6) ]>(PASE utility)</sh>
-
add
(obj)¶ Additional mini dom xml child nodes.
Parameters: obj (iBase) – additional child object Example
itool = iToolKit() itool.add(
iPgm(‘zzcall’,’ZZCALL’) <— child of iToolkit .addParm(iData(‘INCHARA’,’1a’,’a’)) <— child of iPgm )Returns: (void)
-
make
()¶ Assemble coherent mini dom xml, including child nodes.
Parameters: none – Returns: xml.dom.minidom (obj)
-
xml_in
()¶ Return XML string of collected mini dom xml child nodes.
Parameters: none – Returns: XML (str)
-
class
itoolkit.
iSh
(ikey, icmd, iopt={})¶ IBM i XMLSERVICE call PASE utilities.
Parameters: - ikey (str) – XML <ikey>…operation …</ikey> for parsing output.
- icmd (str) – IBM i PASE script/utility (see call qp2term).
- iopt (dict) – option - dictionay of options (below) {‘error’:’on|off|fast’} : XMLSERVICE error choice {‘error’:’fast’} {‘row’:’on|off’} : XMLSERVICE wrap line in row tag? {‘row’:’off’}
Example
iSh(‘ls /home/xml/master | grep -i xml’)
Returns: iSh (obj) Notes
XMLSERVICE perfoms standard PASE shell popen calls, therefore, additional job will be forked, utilities will be exec’d, and stdout will be collected to be returned.
Please note, this is a relatively slow operation, use sparingly on high volume web sites.
- <sh [rows=’on|off’
- hex=’on’ before=’cc1/cc2/cc3/cc4’ after=’cc4/cc3/cc2/cc1’ (1.7.4) error=’on|off|fast’ (1.7.6) ]>(PASE utility)</sh>
-
add
(obj)¶ Additional mini dom xml child nodes.
Parameters: obj (iBase) – additional child object Example
itool = iToolKit() itool.add(
iPgm(‘zzcall’,’ZZCALL’) <— child of iToolkit .addParm(iData(‘INCHARA’,’1a’,’a’)) <— child of iPgm )Returns: (void)
-
make
()¶ Assemble coherent mini dom xml, including child nodes.
Parameters: none – Returns: xml.dom.minidom (obj)
-
xml_in
()¶ Return XML string of collected mini dom xml child nodes.
Parameters: none – Returns: XML (str)
-
class
itoolkit.
iXml
(ixml)¶ IBM i XMLSERVICE raw xml input.
Parameters: ixml (str) – custom XML for XMLSERVICE operation. Example
iXml(“<cmd>CHGLIBL LIBL(XMLSERVICE)</cmd>”) iXml(“<sh>ls /tmp</sh>”)
Returns: iXml (obj) Notes
Not commonly used, but ok when other classes fall short.
-
add
(obj)¶ add input not allowed.
Returns: raise except
-
make
()¶ Assemble coherent mini dom xml.
Parameters: none – Returns: xml.dom.minidom (obj)
-
xml_in
()¶ Return XML string of collected mini dom xml child nodes.
Parameters: none – Returns: XML (str)
-
-
class
itoolkit.
iDS
(ikey, iopt={})¶ Data structure child node for iPgm, iSrvPgm, or nested iDS data structures.
Parameters: - ikey (str) – XML <ds … var=”ikey”> for parsing output.
- iopt (dict) – option - dictionay of options (below) {‘dim’:’n’} : XMLSERVICE dimension/occurs number. {‘dou’:’label’} : XMLSERVICE do until label. {‘len’:’label’} : XMLSERVICE calc length label.
Example
see iPgm
Returns: iDS (obj) Notes
- pgm data structure:
- <ds [dim=’n’ dou=’label’
- len=’label’ (1.5.4) data=’records’ (1.7.5) ]>(see <data>)</ds>
-
add
(obj)¶ Additional mini dom xml child nodes.
Parameters: obj (iBase) – additional child object Example
itool = iToolKit() itool.add(
iPgm(‘zzcall’,’ZZCALL’) <— child of iToolkit .addParm(iData(‘INCHARA’,’1a’,’a’)) <— child of iPgm )Returns: (void)
-
addData
(obj)¶ Add a iData or iDS child node.
Parameters: obj (obj) – iData object or iDs object. Returns: (void)
-
make
()¶ Assemble coherent mini dom xml, including child nodes.
Parameters: none – Returns: xml.dom.minidom (obj)
-
xml_in
()¶ Return XML string of collected mini dom xml child nodes.
Parameters: none – Returns: XML (str)
-
class
itoolkit.
iData
(ikey, itype, ival='', iopt={})¶ Data value child node for iPgm, iSrvPgm, or iDS data structures.
Parameters: - ikey (str) – XML <data … var=”ikey”> for parsing output.
- iparm (obj) – dom for parameter or return or ds.
- itype (obj) – data type [see XMLSERVICE types, ‘3i0’, …].
- ival (obj) – data type value.
- iopt (dict) – option - dictionay of options (below) {‘dim’:’n’} : XMLSERVICE dimension/occurs number. {‘varying’:’on|off|2|4’} : XMLSERVICE varying {‘varying’:’off’}. {‘hex’:’on|off’} : XMLSERVICE hex chracter data {‘hex’:’off’}. {‘enddo’:’label’} : XMLSERVICE enddo until label. {‘setlen’:’label’} : XMLSERVICE set calc length label. {‘offset’:’n’} : XMLSERVICE offset label. {‘next’:’label’} : XMLSERVICE next offset label (value).
Example
see iPgm
Returns: iData (obj) Notes
- pgm data elements:
- <data type=’data types’
- [dim=’n’
- varying=’on|off|2|4’ enddo=’label’ setlen=’label’ (1.5.4) offset=’label’ hex=’on|off’ (1.6.8) before=’cc1/cc2/cc3/cc4’ (1.6.8) after=’cc4/cc3/cc2/cc1’ (1.6.8) trim=’on|off’ (1.7.1) next=’nextoff’ (1.9.2) ]>(value)</data>
For more info on data types you can use, refer to http://yips.idevcloud.com/wiki/index.php/XMLService/DataTypes
Changed in version 1.6.3: ival is now optional and supports non-string parameters.
-
add
(obj)¶ Additional mini dom xml child nodes.
Parameters: obj (iBase) – additional child object Example
itool = iToolKit() itool.add(
iPgm(‘zzcall’,’ZZCALL’) <— child of iToolkit .addParm(iData(‘INCHARA’,’1a’,’a’)) <— child of iPgm )Returns: (void)
-
make
()¶ Assemble coherent mini dom xml, including child nodes.
Parameters: none – Returns: xml.dom.minidom (obj)
-
xml_in
()¶ Return XML string of collected mini dom xml child nodes.
Parameters: none – Returns: XML (str)
Transports¶
-
class
itoolkit.transport.
XmlServiceTransport
(ctl='*here *cdata', ipc='*na')¶ XMLSERVICE transport base class
Parameters: - ctl (str) – XMLSERVICE control options, see http://yips.idevcloud.com/wiki/index.php/XMLService/XMLSERVICEQuick#ctl
- ipc (str) – An XMLSERVICE ipc key for stateful conections, see http://yips.idevcloud.com/wiki/index.php/XMLService/XMLSERVICEConnect
-
call
(tk)¶ Call XMLSERVICE with accumulated actions
Parameters: tk (iToolKit) – An iToolkit object Returns: The XML returned from XMLSERVICE Return type: str
-
close
()¶ Close the connection now rather than when
__del__()
is called.The transport will be unusable from this point forward and a
TransportClosedException
exception will be raised if any operation is attempted with the transport.
HTTP Transport¶
-
class
itoolkit.transport.
HttpTransport
(url, user, password, database='*LOCAL', **kwargs)¶ Call XMLSERVICE using FastCGI endpoint
For more information, refer to http://yips.idevcloud.com/wiki/index.php/XMLService/XMLSERVICEGeneric
Parameters: - url (str) – XMLSERVICE FastCGI endpoint eg. https://example.com/cgi-bin/xmlcgi.pgm
- user (str) – Database user profile name
- password (str, optional) – Database password
- database (str, optional) – Database name (RDB) to connect to
- **kwargs – Base transport options. See XmlServiceTransport.
Example
>>> from itoolkit.transport import HttpTransport >>> endpoint = 'https://example.com/cgi-bin/xmlcgi.pgm' >>> transport = HttpTransport(endpoint, 'user', 'pass')
-
call
(tk)¶ Call XMLSERVICE with accumulated actions
Parameters: tk (iToolKit) – An iToolkit object Returns: The XML returned from XMLSERVICE Return type: str
-
close
()¶ Close the connection now rather than when
__del__()
is called.The transport will be unusable from this point forward and a
TransportClosedException
exception will be raised if any operation is attempted with the transport.
Database Transport¶
-
class
itoolkit.transport.
DatabaseTransport
(conn, **kwargs)¶ Call XMLSERVICE using a database connection
Parameters: - conn – An active database connection object (PEP-249)
- schema (str, optional) – The XMLSERVICE stored procedure schema to use
- **kwargs – Base transport options. See XmlServiceTransport.
Examples
Connecting to XMLSERVICE over ODBC with the default *LOCAL DSN on IBM i.
>>> from itoolkit.transport import DatabaseTransport >>> import pyodbc >>> transport = DatabaseTransport(pyodbc.connect('DSN=*LOCAL'))
Connecting to XMLSERVICE with ibm_db_dbi on IBM i.
>>> from itoolkit.transport import DatabaseTransport >>> import ibm_db_dbi >>> transport = DatabaseTransport(ibm_db_dbi.connect())
-
call
(tk)¶ Call XMLSERVICE with accumulated actions
Parameters: tk (iToolKit) – An iToolkit object Returns: The XML returned from XMLSERVICE Return type: str
-
close
()¶ Close the connection now rather than when
__del__()
is called.The transport will be unusable from this point forward and a
TransportClosedException
exception will be raised if any operation is attempted with the transport.
SSH Transport¶
-
class
itoolkit.transport.
SshTransport
(sshclient=None, **kwargs)¶ Transport XMLSERVICE calls over SSH connection.
Parameters: sshclient (paramiko.SSHClient) – connected and authenticated connection Example
>>> from itoolkit.transport import SshTransport >>> import paramiko >>> ssh = paramiko.SSHClient() >>> ssh.set_missing_host_key_policy(paramiko.WarningPolicy()) >>> ssh.connect(host, username="user", password="pass") >>> transport = SshTransport(ssh)
Warning
Using WarningPolicy is shown only as an example and could lead to security issues. Please refer to the set_missing_host_key_policy docs for more info on other policies that may be more appropriate.
Returns: (obj) -
call
(tk)¶ Call XMLSERVICE with accumulated actions
Parameters: tk (iToolKit) – An iToolkit object Returns: The XML returned from XMLSERVICE Return type: str
-
close
()¶ Close the connection now rather than when
__del__()
is called.The transport will be unusable from this point forward and a
TransportClosedException
exception will be raised if any operation is attempted with the transport.
-
Direct Memory Transport¶
-
class
itoolkit.transport.
DirectTransport
(**kwargs)¶ Call XMLSERVICE directly in-process using _ILECALL
Parameters: **kwargs – Base transport options. See XmlServiceTransport. Example
>>> from itoolkit.transport import DirectTransport >>> transport = DirectTransport()
-
call
(tk)¶ Call XMLSERVICE with accumulated actions
Parameters: tk (iToolKit) – An iToolkit object Returns: The XML returned from XMLSERVICE Return type: str
-
close
()¶ Close the connection now rather than when
__del__()
is called.The transport will be unusable from this point forward and a
TransportClosedException
exception will be raised if any operation is attempted with the transport.
-
Note
This transport will only work when run on an IBM i system. On other operating
systems, calling it will fail with a RuntimeError
.
Warning
When using a 64-bit Python, this transport will only work with XMLSERVICE 2.0.1 or higher. When using the system XMLSERVICE in QXMLSERV, the following PTFs are available to fix this problem:
- IBM i 7.4 - SI70669
- IBM i 7.3 - SI70668
- IBM i 7.2 - SI70667
Deprecated Transports¶
-
class
itoolkit.rest.irestcall.
iRestCall
¶
Deprecated since version 1.6.0: Use itoolkit.transport.HttpTransport
instead.
-
class
itoolkit.db2.idb2call.
iDB2Call
¶
Deprecated since version 1.6.0: Use itoolkit.transport.DatabaseTransport
instead.
-
class
itoolkit.lib.ilibcall.
iLibCall
¶
Deprecated since version 1.6.0: Use itoolkit.transport.DirectTransport
instead.