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 to sys.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:
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.