Learning
Community
Open Exchange
Global Masters
InterSystems IRIS Data Platform 2019.3 / Application Development / Using the Native API for Python / Native API Quick Reference for Python
Previous section   

Native API Quick Reference for Python

This chapter is a quick reference for module irisnative, which contains the following classes:
Note:
This chapter is intended as a convenience for readers of this book, but it is not the definitive reference for the Native API. For the most complete and up-to-date information on these classes, see the online API documentation.

List of Methods by Usage

Module irisnative
The irisnative module provides classes iris, connection, and iterator, plus the following methods:
Class Connection
The connection class encapsulates a connection to the server. Instances of connection are created and connected to the server by irisnative method createConnection().
Class Iris
The iris class provides most of the Native API functionality. Instances of iris are created by irisnative.createIris(). Methods are listed below, organized by usage:
Class iris: Create, access, and delete nodes
Class iris: Transactions and locking
  • iris.lock() — performs an incremental lock on the global, returns True on success.
  • iris.unlock() — performs an immediate or deferred unlock on the global.
  • iris.releaseAllLocks() — releases all locks associated with the session.
  • iris.getTLevel() — returns the current transaction level (0 if not in a transaction).
  • iris.tCommit() — commits the current transaction and decrements the transaction level.
  • iris.tRollback() — rolls back all open transactions in the session.
  • iris.tRollbackOne() — rolls back the current level transaction only.
  • iris.tStart() — starts a transaction and increments the transaction level.
Class iris: ClassMethod and function calls
  • iris.classMethodValue() — calls a user defined ObjectScript method and gets the returned value.
  • iris.classMethodVoid() — calls a user defined ObjectScript method, ignoring any returned value.
  • iris.function() — calls a function of a user defined ObjectScript routine and gets the returned value.
  • iris.procedure() — calls a procedure of a user defined ObjectScript routine.
Class iris: Global iteration and utilities
Class Iterator
The iterator class provides methods to iterate over a set of nodes. Instances of iterator are created by iris.iterator().
  • iterator.next() — returns a tuple containing the subscript and value of the next node in the iteration.
  • iterator.startFrom() — sets the iterator to the specified starting address and returns it, after which next() can be used to advance the iterator to the next node in collating sequence.
  • iterator.reversed() — toggles direction of iteration between forward and reverse collation order.
  • iterator.items() — sets return type to an array containing subscript and node value.
  • iterator.subscripts() — sets return type to return the node subscript only.
  • iterator.values() — sets return type to return the node value only.

Module irisnative

The irisnative module provides classes iris, connection, and iterator, plus methods to create new instances of iris and connection. See “Introduction to Global Arrays” for examples.
createConnection()
irisnative.createConnection() attempts to create a new connection to an iris instance. Returns a new connection object. The object will be open if the connection was successful, or closed otherwise (see connection.isClosed()).
   irisnative.createConnection(hostname,port,namespace,username,password,timeout,sharedmemory,logfile)
   irisnative.createConnection(connectionstr,username,password,timeout,sharedmemory,logfile)
The hostname, port, namespace, timeout, and logfile from the last successful connection attempt are saved as properties of the connection object.
returns: a new instance of connection
parameters: Parameters may be passed by position or keyword.
  • hostname — (Unicode string) the server URL
  • port — (Integer/Long) superserver port number
  • namespace — (Unicode string) – a namespace on the server
  • The following parameter can be used in place of the hostname, port, and namespace arguments:
    • connectionstr (optional Unicode string) – a string of the form hostname:port/namespace.
  • username — (Unicode string) user
  • password — (Unicode string) password
  • timeout — (optional Integer/Long) maximum number of milliseconds to wait while attempting the connection. Defaults to 10000.
  • sharedmemory — (optional Boolean) set to True to attempt a shared memory connection when the hostname is localhost or 127.0.0.1. Set to False to force a connection over TCP/IP. Defaults to True.
  • logfile — (optional Unicode string) – client-side log file path. The maximum path length is 255 ASCII characters.
createIris()
irisnative.createIris() returns a new instance of iris that uses the specified connection. Throws an exception if the connection is closed.
    irisnative.createIris(conn)
returns: a new instance of iris
parameter:
  • conn — (connection object) — object that provides the server connection

Class connection

Class connection is a member of module irisnative. Instances of connection are created by calling irisnative.createConnection(). See “Introduction to Global Arrays” for more details and examples.
close()
connection.close() closes the connection to the iris instance if it is open. Does nothing if the connection is already closed.
   connection.close()
isClosed()
connection.isClosed() returns True if the connection was successful, or False otherwise (see irisnative.createConnection()).
   connection.isClosed()
returns: Boolean
isUsingSharedMemory()
connection.isUsingSharedMemory() returns True if the connection is open and using shared memory.
   connection.isUsingSharedMemory()
returns: Boolean
Properties
The hostname, port, namespace, timeout, and logfile from the last successful connection attempt are saved as properties of the connection object.

Class iris

Class iris is a member of module irisnative. Instances of iris are created by calling irisnative.createIris(). See “Introduction to Global Arrays” for more details and examples.
classMethodValue()
iris.classMethodValue() calls a class method, passing zero or more arguments and returning the value returned by the class method. Throws a <COMMAND> exception if no value is returned.
   iris.classMethodValue(className,methodName,*args)
returns: None, Integer/Long, Unicode string, or Float (depending on the result of the class method)
parameters:
  • className — fully qualified name of the class to which the called method belongs.
  • methodName — name of the class method.
  • args — zero or more method arguments of types None, Integer/Long, Unicode string, Float, or Byte string. Trailing arguments may be omitted (see “Calling ObjectScript Methods and Functions”).
classMethodVoid()
iris.classMethodVoid() calls a class method, passing zero or more arguments. This method will ignore any values returned by the class method.
   iris.classMethodVoid(className,methodName,*args)
parameters:
  • className — fully qualified name of the class to which the called method belongs.
  • methodName — name of the class method.
  • *args — zero or more method arguments of types Integer/Long, Unicode string, Float, Byte string, or None. Trailing arguments may be omitted (see “Calling ObjectScript Methods and Functions”).
This method assumes that there will be no return value, but can be used to call any class method. If you use classMethodVoid() to call a method that returns a value, the method will be executed but the return value will just be ignored.
function()
iris.function() calls a function, passing zero or more arguments and returning the value returned by the function (also see iris.procedure()).
   iris.function(routineName,functionName,*args)
returns: None, Integer/Long, Unicode string, or Float (depending on the result of the function)
parameters:
  • routineName — name of the routine containing the function.
  • functionName — name of the function to call.
  • *args — zero or more function arguments of types None, Integer/Long, Unicode string, Float, or Byte string. Trailing arguments may be omitted (see “Calling ObjectScript Methods and Functions”).
iterator()
iris.iterator() returns an iterator that traverses the immediate children of the specified node. See “Class iterator” for a list of methods that can modify the direction of iteration and the type of return value.
   iris.iterator(globalName,*subscripts)
returns: an instance of iterator
parameters:
  • globalName — global name
  • *subscripts — zero or more subscripts specifying the target node
get()
iris.get() returns the value of the global node as Integer/Long, Unicode string, or Float.
   iris.get(globalName,*subscripts)
returns: Integer/Long, Unicode string, or Float. Returns None if the node is valueless or does not exist.
parameters:
  • globalName — global name
  • *subscripts — zero or more subscripts specifying the target node
getBoolean()
iris.getBoolean() gets the value of the node as a Boolean.
   iris.getBoolean(globalName,*subscripts)
returns: Boolean (or None if node is valueless or does not exist)
parameters:
  • globalName — global name
  • *subscripts — zero or more subscripts specifying the target node
getBytes()
iris.getBytes() gets the value of the node as a Byte string. Throws an exception if the node value is not a byte or ASCII string.
   iris.getBytes(globalName,*subscripts)
returns: Byte string (or b'' if empty string, None if node does not exist)
parameters:
  • globalName — global name
  • *subscripts — zero or more subscripts specifying the target node
getClientVersion()
iris.getClientVersion() returns the version string for this version of the Native API.
   iris.getClientVersion()
returns: Unicode string
getFloat()
iris.getFloat() gets the value of the node as a Float. Returns 0.0 if node value is an empty string, or None if the node does not exist.
   iris.getFloat(globalName,*subscripts)
returns: Float (or 0.0 node is valueless, None if node does not exist)
parameters:
  • globalName — global name
  • *subscripts — zero or more subscripts specifying the target node
getLong()
iris.getLong() gets the value of the node as a Long. Returns 0 if node value is an empty string, or None if the node does not exist.
   iris.getLong(globalName,*subscripts)
returns: Long (or 0 if node is valueless, None if node does not exist)
parameters:
  • globalName — global name
  • *subscripts — zero or more subscripts specifying the target node
getServerVersion()
iris.getServerVersion() returns the version string for the currently connected server.
   iris.getServerVersion()
returns: Unicode string
getString()
iris.getString() gets the value of the global as a Unicode string. Returns None if the node is valueless or does not exist.
   iris.getString(globalName,*subscripts)
returns: Unicode string (or None if node is valueless or does not exist)
parameters:
  • globalName — global name
  • *subscripts — zero or more subscripts specifying the target node
getTLevel()
iris.getTLevel() returns the number of nested transactions currently open in the session (1 if the current transaction is not nested, and 0 if there are no transactions open). This is equivalent to fetching the value of the ObjectScript $TLEVEL special variable.
   iris.getTLevel()
returns: Integer/Long
increment()
iris.increment() increments the global node with the value argument. If there is no existing node at the specified address, a new node is created with the specified value. Returns the new value of the global node.
   iris.increment(value,globalName,*subscripts)
returns: Integer/Long or Float
parameters:
  • value — (Integer/Long or Float) amount to increment by
  • globalName — global name
  • *subscripts — zero or more subscripts specifying the target node
isDefined()
iris.isDefined() returns a value that indicates whether a node has a value, a child node, or both. See “Testing for Child Nodes and Node Values” for details and examples.
   iris.isDefined(globalName,*subscripts)
returns: one of the following Integer/Long values:
  • 0 if the node does not exist.
  • 1 if the node has a value but no descendants.
  • 10 if the node is valueless but has one or more child nodes.
  • 11 if it has a both a value and child nodes.
parameters:
  • globalName — global name
  • *subscripts — zero or more subscripts specifying the target node
kill()
iris.kill() deletes the specified global node and all of its subnodes. If there is no node at the specified address, the command will do nothing. It will not throw an <UNDEFINED> exception.
   iris.kill(globalName,*subscripts)
parameters:
  • globalName — global name
  • *subscripts — zero or more subscripts specifying the target node
lock()
iris.lock() locks the global. This method performs an incremental lock (you must call the releaseAllLocks() method first if you want to unlock all prior locks). Throws a <TIMEOUT> exception if the timeout value is reached waiting to acquire the lock. See “LOCK” in the ObjectScript Reference for detailed information on locks.
   iris.lock(lockMode,timeout,globalName,*subscripts)
parameters:
  • lockMode — one of the following strings: "S" for shared lock, "E" for escalating lock, "SE" for both, or "" for neither. An empty string is the default mode (unshared and non-escalating).
  • timeout — number of seconds to wait to acquire the lock
  • globalName — global name
  • *subscripts — zero or more subscripts specifying the target node
procedure()
iris.procedure() calls an ObjectScript procedure or function, passing zero or more arguments and returning nothing (also see iris.function()).
   iris.procedure(routineName,procedureName,*args)
parameters:
  • routineName — name of the routine containing the procedure.
  • procedureName — name of the procedure to call.
  • *args — zero or more function arguments of types None, Integer/Long, Unicode string, Float, or Byte string. Trailing arguments may be omitted (see “Calling ObjectScript Methods and Functions”).
This method assumes that there will be no return value, but can be used to call any function. If you use procedure() to call a function that returns a value, the function will be executed but the return value will just be ignored.
releaseAllLocks()
iris.releaseAllLocks() releases all locks associated with the session.
iris.releaseAllLocks()
set()
iris.set() assigns value as the current node value. The new value may be a Unicode string, Byte string, Float, Integer/Long, or None.
  iris.set(value,globalName,*subscripts)
parameters:
  • value — new value of the global node (Integer/Long, Unicode string, byte string, Float, or None)
  • globalName — global name
  • *subscripts — zero or more subscripts specifying the target node
tCommit()
iris.tCommit() commits the current transaction.
   iris.tCommit()
tRollback()
iris.tRollback() rolls back all open transactions in the session.
   iris.tRollback()
tRollbackOne()
iris.tRollbackOne() rolls back the current level transaction only. This is intended for nested transactions, when the caller only wants to roll back one level. If this is a nested transaction, any higher-level transactions will not be rolled back.
   iris.tRollbackOne()
tStart()
iris.tStart() starts or opens a transaction.
   iris.tStart()
unlock()
iris.unlock() decrements the lock count on the specified lock, and unlocks it if the lock count is 0. To remove a shared or escalating lock, you must specify the appropriate lockMode ("S" for shared, "E" for escalating lock). See “LOCK” in the ObjectScript Reference for detailed information on locks.
   iris.unlock(lockMode,globalName,*subscripts)
parameters:
  • lockMode — a string containing a combination of 0 or more the following characters:
    • "I" for immediate unlock, "D" for deferred unlock, or "" for neither.
    • "S" to unlock a shared lock, "E" to unlock an escalating lock, or "SE" for both.
    For example, to unlock a Shared, Escalating lock Immediately, you would specify the string "SEI" as the lockMode. The characters may be in any order.
    An empty string is the default mode (unshared, non-escalating, always defers releasing an unlocked lock to the end of the current transaction).
  • globalName — global name
  • *subscripts — zero or more subscripts specifying the target node

Class iterator

Class iterator is a member of module irisnative. Instances of iterator are created by calling iris.iterator(). See “Finding Nodes in a Global Array” for more details and examples.
Note:
All iterator methods except next() return the calling iterator (not a copy) to enable method chaining. For example, the following code would return an iterator for children of node myGlobal('parentNode'). It will iterate in reverse collation order, and is positioned to find the first child node after subscript "V":
  iter = iris.iterator('myGlobal','parentNode').reversed().startFrom('V')
next()
iterator.next() positions the iterator at the next child node and returns the node value, the node subscript, or a tuple containing both, depending on the currently enabled return type (see below). Throws a StopIteration exception if there are no more nodes in the iteration. See “Iteration with next()” for more details and examples.
   iterator.next()
returns: node information in one of the following return types:
  • subscript and value (default) — a tuple containing the subscript and value of the next node in the iteration. The subscript is the first element of the tuple and the value is the second. Enable this type by calling items() if the iterator is currently set to a different return type.
  • subscript only — Enable this return type by calling subscripts().
  • value only — Enable this return type by calling values().
startFrom()
iterator.startFrom() returns the iterator with its starting position set to the specified subscript. The iterator will not point to a node until you call next(), which will advance the iterator to the next child node after the position you specify.
   iterator.startFrom(subscript)
returns: calling instance of iterator
parameter:
  • subscript — a single subscript indicating a starting position.
Calling this method with None as the argument is the same as using the default starting position, which is just before the first node, or just after the last node, depending on the direction of iteration.
reversed()
iterator.reversed() returns the iterator with the direction of iteration reversed from its previous setting (direction is set to forward iteration when the iterator is created).
   iterator.reversed()
returns: same instance of iterator
subscripts()
iterator.subscripts() returns the iterator with its return type set to subscripts-only.
   iterator.subscripts()
returns: same instance of iterator
values()
iterator.values() returns the iterator with its return type set to values-only.
   iterator.values()
returns: same instance of iterator
items()
iterator.items() returns the iterator with its return type set to a tuple containing both the subscript and the node value. The subscript is the first element of the tuple and the value is the second. This is the default setting when the iterator is created.
   iterator.items()
returns: same instance of iterator
Previous section