Skip to main content
Previous section

Native API Quick Reference for Python

This chapter is a quick reference for module irisnative, which contains the following classes:

  • Class connection provides a connection to the server.

  • Class iris provides the main functionality.

  • Class iterator provides methods to navigate a global array.

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)
Copy code to clipboard

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)
Copy code to clipboard

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()
Copy code to clipboard
isClosed()

connection.isClosed() returns True if the connection was successful, or False otherwise (see irisnative.createConnection()).

   connection.isClosed()
Copy code to clipboard

returns: Boolean

isUsingSharedMemory()

connection.isUsingSharedMemory() returns True if the connection is open and using shared memory.

   connection.isUsingSharedMemory()
Copy code to clipboard

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)
Copy code to clipboard

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)
Copy code to clipboard

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)
Copy code to clipboard

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)
Copy code to clipboard

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)
Copy code to clipboard

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)
Copy code to clipboard

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)
Copy code to clipboard

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()
Copy code to clipboard

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)
Copy code to clipboard

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)
Copy code to clipboard

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()
Copy code to clipboard

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)
Copy code to clipboard

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()
Copy code to clipboard

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)
Copy code to clipboard

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)
Copy code to clipboard

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)
Copy code to clipboard

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)
Copy code to clipboard

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)
Copy code to clipboard

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()
Copy code to clipboard
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)
Copy code to clipboard

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()
Copy code to clipboard
tRollback()

iris.tRollback() rolls back all open transactions in the session.

   iris.tRollback()
Copy code to clipboard
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()
Copy code to clipboard
tStart()

iris.tStart() starts or opens a transaction.

   iris.tStart()
Copy code to clipboard
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)
Copy code to clipboard

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')
Copy code to clipboard
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()
Copy code to clipboard

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)
Copy code to clipboard

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()
Copy code to clipboard

returns: same instance of iterator

subscripts()

iterator.subscripts() returns the iterator with its return type set to subscripts-only.

   iterator.subscripts()
Copy code to clipboard

returns: same instance of iterator

values()

iterator.values() returns the iterator with its return type set to values-only.

   iterator.values()
Copy code to clipboard

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()
Copy code to clipboard

returns: same instance of iterator