irisnative.iris¶

class irisnative.iris¶

A way to execute basic ObjectScript commands on an IRIS server.

This class has methods to work with globals and to call class methods and routines. Any errors on the server generate Runtime Errors.

Methods

`iris.getAPIVersion`	Return the version string of the IRIS Native API.
`iris.getServerVersion`	Return the version string of the IRIS server.
`iris.get`	Fetch the value of the global node.
`iris.getLong`	Fetch the value of the global node as a Long.
`iris.getFloat`	Fetch the value of the global node as a Float.
`iris.getString`	Fetch the value of the global node as a Unicode string.
`iris.getBoolean`	Fetch the value of the global node as a Boolean.
`iris.getBytes`	Fetch the value of the global node as a Byte string.
`iris.set`	Set the value of a global node.
`iris.isDefined`	Check whether a global node contains data and whether it has children.
`iris.kill`	Kill the global node including any descendants.
`iris.increment`	Increment the global node by the value argument.
`iris.classMethodValue`	Call the class method and expect a return value.
`iris.classMethodVoid`	Call the class method and do not expect a return value.
`iris.function`	Call the function and expect a return value.
`iris.procedure`	Call the procedure and do not expect a return value.
`iris.lock`	Lock the global node.
`iris.unlock`	Unlock the global node.
`iris.releaseAllLocks`	Release all locks associated with the session (i.e.
`iris.tStart`	Start or open an IRIS transaction.
`iris.tCommit`	Commit the current IRIS transaction.
`iris.tRollback`	Roll back all open IRIS transactions in the session (i.e.
`iris.tRollbackOne`	Roll back the current level of IRIS transaction only.
`iris.getTLevel`	Return the number of nested transactions currently open in the session.
`iris.iterator`	Return an iterator over the immediate children of the global node.

static iris.getAPIVersion()¶

Return the version string of the IRIS Native API.

getAPIVersion()

Returns:	The API version string
Return type:	Unicode string

iris.getServerVersion()¶

Return the version string of the IRIS server.

getServerVersion()

Returns:	The server version string
Return type:	Unicode string

iris.get()¶

Fetch the value of the global node.

get(globalName,subscripts…)

Parameters:	globalName (Unicode string) – global node name subscripts... (Unicode string, optional, variable length) – global subscripts
Returns:	Return None if the node is undefined or set to the empty string. Otherwise, return an Integer/Long, Unicode string, or Float.
Return type:	None, int/long, Unicode string, or float

iris.getLong()¶

Fetch the value of the global node as a Long.

get(globalName,subscripts…)

Parameters:	globalName (Unicode string) – global node name subscripts... (Unicode string, optional, variable length) – global subscripts
Returns:	Return None if the node is undefined and 0 if set to the empty string. Otherwise return the value of the node as a Long.
Return type:	None or long

iris.getFloat()¶

Fetch the value of the global node as a Float.

get(globalName,subscripts…)

Parameters:	globalName (Unicode string) – global node name subscripts... (Unicode string, optional, variable length) – global subscripts
Returns:	Return None if the node is undefined and 0.0 if set to the empty string. Otherwise return the value of the node as a Float.
Return type:	None or float

iris.getString()¶

Fetch the value of the global node as a Unicode string.

get(globalName,subscripts…)

Parameters:

globalName (Unicode string) – global node name
subscripts... (Unicode string, optional, variable length) – global subscripts

Returns:

Return None if the node is undefined or set to the empty string.: Otherwise return the value of the node as a Unicode string.

Return type:

None or Unicode string

iris.getBoolean()¶

Fetch the value of the global node as a Boolean.

get(globalName,subscripts…)

Parameters:	globalName (Unicode string) – global node name subscripts... (Unicode string, optional, variable length) – global subscripts
Returns:	Return None if the node is undefined. Return True if the numeric value of the node is non-zero. Otherwise return False.
Return type:	None or bool

iris.getBytes()¶

Fetch the value of the global node as a Byte string.

get(globalName,subscripts…)

Parameters:	globalName (Unicode string) – global node name subscripts... (Unicode string, optional, variable length) – global subscripts
Returns:	Return None if the node is undefined and b’’ if set to the empty string. Throw an exception if the node value is not a byte or ASCII string. Otherwise return the value of the node as a Byte string.
Return type:	None or Byte string

iris.set()¶

Set the value of a global node.

set(value,globalName,subscripts…)

The new value may be an Integer/Long, Unicode string, Float, None, or Byte string.

Parameters:	value (None, int/long, Unicode string, float, Byte string) – new value of the global node globalName (Unicode string) – global node name subscripts... (Unicode string, optional, variable length) – global subscripts
Returns:	None
Return type:	None

iris.isDefined()¶

Check whether a global node contains data and whether it has children.

isDefined(globalName,subscripts…)

This method is similar to $DATA in ObjectScript.

Parameters:

globalName (Unicode string) – global node name
subscripts... (Unicode string, optional, variable length) – global subscripts

Returns:

Return one of the following four integers:

0 if the node is undefined and has no children

1 if the node is defined and has no children

10 if the node is undefined and has children

11 if the node is defined and has children.

Return type:

int or long

iris.kill()¶

Kill the global node including any descendants.

kill(globalName,subscripts…)

This method is a no-op if called on an undefined global node.

Parameters:	globalName (Unicode string) – global node name subscripts... (Unicode string, optional, variable length) – global subscripts
Returns:	None
Return type:	None

iris.increment()¶

Increment the global node by the value argument.

increment(value,globalName,subscripts…)

Set the node to the given value if it is undefined.

Parameters:	value (int/long or float) – amount to increment by globalName (Unicode string) – global node name subscripts... (Unicode string, optional, variable length) – global subscripts
Returns:	Return the new value of the global node
Return type:	int/long or float

iris.classMethodValue()¶

Call the class method and expect a return value.

classMethodValue(className,methodName,args…)

The method arguments may be of types None, int/long, Unicode string, float, or Byte string. Throw a <COMMAND> exception if no value is returned.

Parameters:	className (Unicode string) – fully qualified name of IRIS class methodName (Unicode string) – name of the class method args... (optional, variable length) – zero or more arguments to pass to the method
Returns:	Return the result of the class method.
Return type:	None, int/long, Unicode string, or float

iris.classMethodVoid()¶

Call the class method and do not expect a return value.

classMethodVoid(className,methodName,args…)

The method arguments may be of types None, int/long, Unicode string, float, or Byte string.

Parameters:	className (Unicode string) – fully qualified name of IRIS class methodName (Unicode string) – name of the class method args... (optional, variable length) – zero or more arguments to pass to the method
Returns:	None
Return type:	None

Notes

Note that using classMethodValue() or classMethodVoid() indicates what the Python caller expects, not what the ObjectScript class method actually does. This means that you can call a class method that does return a value with classMethodVoid() and the return value will just be ignored.

iris.function()¶

Call the function and expect a return value.

function(functionName,routineName,args…)

The function arguments may be of types None, int/long, Unicode string, float, or Byte string. Throw a <COMMAND> exception if no value is returned.

Parameters:	functionName (Unicode string) – name of the function routineName (Unicode string) – name of the IRIS routine args... (optional, variable length) – zero or more arguments to pass to the function
Returns:	Return the result of the function.
Return type:	None, int/long, Unicode string, or float

iris.procedure()¶

Call the procedure and do not expect a return value.

procedure(procedureName,routineName,args…)

The procedure arguments may be of types None, int/long, Unicode string, float, or Byte string.

Parameters:	procedureName (Unicode string) – name of the procedure routineName (Unicode string) – name of the IRIS routine args... (optional, variable length) – zero or more arguments to pass to the procedure
Returns:	None
Return type:	None

Notes

Note that using function() or procedure() indicates what the Python caller expects, not what the ObjectScript function actually does. This means that you can call a function that does return a value with procedure() and the return value will just be ignored.

iris.lock()¶

Lock the global node.

lock(lockMode,timeout,globalName,subscripts…)

Perform an incremental lock and not the implicit unlock before lock feature that is also offered in ObjectScript. Throw a <TIMEOUT> exception if the timeout is reached waiting to acquire the lock.

Parameters:	lockMode (Unicode string) – a string containing zero or more of these characters: S for shared lock, E for escalating lock. An empty string is the default mode (exclusive and non-escalating). timeout (int/long) – number of seconds to wait to acquire the lock globalName (Unicode string) – global node name subscripts... (Unicode string, optional, variable length) – global subscripts
Returns:	None
Return type:	None

iris.unlock()¶

Unlock the global node.

unlock(lockMode,globalName,subscripts…)

Perform an incremental unlock and not the implicit unlock before lock feature that is also offered in ObjectScript.

Parameters:	lockMode (Unicode string) – a string containing zero or more of these characters: S for shared lock, E for escalating lock, I for immediate unlock, D for deferred unlock. An empty string is the default mode (exclusive, non-escalating, always defers releasing an unlocked lock to the end of the current transaction). globalName (Unicode string) – global node name subscripts... (Unicode string, optional, variable length) – global subscripts
Returns:	None
Return type:	None

iris.releaseAllLocks()¶

Release all locks associated with the session (i.e. connection).

releaseAllLocks()

Returns:	None
Return type:	None

iris.tStart()¶

Start or open an IRIS transaction.

tStart()

Returns:	None
Return type:	None

iris.tCommit()¶

Commit the current IRIS transaction.

tCommit()

Returns:	None
Return type:	None

iris.tRollback()¶

Roll back all open IRIS transactions in the session (i.e. connection).

tRollback()

Returns:	None
Return type:	None

iris.tRollbackOne()¶

Roll back the current level of IRIS transaction only.

tRollbackOne()

This method is intended for nested transactions, when the caller only wants to roll back one level.

Returns:	None
Return type:	None

iris.getTLevel()¶

Return the number of nested transactions currently open in the session.

getTLevel()

This is equivalent to fetching the value of the $TLEVEL special variable in ObjectScript.

Returns:	Return 1 if there is a single transaction open, and 0 if there are no transactions open. Otherwise, return the number of open transactions in the current session (i.e. connection).
Return type:	int/long

iris.iterator()¶

Return an iterator over the immediate children of the global node.

iterator(globalName,subscripts…)

The global name and subscripts arguments specify the root node. For example, for the following global:

^gbl(1)=”a”

^gbl(1,11)=”b”

^gbl(1,12)=”c”

^gbl(2)=”d”

iris.iterator(“^gbl”) returns an irisnative.iterator object that traverses the immediate children of ^gbl: ^gbl(1) and ^gbl(2). iris.iterator(“^gbl”,1) returns an irisnative.iterator object that traverses the immediate children of ^gbl(1): ^gbl(1,11) and ^gbl(1,12). The returned iterator is forward-walking and positioned before the first subscript.

Parameters:	globalName (Unicode string) – root global node name subscripts... (Unicode string, optional, variable length) – root global subscripts
Returns:	A new iterator object for the root global specified.
Return type:	irisnative.iterator