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:
obj –
Notes
<?xml version=’1.0’?> <xmlservice>
- call(itrans)
Call xmlservice with accumulated input XML.
- Parameters:
itrans (obj) – XMLSERVICE transport object
- Raises:
itoolkit.transport.TransportClosedError – If the transport has been closed.
- clear()
Clear collecting child objects.
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 and close trace file.
New in version 1.2.
Deprecated since version 2.0: See Tracing.
- trace_open(iname='*terminal')
Open trace file.
If
iname
is “*terminal”, trace will output tosys.stdout
. Otherwise, a file path with the format /tmp/python_toolkit_(iname).log is used to open a trace file in append mode.- Parameters:
iname (str) – Name of trace file or “*terminal” for
sys.stdout
New in version 1.2.
Deprecated since version 2.0: See Tracing.
- xml_in()
return raw xml input.
- Returns:
xml
- xml_out()
return raw xml output.
- 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
Example calling the ZZCALL program with 5 arguments:
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')) )
- add(obj)
Additional mini dom xml child nodes.
- Parameters:
obj (iBase) – additional child object
Example
Adding a program:
itool = iToolKit() itool.add( iPgm('zzcall','ZZCALL') <--- child of iToolkit .addParm(iData('INCHARA','1a','a')) <--- child of iPgm )
- addParm(obj, iopt={})
Add a parameter child node.
- Parameters:
obj (obj) – iData object or iDs object.
iopt (dict) – options to pass to iParm constructor
- make(doc=None)
Assemble coherent mini dom xml, including child nodes.
- Returns:
xml.dom.minidom (obj)
- xml_in()
Return XML string of collected mini dom xml child nodes.
- 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
Adding a program:
itool = iToolKit() itool.add( iPgm('zzcall','ZZCALL') <--- child of iToolkit .addParm(iData('INCHARA','1a','a')) <--- child of iPgm )
- addParm(obj, iopt={})
Add a parameter child node.
- Parameters:
obj (obj) – iData object or iDs object.
iopt (dict) – options to pass to iParm constructor
- addRet(obj)
Add a return structure child node.
- Parameters:
obj (obj) – iData object or iDs object.
- make(doc=None)
Assemble coherent mini dom xml, including child nodes.
- Returns:
xml.dom.minidom (obj)
- xml_in()
Return XML string of collected mini dom xml child nodes.
- 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
Example calling two CL commands:
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
Adding a program:
itool = iToolKit() itool.add( iPgm('zzcall','ZZCALL') <--- child of iToolkit .addParm(iData('INCHARA','1a','a')) <--- child of iPgm )
- make(doc=None)
Assemble coherent mini dom xml, including child nodes.
- Returns:
xml.dom.minidom (obj)
- xml_in()
Return XML string of collected mini dom xml child nodes.
- 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
Adding a program:
itool = iToolKit() itool.add( iPgm('zzcall','ZZCALL') <--- child of iToolkit .addParm(iData('INCHARA','1a','a')) <--- child of iPgm )
- make(doc=None)
Assemble coherent mini dom xml, including child nodes.
- Returns:
xml.dom.minidom (obj)
- xml_in()
Return XML string of collected mini dom xml child nodes.
- 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
Adding a program:
itool = iToolKit() itool.add( iPgm('zzcall','ZZCALL') <--- child of iToolkit .addParm(iData('INCHARA','1a','a')) <--- child of iPgm )
- make(doc=None)
Assemble coherent mini dom xml, including child nodes.
- Returns:
xml.dom.minidom (obj)
- xml_in()
Return XML string of collected mini dom xml child nodes.
- 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(doc=None)
Assemble coherent mini dom xml, including child nodes.
- Returns:
xml.dom.minidom (obj)
- xml_in()
Return XML string of collected mini dom xml child nodes.
- 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
Adding a program:
itool = iToolKit() itool.add( iPgm('zzcall','ZZCALL') <--- child of iToolkit .addParm(iData('INCHARA','1a','a')) <--- child of iPgm )
- addData(obj)
Add a iData or iDS child node.
- Parameters:
obj (obj) – iData object or iDs object.
- make(doc=None)
Assemble coherent mini dom xml, including child nodes.
- Returns:
xml.dom.minidom (obj)
- xml_in()
Return XML string of collected mini dom xml child nodes.
- 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
Adding a program:
itool = iToolKit() itool.add( iPgm('zzcall','ZZCALL') <--- child of iToolkit .addParm(iData('INCHARA','1a','a')) <--- child of iPgm )
- make(doc=None)
Assemble coherent mini dom xml, including child nodes.
- Returns:
xml.dom.minidom (obj)
- xml_in()
Return XML string of collected mini dom xml child nodes.
- 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
Attention
Subclasses should implement
_call()
to call XMLSERVICE instead of overriding this method.
- close()
Close the connection now rather than when
__del__()
is called.The transport will be unusable from this point forward and a
itoolkit.transport.TransportClosedError
exception will be raised if any operation is attempted with the transport.Attention
Subclasses should implement
_close()
to free its resources instead of overriding this method.
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')
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())
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)
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()
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
Exceptions
- class itoolkit.TransportError
Base exception class for all transport errors
New in version 1.7.1.
- class itoolkit.transport.TransportClosedError
Raised when an operation is performed on a closed transport
New in version 1.7.1.
- class itoolkit.TransportClosedException
Alias of
itoolkit.transport.TransportClosedError
Deprecated since version 1.7.1: Use
itoolkit.transport.TransportClosedError
instead.
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.